From 9e388643cf7d02db99e530a2acdd23aac005a78e Mon Sep 17 00:00:00 2001 From: Jwahir Sundai Date: Thu, 10 Sep 2026 10:49:26 -0500 Subject: [PATCH 1/2] workflow section audit --- .../high-availability/ha-connectivity.mdx | 2 +- .../activities/asynchronous-activity.mdx | 2 +- .../dotnet/best-practices/debugging.mdx | 2 +- .../dotnet/best-practices/error-handling.mdx | 4 +- .../dotnet/best-practices/testing-suite.mdx | 2 +- .../develop/dotnet/client/temporal-client.mdx | 2 +- docs/develop/dotnet/index.mdx | 4 +- .../develop/dotnet/platform/observability.mdx | 2 +- docs/develop/dotnet/workflows/basics.mdx | 3 +- .../develop/dotnet/workflows/cancellation.mdx | 8 ++-- .../dotnet/workflows/child-workflows.mdx | 2 +- .../dotnet/workflows/continue-as-new.mdx | 16 ++++---- .../dotnet/workflows/dynamic-workflow.mdx | 1 + docs/develop/dotnet/workflows/index.mdx | 1 + .../dotnet/workflows/message-passing.mdx | 5 ++- docs/develop/dotnet/workflows/schedules.mdx | 2 +- docs/develop/dotnet/workflows/timeouts.mdx | 2 +- docs/develop/dotnet/workflows/timers.mdx | 2 +- docs/develop/dotnet/workflows/versioning.mdx | 4 +- docs/develop/go/workflows/basics.mdx | 11 ++--- docs/develop/go/workflows/continue-as-new.mdx | 14 +++---- .../develop/go/workflows/dynamic-workflow.mdx | 1 + docs/develop/go/workflows/index.mdx | 1 + docs/develop/go/workflows/message-passing.mdx | 2 +- docs/develop/go/workflows/selectors.mdx | 2 +- docs/develop/go/workflows/side-effects.mdx | 1 + docs/develop/go/workflows/timeouts.mdx | 7 ++-- docs/develop/go/workflows/versioning.mdx | 4 +- docs/develop/java/workflows/basics.mdx | 3 +- .../java/workflows/child-workflows.mdx | 2 +- .../java/workflows/continue-as-new.mdx | 14 +++---- docs/develop/java/workflows/index.mdx | 1 + .../java/workflows/message-passing.mdx | 10 ++--- docs/develop/java/workflows/schedules.mdx | 40 +++++++++---------- docs/develop/java/workflows/side-effects.mdx | 1 + docs/develop/java/workflows/timeouts.mdx | 7 ++-- docs/develop/java/workflows/versioning.mdx | 2 +- docs/develop/php/workflows/basics.mdx | 21 +++++----- docs/develop/php/workflows/cancellation.mdx | 4 +- .../develop/php/workflows/child-workflows.mdx | 6 +-- .../develop/php/workflows/continue-as-new.mdx | 14 +++---- docs/develop/php/workflows/index.mdx | 1 + .../develop/php/workflows/message-passing.mdx | 28 ++++++------- docs/develop/php/workflows/schedules.mdx | 8 ++-- docs/develop/php/workflows/side-effects.mdx | 3 +- docs/develop/php/workflows/timeouts.mdx | 7 ++-- docs/develop/php/workflows/timers.mdx | 2 +- docs/develop/php/workflows/versioning.mdx | 2 +- docs/develop/python/workflows/basics.mdx | 1 + .../python/workflows/continue-as-new.mdx | 14 +++---- docs/develop/python/workflows/index.mdx | 1 + .../python/workflows/message-passing.mdx | 2 +- docs/develop/python/workflows/timeouts.mdx | 5 +-- docs/develop/python/workflows/timers.mdx | 2 +- docs/develop/python/workflows/versioning.mdx | 2 +- .../workflows/worker-versioning-legacy.mdx | 4 +- docs/develop/ruby/workflows/basics.mdx | 1 + docs/develop/ruby/workflows/cancellation.mdx | 4 +- .../ruby/workflows/continue-as-new.mdx | 2 +- .../ruby/workflows/dynamic-workflow.mdx | 1 + docs/develop/ruby/workflows/futures.mdx | 1 + docs/develop/ruby/workflows/index.mdx | 1 + .../ruby/workflows/message-passing.mdx | 3 +- docs/develop/ruby/workflows/timeouts.mdx | 2 +- docs/develop/ruby/workflows/versioning.mdx | 2 +- docs/develop/rust/workflows/basics.mdx | 3 +- .../rust/workflows/continue-as-new.mdx | 12 +++--- docs/develop/rust/workflows/index.mdx | 1 + .../rust/workflows/message-passing.mdx | 2 +- .../typescript/client/temporal-client.mdx | 4 +- docs/develop/typescript/set-up.mdx | 2 +- .../typescript/worker-versioning-legacy.mdx | 6 +-- docs/develop/typescript/workflows/basics.mdx | 12 +++--- .../workflows/cancellation-scopes.mdx | 6 +-- .../typescript/workflows/cancellation.mdx | 4 +- .../typescript/workflows/child-workflows.mdx | 4 +- .../typescript/workflows/continue-as-new.mdx | 18 ++++----- docs/develop/typescript/workflows/index.mdx | 1 + .../typescript/workflows/message-passing.mdx | 8 ++-- .../typescript/workflows/schedules.mdx | 4 +- .../develop/typescript/workflows/timeouts.mdx | 29 +++++++------- .../typescript/workflows/versioning.mdx | 2 +- .../event-history/event-history.mdx | 2 +- .../workers/task-queue-naming.mdx | 4 +- .../workflow/workflow-definition.mdx | 6 +-- 85 files changed, 238 insertions(+), 225 deletions(-) diff --git a/docs/cloud/high-availability/ha-connectivity.mdx b/docs/cloud/high-availability/ha-connectivity.mdx index c15c3d7f88..5b59f6d82b 100644 --- a/docs/cloud/high-availability/ha-connectivity.mdx +++ b/docs/cloud/high-availability/ha-connectivity.mdx @@ -48,7 +48,7 @@ When authenticating with mTLS, set the Client's `server_name` / `serverNameOverr This overrides the SNI that the Client will expect during the TLS Handshake with Temporal Cloud. The Regional Endpoint forwards the request to your Namespace, so the Client must expect the Namespace's certificate during the TLS handshake. -For example, in Typescript, the Client's config would be set like this: +For example, in TypeScript, the Client's config would be set like this: ```typescript await Connection.connect({ diff --git a/docs/develop/dotnet/activities/asynchronous-activity.mdx b/docs/develop/dotnet/activities/asynchronous-activity.mdx index f7b97cf8ee..cf884bf7c8 100644 --- a/docs/develop/dotnet/activities/asynchronous-activity.mdx +++ b/docs/develop/dotnet/activities/asynchronous-activity.mdx @@ -6,7 +6,7 @@ description: Asynchronously complete an Activity in Temporal. Follow simple step toc_max_heading_level: 4 tags: - Activities - - .Net SDK + - .NET SDK - Temporal SDKs --- diff --git a/docs/develop/dotnet/best-practices/debugging.mdx b/docs/develop/dotnet/best-practices/debugging.mdx index 1056eed2c0..cfc776d600 100644 --- a/docs/develop/dotnet/best-practices/debugging.mdx +++ b/docs/develop/dotnet/best-practices/debugging.mdx @@ -5,7 +5,7 @@ sidebar_label: Debugging description: Debug Workflows in development and production environments using Temporal .NET SDK. Use logging, debugger, Web UI, CLI, replay, tracing, and more for efficient troubleshooting. toc_max_heading_level: 4 tags: - - .Net SDK + - .NET SDK - Temporal SDKs - Debugging - Errors diff --git a/docs/develop/dotnet/best-practices/error-handling.mdx b/docs/develop/dotnet/best-practices/error-handling.mdx index 4b4fd3d3c8..7b6e2be4a5 100644 --- a/docs/develop/dotnet/best-practices/error-handling.mdx +++ b/docs/develop/dotnet/best-practices/error-handling.mdx @@ -2,12 +2,12 @@ id: error-handling title: Error handling - .NET SDK sidebar_label: Error handling -description: Handle errors with Temporal .Net SDK +description: Handle errors with Temporal .NET SDK toc_max_heading_level: 4 tags: - Activities - Workflows - - .Net SDK + - .NET SDK - Temporal SDKs - Failures - Errors diff --git a/docs/develop/dotnet/best-practices/testing-suite.mdx b/docs/develop/dotnet/best-practices/testing-suite.mdx index 2d855d7ed7..58038355d6 100644 --- a/docs/develop/dotnet/best-practices/testing-suite.mdx +++ b/docs/develop/dotnet/best-practices/testing-suite.mdx @@ -5,7 +5,7 @@ sidebar_label: Testing description: The .NET test-suite guide covers Workflow and integration testing for Temporal. It includes end-to-end, integration, and unit testing, emphasizing the use of the test server to optimize test execution. toc_max_heading_level: 4 tags: - - .Net SDK + - .NET SDK - Temporal SDKs - Testing --- diff --git a/docs/develop/dotnet/client/temporal-client.mdx b/docs/develop/dotnet/client/temporal-client.mdx index fc5f4ec8d4..ef42e01170 100644 --- a/docs/develop/dotnet/client/temporal-client.mdx +++ b/docs/develop/dotnet/client/temporal-client.mdx @@ -6,7 +6,7 @@ description: Create a Temporal Client, connect to Temporal Cloud, start a Workflow, and get Workflow results using the Temporal .NET SDK with detailed steps and code examples. tags: - - .Net SDK + - .NET SDK - Temporal SDKs - Temporal Client - Certificates diff --git a/docs/develop/dotnet/index.mdx b/docs/develop/dotnet/index.mdx index 04a93ce7c7..a9c62b4d61 100644 --- a/docs/develop/dotnet/index.mdx +++ b/docs/develop/dotnet/index.mdx @@ -1,13 +1,13 @@ --- id: index -title: .Net SDK developer guide +title: .NET SDK developer guide sidebar_label: .NET SDK description: Use the Temporal .NET SDK to develop Temporal Applications, connect to the Temporal Service, test Workflows and Activities, handle failures, send messages, and more. toc_max_heading_level: 4 tags: - - .Net SDK + - .NET SDK - Temporal SDKs --- diff --git a/docs/develop/dotnet/platform/observability.mdx b/docs/develop/dotnet/platform/observability.mdx index 8d1c22f111..961e7eba1e 100644 --- a/docs/develop/dotnet/platform/observability.mdx +++ b/docs/develop/dotnet/platform/observability.mdx @@ -5,7 +5,7 @@ sidebar_label: Observability description: Explore Temporal SDK observability features for Metrics, Tracing, Logging, and Visibility. Track Workflow Executions, set up Prometheus endpoints, customize metrics, configure tracing, and more. toc_max_heading_level: 4 tags: - - .Net SDK + - .NET SDK - Temporal SDKs - Observability - Search Attributes diff --git a/docs/develop/dotnet/workflows/basics.mdx b/docs/develop/dotnet/workflows/basics.mdx index 6e8e210088..a56ad7e06a 100644 --- a/docs/develop/dotnet/workflows/basics.mdx +++ b/docs/develop/dotnet/workflows/basics.mdx @@ -5,6 +5,7 @@ sidebar_label: Workflow basics description: This section explains Workflow basics with the .NET SDK toc_max_heading_level: 4 tags: + - Workflows - .NET SDK - Temporal SDKs --- @@ -181,7 +182,7 @@ Here are some known gotchas to avoid with .NET tasks inside of Workflows: - Be wary of additional libraries' implicit use of the default scheduler. - For example, while there are articles for `Dataflow` about [using a specific scheduler](https://learn.microsoft.com/en-us/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block), there are hidden implicit uses of `TaskScheduler.Default`. For example, see [this bug](https://github.com/dotnet/runtime/issues/83159). -In order to help catch wrong scheduler use, by default the Temporal .NET SDK adds an event source listener for info-level task events. +To help catch wrong scheduler use, the Temporal .NET SDK adds an event source listener for info-level task events by default. While this technically receives events from all uses of tasks in the process, we make sure to ignore anything that is not running in a Workflow in a high performant way (basically one thread local check). For code that does run in a Workflow and accidentally starts a task in another scheduler, an `InvalidWorkflowOperationException` will be thrown which "pauses" the Workflow (fails the Workflow Task which continually retries until the code is fixed). diff --git a/docs/develop/dotnet/workflows/cancellation.mdx b/docs/develop/dotnet/workflows/cancellation.mdx index 09425d7947..5b708e62ec 100644 --- a/docs/develop/dotnet/workflows/cancellation.mdx +++ b/docs/develop/dotnet/workflows/cancellation.mdx @@ -2,13 +2,11 @@ id: cancellation title: Cancellation - .NET SDK sidebar_label: Cancellation -description: - Interrupt Workflow Execution in .NET using the Temporal SDK. Cancel for graceful stops; terminate for forceful stops. - Handle Cancellation in Workflow and Activities efficiently. +description: Handle Cancellation in .NET Workflows and Activities, request Cancellation from a Client, and choose between Cancellation, termination, and reset. toc_max_heading_level: 4 tags: - Workflows - - .Net SDK + - .NET SDK - Temporal SDKs --- @@ -126,7 +124,7 @@ var handle = myClient.GetWorkflowHandle("my-workflow-id"); await handle.CancelAsync(); ``` -#### How to request Cancellation of an Activity +#### Request Cancellation of an Activity {/* #request-cancellation-of-an-activity */} By default, Activities are automatically cancelled when the Workflow is cancelled since the workflow cancellation token is used by activities by default. To issue a cancellation explicitly, a new cancellation token can be created. diff --git a/docs/develop/dotnet/workflows/child-workflows.mdx b/docs/develop/dotnet/workflows/child-workflows.mdx index be9f4fc856..ea984b662b 100644 --- a/docs/develop/dotnet/workflows/child-workflows.mdx +++ b/docs/develop/dotnet/workflows/child-workflows.mdx @@ -5,7 +5,7 @@ sidebar_label: Child Workflows description: Start a Child Workflow Execution and set a Parent Close Policy using Temporal .NET SDK. Discover methods like ExecuteChildWorkflowAsync and manage Workflow behaviors. tags: - Workflows - - .Net SDK + - .NET SDK - Temporal SDKs - Child Workflows --- diff --git a/docs/develop/dotnet/workflows/continue-as-new.mdx b/docs/develop/dotnet/workflows/continue-as-new.mdx index 47bf6d7ad8..e23f883652 100644 --- a/docs/develop/dotnet/workflows/continue-as-new.mdx +++ b/docs/develop/dotnet/workflows/continue-as-new.mdx @@ -7,18 +7,18 @@ toc_max_heading_level: 2 tags: - Workflows - continue-as-new - - .Net SDK + - .NET SDK - Temporal SDKs --- import { ViewSourceCodeNotice } from '@site/src/components'; -This page answers the following questions for .NET developers: +This page covers the following for .NET developers: - [What is Continue-As-New?](#what) -- [How to Continue-As-New?](#how) -- [When is it right to Continue-as-New?](#when) -- [How to test Continue-as-New?](#how-to-test) +- [Use Continue-As-New](#how) +- [When is it right to Continue-As-New?](#when) +- [Test Continue-As-New](#how-to-test) ## What is Continue-As-New? {/* #what */} @@ -28,7 +28,7 @@ You can think of it as a checkpoint when your Workflow gets too long or approach The new Workflow Execution is in the same [chain](/workflow-execution#workflow-execution-chain); it keeps the same Workflow Id but gets a new Run Id and a fresh Event History. It also receives your Workflow's usual parameters. -## How to Continue-As-New using the .NET SDK {/* #how */} +## Use Continue-As-New with the .NET SDK {/* #how */} First, design your Workflow parameters so that you can pass in the "current state" when you Continue-As-New into the next Workflow run. This state is typically set to `None` for the original caller of the Workflow. @@ -66,14 +66,14 @@ If you use Updates or Signals, don't call Continue-as-New from the handlers. Instead, wait for your handlers to finish in your main Workflow before you throw `CreateContinueAsNewException`. See the [`AllHandlersFinished`](message-passing#wait-for-message-handlers) example for guidance. -## When is it right to Continue-as-New using the .NET SDK? {/* #when */} +## When is it right to Continue-As-New with the .NET SDK? {/* #when */} Use Continue-as-New when your Workflow might hit [Event History Limits](/workflow-execution/event#event-history). Temporal tracks your Workflow's progress against these limits to let you know when you should Continue-as-New. Call `Workflow.ContinueAsNewSuggested` to check if it's time. -## How to test Continue-as-New using the .NET SDK {/* #how-to-test */} +## Test Continue-As-New with the .NET SDK {/* #how-to-test */} Testing Workflows that naturally Continue-as-New may be time-consuming and resource-intensive. Instead, add a test hook to check your Workflow's Continue-as-New behavior faster in automated tests. diff --git a/docs/develop/dotnet/workflows/dynamic-workflow.mdx b/docs/develop/dotnet/workflows/dynamic-workflow.mdx index 778ad0832f..7abc31366e 100644 --- a/docs/develop/dotnet/workflows/dynamic-workflow.mdx +++ b/docs/develop/dotnet/workflows/dynamic-workflow.mdx @@ -5,6 +5,7 @@ sidebar_label: Dynamic Workflow description: This section explains Dynamic Workflows with the .NET SDK toc_max_heading_level: 4 tags: + - Workflows - .NET SDK - Temporal SDKs --- diff --git a/docs/develop/dotnet/workflows/index.mdx b/docs/develop/dotnet/workflows/index.mdx index 0df4ad08ff..2073a3cf0c 100644 --- a/docs/develop/dotnet/workflows/index.mdx +++ b/docs/develop/dotnet/workflows/index.mdx @@ -5,6 +5,7 @@ sidebar_label: Workflows description: This section explains how to implement Workflows with the .NET SDK toc_max_heading_level: 4 tags: + - Workflows - .NET SDK - Temporal SDKs --- diff --git a/docs/develop/dotnet/workflows/message-passing.mdx b/docs/develop/dotnet/workflows/message-passing.mdx index 22d8d81167..c223bb605b 100644 --- a/docs/develop/dotnet/workflows/message-passing.mdx +++ b/docs/develop/dotnet/workflows/message-passing.mdx @@ -5,7 +5,8 @@ sidebar_label: Message passing description: Develop with Queries, Signals, and Updates with the Temporal .NET SDK. toc_max_heading_level: 3 tags: - - .Net SDK + - Workflows + - .NET SDK - Temporal SDKs --- @@ -421,7 +422,7 @@ Signal and Update handlers can be asynchronous as well as blocking. Using asynchronous calls allows you to `await` Activities, Child Workflows, [`Workflow.DelayAsync`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html?#Temporalio_Workflows_Workflow_DelayAsync_System_Int32_System_Nullable_System_Threading_CancellationToken__) Timers, [`Workflow.WaitConditionAsync`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html?#Temporalio_Workflows_Workflow_WaitConditionAsync_System_Func_System_Boolean__System_Int32_System_Nullable_System_Threading_CancellationToken__) wait conditions, etc. This expands the possibilities for what can be done by a handler but it also means that handler executions and your main Workflow method are all running concurrently, with switching occurring between them at await calls. -It's essential to understand the things that could go wrong in order to use asynchronous handlers safely. +To use asynchronous handlers safely, understand what can go wrong. See [Workflow message passing](/encyclopedia/workflow-message-passing) for guidance on safe usage of async Signal and Update handlers, and the [Controlling handler concurrency](#control-handler-concurrency) and [Waiting for message handlers to finish](#wait-for-message-handlers) sections below. The following code executes an Activity that simulates a network call to a remote service: diff --git a/docs/develop/dotnet/workflows/schedules.mdx b/docs/develop/dotnet/workflows/schedules.mdx index 78e1be4c2e..6cc1b2e085 100644 --- a/docs/develop/dotnet/workflows/schedules.mdx +++ b/docs/develop/dotnet/workflows/schedules.mdx @@ -5,7 +5,7 @@ sidebar_label: Schedules description: Manage and optimize Scheduled Workflows using the Temporal .NET SDK; Schedule, Create, Backfill, Update, Delete, Describe, List, Pause, Trigger, and use Start Delay options. tags: - Workflows - - .Net SDK + - .NET SDK - Temporal SDKs - Schedules --- diff --git a/docs/develop/dotnet/workflows/timeouts.mdx b/docs/develop/dotnet/workflows/timeouts.mdx index ffa5c68abf..c1c842aa84 100644 --- a/docs/develop/dotnet/workflows/timeouts.mdx +++ b/docs/develop/dotnet/workflows/timeouts.mdx @@ -40,7 +40,7 @@ var result = await client.ExecuteWorkflowAsync( }); ``` -### Set Workflow retries {/* #workflow-retries */} +## Workflow retries {/* #workflow-retries */} A Retry Policy can work in cooperation with the timeouts to provide fine controls to optimize the execution experience. diff --git a/docs/develop/dotnet/workflows/timers.mdx b/docs/develop/dotnet/workflows/timers.mdx index ba967a0421..3ac60493ac 100644 --- a/docs/develop/dotnet/workflows/timers.mdx +++ b/docs/develop/dotnet/workflows/timers.mdx @@ -6,7 +6,7 @@ sidebar_label: Timers tags: - Workflows - Durable Timers - - .Net SDK + - .NET SDK - Temporal SDKs --- diff --git a/docs/develop/dotnet/workflows/versioning.mdx b/docs/develop/dotnet/workflows/versioning.mdx index 688542ff8b..08dc5f0690 100644 --- a/docs/develop/dotnet/workflows/versioning.mdx +++ b/docs/develop/dotnet/workflows/versioning.mdx @@ -6,7 +6,7 @@ description: Use the .NET SDK Patching API to safely deploy new code versions, h toc_max_heading_level: 4 tags: - Workflows - - .Net SDK + - .NET SDK - Temporal SDKs - Versioning - Patching @@ -158,7 +158,7 @@ public class MyWorkflow ``` Patching allows you to make changes to currently running Workflows. -It is a powerful method for introducing compatible changes without introducing non-determinism errors. +It introduces compatible changes without causing non-determinism errors. ### Detailed Overview of the Patched Function diff --git a/docs/develop/go/workflows/basics.mdx b/docs/develop/go/workflows/basics.mdx index ba405b791d..98cc310218 100644 --- a/docs/develop/go/workflows/basics.mdx +++ b/docs/develop/go/workflows/basics.mdx @@ -5,11 +5,12 @@ sidebar_label: Workflow basics description: This section explains Workflow basics with the Go SDK toc_max_heading_level: 4 tags: + - Workflows - Go SDK - Temporal SDKs --- -## How to develop a basic Workflow {/* #develop-workflows */} +## Develop a basic Workflow {/* #develop-workflows */} Workflows are the fundamental unit of a Temporal Application, and it all starts with the development of a [Workflow Definition](/workflow-definition). @@ -30,7 +31,7 @@ func YourSimpleWorkflowDefinition(ctx workflow.Context) error { } ``` -### How to define Workflow parameters {/* #workflow-parameters */} +### Define Workflow parameters {/* #workflow-parameters */} Temporal Workflows may have any number of custom parameters. However, we strongly recommend that objects are used as parameters, so that the object's individual fields may be altered without breaking the signature of the Workflow. @@ -86,7 +87,7 @@ func YourWorkflowDefinition(ctx workflow.Context, param YourWorkflowParam) (*You } ``` -### How to define Workflow return parameters {/* #workflow-return-values */} +### Define Workflow return parameters {/* #workflow-return-values */} Workflow return values must also be serializable. Returning results, returning errors, or throwing exceptions is fairly idiomatic in each language that is supported. @@ -142,7 +143,7 @@ func YourWorkflowDefinition(ctx workflow.Context, param YourWorkflowParam) (*You } ``` -### How to customize Workflow Type in Go {/* #customize-workflow-type */} +### Customize Workflow Type {/* #customize-workflow-type */} In Go, by default, the Workflow Type name is the same as the function name. @@ -196,7 +197,7 @@ func main() { } ``` -### How to develop Workflow logic {/* #workflow-logic-requirements */} +### Develop Workflow logic {/* #workflow-logic-requirements */} Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints). Each Temporal SDK provides a set of APIs that can be used inside your Workflow to interact with application code outside the Workflow. diff --git a/docs/develop/go/workflows/continue-as-new.mdx b/docs/develop/go/workflows/continue-as-new.mdx index 10e1d8d635..42e430a279 100644 --- a/docs/develop/go/workflows/continue-as-new.mdx +++ b/docs/develop/go/workflows/continue-as-new.mdx @@ -13,12 +13,12 @@ tags: import { ViewSourceCodeNotice } from '@site/src/components'; -This page answers the following questions for Go developers: +This page covers the following for Go developers: - [What is Continue-As-New?](#what) -- [How to Continue-As-New?](#how) -- [When is it right to Continue-as-New?](#when) -- [How to test Continue-as-New?](#how-to-test) +- [Use Continue-As-New](#how) +- [When is it right to Continue-As-New?](#when) +- [Test Continue-As-New](#how-to-test) ## What is Continue-As-New? {/* #what */} @@ -28,7 +28,7 @@ You can think of it as a checkpoint when your Workflow gets too long or approach The new Workflow Execution is in the same [chain](/workflow-execution#workflow-execution-chain); it keeps the same Workflow Id but gets a new Run Id and a fresh Event History. It also receives your Workflow's usual parameters. -## How to Continue-As-New using the Go SDK {/* #how */} +## Use Continue-As-New with the Go SDK {/* #how */} First, design your Workflow parameters so that you can pass in the "current state" when you Continue-As-New into the next Workflow run. This state is typically set to `None` for the original caller of the Workflow. @@ -66,14 +66,14 @@ If you use Updates or Signals, don't call Continue-as-New from the handlers. Instead, wait for your handlers to finish in your main Workflow before you return `NewContinueAsNewError`. See the [`AllHandlersFinished`](message-passing#wait-for-message-handlers) example for guidance. -## When is it right to Continue-as-New using the Go SDK? {/* #when */} +## When is it right to Continue-As-New with the Go SDK? {/* #when */} Use Continue-as-New when your Workflow might hit [Event History Limits](/workflow-execution/event#event-history). Temporal tracks your Workflow's progress against these limits to let you know when you should Continue-as-New. Call `GetInfo(ctx).GetContinueAsNewSuggested()` to check if it's time. -## How to test Continue-as-New using the Go SDK {/* #how-to-test */} +## Test Continue-As-New with the Go SDK {/* #how-to-test */} Testing Workflows that naturally Continue-as-New may be time-consuming and resource-intensive. Instead, add a test hook to check your Workflow's Continue-as-New behavior faster in automated tests. diff --git a/docs/develop/go/workflows/dynamic-workflow.mdx b/docs/develop/go/workflows/dynamic-workflow.mdx index ed1a959fb6..ac523190a6 100644 --- a/docs/develop/go/workflows/dynamic-workflow.mdx +++ b/docs/develop/go/workflows/dynamic-workflow.mdx @@ -5,6 +5,7 @@ sidebar_label: Dynamic Workflow description: This section explains Dynamic Workflows with the Go SDK toc_max_heading_level: 4 tags: + - Workflows - Go SDK - Temporal SDKs --- diff --git a/docs/develop/go/workflows/index.mdx b/docs/develop/go/workflows/index.mdx index e188a713a3..0a6f473b9e 100644 --- a/docs/develop/go/workflows/index.mdx +++ b/docs/develop/go/workflows/index.mdx @@ -5,6 +5,7 @@ sidebar_label: Workflows description: This section explains how to implement Workflows with the Go SDK toc_max_heading_level: 4 tags: + - Workflows - Go SDK - Temporal SDKs --- diff --git a/docs/develop/go/workflows/message-passing.mdx b/docs/develop/go/workflows/message-passing.mdx index f65ff04ab0..fb9ea95014 100644 --- a/docs/develop/go/workflows/message-passing.mdx +++ b/docs/develop/go/workflows/message-passing.mdx @@ -460,7 +460,7 @@ Signal and Update handlers can block. This allows you to use Activities, Child Workflows, durable [workflow.Sleep](https://pkg.go.dev/go.temporal.io/sdk/workflow#Sleep) Timers, [`workflow.Await`](https://pkg.go.dev/go.temporal.io/sdk/workflow#Await) conditions, etc. This expands the possibilities for what can be done by a handler but it also means that handler executions and your main Workflow method are all running concurrently, with switching occurring between them at await calls. -It's essential to understand the things that could go wrong in order to use blocking handlers safely. +To use blocking handlers safely, understand what can go wrong. See [Workflow message passing](/encyclopedia/workflow-message-passing) for guidance on safe usage of blocking Signal and Update handlers, and the [Controlling handler concurrency](#control-handler-concurrency) and [Waiting for message handlers to finish](#wait-for-message-handlers) sections below. The following code modifies the Update handler from earlier on in this page. diff --git a/docs/develop/go/workflows/selectors.mdx b/docs/develop/go/workflows/selectors.mdx index ee2d9086d5..b3217039ec 100644 --- a/docs/develop/go/workflows/selectors.mdx +++ b/docs/develop/go/workflows/selectors.mdx @@ -24,7 +24,7 @@ It chooses one at random if multiple are ready. However, a normal Go select statement can not be used inside of Workflows directly because of the random nature. Temporal's Go SDK `Selector`s are similar and act as a replacement. They can block on sending and receiving from Channels but as a bonus can listen on Future deferred work. -Usage of Selectors to defer and process work (in place of Go's `select`) are necessary in order to ensure deterministic Workflow code execution (though using `select` in Activity code is fine). +Use Selectors to defer and process work in place of Go's `select`, which keeps Workflow code execution deterministic. Using `select` in Activity code is fine. ## Full API example {/* #api-example */} diff --git a/docs/develop/go/workflows/side-effects.mdx b/docs/develop/go/workflows/side-effects.mdx index fe0fa60909..dbae4fa5f6 100644 --- a/docs/develop/go/workflows/side-effects.mdx +++ b/docs/develop/go/workflows/side-effects.mdx @@ -4,6 +4,7 @@ title: Side Effects - Go SDK sidebar_label: Side Effects toc_max_heading_level: 4 tags: + - Workflows - Side-effects - Go SDK - Temporal SDKs diff --git a/docs/develop/go/workflows/timeouts.mdx b/docs/develop/go/workflows/timeouts.mdx index afb50df26b..59b07632da 100644 --- a/docs/develop/go/workflows/timeouts.mdx +++ b/docs/develop/go/workflows/timeouts.mdx @@ -19,9 +19,8 @@ Each Workflow timeout controls the maximum duration of a different aspect of a W Workflow timeouts are set when [starting the Workflow Execution](#workflow-timeouts). -Before we continue, we want to note that we generally do not recommend setting Workflow Timeouts, because Workflows are designed to be long-running and resilient. -Instead, setting a Timeout can limit its ability to handle unexpected delays or long-running processes. -If you need to perform an action inside your Workflow after a specific period of time, we recommend using a Timer. +Avoid setting Workflow Timeouts. Workflows are designed to be long-running and resilient, and a Timeout limits a Workflow's ability to handle unexpected delays or long-running processes. +To perform an action inside your Workflow after a specific period of time, use a Timer instead. - **[Workflow Execution Timeout](/encyclopedia/detecting-workflow-failures#workflow-execution-timeout)** - restricts the maximum amount of time that a single Workflow Execution can be executed. - **[Workflow Run Timeout](/encyclopedia/detecting-workflow-failures#workflow-run-timeout):** restricts the maximum amount of time that a single Workflow Run can last. @@ -50,7 +49,7 @@ if err != nil { } ``` -## Workflow Retry Policy {/* #workflow-retries */} +## Workflow retries {/* #workflow-retries */} A Retry Policy can work in cooperation with the timeouts to provide fine controls to optimize the execution experience. diff --git a/docs/develop/go/workflows/versioning.mdx b/docs/develop/go/workflows/versioning.mdx index 9146bd2910..94a5da85b5 100644 --- a/docs/develop/go/workflows/versioning.mdx +++ b/docs/develop/go/workflows/versioning.mdx @@ -1,7 +1,7 @@ --- id: versioning title: Versioning - Go SDK -description: Temporal's Go SDK ensures Workflow Definition determinism through Patching APIs and Worker Versioning. Update Workflow code without causing non-deterministic issues, understand versioning best practices, and use dynamic configuration parameters for seamless updating of long-running Workflows. +description: Patch Go Workflow code with GetVersion, deprecate old Workflow versions, and plan cutovers without breaking running Executions. sidebar_label: Versioning toc_max_heading_level: 4 tags: @@ -183,7 +183,7 @@ if version == 2 { ``` Patching allows you to make changes to currently running Workflows. -It is a powerful method for introducing compatible changes without introducing non-determinism errors. +It introduces compatible changes without causing non-determinism errors. ### Workflow cutovers diff --git a/docs/develop/java/workflows/basics.mdx b/docs/develop/java/workflows/basics.mdx index 6ecdc2c838..3d0d5abd5e 100644 --- a/docs/develop/java/workflows/basics.mdx +++ b/docs/develop/java/workflows/basics.mdx @@ -5,11 +5,12 @@ sidebar_label: Workflow basics description: This section explains how to implement Workflows with the Java SDK toc_max_heading_level: 4 tags: + - Workflows - Java SDK - Temporal SDKs --- -## How to develop a Workflow {/* #develop-workflows */} +## Develop a Workflow {/* #develop-workflows */} Workflows are the fundamental unit of a Temporal Application, and it all starts with the development of a [Workflow Definition](/workflow-definition). diff --git a/docs/develop/java/workflows/child-workflows.mdx b/docs/develop/java/workflows/child-workflows.mdx index 296618b335..5755cc4d13 100644 --- a/docs/develop/java/workflows/child-workflows.mdx +++ b/docs/develop/java/workflows/child-workflows.mdx @@ -135,7 +135,7 @@ The following examples show how to spawn a Child Workflow: Related reads: -- [How to develop a Workflow Definition](/develop/java/workflows/basics) +- [Develop a Workflow Definition](/develop/java/workflows/basics) - Java Workflow reference: [https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/package-summary.html](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/package-summary.html) diff --git a/docs/develop/java/workflows/continue-as-new.mdx b/docs/develop/java/workflows/continue-as-new.mdx index 314a6d3646..6780d27fee 100644 --- a/docs/develop/java/workflows/continue-as-new.mdx +++ b/docs/develop/java/workflows/continue-as-new.mdx @@ -13,12 +13,12 @@ tags: import { ViewSourceCodeNotice } from '@site/src/components'; -This page answers the following questions for Java developers: +This page covers the following for Java developers: - [What is Continue-As-New?](#what) -- [How to Continue-As-New?](#how) -- [When is it right to Continue-as-New?](#when) -- [How to test Continue-as-New?](#how-to-test) +- [Use Continue-As-New](#how) +- [When is it right to Continue-As-New?](#when) +- [Test Continue-As-New](#how-to-test) ## What is Continue-As-New? {/* #what */} @@ -28,7 +28,7 @@ You can think of it as a checkpoint when your Workflow gets too long or approach The new Workflow Execution is in the same [chain](/workflow-execution#workflow-execution-chain); it keeps the same Workflow Id but gets a new Run Id and a fresh Event History. It also receives your Workflow's usual parameters. -## How to Continue-As-New using the Java SDK {/* #how */} +## Use Continue-As-New with the Java SDK {/* #how */} First, design your Workflow parameters so that you can pass in the "current state" when you Continue-As-New into the next Workflow run. This state is typically set to `None` for the original caller of the Workflow. @@ -60,14 +60,14 @@ Workflow.continueAsNew( If you use Updates or Signals, don't call Continue-as-New from the handlers. Instead, wait for your handlers to finish in your main Workflow before you run `continueAsNew`. -## When is it right to Continue-as-New using the Java SDK? {/* #when */} +## When is it right to Continue-As-New with the Java SDK? {/* #when */} Use Continue-as-New when your Workflow might hit [Event History Limits](/workflow-execution/event#event-history). Temporal tracks your Workflow's progress against these limits to let you know when you should Continue-as-New. Call `Workflow.getInfo().isContinueAsNewSuggested()` to check if it's time. -## How to test Continue-as-New using the Java SDK {/* #how-to-test */} +## Test Continue-As-New with the Java SDK {/* #how-to-test */} Testing Workflows that naturally Continue-as-New may be time-consuming and resource-intensive. Instead, add a test hook to check your Workflow's Continue-as-New behavior faster in automated tests. diff --git a/docs/develop/java/workflows/index.mdx b/docs/develop/java/workflows/index.mdx index 1cb96ac341..0991ab1694 100644 --- a/docs/develop/java/workflows/index.mdx +++ b/docs/develop/java/workflows/index.mdx @@ -5,6 +5,7 @@ sidebar_label: Workflows description: This section covers Workflows with the Java SDK toc_max_heading_level: 4 tags: + - Workflows - Java SDK - Temporal SDKs --- diff --git a/docs/develop/java/workflows/message-passing.mdx b/docs/develop/java/workflows/message-passing.mdx index 7a27f8253a..2c916c6a03 100644 --- a/docs/develop/java/workflows/message-passing.mdx +++ b/docs/develop/java/workflows/message-passing.mdx @@ -477,7 +477,7 @@ Signal and Update handlers can block. This allows you to use [`Workflow.await`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/Workflow.html#await(java.time.Duration,java.util.function.Supplier)), Activities, Child Workflows, [`Workflow.sleep`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/Workflow.html#sleep(java.time.Duration)) Timers, etc. This expands the possibilities for what can be done by a handler but it also means that handler executions and your main Workflow method are all running concurrently, with switching occurring between them at await calls. -It's essential to understand the things that could go wrong in order to use blocking handlers safely. +To use blocking handlers safely, understand what can go wrong. See [Workflow message passing](/encyclopedia/workflow-message-passing) for guidance on safe usage of blocking Signal and Update handlers, and the [Controlling handler concurrency](#control-handler-concurrency) and [Waiting for message handlers to finish](#wait-for-message-handlers) sections below. The following code modifies the Update handler from earlier on in this page. @@ -787,7 +787,7 @@ public class MyDynamicWorkflow implements DynamicWorkflow { } ``` -### How to set a Dynamic Activity {/* #set-a-dynamic-activity */} +### Set a Dynamic Activity {/* #set-a-dynamic-activity */} To handle Activity types that do not have an explicitly registered handler, you can directly implement a dynamic Activity. @@ -815,7 +815,7 @@ The dynamic Activity interface is implemented with the `execute` method, as show Use `Activity.getExecutionContext()` to get information about the Activity type that should be implemented dynamically. -### How to set a Dynamic Signal {/* #set-a-dynamic-signal */} +### Set a Dynamic Signal {/* #set-a-dynamic-signal */} You can also implement Signal handlers dynamically. This is useful for library-level code and implementation of DSLs. @@ -831,7 +831,7 @@ When registered, any Signals sent to the Workflow without a defined handler will Note that you can only register one `Workflow.registerListener(Object)` per Workflow Execution. `DynamicSignalHandler` can be implemented in both regular and dynamic Workflow implementations. -### How to set a Dynamic Query {/* #set-a-dynamic-query */} +### Set a Dynamic Query {/* #set-a-dynamic-query */} You can also implement Query handlers dynamically. This is useful for library-level code and implementation of DSLs. @@ -847,7 +847,7 @@ When registered, any Queries sent to the Workflow without a defined handler will Note that you can only register one `Workflow.registerListener(Object)` per Workflow Execution. `DynamicQueryHandler` can be implemented in both regular and dynamic Workflow implementations. -### How to set a Dynamic Update {/* #set-a-dynamic-update */} +### Set a Dynamic Update {/* #set-a-dynamic-update */} You can also implement Update handlers dynamically. This is useful for library-level code and implementation of DSLs. diff --git a/docs/develop/java/workflows/schedules.mdx b/docs/develop/java/workflows/schedules.mdx index 226d0dc005..e678ad9883 100644 --- a/docs/develop/java/workflows/schedules.mdx +++ b/docs/develop/java/workflows/schedules.mdx @@ -14,19 +14,19 @@ description: Schedule, Backfill, Delete, Describe, List, Pause, Trigger, Update, This page shows how to do the following: -- [How to Schedule a Workflow](#schedule-a-workflow) - - [How to create a Schedule in Java](#create-schedule) - - [How to backfill a Schedule in Java](#backfill-schedule) - - [How to delete a Schedule in Java](#delete-schedule) - - [How to describe a Schedule in Java](#describe-schedule) - - [How to list a Schedule in Java](#list-schedule) - - [How to pause a Schedule in Java](#pause-schedule) - - [How to trigger a Schedule in Java](#trigger-schedule) - - [How to update a Schedule in Java](#update-schedule) -- [How to set a Cron Schedule in Java](#cron-schedule) +- [Schedule a Workflow](#schedule-a-workflow) + - [Create a Schedule](#create-schedule) + - [Backfill a Schedule](#backfill-schedule) + - [Delete a Schedule](#delete-schedule) + - [Describe a Schedule](#describe-schedule) + - [List a Schedule](#list-schedule) + - [Pause a Schedule](#pause-schedule) + - [Trigger a Schedule](#trigger-schedule) + - [Update a Schedule](#update-schedule) +- [Set a Cron Schedule](#cron-schedule) - [Start Delay](#start-delay) -## How to Schedule a Workflow {/* #schedule-a-workflow */} +## Schedule a Workflow {/* #schedule-a-workflow */} Scheduling Workflows is a crucial aspect of any automation process, especially when dealing with time-sensitive tasks. By scheduling a Workflow, you can automate repetitive tasks, reduce the need for manual intervention, and ensure timely execution of your business processes. @@ -35,7 +35,7 @@ Use any of the following actions to help Schedule a Workflow Execution and take Schedule behavior is governed by the Schedule's [Overlap Policy](/schedule#overlap-policy). If a Workflow Execution started by a Schedule is [Paused](/cli/command-reference/workflow#pause), it remains open and counts as the running execution for overlap decisions. -### How to create a Schedule in Java {/* #create-schedule */} +### Create a Schedule {/* #create-schedule */} The create action enables you to create a new Schedule. When you create a new Schedule, a unique Schedule ID is generated, which you can use to reference the Schedule in other Schedule commands. @@ -79,7 +79,7 @@ The Temporal Service doesn't guarantee when this removal will happen. ::: -### How to backfill a Schedule in Java {/* #backfill-schedule */} +### Backfill a Schedule {/* #backfill-schedule */} The backfill action executes Actions ahead of their specified time range. This command is useful when you need to execute a missed or delayed Action, or when you want to test the Workflow before its scheduled time. @@ -95,7 +95,7 @@ handle.backfill( new ScheduleBackfill(now.minusMillis(2500), now))); ``` -### How to delete a Schedule in Java {/* #delete-schedule */} +### Delete a Schedule {/* #delete-schedule */} The delete action enables you to delete a Schedule. When you delete a Schedule, it does not affect any Workflows that were started by the Schedule. @@ -106,7 +106,7 @@ ScheduleHandle handle = client.getHandle("schedule-id") handle.delete(); ``` -### How to describe a Schedule in Java {/* #describe-schedule */} +### Describe a Schedule {/* #describe-schedule */} The describe action shows the current Schedule configuration, including information about past, current, and future Workflow Runs. This command is helpful when you want to get a detailed view of the Schedule and its associated Workflow Runs. @@ -117,7 +117,7 @@ ScheduleHandle handle = client.getHandle("schedule-id") ScheduleDescription description = handle.describe(); ``` -### How to list a Schedule in Java {/* #list-schedule */} +### List a Schedule {/* #list-schedule */} The list action lists all the available Schedules. This command is useful when you want to view a list of all the Schedules and their respective Schedule IDs. @@ -128,7 +128,7 @@ If a schedule is added or deleted, it may not be available in the list immediate Stream scheduleStream = client.listSchedules(); ``` -### How to pause a Schedule in Java {/* #pause-schedule */} +### Pause a Schedule {/* #pause-schedule */} The pause action enables you to pause and unpause a Schedule. When you pause a Schedule, all the future Workflow Runs associated with the Schedule are temporarily stopped. This command is useful when you want to temporarily halt a Workflow due to maintenance or any other reason. @@ -140,7 +140,7 @@ ScheduleHandle handle = client.getHandle("schedule-id") handle.pause("Pausing the schedule for now"); ``` -### How to trigger a Schedule in Java {/* #trigger-schedule */} +### Trigger a Schedule {/* #trigger-schedule */} The trigger action triggers an immediate action with a given Schedule. By default, this action is subject to the Overlap Policy of the Schedule. This command is helpful when you want to execute a Workflow outside of its scheduled time. @@ -151,7 +151,7 @@ ScheduleHandle handle = client.getHandle("schedule-id") handle.trigger(); ``` -### How to update a Schedule in Java {/* #update-schedule */} +### Update a Schedule {/* #update-schedule */} The update action enables you to update an existing Schedule. This command is useful when you need to modify the Schedule's configuration, such as changing the start time, end time, or interval. @@ -174,7 +174,7 @@ handle.update( }); ``` -## How to set a Cron Schedule in Java {/* #cron-schedule */} +## Set a Cron Schedule {/* #cron-schedule */} :::caution Cron support is not recommended diff --git a/docs/develop/java/workflows/side-effects.mdx b/docs/develop/java/workflows/side-effects.mdx index d3ee7b28b1..51ad67592a 100644 --- a/docs/develop/java/workflows/side-effects.mdx +++ b/docs/develop/java/workflows/side-effects.mdx @@ -5,6 +5,7 @@ sidebar_label: Side Effects slug: /develop/java/workflows/side-effects toc_max_heading_level: 2 tags: + - Workflows - Side-effects - Java SDK - Temporal SDKs diff --git a/docs/develop/java/workflows/timeouts.mdx b/docs/develop/java/workflows/timeouts.mdx index 89012ea4cf..426d094f1c 100644 --- a/docs/develop/java/workflows/timeouts.mdx +++ b/docs/develop/java/workflows/timeouts.mdx @@ -19,9 +19,8 @@ Each Workflow timeout controls the maximum duration of a different aspect of a W Workflow timeouts are set when [starting the Workflow Execution](#workflow-timeouts). -Before we continue, we want to note that we generally do not recommend setting Workflow Timeouts, because Workflows are designed to be long-running and resilient. -Instead, setting a Timeout can limit its ability to handle unexpected delays or long-running processes. -If you need to perform an action inside your Workflow after a specific period of time, we recommend using a Timer. +Avoid setting Workflow Timeouts. Workflows are designed to be long-running and resilient, and a Timeout limits a Workflow's ability to handle unexpected delays or long-running processes. +To perform an action inside your Workflow after a specific period of time, use a Timer instead. - **[Workflow Execution Timeout](/encyclopedia/detecting-workflow-failures#workflow-execution-timeout)** - restricts the maximum amount of time that a single Workflow Execution can be executed. - **[Workflow Run Timeout](/encyclopedia/detecting-workflow-failures#workflow-run-timeout):** restricts the maximum amount of time that a single Workflow Run can last. @@ -50,7 +49,7 @@ YourWorkflowInterface workflow1 = .build()); ``` -## Workflow Retry Policy {/* #workflow-retries */} +## Workflow retries {/* #workflow-retries */} **How to set a Workflow Retry Policy in Java.** diff --git a/docs/develop/java/workflows/versioning.mdx b/docs/develop/java/workflows/versioning.mdx index 25baebda81..eae0892302 100644 --- a/docs/develop/java/workflows/versioning.mdx +++ b/docs/develop/java/workflows/versioning.mdx @@ -185,7 +185,7 @@ Workflow.upsertTypedSearchAttributes(TEMPORAL_CHANGE_VERSION.valueSet(list)); ``` Patching allows you to make changes to currently running Workflows. -It is a powerful method for introducing compatible changes without introducing non-determinism errors. +It introduces compatible changes without causing non-determinism errors. ### Workflow cutovers diff --git a/docs/develop/php/workflows/basics.mdx b/docs/develop/php/workflows/basics.mdx index 2d9a777ffb..130936b2f4 100644 --- a/docs/develop/php/workflows/basics.mdx +++ b/docs/develop/php/workflows/basics.mdx @@ -5,11 +5,12 @@ sidebar_label: Workflow Basics description: This section explains Workflow Basics with the PHP SDK toc_max_heading_level: 4 tags: + - Workflows - PHP SDK - Temporal SDKs --- -## How to develop a basic Workflow {/* #develop-workflows */} +## Develop a basic Workflow {/* #develop-workflows */} Workflows are the fundamental unit of a Temporal Application, and it all starts with the development of a [Workflow Definition](/workflow-definition). @@ -28,7 +29,7 @@ interface FileProcessingWorkflow } ``` -### How to define Workflow parameters {/* #workflow-parameters */} +### Define Workflow parameters {/* #workflow-parameters */} Temporal Workflows may have any number of custom parameters. However, we strongly recommend that objects are used as parameters, so that the object's individual fields may be altered without breaking the signature of the Workflow. @@ -50,7 +51,7 @@ interface FileProcessingWorkflow { } ``` -### How to define Workflow return parameters {/* #workflow-return-values */} +### Define Workflow return parameters {/* #workflow-return-values */} Workflow return values must also be serializable. Returning results, returning errors, or throwing exceptions is fairly idiomatic in each language that is supported. @@ -69,7 +70,7 @@ interface FileProcessingWorkflow { } ``` -### How to customize your Workflow Type {/* #workflow-type */} +### Customize your Workflow Type {/* #workflow-type */} Workflows have a Type that are referred to as the Workflow name. @@ -127,15 +128,15 @@ class GreetingExample } ``` -### How to develop Workflow logic {/* #workflow-logic-requirements */} +### Develop Workflow logic {/* #workflow-logic-requirements */} -Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints). Each Temporal SDK provides a set of APIs that can be used inside your Workflow to interact with application code outside the Workflow. used inside your Workflow to interact with external (to the Workflow) application code. +Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints). Each Temporal SDK provides a set of APIs that can be used inside your Workflow to interact with application code outside the Workflow. -\*\*Temporal uses the [Microsoft Azure Event Sourcing pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/event-sourcing) to recover the state of a Workflow object including its local variable values. +Temporal uses the [Microsoft Azure Event Sourcing pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/event-sourcing) to recover the state of a Workflow object including its local variable values. In essence, every time a Workflow state has to be restored, its code is re-executed from the beginning. When replaying, side effects (such as Activity invocations) are ignored because they are already recorded in the Workflow event history. -When writing Workflow logic, the replay is not visible, so the code should be written since it executes only once. +The replay is not visible while the Workflow runs, so write your Workflow code as if it executes only once. This design puts the following constraints on the Workflow implementation: - Do not use any mutable global variables because multiple instances of Workflows are executed in parallel. @@ -152,7 +153,7 @@ Always do the following in the Workflow implementation code: - Don't access configuration APIs directly from a Workflow because changes in the configuration might affect a Workflow Execution path. Pass it as an argument to a Workflow function or use an Activity to load it. -Workflow method arguments and return values are serializable to a byte array using the provided [DataConverter](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/common/converter/DataConverter.html) interface. +Workflow method arguments and return values are serializable to a byte array using the provided [DataConverter](https://github.com/temporalio/sdk-php/blob/master/src/DataConverter/DataConverterInterface.php) interface. The default implementation uses JSON serializer, but you can use any alternative serialization mechanism. Make sure to annotate your `WorkflowMethod` using `ReturnType` to specify concrete return type. @@ -163,4 +164,4 @@ The values passed to Workflows through invocation parameters or returned through The entire execution history is transferred from the Temporal service to Workflow workers with every event that the Workflow logic needs to process. A large execution history can thus adversely impact the performance of your Workflow. Therefore, be mindful of the amount of data that you transfer via Activity invocation parameters or return values. -Otherwise, no additional limitations exist on Activity implementations.\*\* +Otherwise, no additional limitations exist on Activity implementations. diff --git a/docs/develop/php/workflows/cancellation.mdx b/docs/develop/php/workflows/cancellation.mdx index 60894e1350..bf00d14e53 100644 --- a/docs/develop/php/workflows/cancellation.mdx +++ b/docs/develop/php/workflows/cancellation.mdx @@ -8,9 +8,7 @@ tags: - Workflows - PHP SDK - Temporal SDKs -description: - Effectively cancel an Activity from a Workflow using Heartbeats and Heartbeat Timeouts. Discover the essential steps - for handling Activity cancellations to ensure proper Workflow management. +description: Cancel a PHP Activity from a Workflow using Heartbeats and a Heartbeat Timeout, and reset a Workflow Execution from its Event History. --- ## Cancel an Activity from a Workflow {/* #cancel-an-activity */} diff --git a/docs/develop/php/workflows/child-workflows.mdx b/docs/develop/php/workflows/child-workflows.mdx index 183ca16eb3..f86b09494f 100644 --- a/docs/develop/php/workflows/child-workflows.mdx +++ b/docs/develop/php/workflows/child-workflows.mdx @@ -9,10 +9,10 @@ tags: - Child Workflows - PHP SDK - Temporal SDKs -description: Start a Child Workflow Execution within a parent Workflow using Temporal in PHP. Configure ChildWorkflowOptions, handle Parent Close Policy, and implement asynchronous calls with promises. +description: Start a Child Workflow Execution in PHP, configure ChildWorkflowOptions, set a Parent Close Policy, and call children asynchronously with promises. --- -## How to start a Child Workflow Execution {/* #child-workflows */} +## Start a Child Workflow Execution {/* #child-workflows */} A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. @@ -76,7 +76,7 @@ $childResult = yield Workflow::executeChildWorkflow( ); ``` -#### How to set a Parent Close Policy {/* #parent-close-policy */} +#### Set a Parent Close Policy {/* #parent-close-policy */} A [Parent Close Policy](/parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). diff --git a/docs/develop/php/workflows/continue-as-new.mdx b/docs/develop/php/workflows/continue-as-new.mdx index 556824b028..b65bf1c008 100644 --- a/docs/develop/php/workflows/continue-as-new.mdx +++ b/docs/develop/php/workflows/continue-as-new.mdx @@ -13,12 +13,12 @@ tags: import { ViewSourceCodeNotice } from '@site/src/components'; -This page answers the following questions for PHP developers: +This page covers the following for PHP developers: - [What is Continue-As-New?](#what) -- [How to Continue-As-New?](#how) -- [When is it right to Continue-as-New?](#when) -- [How to test Continue-as-New?](#how-to-test) +- [Use Continue-As-New](#how) +- [When is it right to Continue-As-New?](#when) +- [Test Continue-As-New](#how-to-test) ## What is Continue-As-New? {/* #what */} @@ -28,7 +28,7 @@ You can think of it as a checkpoint when your Workflow gets too long or approach The new Workflow Execution is in the same [chain](/workflow-execution#workflow-execution-chain); it keeps the same Workflow Id but gets a new Run Id and a fresh Event History. It also receives your Workflow's usual parameters. -## How to Continue-As-New using the PHP SDK {/* #how */} +## Use Continue-As-New with the PHP SDK {/* #how */} First, design your Workflow parameters so that you can pass in the "current state" when you Continue-As-New into the next Workflow run. This state is typically set to `None` for the original caller of the Workflow. @@ -69,14 +69,14 @@ If you use Updates or Signals, don't call Continue-as-New from the handlers. Instead, wait for your handlers to finish in your main Workflow before you run `continueAsNew`. See the [`allHandlersFinished`](message-passing#wait-for-message-handlers) example for guidance. -## When is it right to Continue-as-New using the PHP SDK? {/* #when */} +## When is it right to Continue-As-New with the PHP SDK? {/* #when */} Use Continue-as-New when your Workflow might hit [Event History Limits](/workflow-execution/event#event-history). Temporal tracks your Workflow's progress against these limits to let you know when you should Continue-as-New. Call `Workflow::getInfo()->shouldContinueAsNew` to check if it's time. -## How to test Continue-as-New using the PHP SDK {/* #how-to-test */} +## Test Continue-As-New with the PHP SDK {/* #how-to-test */} Testing Workflows that naturally Continue-as-New may be time-consuming and resource-intensive. Instead, add a test hook to check your Workflow's Continue-as-New behavior faster in automated tests. diff --git a/docs/develop/php/workflows/index.mdx b/docs/develop/php/workflows/index.mdx index 5a41889007..625a2560ff 100644 --- a/docs/develop/php/workflows/index.mdx +++ b/docs/develop/php/workflows/index.mdx @@ -5,6 +5,7 @@ sidebar_label: Workflows description: This section explains how to implement Workflows with the PHP SDK toc_max_heading_level: 4 tags: + - Workflows - PHP SDK - Temporal SDKs --- diff --git a/docs/develop/php/workflows/message-passing.mdx b/docs/develop/php/workflows/message-passing.mdx index f45ffc0672..09c139b7a2 100644 --- a/docs/develop/php/workflows/message-passing.mdx +++ b/docs/develop/php/workflows/message-passing.mdx @@ -14,14 +14,14 @@ tags: description: Develop with Signals, Queries, and Updates in Temporal Workflows. Define, handle, and send Signals or Queries, and validate updates from a Temporal Client. --- -## How to develop with Signals {/* #signals */} +## Develop with Signals {/* #signals */} A [Signal](/sending-messages#sending-signals) is a message sent to a running Workflow Execution. Signals are defined in your code and handled in your Workflow Definition. Signals can be sent to Workflow Executions from a Temporal Client or from another Workflow Execution. -### How to define a Signal {/* #define-signal */} +### Define a Signal {/* #define-signal */} A Signal has a name and can have arguments. @@ -75,7 +75,7 @@ If name is not specified the short name of the Workflow interface is used. In the preceding code the `#[WorkflowMethod(name)]` is not specified, thus the Workflow Type defaults to `"FileProcessingWorkflow"`. -### How to handle a Signal {/* #handle-signal */} +### Handle a Signal {/* #handle-signal */} Workflows listen for Signals by the Signal's name. @@ -107,7 +107,7 @@ class YourWorkflow In the preceding example, the Workflow updates the protected value. The main Workflow coroutine waits for the value to change by using the `Workflow::await()` function. -### How to send a Signal from a Temporal Client {/* #send-signal-from-client */} +### Send a Signal from a Temporal Client {/* #send-signal-from-client */} When a Signal is sent successfully from the Temporal Client, the [WorkflowExecutionSignaled](/references/events#workflowexecutionsignaled) Event appears in the Event History of the Workflow that receives the Signal. @@ -136,7 +136,7 @@ $workflow->setValue(true); See [Handle Signal](#handle-signal) for details on how to handle Signals in a Workflow. -### How to send a Signal from a Workflow {/* #send-signal-from-workflow */} +### Send a Signal from a Workflow {/* #send-signal-from-workflow */} A Workflow can send a Signal to another Workflow, in which case it's called an _External Signal_. @@ -167,7 +167,7 @@ $workflow = $workflowClient->newRunningWorkflowStub(YourWorkflow::class, 'workfl $workflow->setValue(true); ``` -### How to Signal-With-Start {/* #signal-with-start */} +### Use Signal-With-Start {/* #signal-with-start */} Signal-With-Start is used from the Client. It takes a Workflow Id, Workflow arguments, a Signal name, and Signal arguments. @@ -189,11 +189,11 @@ $run = $workflowClient->startWithSignal( ); ``` -## How to develop with Queries {/* #queries */} +## Develop with Queries {/* #queries */} A [Query](/sending-messages#sending-queries) is a synchronous operation that is used to get the state of a Workflow Execution. -### How to define a Query {/* #define-query */} +### Define a Query {/* #define-query */} A Query has a name and can have arguments. @@ -247,7 +247,7 @@ If name is not specified the short name of the Workflow interface is used. In the preceding code the `#[WorkflowMethod(name)]` is not specified, thus the Workflow Type defaults to `"FileProcessingWorkflow"`. -### How to handle a Query {/* #handle-query */} +### Handle a Query {/* #handle-query */} Queries are handled by your Workflow. @@ -342,11 +342,11 @@ sleep(60); var_dump($workflow->getCurrentState()); ``` -### How to send a Query {/* #send-query */} +### Send a Query {/* #send-query */} Queries are sent from a Temporal Client. -## How to develop with Updates {/* #updates */} +## Develop with Updates {/* #updates */} An [Update](/sending-messages#sending-updates) is an operation that can mutate the state of a Workflow Execution and return a response. @@ -855,7 +855,7 @@ They are meant to handle edge cases and act as a catch-all, not as the main way ::: -### How to set a Dynamic Query {/* #set-a-dynamic-query */} +### Set a Dynamic Query {/* #set-a-dynamic-query */} A Dynamic Query in Temporal is a Query method that is invoked dynamically at runtime if no other Query with the same name is registered. Use [`Workflow::registerDynamicQuery()`](https://php.temporal.io/classes/Temporal-Workflow.html#method_registerDynamicQuery) to set a dynamic Query handler. @@ -872,7 +872,7 @@ Workflow::registerDynamicQuery(function (string $name, ValuesInterface $argument }); ``` -### How to set a Dynamic Signal {/* #set-a-dynamic-signal */} +### Set a Dynamic Signal {/* #set-a-dynamic-signal */} A Dynamic Signal in Temporal is a Signal that is invoked dynamically at runtime if no other Signal with the same input is registered. Use [`Workflow::registerDynamicSignal()`](https://php.temporal.io/classes/Temporal-Workflow.html#method_registerDynamicSignal) to set a dynamic Signal handler. @@ -889,7 +889,7 @@ Workflow::registerDynamicSignal(function (string $name, ValuesInterface $argumen }); ``` -### How to set a Dynamic Update {/* #set-a-dynamic-update */} +### Set a Dynamic Update {/* #set-a-dynamic-update */} A Dynamic Update in Temporal is an Update that is invoked dynamically at runtime if no other Update with the same input is registered. Use [`Workflow::registerDynamicUpdate()`](https://php.temporal.io/classes/Temporal-Workflow.html#method_registerDynamicUpdate) to set a dynamic Update handler. diff --git a/docs/develop/php/workflows/schedules.mdx b/docs/develop/php/workflows/schedules.mdx index c8bca7f96e..4cf885447f 100644 --- a/docs/develop/php/workflows/schedules.mdx +++ b/docs/develop/php/workflows/schedules.mdx @@ -14,13 +14,13 @@ description: Use Workflow Start Delay and Temporal Cron Jobs in PHP. Delay Workf This page shows how to do the following: -- [How to use Start Delay](#start-delay) -- [How to use Temporal Cron Jobs](#temporal-cron-jobs) +- [Use Start Delay](#start-delay) +- [Use Temporal Cron Jobs](#temporal-cron-jobs) For recurring automation, Temporal recommends [Schedules](/schedule) instead of Cron Jobs. If a Workflow Execution started by a Schedule is [Paused](/cli/command-reference/workflow#pause), it remains open and can affect future scheduled starts through the Schedule's [Overlap Policy](/schedule#overlap-policy). -## How to use Start Delay {/* #start-delay */} +## Use Start Delay {/* #start-delay */} Use the Workflow [Start Delay](/workflow-execution/timers-delays) functionality if you need to delay the execution of the Workflow without the need for regular launches. Here you simply specify the time to wait before dispatching the first Workflow task. @@ -34,7 +34,7 @@ $workflow = $workflowClient->newWorkflowStub( $workflowClient->start($workflow, 'Hello world!'); ``` -## How to use Temporal Cron Jobs {/* #temporal-cron-jobs */} +## Use Temporal Cron Jobs {/* #temporal-cron-jobs */} :::caution Cron support is not recommended diff --git a/docs/develop/php/workflows/side-effects.mdx b/docs/develop/php/workflows/side-effects.mdx index 0628acbfd9..37a27e7a3d 100644 --- a/docs/develop/php/workflows/side-effects.mdx +++ b/docs/develop/php/workflows/side-effects.mdx @@ -5,13 +5,14 @@ sidebar_label: Side effects slug: /develop/php/workflows/side-effects toc_max_heading_level: 2 tags: + - Workflows - Side-effects - PHP SDK - Temporal SDKs description: Use Side Effects in PHP to execute non-deterministic code like generating UUIDs or random numbers in a Workflow without compromising its determinism. --- -## How to use Side Effects in PHP {/* #side-effects */} +## Use Side Effects {/* #side-effects */} Side Effects are used to execute non-deterministic code, such as generating a UUID or a random number, without compromising determinism in the Workflow. This is done by storing the results of the Side Effect into the Workflow [Event History](/workflow-execution/event#event-history). diff --git a/docs/develop/php/workflows/timeouts.mdx b/docs/develop/php/workflows/timeouts.mdx index 8a54381690..515b66409c 100644 --- a/docs/develop/php/workflows/timeouts.mdx +++ b/docs/develop/php/workflows/timeouts.mdx @@ -17,9 +17,8 @@ tags: Each Workflow timeout controls the maximum duration of a different aspect of a Workflow Execution. -Before we continue, we want to note that we generally do not recommend setting Workflow Timeouts, because Workflows are designed to be long-running and resilient. -Instead, setting a Timeout can limit its ability to handle unexpected delays or long-running processes. -If you need to perform an action inside your Workflow after a specific period of time, we recommend using a Timer. +Avoid setting Workflow Timeouts. Workflows are designed to be long-running and resilient, and a Timeout limits a Workflow's ability to handle unexpected delays or long-running processes. +To perform an action inside your Workflow after a specific period of time, use a Timer instead. Workflow timeouts are set when [starting the Workflow Execution](#workflow-timeouts). @@ -48,7 +47,7 @@ $workflow = $this->workflowClient->newWorkflowStub( ); ``` -### Workflow retries {/* #workflow-retries */} +## Workflow retries {/* #workflow-retries */} A Retry Policy can work in cooperation with the timeouts to provide fine controls to optimize the execution experience. diff --git a/docs/develop/php/workflows/timers.mdx b/docs/develop/php/workflows/timers.mdx index da8d88319d..3f8faecd7b 100644 --- a/docs/develop/php/workflows/timers.mdx +++ b/docs/develop/php/workflows/timers.mdx @@ -9,7 +9,7 @@ tags: - Durable Timers - PHP SDK - Temporal SDKs -description: A Timer in a Workflow sets a durable pause for a fixed time. Even after downtimes, your Workflow resumes execution. Lightweight and scalable, millions of Timers can run on a single Worker. +description: Set a durable Timer in PHP with Workflow::timer(). Timers persist across Worker downtime, and a single Worker can run millions of them. --- ## What is a Timer? {/* #timers */} diff --git a/docs/develop/php/workflows/versioning.mdx b/docs/develop/php/workflows/versioning.mdx index 6d71fc3772..1aa8a9d904 100644 --- a/docs/develop/php/workflows/versioning.mdx +++ b/docs/develop/php/workflows/versioning.mdx @@ -143,7 +143,7 @@ After all the Workflow Executions for version 1 have left retention, you can rem ``` Patching allows you to make changes to currently running Workflows. -It is a powerful method for introducing compatible changes without introducing non-determinism errors. +It introduces compatible changes without causing non-determinism errors. ### Workflow cutovers diff --git a/docs/develop/python/workflows/basics.mdx b/docs/develop/python/workflows/basics.mdx index 9c925ebca7..464cc2d04f 100644 --- a/docs/develop/python/workflows/basics.mdx +++ b/docs/develop/python/workflows/basics.mdx @@ -5,6 +5,7 @@ sidebar_label: Workflow basics description: This section explains Workflow Basics with the Python SDK toc_max_heading_level: 4 tags: + - Workflows - Python SDK - Temporal SDKs --- diff --git a/docs/develop/python/workflows/continue-as-new.mdx b/docs/develop/python/workflows/continue-as-new.mdx index b8a25589ff..bb0591d13f 100644 --- a/docs/develop/python/workflows/continue-as-new.mdx +++ b/docs/develop/python/workflows/continue-as-new.mdx @@ -13,12 +13,12 @@ tags: import { ViewSourceCodeNotice } from '@site/src/components'; -This page answers the following questions for Python developers: +This page covers the following for Python developers: - [What is Continue-As-New?](#what) -- [How to Continue-As-New?](#how) -- [When is it right to Continue-as-New?](#when) -- [How to test Continue-as-New?](#how-to-test) +- [Use Continue-As-New](#how) +- [When is it right to Continue-As-New?](#when) +- [Test Continue-As-New](#how-to-test) ## What is Continue-As-New? {/* #what */} @@ -28,7 +28,7 @@ You can think of it as a checkpoint when your Workflow gets too long or approach The new Workflow Execution is in the same [chain](/workflow-execution#workflow-execution-chain); it keeps the same Workflow Id but gets a new Run Id and a fresh Event History. It also receives your Workflow's usual parameters. -## How to Continue-As-New using the Python SDK {/* #how */} +## Use Continue-As-New with the Python SDK {/* #how */} First, design your Workflow parameters so that you can pass in the "current state" when you Continue-As-New into the next Workflow run. This state is typically set to `None` for the original caller of the Workflow. @@ -65,14 +65,14 @@ If you use Updates or Signals, don't call Continue-as-New from the handlers. Instead, wait for your handlers to finish in your main Workflow before you run `continue_as_new`. See the [`all_handlers_finished`](message-passing#wait-for-message-handlers) example for guidance. -## When is it right to Continue-as-New using the Python SDK? {/* #when */} +## When is it right to Continue-As-New with the Python SDK? {/* #when */} Use Continue-as-New when your Workflow might encounter degraded performance or [Event History Limits](/workflow-execution/event#event-history). Temporal tracks your Workflow's progress against these limits to let you know when you should Continue-as-New. Call `workflow.info().is_continue_as_new_suggested()` to check if it's time. -## How to test Continue-as-New using the Python SDK {/* #how-to-test */} +## Test Continue-As-New with the Python SDK {/* #how-to-test */} Testing Workflows that naturally Continue-as-New may be time-consuming and resource-intensive. Instead, add a test hook to check your Workflow's Continue-as-New behavior faster in automated tests. diff --git a/docs/develop/python/workflows/index.mdx b/docs/develop/python/workflows/index.mdx index 8f92a9bdf5..f5789317af 100644 --- a/docs/develop/python/workflows/index.mdx +++ b/docs/develop/python/workflows/index.mdx @@ -5,6 +5,7 @@ sidebar_label: Workflows description: This section explains how to implement Workflows with the Python SDK toc_max_heading_level: 4 tags: + - Workflows - Python SDK - Temporal SDKs --- diff --git a/docs/develop/python/workflows/message-passing.mdx b/docs/develop/python/workflows/message-passing.mdx index 995bdcb240..0bd71c5a8c 100644 --- a/docs/develop/python/workflows/message-passing.mdx +++ b/docs/develop/python/workflows/message-passing.mdx @@ -412,7 +412,7 @@ For additional information, see [Inject work into the main Workflow](/handling-m Signal and Update handlers can be `async def` as well as `def`. Using `async def` allows you to use `await` with Activities, Child Workflows, [`asyncio.sleep`](https://docs.python.org/3/library/asyncio-task.html#asyncio.sleep) Timers, [`workflow.wait_condition`](https://python.temporal.io/temporalio.workflow.html#wait_condition) conditions, etc. This expands the possibilities for what can be done by a handler but it also means that handler executions and your main Workflow method are all running concurrently, with switching occurring between them at `await` calls. -It's essential to understand the things that could go wrong in order to use `async def` handlers safely. +To use `async def` handlers safely, understand what can go wrong. See [Workflow message passing](/encyclopedia/workflow-message-passing) for guidance on safe usage of async Signal and Update handlers, the [Safe message handlers](https://github.com/temporalio/samples-python/tree/main/message_passing/safe_message_handlers) sample, and the [Controlling handler concurrency](#control-handler-concurrency) and [Waiting for message handlers to finish](#wait-for-message-handlers) sections below. The following code executes an Activity that makes a network call to a remote service. diff --git a/docs/develop/python/workflows/timeouts.mdx b/docs/develop/python/workflows/timeouts.mdx index b9ce9b7780..095ef8fb1d 100644 --- a/docs/develop/python/workflows/timeouts.mdx +++ b/docs/develop/python/workflows/timeouts.mdx @@ -17,9 +17,8 @@ tags: Each Workflow timeout controls the maximum duration of a different aspect of a Workflow Execution. -Before we continue, we want to note that we generally do not recommend setting Workflow Timeouts, because Workflows are designed to be long-running and resilient. -Instead, setting a Timeout can limit its ability to handle unexpected delays or long-running processes. -If you need to perform an action inside your Workflow after a specific period of time, we recommend using a Timer. +Avoid setting Workflow Timeouts. Workflows are designed to be long-running and resilient, and a Timeout limits a Workflow's ability to handle unexpected delays or long-running processes. +To perform an action inside your Workflow after a specific period of time, use a Timer instead. Workflow timeouts are set when [starting the Workflow Execution](#workflow-timeouts). diff --git a/docs/develop/python/workflows/timers.mdx b/docs/develop/python/workflows/timers.mdx index 27bd3fd237..40fc913751 100644 --- a/docs/develop/python/workflows/timers.mdx +++ b/docs/develop/python/workflows/timers.mdx @@ -2,7 +2,7 @@ id: timers title: Timers - Python SDK sidebar_label: Timers -description: Set durable Timers with Temporal Workflows using sleep() or timer(), ensuring code execution resumes after downtime. Sleep for months using resource-light operations in Python. +description: Set a durable Timer in Python with asyncio.sleep(). Timers persist across Worker downtime, and a single Worker can run millions of them. slug: /develop/python/workflows/timers toc_max_heading_level: 2 tags: diff --git a/docs/develop/python/workflows/versioning.mdx b/docs/develop/python/workflows/versioning.mdx index f64a9bb1a9..1e0d68d712 100644 --- a/docs/develop/python/workflows/versioning.mdx +++ b/docs/develop/python/workflows/versioning.mdx @@ -179,7 +179,7 @@ class MyWorkflow: ``` Patching allows you to make changes to currently running Workflows. -It is a powerful method for introducing compatible changes without introducing non-determinism errors. +It introduces compatible changes without causing non-determinism errors. ### Detailed Description of the Patched Function diff --git a/docs/develop/python/workflows/worker-versioning-legacy.mdx b/docs/develop/python/workflows/worker-versioning-legacy.mdx index 1ce8a9a148..26403cb5cf 100644 --- a/docs/develop/python/workflows/worker-versioning-legacy.mdx +++ b/docs/develop/python/workflows/worker-versioning-legacy.mdx @@ -5,11 +5,13 @@ description: Learn the Python SDK's outdated Worker Versioning APIs. slug: /develop/python/workflows/worker-versioning-legacy toc_max_heading_level: 2 tags: + - Workflows - Deprecated - Python SDK + - Temporal SDKs --- -## (Deprecated) How to use Worker Versioning in Python {/* #worker-versioning */} +## (Deprecated) Use Worker Versioning in Python {/* #worker-versioning */} :::caution diff --git a/docs/develop/ruby/workflows/basics.mdx b/docs/develop/ruby/workflows/basics.mdx index fc864ee9fd..5f38a874e8 100644 --- a/docs/develop/ruby/workflows/basics.mdx +++ b/docs/develop/ruby/workflows/basics.mdx @@ -5,6 +5,7 @@ sidebar_label: Workflow basics description: This section explains Workflow basics with the Ruby SDK toc_max_heading_level: 4 tags: + - Workflows - Ruby SDK - Temporal SDKs --- diff --git a/docs/develop/ruby/workflows/cancellation.mdx b/docs/develop/ruby/workflows/cancellation.mdx index 7301d9191c..480052a59d 100644 --- a/docs/develop/ruby/workflows/cancellation.mdx +++ b/docs/develop/ruby/workflows/cancellation.mdx @@ -2,9 +2,7 @@ id: cancellation title: Cancellation - Ruby SDK sidebar_label: Cancellation -description: - Interrupt Workflow Execution in Ruby using the Temporal SDK. Cancel for graceful stops; terminate for forceful stops. - Handle Cancellation in Workflow and Activities efficiently. +description: Handle Cancellation in Ruby Workflows and Activities, request Cancellation from a Client, and choose between Cancellation, termination, and reset. toc_max_heading_level: 4 tags: - Workflows diff --git a/docs/develop/ruby/workflows/continue-as-new.mdx b/docs/develop/ruby/workflows/continue-as-new.mdx index 4d6d5d6163..26dff7ddc0 100644 --- a/docs/develop/ruby/workflows/continue-as-new.mdx +++ b/docs/develop/ruby/workflows/continue-as-new.mdx @@ -2,7 +2,7 @@ id: continue-as-new title: Continue-As-New - Ruby SDK sidebar_label: Continue-As-New -description: Use Continue-As-New with the Temporal Ruby SDK to manage Workflow Event Histories, ensuring optimal performance by starting new Executions seamlessly. +description: Use Continue-As-New in Ruby to close a Workflow Execution and start a new one with the same Workflow Id and a fresh Event History. tags: - Workflows - Ruby SDK diff --git a/docs/develop/ruby/workflows/dynamic-workflow.mdx b/docs/develop/ruby/workflows/dynamic-workflow.mdx index 341fc13227..9bcf55b2de 100644 --- a/docs/develop/ruby/workflows/dynamic-workflow.mdx +++ b/docs/develop/ruby/workflows/dynamic-workflow.mdx @@ -5,6 +5,7 @@ sidebar_label: Dynamic Workflow description: This section explains Dynamic Workflows with the Ruby SDK toc_max_heading_level: 4 tags: + - Workflows - Ruby SDK - Temporal SDKs --- diff --git a/docs/develop/ruby/workflows/futures.mdx b/docs/develop/ruby/workflows/futures.mdx index 764b3c8619..dbece36f82 100644 --- a/docs/develop/ruby/workflows/futures.mdx +++ b/docs/develop/ruby/workflows/futures.mdx @@ -5,6 +5,7 @@ sidebar_label: Workflow futures description: This section explains Workflow futures with the Ruby SDK toc_max_heading_level: 4 tags: + - Workflows - Ruby SDK - Temporal SDKs --- diff --git a/docs/develop/ruby/workflows/index.mdx b/docs/develop/ruby/workflows/index.mdx index 454cdc7bdb..083490c3a9 100644 --- a/docs/develop/ruby/workflows/index.mdx +++ b/docs/develop/ruby/workflows/index.mdx @@ -5,6 +5,7 @@ sidebar_label: Workflows description: This section explains how to implement Workflows with the Ruby SDK toc_max_heading_level: 4 tags: + - Workflows - Ruby SDK - Temporal SDKs --- diff --git a/docs/develop/ruby/workflows/message-passing.mdx b/docs/develop/ruby/workflows/message-passing.mdx index 2db32d41fa..45c3c6119c 100644 --- a/docs/develop/ruby/workflows/message-passing.mdx +++ b/docs/develop/ruby/workflows/message-passing.mdx @@ -5,6 +5,7 @@ sidebar_label: Message passing description: Develop with Queries, Signals, and Updates using the Temporal Ruby SDK. toc_max_heading_level: 3 tags: + - Workflows - Ruby SDK - Temporal SDKs --- @@ -362,7 +363,7 @@ Signal and Update handlers can be asynchronous as well as blocking. Using asynchronous calls allows you to wait for Activities, Child Workflows, Durable Timers, wait conditions, etc. This expands the possibilities for what can be done by a handler but it also means that handler executions and your main Workflow method are all running concurrently, with switching occurring between them at await calls. -It's essential to understand the things that could go wrong in order to use asynchronous handlers safely. +To use asynchronous handlers safely, understand what can go wrong. See [Workflow message passing](/encyclopedia/workflow-message-passing) for guidance on safe usage of async Signal and Update handlers, and the [Controlling handler concurrency](#control-handler-concurrency) and [Waiting for message handlers to finish](#wait-for-message-handlers) sections below. The following code is an Activity that simulates a network call to a remote service: diff --git a/docs/develop/ruby/workflows/timeouts.mdx b/docs/develop/ruby/workflows/timeouts.mdx index d0d270c50d..098f2d13c8 100644 --- a/docs/develop/ruby/workflows/timeouts.mdx +++ b/docs/develop/ruby/workflows/timeouts.mdx @@ -31,7 +31,7 @@ result = my_client.execute_workflow( ) ``` -### Workflow retries {/* #workflow-retries */} +## Workflow retries {/* #workflow-retries */} A Retry Policy can work in cooperation with the timeouts to provide fine controls to optimize the execution experience. diff --git a/docs/develop/ruby/workflows/versioning.mdx b/docs/develop/ruby/workflows/versioning.mdx index 2c8b73be4f..5580749ef5 100644 --- a/docs/develop/ruby/workflows/versioning.mdx +++ b/docs/develop/ruby/workflows/versioning.mdx @@ -129,7 +129,7 @@ end Once the pre-patch Workflows have left retention, you can then safely deploy Workers that no longer use either the `patched()` or `deprecate_patch()` calls: Patching allows you to make changes to currently running Workflows. -It is a powerful method for introducing compatible changes without introducing non-determinism errors. +It introduces compatible changes without causing non-determinism errors. ### Workflow cutovers diff --git a/docs/develop/rust/workflows/basics.mdx b/docs/develop/rust/workflows/basics.mdx index be56149cb6..1a6b9f113d 100644 --- a/docs/develop/rust/workflows/basics.mdx +++ b/docs/develop/rust/workflows/basics.mdx @@ -5,11 +5,12 @@ sidebar_label: Workflow basics description: This section explains how to implement Workflows with the Rust SDK toc_max_heading_level: 4 tags: + - Workflows - Rust SDK - Temporal SDKs --- -## How to develop a Workflow {/* #develop-workflows */} +## Develop a Workflow {/* #develop-workflows */} Workflows are the fundamental unit of a Temporal Application and it all starts with the development of a [Workflow Definition](/workflow-definition). diff --git a/docs/develop/rust/workflows/continue-as-new.mdx b/docs/develop/rust/workflows/continue-as-new.mdx index 79c9c4cd03..c6f07eec11 100644 --- a/docs/develop/rust/workflows/continue-as-new.mdx +++ b/docs/develop/rust/workflows/continue-as-new.mdx @@ -11,11 +11,11 @@ tags: - Temporal SDKs --- -This page answers the following questions for Rust developers: +This page covers the following for Rust developers: - [What is Continue-As-New?](#what) -- [How to Continue-As-New?](#how) -- [When is it right to Continue-as-New?](#when) +- [Use Continue-As-New](#how) +- [When is it right to Continue-As-New?](#when) ## What is Continue-As-New? {/* #what */} @@ -24,7 +24,7 @@ This page answers the following questions for Rust developers: The new Workflow execution is in the same [chain](/workflow-execution#workflow-execution-chain); it keeps the same Workflow Id but gets a new Run Id and a fresh Event History. It also receives your Workflow's usual parameters. -## How to Continue-As-New using the Rust SDK {/* #how */} +## Use Continue-As-New with the Rust SDK {/* #how */} First, design your Workflow parameters so that you can pass in the "current state" when you Continue-As-New into the next Workflow run. This state is typically passed as a parameter or stored in the Workflow struct. @@ -68,13 +68,13 @@ impl GreetingWorkflow { The `ctx.continue_as_new()` method accepts the input to pass to the next Workflow Run. -## When is it right to Continue-as-New using the Rust SDK? {/* #when */} +## When is it right to Continue-As-New with the Rust SDK? {/* #when */} Use Continue-as-New when your Workflow might encounter degraded performance or [Event History Limits](/workflow-execution/event#event-history). Temporal tracks your Workflow's progress against these limits to let you know when you should Continue-as-New. Call `ctx.continue_as_new_suggested()` to check if it's time. -## How to test Continue-as-New using the Rust SDK +## Test Continue-As-New with the Rust SDK {/* #how-to-test */} Testing Workflows that naturally Continue-as-New may be time-consuming and resource-intensive. Instead, add a test hook to check your Workflow's Continue-as-New behavior faster in automated tests. diff --git a/docs/develop/rust/workflows/index.mdx b/docs/develop/rust/workflows/index.mdx index ccb3988f83..8e38f2f12f 100644 --- a/docs/develop/rust/workflows/index.mdx +++ b/docs/develop/rust/workflows/index.mdx @@ -6,6 +6,7 @@ description: This section explains how to implement Workflows with the Rust SDK toc_max_heading_level: 4 tags: + - Workflows - Rust SDK - Temporal SDKs --- diff --git a/docs/develop/rust/workflows/message-passing.mdx b/docs/develop/rust/workflows/message-passing.mdx index 35dae7c6b2..0f72857e4e 100644 --- a/docs/develop/rust/workflows/message-passing.mdx +++ b/docs/develop/rust/workflows/message-passing.mdx @@ -340,7 +340,7 @@ let update_handle = main_wf_handle.start_update( Signal and Update handlers can be `async fn` as well as `fn`. Using `async fn` allows you to use await with Activities, Child Workflows, Timers, etc. This expands the possibilities for what can be done by a handler, but it also means that handler executions and your main Workflow method are all running concurrently, with switching occurring between them at await calls. -It's essential to understand the things that could go wrong in order to use `async fn` handlers safely. See [Workflow message passing](/encyclopedia/workflow-message-passing) for guidance on safe usage of async Signal and Update handlers, the Safe message handlers sample and the sections below. +To use `async fn` handlers safely, understand what can go wrong. See [Workflow message passing](/encyclopedia/workflow-message-passing) for guidance on safe usage of async Signal and Update handlers, the Safe message handlers sample and the sections below. The following code executes an Activity that makes a network call to a remote service: diff --git a/docs/develop/typescript/client/temporal-client.mdx b/docs/develop/typescript/client/temporal-client.mdx index 142f03a6fd..a9708a33eb 100644 --- a/docs/develop/typescript/client/temporal-client.mdx +++ b/docs/develop/typescript/client/temporal-client.mdx @@ -1,6 +1,6 @@ --- id: temporal-client -title: Temporal Client - Typescript SDK +title: Temporal Client - TypeScript SDK sidebar_label: Temporal Client toc_max_heading_level: 4 description: @@ -639,7 +639,7 @@ Service endpoint, TLS settings, and authentication credentials. When instantiati ## Start Workflow Execution {/* #start-workflow-execution */} -**How to start a Workflow Execution using the Typescript SDK** +**How to start a Workflow Execution using the TypeScript SDK** [Workflow Execution](/workflow-execution) semantics rely on several parameters—that is, to start a Workflow Execution you must supply a Task Queue that will be used for the Tasks (one that a Worker is polling), the Workflow Type, diff --git a/docs/develop/typescript/set-up.mdx b/docs/develop/typescript/set-up.mdx index 57d7e2c51d..408836045b 100644 --- a/docs/develop/typescript/set-up.mdx +++ b/docs/develop/typescript/set-up.mdx @@ -1,6 +1,6 @@ --- id: set-up-your-local-typescript -title: Set up your local with the Typescript SDK +title: Set up your local with the TypeScript SDK sidebar_label: Quickstart description: Configure your local development environment to get started developing with Temporal tags: diff --git a/docs/develop/typescript/worker-versioning-legacy.mdx b/docs/develop/typescript/worker-versioning-legacy.mdx index ac91a9e4d1..6753c379de 100644 --- a/docs/develop/typescript/worker-versioning-legacy.mdx +++ b/docs/develop/typescript/worker-versioning-legacy.mdx @@ -1,7 +1,7 @@ --- id: worker-versioning-legacy -title: Worker Versioning (Legacy) - Typescript SDK -description: Learn the Typescript SDK's outdated Worker Versioning APIs. +title: Worker Versioning (Legacy) - TypeScript SDK +description: Learn the TypeScript SDK's outdated Worker Versioning APIs. slug: /develop/typescript/worker-versioning-legacy toc_max_heading_level: 2 tags: @@ -20,7 +20,7 @@ See the [Pre-release README](https://github.com/temporalio/temporal/blob/main/do ::: A Build ID corresponds to a deployment. If you don't already have one, we recommend a hash of the code--such as a Git SHA--combined with a human-readable timestamp. -To use Worker Versioning, you need to pass a Build ID to your Typescript Worker and opt in to Worker Versioning. +To use Worker Versioning, you need to pass a Build ID to your TypeScript Worker and opt in to Worker Versioning. ### Assign a Build ID to your Worker and opt in to Worker Versioning diff --git a/docs/develop/typescript/workflows/basics.mdx b/docs/develop/typescript/workflows/basics.mdx index e9ba5ec5f6..ec3edfb38a 100644 --- a/docs/develop/typescript/workflows/basics.mdx +++ b/docs/develop/typescript/workflows/basics.mdx @@ -8,10 +8,10 @@ toc_max_heading_level: 3 tags: - TypeScript SDK - Temporal SDKs - - Workflow + - Workflows --- -## How to develop a Workflow {/* #develop-workflows */} +## Develop a Workflow {/* #develop-workflows */} Workflows are the fundamental unit of a Temporal Application, and it all starts with the development of a [Workflow Definition](/workflow-definition). @@ -30,7 +30,7 @@ export async function example(args: ExampleArgs): Promise<{ greeting: string }> } ``` -## How to define Workflow parameters {/* #workflow-parameters */} +## Define Workflow parameters {/* #workflow-parameters */} Temporal Workflows may have any number of custom parameters. However, we strongly recommend that objects are used as parameters, so that the object's individual fields may be altered without breaking the signature of the Workflow. All @@ -71,7 +71,7 @@ export async function example({ name, born }: ExampleParam): Promise { } ``` -## How to define Workflow return parameters {/* #workflow-return-values */} +## Define Workflow return parameters {/* #workflow-return-values */} Workflow return values must also be serializable. Returning results, returning errors, or throwing exceptions is fairly idiomatic in each language that is supported. However, Temporal APIs that must be used to get the result of a Workflow @@ -92,7 +92,7 @@ export async function example({ name, born }: ExampleParam): Promise { } ``` -## How to customize your Workflow Type {/* #workflow-type */} +## Customize your Workflow Type {/* #workflow-type */} Workflows have a Type that are referred to as the Workflow name. @@ -112,7 +112,7 @@ export async function helloWorld(): Promise { ``` -## How to develop Workflow logic {/* #workflow-logic-requirements */} +## Develop Workflow logic {/* #workflow-logic-requirements */} Workflow logic is constrained by [deterministic execution requirements](/workflow-definition#deterministic-constraints). Each Temporal SDK provides a diff --git a/docs/develop/typescript/workflows/cancellation-scopes.mdx b/docs/develop/typescript/workflows/cancellation-scopes.mdx index 6181faab6d..96447904dc 100644 --- a/docs/develop/typescript/workflows/cancellation-scopes.mdx +++ b/docs/develop/typescript/workflows/cancellation-scopes.mdx @@ -1,17 +1,17 @@ --- id: cancellation-scopes title: Cancellation scopes - TypeScript SDK -description: Shows cancellation scopes with the TypeScript SDK +description: Control cancellation in TypeScript Workflows with the CancellationScope tree, including nonCancellable, withTimeout, nesting, and shared promises. sidebar_label: Cancellation scopes slug: /develop/typescript/workflows/cancellation-scopes toc_max_heading_level: 3 tags: - TypeScript SDK - Temporal SDKs - - Workflow + - Workflows --- -## Cancellation scopes in Typescript {/* #cancellation-scopes */} +## Cancellation scopes in TypeScript {/* #cancellation-scopes */} In the TypeScript SDK, Workflows are represented internally by a tree of cancellation scopes, each with cancellation behaviors you can specify. By default, everything runs in the "root" scope. diff --git a/docs/develop/typescript/workflows/cancellation.mdx b/docs/develop/typescript/workflows/cancellation.mdx index 244c72069c..f2da91b6a6 100644 --- a/docs/develop/typescript/workflows/cancellation.mdx +++ b/docs/develop/typescript/workflows/cancellation.mdx @@ -7,9 +7,7 @@ tags: - Workflows - TypeScript SDK - Temporal SDKs -description: - Explore the power of Cancellation Scopes in TypeScript to manage nested, non-cancellable, and timeout-based operations - within Temporal Workflows with ease. +description: Cancel a TypeScript Activity from a Workflow using Heartbeats and a Heartbeat Timeout, and reset a Workflow Execution from its Event History. --- ## Cancel an Activity from a Workflow {/* #cancel-an-activity */} diff --git a/docs/develop/typescript/workflows/child-workflows.mdx b/docs/develop/typescript/workflows/child-workflows.mdx index a1bf475dee..44a05eacc3 100644 --- a/docs/develop/typescript/workflows/child-workflows.mdx +++ b/docs/develop/typescript/workflows/child-workflows.mdx @@ -12,7 +12,7 @@ tags: description: Start and manage Child Workflow Executions using Temporal's Child Workflow API, including setting Parent Close Policy, handling Events, and advanced Child Workflow options. --- -## How to start a Child Workflow Execution {/* #child-workflows */} +## Start a Child Workflow Execution {/* #child-workflows */} A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. @@ -89,7 +89,7 @@ Two advanced options are unique to Child Workflows: If you need to cancel a Child Workflow Execution, use [cancellation scopes](/develop/typescript/workflows/cancellation-scopes). A Child Workflow Execution is automatically cancelled when its containing scope is cancelled. -### How to set a Parent Close Policy {/* #parent-close-policy */} +### Set a Parent Close Policy {/* #parent-close-policy */} A [Parent Close Policy](/parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). diff --git a/docs/develop/typescript/workflows/continue-as-new.mdx b/docs/develop/typescript/workflows/continue-as-new.mdx index 948f8fe935..8e1de43508 100644 --- a/docs/develop/typescript/workflows/continue-as-new.mdx +++ b/docs/develop/typescript/workflows/continue-as-new.mdx @@ -1,8 +1,8 @@ --- id: continue-as-new -title: Continue-As-New - Typescript SDK +title: Continue-As-New - TypeScript SDK sidebar_label: Continue-As-New -description: Use Temporal's Continue-As-New in Typescript to manage large Event Histories by atomically creating new Workflow Executions with the same Workflow Id and fresh parameters. +description: Use Temporal's Continue-As-New in TypeScript to manage large Event Histories by atomically creating new Workflow Executions with the same Workflow Id and fresh parameters. toc_max_heading_level: 2 tags: - Workflows @@ -13,12 +13,12 @@ tags: import { ViewSourceCodeNotice } from '@site/src/components'; -This page answers the following questions for Typescript developers: +This page covers the following for TypeScript developers: - [What is Continue-As-New?](#what) -- [How to Continue-As-New?](#how) -- [When is it right to Continue-as-New?](#when) -- [How to test Continue-as-New?](#how-to-test) +- [Use Continue-As-New](#how) +- [When is it right to Continue-As-New?](#when) +- [Test Continue-As-New](#how-to-test) ## What is Continue-As-New? {/* #what */} @@ -28,7 +28,7 @@ You can think of it as a checkpoint when your Workflow gets too long or approach The new Workflow Execution is in the same [chain](/workflow-execution#workflow-execution-chain); it keeps the same Workflow Id but gets a new Run Id and a fresh Event History. It also receives your Workflow's usual parameters. -## How to Continue-As-New using the Typescript SDK {/* #how */} +## Use Continue-As-New with the TypeScript SDK {/* #how */} First, design your Workflow parameters so that you can pass in the "current state" when you Continue-As-New into the next Workflow run. This state is typically set to `None` for the original caller of the Workflow. @@ -61,14 +61,14 @@ If you use Updates or Signals, don't call Continue-as-New from the handlers. Instead, wait for your handlers to finish in your main Workflow before you run `ContinueAsNew`. See the [`allHandlersFinished`](message-passing#wait-for-message-handlers) example for guidance. -## When is it right to Continue-as-New using the Typescript SDK? {/* #when */} +## When is it right to Continue-As-New with the TypeScript SDK? {/* #when */} Use Continue-as-New when your Workflow might hit [Event History Limits](/workflow-execution/event#event-history). Temporal tracks your Workflow's progress against these limits to let you know when you should Continue-as-New. Call `wf.workflowInfo().continueAsNewSuggested` to check if it's time. -## How to test Continue-as-New using the Typescript SDK {/* #how-to-test */} +## Test Continue-As-New with the TypeScript SDK {/* #how-to-test */} Testing Workflows that naturally Continue-as-New may be time-consuming and resource-intensive. Instead, add a test hook to check your Workflow's Continue-as-New behavior faster in automated tests. diff --git a/docs/develop/typescript/workflows/index.mdx b/docs/develop/typescript/workflows/index.mdx index 91044ad4c9..d77049cb83 100644 --- a/docs/develop/typescript/workflows/index.mdx +++ b/docs/develop/typescript/workflows/index.mdx @@ -5,6 +5,7 @@ sidebar_label: Workflows description: This section explains how to implement Workflows with the TypeScript SDK toc_max_heading_level: 4 tags: + - Workflows - TypeScript SDK - Temporal SDKs --- diff --git a/docs/develop/typescript/workflows/message-passing.mdx b/docs/develop/typescript/workflows/message-passing.mdx index ea2f5f00a6..5543e42b9c 100644 --- a/docs/develop/typescript/workflows/message-passing.mdx +++ b/docs/develop/typescript/workflows/message-passing.mdx @@ -2,7 +2,7 @@ id: message-passing title: Workflow message passing - TypeScript SDK sidebar_label: Message passing -description: Develop with Queries, Signals, and Updates with the Temporal Typescript SDK. +description: Develop with Queries, Signals, and Updates with the Temporal TypeScript SDK. toc_max_heading_level: 3 tags: - Workflows @@ -18,7 +18,7 @@ A Workflow can act like a stateful web service that receives messages: Queries, The Workflow implementation defines these endpoints via handler methods that can react to incoming messages and return values. Temporal Clients use messages to read Workflow state and control its execution. See [Workflow message passing](/encyclopedia/workflow-message-passing) for a general overview of this topic. -This page introduces these features for the Temporal Typescript SDK. +This page introduces these features for the Temporal TypeScript SDK. ## Write message handlers {/* #writing-message-handlers */} @@ -391,7 +391,7 @@ const finalReport = await wfHandle.result(); :::info SEND MESSAGES WITHOUT TYPE SAFETY In real-world development, sometimes you may be unable to import message type objects defined by `defineQuery`, `defineSignal`, or `defineUpdate`. -When you don't have access to the Workflow Definition or it isn't written in Typescript, you can still use APIs that aren't type-safe, and dynamic method invocation. +When you don't have access to the Workflow Definition or it isn't written in TypeScript, you can still use APIs that aren't type-safe, and dynamic method invocation. Pass message type names instead of message type objects to: - [`client.workflow.start`](https://typescript.temporal.io/api/classes/client.WorkflowClient#start) @@ -423,7 +423,7 @@ For additional information, see [Inject work into the main Workflow](/handling-m Signal and Update handlers can be `async` functions. Using `async` allows you to use `await` with Activities, Child Workflows, durable [`workflow.sleep`](https://typescript.temporal.io/api/namespaces/workflow#sleep) Timers, [`workflow.condition`](https://typescript.temporal.io/api/namespaces/workflow#condition) conditions, etc. This expands the possibilities for what can be done by a handler but it also means that handler executions and your main Workflow method are all running concurrently, with switching occurring between them at `await` calls. -It's essential to understand the things that could go wrong in order to use `async` handlers safely. +To use `async` handlers safely, understand what can go wrong. See [Workflow message passing](/encyclopedia/workflow-message-passing) for guidance on safe usage of async Signal and Update handlers, the [Safe message handlers](https://github.com/temporalio/samples-typescript/blob/main/message-passing/safe-message-handlers/README.md) sample, and the [Controlling handler concurrency](#control-handler-concurrency) and [Waiting for message handlers to finish](#wait-for-message-handlers) sections below. The following code executes an Activity that makes a network call to a remote service. diff --git a/docs/develop/typescript/workflows/schedules.mdx b/docs/develop/typescript/workflows/schedules.mdx index ffe463bc73..4e55b2b715 100644 --- a/docs/develop/typescript/workflows/schedules.mdx +++ b/docs/develop/typescript/workflows/schedules.mdx @@ -9,7 +9,7 @@ tags: - Schedules - TypeScript SDK - Temporal SDKs -description: Schedule automated tasks effortlessly with Temporal. Create, backfill, delete, describe, list, pause, trigger, and update Schedules. Control your Workflow execution with Temporal Cron Jobs and ensure timely, automated business processes. Automate repetitive tasks and reduce manual intervention now! +description: Create, backfill, pause, trigger, and update Schedules with the TypeScript SDK, plus Temporal Cron Jobs and Start Delay. --- This page shows how to do the following: @@ -26,7 +26,7 @@ This page shows how to do the following: - [Temporal Cron Jobs](#temporal-cron-jobs) - [Start Delay](#start-delay) -## How to Schedule a Workflow {/* #schedule-a-workflow */} +## Schedule a Workflow {/* #schedule-a-workflow */} Scheduling Workflows is a crucial aspect of any automation process, especially when dealing with time-sensitive tasks. By scheduling a Workflow, you can automate repetitive tasks, reduce the need for manual intervention, and ensure timely execution of your business processes. diff --git a/docs/develop/typescript/workflows/timeouts.mdx b/docs/develop/typescript/workflows/timeouts.mdx index 986cc3ece7..d3b13e96e7 100644 --- a/docs/develop/typescript/workflows/timeouts.mdx +++ b/docs/develop/typescript/workflows/timeouts.mdx @@ -15,19 +15,19 @@ tags: This page shows how to do the following: -- [Raise and Handle Exceptions](#exception-handling) -- [Deliberately Fail Workflows](#workflow-failure) -- [Workflow Timeouts](#workflow-timeouts) +- [Raise and handle exceptions](#exception-handling) +- [Fail Workflows deliberately](#workflow-failure) +- [Workflow timeouts](#workflow-timeouts) - [Workflow retries](#workflow-retries) -## Raise and Handle Exceptions {/* #exception-handling */} +## Raise and handle exceptions {/* #exception-handling */} In each Temporal SDK, error handling is implemented idiomatically, following the conventions of the language. -Temporal uses several different error classes internally — for example, [`CancelledFailure`](https://typescript.temporal.io/api/classes/common.CancelledFailure) in the Typescript SDK, to handle a Workflow cancellation. +Temporal uses several different error classes internally — for example, [`CancelledFailure`](https://typescript.temporal.io/api/classes/common.CancelledFailure) in the TypeScript SDK, to handle a Workflow cancellation. You should not raise or otherwise implement these manually, as they are tied to Temporal platform logic. The one Temporal error class that you will typically raise deliberately is [`ApplicationFailure`](https://typescript.temporal.io/api/classes/common.ApplicationFailure). -In fact, *any* other exceptions that are raised from your Typescript code in a Temporal Activity will be converted to an `ApplicationError` internally. +In fact, *any* other exceptions that are raised from your TypeScript code in a Temporal Activity will be converted to an `ApplicationFailure` internally. This way, an error's type, severity, and any additional details can be sent to the Temporal Service, indexed by the Web UI, and even serialized across language boundaries. In other words, these two code samples do the same thing: @@ -37,7 +37,7 @@ class InvalidChargeError extends Error { constructor(message: string) { super(message); this.name = "InvalidChargeError"; - Object.setPrototypeOf(this, CustomError.prototype); + Object.setPrototypeOf(this, InvalidChargeError.prototype); } } @@ -56,7 +56,7 @@ if (chargeAmount < 0) { ``` Depending on your implementation, you may decide to use either method. -One reason to use the Temporal `ApplicationFailure` class is because it allows you to set an additional `non_retryable` parameter. +One reason to use the Temporal `ApplicationFailure` class is because it allows you to set an additional `nonRetryable` parameter. This way, you can decide whether an error should not be retried automatically by Temporal. This can be useful for deliberately failing a Workflow due to bad input data, rather than waiting for a timeout to elapse: @@ -71,7 +71,7 @@ if (chargeAmount < 0) { You can alternately specify a list of errors that are non-retryable in your Activity [Retry Policy](/develop/typescript/activities/timeouts#activity-retries). -## Failing Workflows {/* #workflow-failure */} +## Fail Workflows deliberately {/* #workflow-failure */} One of the core design principles of Temporal is that an Activity Failure will never directly cause a Workflow Failure — a Workflow should never return as Failed unless deliberately. The default retry policy associated with Temporal Activities is to retry them until reaching a certain timeout threshold. @@ -94,20 +94,19 @@ try { ``` This works differently in a Workflow than raising exceptions from Activities. -In an Activity, any Typescript exceptions or custom exceptions are converted to a Temporal `ApplicationFailure`. +In an Activity, any TypeScript exceptions or custom exceptions are converted to a Temporal `ApplicationFailure`. In a Workflow, any exceptions that are raised other than an explicit Temporal `ApplicationFailure` will only fail that particular [Workflow Task](/tasks#workflow-task-execution) and be retried. -This includes any typical Typescript runtime errors like an `undefined` error that are raised automatically. +This includes any typical TypeScript runtime errors like an `undefined` error that are raised automatically. These errors are treated as bugs that can be corrected with a fixed deployment, rather than a reason for a Temporal Workflow Execution to return unexpectedly. -## Workflow Timeouts {/* #workflow-timeouts */} +## Workflow timeouts {/* #workflow-timeouts */} **How to set Workflow Timeouts using the Temporal TypeScript SDK** Each Workflow timeout controls the maximum duration of a different aspect of a Workflow Execution. -Before we continue, we want to note that we generally do not recommend setting Workflow Timeouts, because Workflows are designed to be long-running and resilient. -Instead, setting a Timeout can limit its ability to handle unexpected delays or long-running processes. -If you need to perform an action inside your Workflow after a specific period of time, we recommend using a Timer. +Avoid setting Workflow Timeouts. Workflows are designed to be long-running and resilient, and a Timeout limits a Workflow's ability to handle unexpected delays or long-running processes. +To perform an action inside your Workflow after a specific period of time, use a Timer instead. Workflow Timeouts are set when starting a Workflow using either the Client or Workflow API. diff --git a/docs/develop/typescript/workflows/versioning.mdx b/docs/develop/typescript/workflows/versioning.mdx index e0869163ef..c378df8bdd 100644 --- a/docs/develop/typescript/workflows/versioning.mdx +++ b/docs/develop/typescript/workflows/versioning.mdx @@ -128,7 +128,7 @@ export async function myWorkflow(): Promise { Once your pre-patch Workflows have left retention, you can then safely deploy Workers that no longer use either the `patched()` or `deprecatePatch()` calls: Patching allows you to make changes to currently running Workflows. -It is a powerful method for introducing compatible changes without introducing non-determinism errors. +It introduces compatible changes without causing non-determinism errors. ### Workflow cutovers diff --git a/docs/encyclopedia/event-history/event-history.mdx b/docs/encyclopedia/event-history/event-history.mdx index f40a3555cd..7dcc96752f 100644 --- a/docs/encyclopedia/event-history/event-history.mdx +++ b/docs/encyclopedia/event-history/event-history.mdx @@ -21,5 +21,5 @@ For a deep dive on how the Event History works, refer to the walkthroughs in the - [Go](/encyclopedia/event-history/event-history-go) - [Java](/encyclopedia/event-history/event-history-java) - [Python](/encyclopedia/event-history/event-history-python) -- [Typescript](/encyclopedia/event-history/event-history-typescript) +- [TypeScript](/encyclopedia/event-history/event-history-typescript) - [.NET](/encyclopedia/event-history/event-history-dotnet) diff --git a/docs/encyclopedia/workers/task-queue-naming.mdx b/docs/encyclopedia/workers/task-queue-naming.mdx index b49a034db2..e17e27d9ba 100644 --- a/docs/encyclopedia/workers/task-queue-naming.mdx +++ b/docs/encyclopedia/workers/task-queue-naming.mdx @@ -86,7 +86,7 @@ Worker worker = factory.newWorker("my-task-queue-name"); ``` - + **Excerpt of code used to start the Workflow in TypeScript** @@ -249,7 +249,7 @@ Worker worker = factory.newWorker(Constants.taskQueueName); ``` - + **Excerpt of code used to define a constant with the Task Queue name in TypeScript** diff --git a/docs/encyclopedia/workflow/workflow-definition.mdx b/docs/encyclopedia/workflow/workflow-definition.mdx index cf5f63f690..620a1ce743 100644 --- a/docs/encyclopedia/workflow/workflow-definition.mdx +++ b/docs/encyclopedia/workflow/workflow-definition.mdx @@ -109,11 +109,11 @@ class YourWorkflow: ``` - + -**[Workflow Definition in Typescript](/develop/typescript/workflows/basics)** +**[Workflow Definition in TypeScript](/develop/typescript/workflows/basics)** -```Typescript +```typescript type BasicWorkflowArgs = { param: string; }; From b69ce5ab14bdfbc1fc69a5eef0816cbe44c73291 Mon Sep 17 00:00:00 2001 From: Jwahir Sundai Date: Thu, 10 Sep 2026 10:57:06 -0500 Subject: [PATCH 2/2] revert timeouts paragraph --- docs/develop/go/workflows/timeouts.mdx | 5 +++-- docs/develop/java/workflows/timeouts.mdx | 5 +++-- docs/develop/php/workflows/timeouts.mdx | 5 +++-- docs/develop/python/workflows/timeouts.mdx | 5 +++-- docs/develop/typescript/workflows/timeouts.mdx | 5 +++-- 5 files changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/develop/go/workflows/timeouts.mdx b/docs/develop/go/workflows/timeouts.mdx index 59b07632da..470f503c52 100644 --- a/docs/develop/go/workflows/timeouts.mdx +++ b/docs/develop/go/workflows/timeouts.mdx @@ -19,8 +19,9 @@ Each Workflow timeout controls the maximum duration of a different aspect of a W Workflow timeouts are set when [starting the Workflow Execution](#workflow-timeouts). -Avoid setting Workflow Timeouts. Workflows are designed to be long-running and resilient, and a Timeout limits a Workflow's ability to handle unexpected delays or long-running processes. -To perform an action inside your Workflow after a specific period of time, use a Timer instead. +Before we continue, we want to note that we generally do not recommend setting Workflow Timeouts, because Workflows are designed to be long-running and resilient. +Instead, setting a Timeout can limit its ability to handle unexpected delays or long-running processes. +If you need to perform an action inside your Workflow after a specific period of time, we recommend using a Timer. - **[Workflow Execution Timeout](/encyclopedia/detecting-workflow-failures#workflow-execution-timeout)** - restricts the maximum amount of time that a single Workflow Execution can be executed. - **[Workflow Run Timeout](/encyclopedia/detecting-workflow-failures#workflow-run-timeout):** restricts the maximum amount of time that a single Workflow Run can last. diff --git a/docs/develop/java/workflows/timeouts.mdx b/docs/develop/java/workflows/timeouts.mdx index 426d094f1c..4e6427f253 100644 --- a/docs/develop/java/workflows/timeouts.mdx +++ b/docs/develop/java/workflows/timeouts.mdx @@ -19,8 +19,9 @@ Each Workflow timeout controls the maximum duration of a different aspect of a W Workflow timeouts are set when [starting the Workflow Execution](#workflow-timeouts). -Avoid setting Workflow Timeouts. Workflows are designed to be long-running and resilient, and a Timeout limits a Workflow's ability to handle unexpected delays or long-running processes. -To perform an action inside your Workflow after a specific period of time, use a Timer instead. +Before we continue, we want to note that we generally do not recommend setting Workflow Timeouts, because Workflows are designed to be long-running and resilient. +Instead, setting a Timeout can limit its ability to handle unexpected delays or long-running processes. +If you need to perform an action inside your Workflow after a specific period of time, we recommend using a Timer. - **[Workflow Execution Timeout](/encyclopedia/detecting-workflow-failures#workflow-execution-timeout)** - restricts the maximum amount of time that a single Workflow Execution can be executed. - **[Workflow Run Timeout](/encyclopedia/detecting-workflow-failures#workflow-run-timeout):** restricts the maximum amount of time that a single Workflow Run can last. diff --git a/docs/develop/php/workflows/timeouts.mdx b/docs/develop/php/workflows/timeouts.mdx index 515b66409c..59ac35c5c2 100644 --- a/docs/develop/php/workflows/timeouts.mdx +++ b/docs/develop/php/workflows/timeouts.mdx @@ -17,8 +17,9 @@ tags: Each Workflow timeout controls the maximum duration of a different aspect of a Workflow Execution. -Avoid setting Workflow Timeouts. Workflows are designed to be long-running and resilient, and a Timeout limits a Workflow's ability to handle unexpected delays or long-running processes. -To perform an action inside your Workflow after a specific period of time, use a Timer instead. +Before we continue, we want to note that we generally do not recommend setting Workflow Timeouts, because Workflows are designed to be long-running and resilient. +Instead, setting a Timeout can limit its ability to handle unexpected delays or long-running processes. +If you need to perform an action inside your Workflow after a specific period of time, we recommend using a Timer. Workflow timeouts are set when [starting the Workflow Execution](#workflow-timeouts). diff --git a/docs/develop/python/workflows/timeouts.mdx b/docs/develop/python/workflows/timeouts.mdx index 095ef8fb1d..b9ce9b7780 100644 --- a/docs/develop/python/workflows/timeouts.mdx +++ b/docs/develop/python/workflows/timeouts.mdx @@ -17,8 +17,9 @@ tags: Each Workflow timeout controls the maximum duration of a different aspect of a Workflow Execution. -Avoid setting Workflow Timeouts. Workflows are designed to be long-running and resilient, and a Timeout limits a Workflow's ability to handle unexpected delays or long-running processes. -To perform an action inside your Workflow after a specific period of time, use a Timer instead. +Before we continue, we want to note that we generally do not recommend setting Workflow Timeouts, because Workflows are designed to be long-running and resilient. +Instead, setting a Timeout can limit its ability to handle unexpected delays or long-running processes. +If you need to perform an action inside your Workflow after a specific period of time, we recommend using a Timer. Workflow timeouts are set when [starting the Workflow Execution](#workflow-timeouts). diff --git a/docs/develop/typescript/workflows/timeouts.mdx b/docs/develop/typescript/workflows/timeouts.mdx index d3b13e96e7..0fa08b03cf 100644 --- a/docs/develop/typescript/workflows/timeouts.mdx +++ b/docs/develop/typescript/workflows/timeouts.mdx @@ -105,8 +105,9 @@ These errors are treated as bugs that can be corrected with a fixed deployment, Each Workflow timeout controls the maximum duration of a different aspect of a Workflow Execution. -Avoid setting Workflow Timeouts. Workflows are designed to be long-running and resilient, and a Timeout limits a Workflow's ability to handle unexpected delays or long-running processes. -To perform an action inside your Workflow after a specific period of time, use a Timer instead. +Before we continue, we want to note that we generally do not recommend setting Workflow Timeouts, because Workflows are designed to be long-running and resilient. +Instead, setting a Timeout can limit its ability to handle unexpected delays or long-running processes. +If you need to perform an action inside your Workflow after a specific period of time, we recommend using a Timer. Workflow Timeouts are set when starting a Workflow using either the Client or Workflow API.