Workflow

• 1: Workflow overview
• 2: Features and concepts
• 3: Workflow history propagation
• 4: Workflow versioning
• 5: Detached workflows
• 6: Stateful workflow client
• 7: Workflow patterns
• 8: Workflow architecture
• 9: Workflow fast path
• 10: How to: Author a workflow
• 11: How to: Manage workflows
• 12: Multi Application Workflows
• 13: History Retention Policy
• 14: Workflow Concurrency Limits
• 15: Workflow history signing
• 16: Workflow payload size

1 - Workflow overview

Dapr Workflow is a durable execution engine. You write workflow logic as ordinary code with a Dapr SDK. Dapr persists the result of each completed step and resumes the workflow from the last completed step after a crash, a restart, or a redeployment. Dapr workflows are stateful, so they support long-running and fault-tolerant applications. They also orchestrate other Dapr building blocks, such as service invocation, pub/sub, state management, and bindings.

The durable, resilient Dapr Workflow capability:

• Offers a built-in workflow runtime for driving Dapr Workflow execution.
• Provides SDKs for authoring workflows in code. See the supported SDKs.
• Provides HTTP and gRPC APIs for managing workflows (start, query, pause/resume, raise event, terminate, purge).

Some example scenarios that Dapr Workflow can perform are:

• Order processing involving orchestration between inventory management, payment systems, and shipping services.
• HR onboarding workflows coordinating tasks across multiple departments and participants.
• Orchestrating the roll-out of digital menu updates in a national restaurant chain.
• Image processing workflows involving API-based classification and storage.

Features

Workflows and activities

With Dapr Workflow, you can write activities and then orchestrate those activities in a workflow. Workflow activities are:

• The basic unit of work in a workflow
• Used for calling other (Dapr) services, interacting with state stores, and pub/sub brokers.
• Used for calling external third party services.

Learn more about workflow activities.

Child workflows

In addition to activities, you can write workflows to schedule other workflows as child workflows. A child workflow has its own instance ID, history, and status that is independent of the parent workflow that started it, except for the fact that terminating the parent workflow terminates all of the child workflows created by it. Child workflow also supports automatic retry policies.

Learn more about child workflows.

Detached workflows

You can also schedule a new workflow as a detached workflow: a fire-and-forget instance that runs fully independently of the workflow that started it. The calling workflow receives the new instance ID immediately and continues, and the detached workflow’s success or failure does not flow back to the caller. This is useful for triggering isolated, independent work, such as per-tenant fan-out.

Learn more about detached workflows.

Multi-application workflows

Multi-application workflows, enable you to orchestrate complex business processes that span across multiple applications. This allows a workflow to call activities or start child workflows in different applications, distributing the workflow execution while maintaining the security, reliability and durability guarantees of Dapr’s workflow engine.

Learn more about multi-application workflows.

History signing

When mTLS and the WorkflowHistorySigning feature flag are enabled, Dapr cryptographically signs every workflow history event using the sidecar’s X.509 SPIFFE identity. On each load, the full signature chain is verified, detecting any tampering of workflow state in the state store.

For example, consider an order-processing workflow that captures payment, ships the goods, and emails a receipt. Without signing, an attacker with write access to the state store could rewrite the recorded order total between the payment step and the shipping step, so the workflow ships at a lower price than was actually charged, and Dapr would have no way to know. With signing enabled, the modified event no longer matches its signature, the next load fails verification, and Dapr marks the workflow as FAILED with error type DAPR_WORKFLOW_HISTORY_TAMPERED instead of acting on the forged data. The same protection applies to approvals being flipped from denied to approved, extra recipients being added to outbound messages, or fake activity results being injected into the inbox.

Signing is a one-way commitment: once enabled for a workflow, it cannot be disabled.

Learn more about workflow history signing.

Fast path

The WorkflowsFastPath preview feature drives workflow turns and activity bodies on the host that already holds the work, and folds activity completions into the next turn’s single state store commit, instead of creating a Scheduler reminder for every event. This removes the per-event Scheduler round trips and most state store commits from the workflow hot path. At-least-once execution is unchanged: a per-instance janitor reminder and automatic escalation back to durable reminders provide recovery.

Learn more about the workflow fast path.

Timers and reminders

Same as Dapr actors, you can schedule reminder-like durable delays for any time range.

Learn more about workflow timers and reminders

History propagation

Workflow history propagation enables a current workflow to look back over the set of events that the workflow or a another workflow has executed and verify these actually occurred. Scenarios include fraud checks, checking compliance gates (was this activity called or not), or enabling long-running AI agents/workflows to maintain context across calls (multi-agent, multi-app workflows) to determine what the agent or workflows claims to have done, it actually true.

A parent workflow can opt to share its execution history with child workflows and activities — useful for chain-of-custody verification, fraud detection, audit, and AI-agent context that must flow across hops.

For details, read [workflow history propagation ](https://v1-19.docs.dapr.io/developing-applications/building-blocks/workflow/workflow-history-propagation/ to understand how to apply this to a workflow, child workflow and activities.

Learn more about workflow history propagation.

Workflow HTTP calls to manage a workflow

When you create an application with workflow code and run it with Dapr, you can call specific workflows that reside in the application. Each individual workflow can be:

• Started or terminated through a POST request
• Triggered to deliver a named event through a POST request
• Paused and then resumed through a POST request
• Purged from your state store through a POST request
• Queried for workflow status through a GET request

Learn more about how manage a workflow using HTTP calls.

Workflow patterns

Dapr Workflow simplifies complex, stateful coordination requirements in microservice architectures. The following sections describe several application patterns that can benefit from Dapr Workflow.

Learn more about different types of workflow patterns

Workflow SDKs

The Dapr Workflow authoring SDKs are language-specific SDKs that contain types and functions to implement workflow logic. The workflow logic lives in your application and is orchestrated by the Dapr Workflow engine running in the Dapr sidecar via a gRPC stream.

Supported SDKs

You can use the following SDKs to author a workflow.

Try out workflows

Quickstarts and tutorials

Want to put workflows to the test? Walk through the following quickstart and tutorials to see workflows in action:

Start using workflows directly in your app

Want to skip the quickstarts? Not a problem. You can try out the workflow building block directly in your application. After Dapr is installed, you can begin using workflows, starting with how to author a workflow.

Managing Workflows

Dapr provides comprehensive workflow management capabilities through both the HTTP API and the CLI.

Workflow Lifecycle Operations

Start Workflows

dapr workflow run MyWorkflow --app-id myapp --input '{"key": "value"}'

Monitor Workflows

# List active workflows for a given application
dapr workflow list --app-id myapp --filter-status RUNNING

# View execution history
dapr workflow history <instance-id> --app-id myapp

Control Workflows

# Suspend, resume, or terminate
dapr workflow suspend <instance-id> --app-id myapp
dapr workflow resume <instance-id> --app-id myapp
dapr workflow terminate <instance-id> --app-id myapp

Maintenance Operations

# Purge completed workflows
dapr workflow purge --app-id myapp --all-older-than 720h

See How-To: Manage workflows for detailed instructions.

Inspect Workflows Visually

During local development, you can use the Dapr Dev Dashboard to browse workflow instances, check their status, and drill down into the event history of each execution.

Limitations

• State stores: You can only use state stores which support workflows, as described here.
• Azure Cosmos DB has payload and workflow complexity limitations.
• AWS DynamoDB has workflow complexity limitations.

Workflow security

Dapr provides fine-grained access control for workflow and activity scheduling through the WorkflowAccessPolicy resource. You can restrict which applications are permitted to start specific workflows or call specific activities on your application.

Workflow access policies for a given application (appID) are loaded by the sidecar when the application is instantiated, and are hot-reloaded thereafter when policies are added, updated, or removed. Policies are a pure allow-list evaluated on the callee side: a cross-app schedule is permitted only if some rule in some loaded policy matches the caller and the workflow or activity name.

This is especially important for multi-application workflows, where activities and child workflows execute across application boundaries. Read How-To: Apply workflow access policies for full configuration details.

Watch the demo

Watch this video for an overview on Dapr Workflow:

Next steps

Related links

• Workflow API reference
• Try out the full SDK examples:
  • Python example
  • JavaScript example
  • .NET example
  • Java example
  • Go example

2 - Features and concepts

Now that you’ve learned about the workflow building block at a high level, let’s deep dive into the features and concepts included with the Dapr Workflow engine and SDKs. Dapr Workflow exposes several core features and concepts which are common across all supported languages.

Workflows

Dapr Workflows are functions you write that define a series of tasks to be executed in a particular order. The Dapr Workflow engine takes care of scheduling and execution of the tasks, including managing failures and retries. If the app hosting your workflows is scaled out across multiple machines, the workflow engine load balances the execution of workflows and their tasks across multiple machines. You can configure concurrency limits to control how many workflows and activities run simultaneously, either per-sidecar or globally across all replicas.

There are several different kinds of tasks that a workflow can schedule, including

• Activities for executing custom logic
• Durable timers for putting the workflow to sleep for arbitrary lengths of time
• Child workflows for breaking larger workflows into smaller pieces
• Detached workflows for spawning independent, fire-and-forget workflows that run on their own
• External event waiters for blocking workflows until they receive external event signals. These tasks are described in more details in their corresponding sections.

Workflow Instance Management

Querying Workflow State

You can query workflow instances using the CLI:

# Find all running workflows
dapr workflow list --app-id myapp --filter-status RUNNING

# Find workflows by name
dapr workflow list --app-id myapp --filter-name OrderProcessing

# Find recent workflows (last 2 hours)
dapr workflow list --app-id myapp --filter-max-age 2h

# Get detailed JSON output
dapr workflow list --app-id myapp --output json

Workflow History

View the complete execution history:

dapr workflow history wf-12345 --app-id myapp --output json

This shows all events, activities, and state transitions.

External Events

Raising Events via CLI

dapr workflow raise-event wf-12345/ApprovalReceived \
  --app-id myapp \
  --input '{"approved": true, "comments": "Approved by manager"}'

Workflow Suspension and Resumption

Using the CLI

# Suspend for manual intervention
dapr workflow suspend wf-12345 \
  --app-id myapp \
  --reason "Awaiting customer response"

# Resume when ready
dapr workflow resume wf-12345 \
  --app-id myapp \
  --reason "Customer responded"

Workflow identity

Each workflow you define has a type name, and individual executions of a workflow require a unique instance ID. Workflow instance IDs can be generated by your app code, which is useful when workflows correspond to business entities like documents or jobs, or can be auto-generated UUIDs. A workflow’s instance ID is useful for debugging and also for managing workflows using the Workflow APIs.

Only one workflow instance with a given ID can exist at any given time. Attempting to create a new workflow instance with the same ID as an existing instance results in an error unless the existing instance, and every child workflow it created (checked recursively), has reached a terminal state: COMPLETED, FAILED, or TERMINATED. Once the entire workflow tree is terminal, creating a new instance with the same ID starts a fresh execution that replaces the previous one in the state store.

SDK workflow clients get the gRPC AlreadyExists status code when the instance ID belongs to an active instance (the Java SDK raises WorkflowInstanceAlreadyExistsException). A client can therefore start a workflow with a fixed instance ID as an idempotent call and treat AlreadyExists as “already running”, without parsing the error message. A completed instance ID is reused by default. It also returns AlreadyExists when a durabletask-go client sets api.WithEnforceUniqueInstanceID(), or when the old instance’s child workflows have not finished. The workflow API (HTTP and gRPC StartWorkflowBeta1) keeps its error response: HTTP 500 with error code ERR_START_WORKFLOW.

Implications of Instance ID Reuse

Reusing an instance ID for a new workflow execution has costs that a fresh ID does not:

• The previous execution is replaced. Its history, output, and failure details are overwritten in the state store the moment the new execution is created. The audit trail is lost and it can no longer be queried what the earlier run did.
• Every reuse is a conflict check across the whole previous workflow tree. Before accepting the create, the runtime must confirm that the previous instance and every child workflow it created, recursively and possibly in other applications, has reached a terminal state. A child that is still running rejects the create with a conflict and a child that cannot be reached during an outage rejects the create as unavailable. A create with a fresh ID has no such dependency and succeeds in the same conditions.
• Work addressed to the old execution can arrive at the new one. Events, activity results, and reminders are routed by instance ID and can outlive the execution that produced them. Dapr guards against them being applied to the wrong execution, but it is still riskier than no reuse.
• Recovery and troubleshooting are harder. The engine’s recovery paths key on the instance ID. When one ID has carried several executions, an operator looking at a stuck instance first has to work out which execution the stored state, reminders, and logs belong to.

Recommended patterns instead of reuse:

• Let Dapr generate the ID, or derive one from your business key plus a unique suffix, such as order-1234-<uuid> or order-1234-attempt-3. Keep the mapping from business entity to current instance ID in your own state store, or expose it through the workflow’s custom status, so callers can find the active instance.
• Use a fixed ID only to deduplicate a single logical start. If two callers may race to start the same logical workflow, a deterministic ID makes the second create fail with a conflict while the first is running, which is the intended signal. Do not use the same ID to run a sequence of executions.
• If a business identifier must be the instance ID and executions repeat, purge the previous instance with the purge API or a retention policy before starting the next one, and treat the purge and the create as as transaction in code.

Workflow replay

Dapr Workflows maintain their execution state by using a technique known as event sourcing. Instead of storing the current state of a workflow as a snapshot, the workflow engine manages an append-only log of history events that describe the various steps that a workflow has taken. When using the workflow SDK, these history events are stored automatically whenever the workflow “awaits” for the result of a scheduled task.

When a workflow “awaits” a scheduled task, it unloads itself from memory until the task completes. Once the task completes, the workflow engine schedules the workflow function to run again. This second workflow function execution is known as a replay.

When a workflow function is replayed, it runs again from the beginning. However, when it encounters a task that already completed, instead of scheduling that task again, the workflow engine:

1. Returns the stored result of the completed task to the workflow.
2. Continues execution until the next “await” point.

This “replay” behavior continues until the workflow function completes or fails with an error.

Using this replay technique, a workflow is able to resume execution from any “await” point as if it had never been unloaded from memory. Even the values of local variables from previous runs can be restored without the workflow engine knowing anything about what data they stored. This ability to restore state makes Dapr Workflows durable and fault tolerant.

Infinite loops and eternal workflows

As discussed in the workflow replay section, workflows maintain a write-only event-sourced history log of all its operations. To avoid runaway resource usage, workflows must limit the number of operations they schedule. For example, ensure your workflow doesn’t:

• Use infinite loops in its implementation
• Schedule thousands of tasks.

You can use the following two techniques to write workflows that may need to schedule extreme numbers of tasks:

1. Use the continue-as-new API: Each workflow SDK exposes a continue-as-new API that workflows can invoke to restart themselves with a new input and history. The continue-as-new API is especially ideal for implementing “eternal workflows”, like monitoring agents, which would otherwise be implemented using a while (true)-like construct. Using continue-as-new is a great way to keep the workflow history size small.

   Note

   Continue-as-new restarts the workflow immediately and discards the results of any incomplete tasks - including activities, timers, and child workflows that were started but not awaited.

   The continue-as-new API truncates the existing history, replacing it with a new history.

2. Use child workflows: Each workflow SDK exposes an API for creating child workflows. A child workflow behaves like any other workflow, except that it’s scheduled by a parent workflow. Child workflows have:

   • Their own history
   • The benefit of distributing workflow function execution across multiple machines.

   If a workflow needs to schedule thousands of tasks or more, it’s recommended that those tasks be distributed across child workflows so that no single workflow’s history size grows too large.

Updating workflow code

Because workflows are long-running and durable, updating workflow code must be done with extreme care. As discussed in the workflow determinism limitation section, workflow code must be deterministic. Updates to workflow code must preserve this determinism if there are any non-completed workflow instances in the system. Otherwise, updates to workflow code can result in runtime failures the next time those workflows execute.

See known limitations

Workflow activities

Workflow activities are the basic unit of work in a workflow and are the tasks that get orchestrated in the business process. For example, you might create a workflow to process an order. The tasks may involve checking the inventory, charging the customer, and creating a shipment. Each task would be a separate activity. These activities may be executed serially, in parallel, or some combination of both.

Unlike workflows, activities aren’t restricted in the type of work you can do in them. Activities are frequently used to make network calls or run CPU intensive operations. An activity can also return data back to the workflow.

The Dapr Workflow engine guarantees that each called activity is executed at least once as part of a workflow’s execution. Because activities only guarantee at-least-once execution, it’s recommended that activity logic be implemented as idempotent whenever possible.

Child workflows

In addition to activities, workflows can schedule other workflows as child workflows. A child workflow has its own instance ID, history, and status that is independent of the parent workflow that started it.

Child workflows have many benefits:

• You can split large workflows into a series of smaller child workflows, making your code more maintainable.
• You can distribute workflow logic across multiple compute nodes concurrently, which is useful if your workflow logic otherwise needs to coordinate a lot of tasks.
• You can reduce memory usage and CPU overhead by keeping the history of parent workflow smaller.

The return value of a child workflow is its output. If a child workflow fails with an exception, then that exception is surfaced to the parent workflow, just like it is when an activity task fails with an exception. Child workflows also support automatic retry policies.

Terminating a parent workflow terminates all of the child workflows created by the workflow instance. See the terminate workflow api for more information.

Detached workflows

In addition to child workflows, a workflow can schedule another workflow as a detached workflow: a fire-and-forget instance that runs fully independently of the caller. The call returns the new instance ID synchronously and the scheduling workflow continues immediately, without waiting for the detached workflow. Unlike a child workflow, there is no parent linkage: the detached workflow’s success or failure does not flow back to the caller, and terminating the caller does not terminate the detached workflow.

For the comparison with child workflows, guidance on when to use them, and a code example, see Detached workflows.

Durable timers

Dapr Workflows allow you to schedule reminder-like durable delays for any time range, including minutes, days, or even years. These durable timers can be scheduled by workflows to implement simple delays or to set up ad-hoc timeouts on other async tasks. More specifically, a durable timer can be set to trigger on a particular date or after a specified duration. There are no limits to the maximum duration of durable timers, which are internally backed by internal actor reminders. For example, a workflow that tracks a 30-day free subscription to a service could be implemented using a durable timer that fires 30-days after the workflow is created. Workflows can be safely unloaded from memory while waiting for a durable timer to fire.

Retry policies

Workflows support durable retry policies for activities and child workflows. Workflow retry policies are separate and distinct from Dapr resiliency policies in the following ways.

• Workflow retry policies are configured by the workflow author in code, whereas Dapr Resiliency policies are configured by the application operator in YAML.
• Workflow retry policies are durable and maintain their state across application restarts, whereas Dapr Resiliency policies are not durable and must be re-applied after application restarts.
• Workflow retry policies are triggered by unhandled errors/exceptions in activities and child workflows, whereas Dapr Resiliency policies are triggered by operation timeouts and connectivity faults.

Retries are internally implemented using durable timers. This means that workflows can be safely unloaded from memory while waiting for a retry to fire, conserving system resources. This also means that delays between retries can be arbitrarily long, including minutes, hours, or even days.

It’s possible to use both workflow retry policies and Dapr Resiliency policies together. For example, if a workflow activity uses a Dapr client to invoke a service, the Dapr client uses the configured resiliency policy. See Quickstart: Service-to-service resiliency for more information with an example. However, if the activity itself fails for any reason, including exhausting the retries on the resiliency policy, then the workflow’s resiliency policy kicks in.

Because workflow retry policies are configured in code, the exact developer experience may vary depending on the version of the workflow SDK. In general, workflow retry policies can be configured with the following parameters.

Each retry of a child workflow is a separate instance with its own instance ID. From Dapr 1.19, the ChildWorkflowInstanceCreated event of a retry attempt in the parent’s history records the instance ID of the first attempt (retryParentInstanceInfo). Tooling that reads a parent’s history can group the attempts of one call by that ID, without walking the retry timers between them.

External events

Sometimes workflows will need to wait for events that are raised by external systems. For example, an approval workflow may require a human to explicitly approve an order request within an order processing workflow if the total cost exceeds some threshold. Another example is a trivia game orchestration workflow that pauses while waiting for all participants to submit their answers to trivia questions. These mid-execution inputs are referred to as external events.

External events have a name and a payload and are delivered to a single workflow instance. Workflows can create “wait for external event” tasks that subscribe to external events and await those tasks to block execution until the event is received. The workflow can then read the payload of these events and make decisions about which next steps to take. External events can be processed serially or in parallel. External events can be raised by other workflows or by workflow code.

Workflows can also wait for multiple external event signals of the same name, in which case they are dispatched to the corresponding workflow tasks in a first-in, first-out (FIFO) manner. If a workflow receives an external event signal but has not yet created a “wait for external event” task, the event will be saved into the workflow’s history and consumed immediately after the workflow requests the event.

Learn more about external system interaction.

Workflow history propagation

Workflow history propagation enables a workflow instance to look back over the set of events that the workflow or a another workflow has executed and verify these actually occurred. Some scenarios include performance fraud checks, checking compliance gates, or enable long-running AI agents/workflows to maintain context across calls (multi-agent, multi-app workflows) to determine what the agent or workflows claims to have done, it actually true.

For example if you have a workflow that verifies a credit check for a user, you can use workflow history propagation to verify this actually happened for the named user. When this is combined with workflow history signing, you can further cryptographically confirm or attest this.

A parent workflow can opt to share its execution history with downstream child and grandchild workflows and activities. Two scopes are available:

• Lineage — caller’s events plus the full ancestor chain (chain-of-custody)
• Own history — caller’s events only (a trust boundary, ancestral lineage dropped)

The receiving workflow/activity reads its inherited history via the SDKs GetPropagatedHistory() API and can verify what happened upstream.

For details, the scope comparison, and code examples, see workflow history propagation.

Stateful workflow client

A workflow is replayed from its history on every turn, and that history only grows. Rather than sending the whole thing each time, the workflow SDK keeps the history it has already replayed in memory and the sidecar sends only the events added since the previous turn. The per-turn payload therefore stops growing with the length of the workflow, which matters most for long-running, monitor-pattern, and large fan-out workflows.

This is enabled by default, requires no configuration or code changes, and never affects correctness: if the worker’s cached history does not match what the sidecar expects, the full history is fetched instead.

Learn more about the stateful workflow client.

Purging

Workflow state can be purged from a state store, purging all its history and removing all metadata related to a specific workflow instance. The purge capability is used for workflows that have run to a COMPLETED, FAILED, or TERMINATED state.

Learn more in the workflow API reference guide.

Versioning

Workflow code is long-running and must remain deterministic during updates. For details on patching and named workflow versioning, see Workflow versioning.

Limitations

Payload size

A single workflow or activity dispatch is bounded by the sidecar’s --max-body-size setting (default 4 MiB). If a workflow’s PastEvents + NewEvents + PropagatedHistory would exceed 95% of that limit, the workflow is stalled rather than tearing down the dispatch stream. Metrics expose how close each workflow and activity is to the limit so operators can act before a stall. See Workflow payload size for details and remediation steps.

Fast path and concurrency limits

The WorkflowsFastPath preview feature disables itself when Scheduler-enforced concurrency limits (globalMaxConcurrentWorkflowInvocations, globalMaxConcurrentActivityInvocations, or per-name workflowConcurrencyLimits and activityConcurrencyLimits) are configured, because those limits gate each Scheduler job delivery and the fast path drives work without Scheduler jobs. Per-sidecar limits are compatible. See Workflow fast path and Workflow concurrency limits.

Workflow determinism and code restraints

To take advantage of the workflow replay technique, your workflow code needs to be deterministic. For your workflow code to be deterministic, you may need to work around some limitations.

Workflow functions must call deterministic APIs

APIs that generate random numbers, random UUIDs, or the current date are non-deterministic. To work around this limitation, you can:

• Use these APIs in activity functions, or
• (Preferred) Use built-in equivalent APIs offered by the SDK. For example, each authoring SDK provides an API for retrieving the current time in a deterministic manner.

For example, instead of this:

• .NET
• Java
• JavaScript
• Go

// DON'T DO THIS!
DateTime currentTime = DateTime.UtcNow;
Guid newIdentifier = Guid.NewGuid();
string randomString = GetRandomString();

// DON'T DO THIS!
Instant currentTime = Instant.now();
UUID newIdentifier = UUID.randomUUID();
String randomString = getRandomString();

// DON'T DO THIS!
const currentTime = new Date();
const newIdentifier = uuidv4();
const randomString = getRandomString();

// DON'T DO THIS!
const currentTime = time.Now()

Do this:

• .NET
• Java
• JavaScript
• Go

// Do this!!
DateTime currentTime = context.CurrentUtcDateTime;
Guid newIdentifier = context.NewGuid();
string randomString = await context.CallActivityAsync<string>(nameof("GetRandomString")); //Use "nameof" to prevent specifying an activity name that does not exist in your application

// Do this!!
Instant currentTime = context.getCurrentInstant();
Guid newIdentifier = context.newGuid();
String randomString = context.callActivity(GetRandomString.class.getName(), String.class).await();

// Do this!!
const currentTime = context.getCurrentUtcDateTime();
const randomString = yield context.callActivity(getRandomString);

const currentTime = ctx.CurrentUTCDateTime()

Workflow functions must only interact indirectly with external state.

External data includes any data that isn’t stored in the workflow state. Workflows must not interact with global variables, environment variables, the file system, or make network calls.

Instead, workflows should interact with external state indirectly using workflow inputs, activity tasks, and through external event handling.

For example, instead of this:

• .NET
• Java
• JavaScript
• Go

// DON'T DO THIS!
string configuration = Environment.GetEnvironmentVariable("MY_CONFIGURATION")!;
string data = await new HttpClient().GetStringAsync("https://example.com/api/data");

// DON'T DO THIS!
String configuration = System.getenv("MY_CONFIGURATION");

HttpRequest request = HttpRequest.newBuilder().uri(new URI("https://postman-echo.com/post")).GET().build();
HttpResponse<String> response = HttpClient.newBuilder().build().send(request, HttpResponse.BodyHandlers.ofString());

// DON'T DO THIS!
// Accessing an Environment Variable (Node.js)
const configuration = process.env.MY_CONFIGURATION;

fetch('https://postman-echo.com/get')
  .then(response => response.text())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('Error:', error);
  });

// DON'T DO THIS!
resp, err := http.Get("http://example.com/api/data")

Do this:

• .NET
• Java
• JavaScript
• Go

// Do this!!
string configuration = workflowInput.Configuration; // imaginary workflow input argument
string data = await context.CallActivityAsync<string>(nameof("MakeHttpCall"), "https://example.com/api/data");

// Do this!!
String configuration = ctx.getInput(InputType.class).getConfiguration(); // imaginary workflow input argument
String data = ctx.callActivity(MakeHttpCall.class, "https://example.com/api/data", String.class).await();

// Do this!!
const configuration = workflowInput.getConfiguration(); // imaginary workflow input argument
const data = yield ctx.callActivity(makeHttpCall, "https://example.com/api/data");

// Do this!!
err := ctx.CallActivity(MakeHttpCallActivity, workflow.ActivityInput("https://example.com/api/data")).Await(&output)

Workflow functions must execute only on the workflow dispatch thread.

The implementation of each language SDK requires that all workflow function operations operate on the same thread (goroutine, etc.) that the function was scheduled on. Workflow functions must never:

• Schedule background threads, or
• Use APIs that schedule a callback function to run on another thread.

Failure to follow this rule could result in undefined behavior. Any background processing should instead be delegated to activity tasks, which can be scheduled to run serially or concurrently.

For example, instead of this:

• .NET
• Java
• JavaScript
• Go

// DON'T DO THIS!
Task t = Task.Run(() => context.CallActivityAsync("DoSomething"));
await context.CreateTimer(5000).ConfigureAwait(false);

// DON'T DO THIS!
new Thread(() -> {
    ctx.callActivity(DoSomethingActivity.class.getName()).await();
}).start();
ctx.createTimer(Duration.ofSeconds(5)).await();

// DON'T DO THIS!
go func() {
  err := ctx.CallActivity(DoSomething).Await(nil)
}()
err := ctx.CreateTimer(time.Second).Await(nil)

Do this:

• .NET
• Java
• JavaScript
• Go

// Do this!!
Task t = context.CallActivityAsync(nameof("DoSomething"));
await context.CreateTimer(5000).ConfigureAwait(true);

// Do this!!
ctx.callActivity(DoSomethingActivity.class.getName()).await();
ctx.createTimer(Duration.ofSeconds(5)).await();

// Do this!
task := ctx.CallActivity(DoSomething)
task.Await(nil)

Updating workflow code

Make sure updates you make to the workflow code maintain its determinism. Here are a few example of code updates that can break workflow determinism:

• Changing the workflow function signature: Changing the name, input, or output of a workflow or activity is considered a breaking change and must be avoided.
• Changing the number or order of workflow tasks: Changing the number or order of workflow tasks causes a workflow’s history to no longer match the workflow code and may result in runtime errors or other unexpected behavior.

To work around these constraints, use the workflow versioning concepts described in the versioning guide to patch and introduce new named workflow versions to incorporate changes to your workflows deterministically.

Next steps

Related links

• Try out Dapr Workflow using the quickstart
• Workflow overview
• Workflow fast path
• How-To: Apply workflow access policies
• Workflow API reference
• Try out the following examples:
  • Python
  • JavaScript
  • .NET
  • Java
  • Go

3 - Workflow history propagation

By default, a child workflow or activity only sees the input it was scheduled with. The parent’s execution history — what activities ran, what child workflows it spawned, what events it observed — is invisible. Workflow history propagation lets a parent opt-in to share that history with the workflows it schedules.

This is useful for:

• Chain-of-custody and audit — a fraud check, compliance gate, or settlement step can verify what already happened upstream rather than trusting the caller’s claims.
• Cross-app workflows — a downstream app, often owned by a different team, can confirm an upstream activity ran without an out-of-band query.
• AI agents and long-running orchestrations — agents that loop with ContinueAsNew or fan out to sub-agents can carry context (tool calls, model outputs, intermediate decisions) forward without re-prompting expensive calls from scratch.

Propagation scopes

Two scopes are exposed. The default is no propagation.

The helpers (PropagateLineage / PropagateOwnHistory) are what you pass when scheduling — each SDK has its own equivalent (see the examples below). The scope values (LINEAGE / OWN_HISTORY) are the runtime enum names carried on the propagation.

PropagateOwnHistory is the trust boundary: choosing it tells the runtime to stop forwarding any history the caller itself received. This is the right choice when the receiver is a less-trusted app, a third party, or operates under different compliance rules.

Which scope should I use?

PropagateLineage is the most common choice, as most workflows will want the receiver to see the full chain of what happened upstream — that’s what makes the chain-of-custody, audit, and agent-context use cases above work. The decision is about how far down the chain you’re willing to share.

Use PropagateOwnHistory only when you’re crossing a trust boundary: the receiver is a less-trusted app, a third party, or runs under different compliance rules, and you’re willing to vouch for your own steps but not forward everything you inherited from your own parent. Outside those cases, prefer lineage.

Setting it up

A parent enables propagation for a single child workflow or activity with a per-call option. Other calls in the same workflow are unaffected, and the default remains no propagation.

• Python
• .NET
• Go

import dapr.ext.workflow as wf

@wfr.workflow(name='MerchantCheckout')
def merchant_checkout(ctx: wf.DaprWorkflowContext, order_json: str):
    # The validate_merchant activity does NOT receive propagated history (default).
    yield ctx.call_activity(validate_merchant, input=order_json)

    # The process_payment child workflow DOES receive parent's history (LINEAGE).
    result = yield ctx.call_child_workflow(
        process_payment,
        input=order_json,
        propagation=wf.PropagationScope.LINEAGE,
    )
    return result

using Dapr.Workflow;

public sealed class MerchantCheckoutWorkflow : Workflow<Order, string>
{
    public override async Task<string> RunAsync(WorkflowContext ctx, Order order)
    {
        // The ValidateMerchantActivity does NOT receive propagated history (default).
        await ctx.CallActivityAsync<bool>(nameof(ValidateMerchantActivity), order);

        // The ProcessPaymentWorkflow child workflow DOES receive parent's history (Lineage).
        var childOptions = new ChildWorkflowTaskOptions()
            .WithHistoryPropagation(HistoryPropagationScope.Lineage);
        return await ctx.CallChildWorkflowAsync<string>(
            nameof(ProcessPaymentWorkflow),
            order,
            options: childOptions);
    }
}

import (
    "github.com/dapr/durabletask-go/workflow"
)

func MerchantCheckout(ctx *workflow.WorkflowContext) (any, error) {
    // Activity does NOT receive propagated history (default).
    if err := ctx.CallActivity("ValidateMerchant").Await(nil); err != nil {
        return nil, err
    }

    // Child workflow DOES receive parent's history (LINEAGE).
    var result string
    if err := ctx.CallChildWorkflow("ProcessPayment",
        workflow.WithHistoryPropagation(workflow.PropagateLineage()),
    ).Await(&result); err != nil {
        return nil, err
    }
    return result, nil
}

Accessing propagated history

Inside a child workflow or activity, call GetPropagatedHistory() (Go / .NET) or get_propagated_history() (Python). It returns the propagated history if the caller opted in, or None / nil if it didn’t.

What you get back is a point-in-time snapshot of the caller’s execution at the moment it scheduled this call — the steps that had already run, not anything the caller does afterward. In the MerchantCheckout parent above, ValidateMerchant completed before the child workflow was scheduled, so it appears in the propagated history the child receives.

The example below assumes the parent workflow shown above is registered as MerchantCheckout with an activity ValidateMerchant and a child workflow ProcessPayment (called with Lineage).

• Python
• .NET
• Go

import dapr.ext.workflow as wf

@wfr.workflow(name='FraudDetection')
def fraud_detection(ctx: wf.DaprWorkflowContext, order_json: str):
    history = ctx.get_propagated_history()
    if history is None:
        return 'no upstream history'

    # Logs once instead of repeatedly during replays — not required, just keeps logging clean.
    if not ctx.is_replaying:
        print(f'scope={history.scope}, workflows={[w.name for w in history.get_workflows()]}')

    try:
        merchant_wf = history.get_last_workflow_by_name('MerchantCheckout')
        validation = merchant_wf.get_last_activity_by_name('ValidateMerchant')
    except wf.PropagationNotFoundError as exc:
        return f'missing required upstream step: {exc}'

    if not validation.completed:
        return 'merchant validation did not complete, rejecting'
    return 'approved'

using Dapr.Workflow;

public sealed class FraudDetectionWorkflow : Workflow<Order, string>
{
    public override Task<string> RunAsync(WorkflowContext ctx, Order order)
    {
        var history = ctx.GetPropagatedHistory();
        if (history is null)
            return Task.FromResult("no upstream history");

        // Logs once instead of repeatedly during replays — not required, just keeps logging clean.
        if (!ctx.IsReplaying)
            Console.WriteLine($"received {history.Events.Count} ancestor workflow event(s)");

        // Verify MerchantCheckout is present in the ancestor chain.
        if (!history.TryGetLastWorkflowEventByName(nameof(MerchantCheckoutWorkflow), out _))
            return Task.FromResult("MerchantCheckout missing from propagated history, rejecting");

        return Task.FromResult("approved");
    }
}

import (
    "fmt"

    "github.com/dapr/durabletask-go/workflow"
)

func FraudDetection(ctx *workflow.WorkflowContext) (any, error) {
    propagatedHistory := ctx.GetPropagatedHistory()
    if propagatedHistory == nil {
        return "no upstream history", nil
    }

    // The history exposes both raw events and per-app/per-instance chunks.
    fmt.Printf("scope: %s, %d events from apps %v\n",
        propagatedHistory.Scope(), len(propagatedHistory.Events()), propagatedHistory.GetAppIDs())

    // Drill into a specific upstream workflow's activities.
    merchantWf, err := propagatedHistory.GetLastWorkflowByName("MerchantCheckout")
    if err != nil {
        return nil, fmt.Errorf("expected MerchantCheckout in propagated history: %w", err)
    }
    validation, err := merchantWf.GetLastActivityByName("ValidateMerchant")
    if err != nil {
        return nil, fmt.Errorf("expected ValidateMerchant in propagated history: %w", err)
    }
    if !validation.Completed {
        return "merchant validation didn't complete, rejecting", nil
    }
    return "approved", nil
}

Every SDK gives you the same underlying model — an execution-ordered chain of ancestor workflows, each carrying its identity (app ID, instance ID, name) plus the activities and child workflows it ran. From the returned object you can:

• List the ancestor chain — one entry per ancestor workflow, in execution order.
• Look up an ancestor workflow by name — either the most-recent match or all matches.
• Look up activities or child workflows within an entry by name, with the same pattern.
• See which apps contributed to the chain (deduplicated).
• Read the propagation scope the parent chose (LINEAGE or OWN_HISTORY), where the SDK exposes it on the receiver.

For exact method signatures in each language see the runnable examples linked under Related links.

History propagation in multi-app workflows

When a parent workflow in App A calls a child workflow in App B using multi-app workflow calling, the propagated context travels across the network between the two sidecars. Two things secure that hop: the channel it travels over, and the signature on the context itself.

Transport security (mTLS)

The propagated context rides the inter-sidecar gRPC channel, so it inherits whatever protects that channel. When Dapr runs with mTLS — the default for Helm and dapr init -k — that traffic is encrypted and the two sidecars are mutually authenticated, so the context can’t be read or injected by anything sitting between App A and App B. mTLS is also the prerequisite for signing below: the SPIFFE X.509 identity it provides is the key the producer signs with.

Workflow history signing

mTLS protects the context in transit, but says nothing about whether the contents are authentic once they arrive. Signing closes that gap. With the WorkflowHistorySigning Configuration feature enabled, the producing app signs each propagated chunk with its SPIFFE identity, and the receiver can cryptographically verify the chunk wasn’t tampered with after it left the producer. For the full mechanism — how signatures are chained, stored, and verified on load — see Workflow history signing.

If WorkflowHistorySigning is not enabled, daprd logs a warning per dispatch:

propagating unsigned workflow history to child workflow '...' (signing is not configured; context cannot be cryptographically verified by the receiver)

ContinueAsNew and rerun

Propagated history is correctly maintained with both ContinueAsNew and Rerun workflow operations.

• A workflow that received propagated history and calls ContinueAsNew passes the same incoming context to its next generation.
• Re-running a workflow re-issues activity / child-workflow calls with the same propagation scope they were originally scheduled with — LINEAGE stays LINEAGE, OWN_HISTORY stays OWN_HISTORY.

This makes long-running agents and crash-recovery scenarios behave the way you’d expect: the receiving generation/rerun sees the same history the original run did.

Next steps

Discover how to apply workflow history signing to cryptographically attest the validity of a previous workflow or activity step.

Related links

• Workflow history signing
• Workflow overview
• Workflow features and concepts
• Workflow architecture
• How to author a workflow
• Workflow API reference
• Try out the example code in each SDK:
  • Python example
  • .NET quickstart
  • Go example

4 - Workflow versioning

Versioning

There are many scenarios where it is necessary to introduce changes to workflow code while workflows are actively running. In cases where these changes are non-deterministic, a versioning strategy is required so that existing workflows can continue executing with the original code, while new workflows use the updated version.

Workflows can be versioned using two complementary approaches and it’s intended that both are used in conjunction with one another. These are:

• Patching
• Named workflow versioning

What Does Versioning Solve?

To best understand how versioning works and how to use it effectively, it helps to first understand what it’s solving and why versioning is necesssary at all. Workflows are required to be deterministic meaning that every time they are run, they produce precisely the same output as the last time.

This is a key concept because Dapr Workflows are implemented to use an event sourcing approach to persist the workflow state. As activities and child workflows are executed within the workflow, Dapr is maintaining a history that logs the inputs and outputs at each of those boundary executions. As each completes, we persist the updated event history then re-invoke the workflow from the top (this is called a “replay”). This time, when it hits one of these activities or child workflows, it substitutes in the already-realized output and skips re-executing it and repeats.

Because of this, it’s critical that no code be arbitrarily introduced into a workflow while it’s in-flight because when the engine replays the workflow, your changes risk the workflow no longer matching with its history and failing.

Patching

Patches are the first of our two versioning approaches that allow you to introduce changes to your workflow while keeping it deterministic between replays. It works by allowing you to insert branched logic associated with named identifiers via if statements. The workflow history keeps track of where these named identifiers have been observed while replaying the workflow ensuring that a consistent logical path is followed between replays.

This enables you to apply targeted changes to your workflow code in only those specific places where a tweak is necessary.

To add a patch, select a stable, unique name that identifies the patch. This can be something descriptive like use-sms that characterizes what the patch changes or something that’s inherently different like the current timestamp or date. The specific value you use doesn’t matter so long as you don’t use an identifier that you’ve already deployed into production. You’ll insert the patch by adding an if statement that evaluates if the workflow has applied this patch or not - if so, the patch’s code is used and if not, the original code path is taken.

The uniqueness requirement for the patch identifier only extends to this workflow; patches between workflows are not evaluated, so a duplicate identifier can be used across multiple workflows without conflict.

The following example demonstrates this by checking if the use-sms patch has been applied to this workflow instance. If so, ths SendSMS activity is executed; otherwise, it falls back to the original path and uses the SendEmail activity.

• .NET
• Go
• Python

public sealed class MyWorkflow : Workflow<string, object?>
{
    public overrride async Task<object?> RunAsync(WorkflowContext context, string input)
    {
        // ...
        if (context.IsPatched("use-sms"))
        {
            // Patched code
            await context.CallActivityAsync(nameof(SendSMS), input);
        }
        else {
            // Original code
            await context.CallActivityAsync(nameof(SendEmail), input);
        }
        return null;
    }
}

import "github.com/dapr/durabletask-go/workflow"

func Workflow(ctx *workflow.WorkflowContext) error {
  // ...
  if ctx.IsPatched("use-sms") {
    if err := ctx.CallActivity("SendSMS", ctx.GetInput()).Await(); err != nil {
      return err
    }
  } else {
    if err := ctx.CallActivity("SendEmail", ctx.GetInput()).Await(); err != nil {
      return err
    }
  }
  // ...
}

from dapr.ext.workflow import DaprWorkflowContext, WorkflowRuntime

wfr = WorkflowRuntime()

@wfr.workflow
def my_workflow(ctx: DaprWorkflowContext, wf_input: str):
  # ...
  if ctx.is_patched("use-sms"):
    yield ctx.call_activity(send_sms)
  else:
    yield ctx.call_activity(send_email)
  # ...

Using this approach, new workflow instances will take the patched code path but existing workflows that are in-flight when the patch is introduced will continue to use the original code path. Patch checks are recorded in the workflow instance history the first time they are evaluated, meaning that it’s safe to use the same identifier in different places throughout your workflow.

Again, it’s imperative that once your patched workflow is running in production, you do not repurpose that identifier again though. Once deployed, it should be assumed that the engine will handle the workflow deterministically, but adding a new patch with a previously used identifier would break that contract: if your new code was inserted earlier than an in-flight workflow instance had evaluated to that point, when it replayed, it would take your patch branch, but your changes may no longer match the existing workflow history and cause the workflow to stall indefinitely (at least until you removed the new or updated it to use a different unique identifier).

The list of patches applied to a workflow are stored in the workflow’s history, so it’s important to be mindful that the more patches you use, the larger your workflow state history. This will increasingly have a negative impact on workflow performance because it needs to be retrieved every replay and as the state grows, this incurs added retrieval and parsing overhead.

Validating stalls

In addition to the re-use of an identifier as described above, there are several other reasons for workflows to stall when using patches:

• Removing (or renaming) a patch identifier
• Changing the order of patches

You can use the workflow commands in the Dapr CLI to check for stalled workflows. For example, the following is what the dapr workflow list command would look like if a workflow is stalled:

> dapr workflow list
NAME           ID          STATUS     AGE
workflow       <ID>        STALLED    9m39s

The following is what the dapr workflow history command would look like when a workflow is stalled:

> dapr workflow history <ID> -k -o wide
PLAY  TYPE                 NAME      TIMESTAMP    ELAPSED    STATUS   DETAILS        ROUTER     EXECUTION ID  ATTRS
0     ExecutionStarted     workflow  <TIMESTAMP>  Age:15.8h  RUNNING  workflowStart  workflows  <EXEC_ID>     input=2026-01-22T14:44:02.728101
1     OrchestratorStarted            <TIMESTAMP>  25.3ms     RUNNING  replay                                  versionName=workflow_v1
1     ExecutionStalled               <TIMESTAMP>  8.9m       STALLED                                          reason=VERSION_NAME_MISMATCH;description=Version not available: workflow_v1

Patching best practices

The following represents some additional suggestions that should be considered to eliminate the possibility of a stalled or failed workflow as a result of using patches:

• The original code must remain available and unchanged when applying a patch so it’s present for in-flight workflows to evaluate in the same way.
• Patches should be applied in an additive way meaning that once they’re added and your application deployed, you should never move nor remove them from your workflow. They must exist to retain in-flight workflow determinism.
• As covered above, you must not re-use a patch identifier that you’ve used in previous deployments as this will break the determinism guarantee. However, you’re welcome to use that same identifier within the same deployment in multiple places and without concern across different workflows.
• If you can avoid using an else branch when applying your patch, it will make it easier to apply future patches. While this generally can’t be avoided if you’re replacing existing code, it’s certainly manageable if you’re simply adding new logic to your workflow.
• If you must nest patches, you must do so within existing patches. For example your new patch cannot wrap an existing patch else in the else branch. Doing so would other mean that the originally code cannot be accessed by in-flight workflows, breaking the determinism guarantee.

Named Workflow Versioning

Named workflow versioning represents our second approach to facilitating a means of versioning your workflows in a deterministically safe way. In this approach, you introduce a new workflow version by duplicating an existing workflow and assigning it a new “versioned” name. Because you can then refactor your workflow logic from scratch to remove any patches and otherwise introduce any other changes you want, this approach offers a clean break from previous workflows versions.

While the particulars of how this is achieved will vary depending on the language SDK you’re using, generally, the idea is that you’ll duplicate your latest workflow, assign it a unique name that reflects the newer version and register this with your SDK. A registry will be built of each workflow so that at runtime, Dapr will call in with a workflow name to execute and the SDK will either route to the old workflow (if in-flight) or to the newer version.

Do note that across all SDKs, the runtime does not migrate workflows between versions sequentially. Rather, when the SDKs receive a request to run a new workflow, it chooses to run the latest version, not simply the “next” one, so there’s is no need to handle any compensation logic between versions.

The language SDKs may expose a way to register versions when using the same workflow name, but this varies by SDK, so refer to the documentation for a specific SDK for more information. For example, some may use a mechanism by which you would explicitly supply an is_latest flag to indicate which version is the latest.

When the SDK receives a request to run a workflow in a version that is not registered, the workflow will stall. This can happen naturally during application rollouts, but can also happen if a version is removed while some workflow instances are still using it. The recommendation is that older named workflow versions should not be deleted at all unless you’ve independently confirmed that there are no outstanding (in-flight or dormant) workflow instances that are running against that version.

• .NET
• Go
• Python

import "github.com/dapr/durabletask-go/workflow"

func WorkflowV1(ctx *workflow.WorkflowContext) error {
  // ...
  return nil
}

func WorkflowV2(ctx *workflow.WorkflowContext) error {
  // ...
  return nil
}

import "github.com/dapr/durabletask-go/workflow"

registry := workflow.NewRegistry()
// This is the previous workflow version, so `isLatest` is false
registry.AddVersionedWorkflow("Workflow", false, WorkflowV1)
// This is the latest workflow version, so `isLatest` is true
registry.AddVersionedWorkflow("Workflow", true, WorkflowV2)

import "github.com/dapr/durabletask-go/workflow"

registry := workflow.NewRegistry()
// This is the previous workflow version, so `isLatest` is false
registry.AddVersionedWorkflow("Workflow", "WorkflowV1", false, WorkflowV1)
// This is the latest workflow version, so `isLatest` is true
registry.AddVersionedWorkflow("Workflow", "WorkflowV2", true, WorkflowV2)

from dapr.ext.workflow import DaprWorkflowContext, WorkflowRuntime

wfr = WorkflowRuntime()

@wfr.versioned_workflow(name="workflow")
def workflow_v1(ctx: DaprWorkflowContext, wf_input: str):
  # ...

@wfr.versioned_workflow(name="workflow", is_latest=True)
def workflow_v2(ctx: DaprWorkflowContext, wf_input: str):
  # ...

from dapr.ext.workflow import DaprWorkflowContext, WorkflowRuntime

wfr = WorkflowRuntime()

@wfr.versioned_workflow(name="workflow", version_name="workflow_v1")
def workflow_v1(ctx: DaprWorkflowContext, wf_input: str):
  # ...

@wfr.versioned_workflow(name="workflow", version_name="workflow_v2", is_latest=True)
def workflow_v2(ctx: DaprWorkflowContext, wf_input: str):
  # ...

Versioning Process Guidance

Because named workflows are fully compatible with patches, the approach is that changes to your workflow are initially made by applying patches to your existing workflow logic. Eventually you’ll hit one of the following problems after applying several patches:

• You’re concerned about the overhead to your workflow state history because of the number of applied patches;
• The golden path through your workflow logic is hard to follow;
• You need to make another workflow tweak, but can’t figure out how to apply a patch that doesn’t break the determinism guarantee.

At this point, the recommendation is that you introduce a named version of your workflow. Copy your existing workflow, change its name to reflect whatever versioning strategy you’re using in your SDK and refactor to remove all your patches and retain only your intended “latest” logic. Apply your new changes (no need for a patch here – it’s a new workflow) and deploy it.

Here, apply patches again as needed to address future changes and when necessary, introduce another named workflow version and continue. Repeat this process indefinitely.

It is recommended that you retain old workflow versions until you’re completely confident that nothing is in-flight (including deferred with a long-running timer) that uses any of your old workflow versions.

Workflow versioning doesn’t address changing the types of inputs and outputs of the workflows themselves. As general guidance, it is recommended to either return serialized values like strings (making the consumer of the output responsible for being able to deserialize different outputs over time) or adopt complex types that incorporate optional properties to include new expected output values.

5 - Detached workflows

In addition to child workflows, a workflow can schedule another workflow as a detached workflow. With a detached workflow, however, the relationship is fire-and-forget: the calling workflow asks the runtime to start a new, fully independent workflow instance and then immediately continues with the rest of its own logic, without waiting for the detached workflow to complete.

When you schedule a detached workflow, the call returns the new instance ID synchronously. The detached workflow then runs as its own top-level instance, with its own instance ID, history, and lifecycle, exactly as if it had been scheduled directly by a client. There is no parent linkage: the detached workflow’s success or failure does not flow back to the caller, and terminating the caller does not terminate the detached workflow.

This reference is one-directional. The calling workflow records the spawn as a single event in its own history, so it keeps a reference to the detached instance it created. The detached workflow, however, holds no reference back to its caller: it has no parent instance and behaves like a standalone, top-level workflow.

Recording the spawn in the caller’s history is also what keeps the calling workflow deterministic. As with any workflow action, the spawn must be captured in the history so that, when the workflow replays, the runtime knows the detached workflow was already created and does not schedule it a second time. Without this event, a replay would have no way to know whether the detached workflow had already been started.

Detached workflows compared to child workflows

If you need the result of the scheduled workflow, want its failures to propagate, or want it to be terminated alongside its parent, use a child workflow instead.

When to use detached workflows

Detached workflows are a good fit when a workflow needs to trigger independent work that should be isolated from the caller, such as:

• Multi-tenant fan-out: a workflow that iterates over tenants, organizations, or customers and starts an isolated workflow per entity, where you want hard isolation between each tenant’s work and the orchestrating workflow.
• Fire-and-forget downstream work: triggering follow-on processing (notifications, audits, cleanup) whose outcome should not affect the workflow that started it.
• Forking a new history chain: starting a long-running or independently-managed workflow that should not inflate the caller’s history or share its failure domain.

Schedule a detached workflow

The following example schedules a detached AuditWorkflow from within ParentWorkflow. Unlike a child workflow, there is no task to await: the call returns the new instance ID synchronously and the scheduling workflow continues immediately. Both the scheduling workflow and the detached workflow must be registered with the worker, the same way as any other workflow.

• Go
• .NET

// ParentWorkflow schedules a detached workflow and continues immediately,
// without waiting for it to finish.
func ParentWorkflow(ctx *workflow.WorkflowContext) (any, error) {
	// ScheduleNewDetachedWorkflow starts a detached, fire-and-forget workflow
	// and returns its instance ID synchronously. There is no task to await.
	instanceID, err := ctx.ScheduleNewDetachedWorkflow(AuditWorkflow,
		workflow.WithDetachedWorkflowInput("order-1234"),
	)
	if err != nil {
		return nil, err
	}

	// The parent continues without waiting. The detached workflow's success
	// or failure does not affect this workflow.
	return instanceID, nil
}

// AuditWorkflow runs independently as its own top-level workflow instance.
func AuditWorkflow(ctx *workflow.WorkflowContext) (any, error) {
	var orderID string
	if err := ctx.GetInput(&orderID); err != nil {
		return nil, err
	}
	if err := ctx.CreateTimer(3 * time.Second).Await(nil); err != nil {
		return nil, err
	}
	return "audit completed for " + orderID, nil
}

// ParentWorkflow schedules a detached workflow and continues immediately,
// without waiting for it to finish.
public sealed class ParentWorkflow : Workflow<string, string>
{
    public override async Task<string> RunAsync(WorkflowContext context, string orderId)
    {
        // Returns the new instance ID. There is no result to await.
        string instanceId = await context.ScheduleNewDetachedWorkflowAsync(
            nameof(AuditWorkflow), input: orderId);
        return instanceId;
    }
}

// AuditWorkflow runs independently as its own top-level workflow instance.
public sealed class AuditWorkflow : Workflow<string, string>
{
    public override async Task<string> RunAsync(WorkflowContext context, string orderId)
    {
        await context.CreateTimer(TimeSpan.FromSeconds(3));
        return $"audit completed for {orderId}";
    }
}

Detached workflow options

When scheduling a detached workflow, you can set the following options to control the new instance. The exact API and naming depend on the SDK.

Related links

• Workflow overview
• Workflow features and concepts
• Child workflows
• Multi application workflows
• How to: Author workflows

6 - Stateful workflow client

Every time a workflow makes progress, the Dapr sidecar hands the workflow SDK the history it needs to replay the workflow back to its current point. Historically that meant sending the instance’s entire committed history on every turn, so the same events were serialized, transferred, and deserialized again and again as the workflow grew.

The stateful workflow client removes that repetition. The SDK’s workflow worker keeps the history it has already replayed in memory, tells the sidecar it can do so, and the sidecar then sends only the events added since the last turn.

Why it matters

A workflow’s history only grows. Each activity call, timer, and external event appends to it, and the workflow is replayed from that history on every turn.

When the full history is sent every turn, the cost of a single turn grows with the length of the whole workflow. A workflow on its hundredth turn re-receives everything from the previous ninety-nine. The work is paid three times over: the sidecar serializes the history, the connection carries it, and the worker deserializes it.

With the stateful workflow client, a warm worker receives only the events committed since its previous turn, which is typically a handful regardless of how long the workflow has been running. The per-turn history payload stops growing with the length of the workflow.

The workflows that benefit most are the ones where history accumulates:

• Long-running workflows, and workflows with large loops.
• Monitor-pattern and eternal workflows that run for days or longer.
• Fan-out/fan-in workflows that collect many activity completions.

As a concrete illustration, Dapr’s integration tests run a workflow with 40 sequential activities. At most two of its turns are sent as a full history, and every remaining turn is sent as a delta.

How it works

When the worker opens its work item stream, it advertises that it retains history between turns. The sidecar records this per stream, then tracks how much committed history each connected stream has been given. On later turns it omits the prefix the worker already holds and tells the worker how many events it left out.

Two separate pieces of state make this work:

• The sidecar stores only a watermark: a count, per instance, of how many committed events that stream has been sent.
• The worker stores the actual events.

Both are scoped to a single work item stream and neither is persisted.

The first two turns are always full sends

The sidecar records its watermark only after it has prepared a work item, which produces a short warm-up:

• Turn 1 starts from an empty committed history, so there is nothing to omit and the watermark is recorded as zero.
• Turn 2 now has real committed history, but the watermark is still zero, so there is still no prefix the worker is known to hold.
• Turn 3 onwards the watermark is non-zero and the sidecar sends deltas.

This warm-up repeats whenever a worker starts cold, including after a reconnect.

Cache hits and misses

The worker validates every delta before using it: the number of events it has cached must exactly match the count the sidecar says it omitted. If it does not match, or nothing is cached at all, the worker treats it as a cache miss and fetches the full history from the sidecar with a GetInstanceHistory call.

A cache miss costs one extra call and is always safe, which is what lets the cache be evicted freely.

When cached history is dropped

The worker releases an instance’s cached history when:

• The instance ends. Completion, failure, termination, and continue-as-new all end the current execution, after which the cached history no longer extends.
• The entry goes idle. Each entry has a sliding time-to-live, refreshed on every turn, that reclaims memory from instances that stop receiving turns without completing.
• A cache bound is reached. The least recently used entries are evicted first, so the active working set is preserved.
• The stream reconnects. The cache lives only as long as the work item stream. A reconnected worker starts cold and is re-warmed with a full history.

What this does not change

Your workflow code. This is a transport optimization between the sidecar and the SDK. Workflow and activity code is unaffected, and replay behaves exactly as before.

Correctness. The sidecar only ever omits a prefix that it sent to that same stream in the first place, so the cached prefix plus the delta is, by construction, the history the sidecar holds. Three independent fallbacks protect the rest:

• A prefix that does not match the expected length is treated as a miss and recovered with a full fetch.
• A history that shrinks, as it does on continue-as-new, never produces a delta and is re-sent in full.
• A turn that lands on any other stream finds no watermark there and is re-sent in full.

The payload size limit. Delta sends shrink what crosses the wire, but they do not raise the effective ceiling on history size. The sidecar checks a workflow’s size against the maximum body size using the full history held in state, before the work item is reduced to a delta. A workflow with a very large history still stalls at the same point, even though the delta that would have been sent was small. The check is deliberately conservative: at the point it runs, the sidecar does not yet know which worker will receive the turn, and a worker that is cold for that instance is always sent the full history.

Running multiple workers

When several workers, or several replicas of the same app, are connected to a sidecar, the sidecar prefers to route an instance’s turns back to the stream that already holds its history. It does this with rendezvous hashing, so when a worker joins or leaves, only a small fraction of instances change owner and most caches survive the change.

A few properties are worth knowing:

• Affinity is a preference, not a constraint. If the preferred worker is busy or gone, the turn goes to another worker after a brief wait, and that worker is simply sent the full history. Throughput and liveness always take priority over cache hits.
• Warm state belongs to one sidecar. Which sidecar owns an instance is decided by actor placement. Cached history is never transferred between sidecars.
• Worker restarts are safe. A new or reconnected worker starts cold, is re-warmed with a full history, and resumes receiving deltas.

Enabling and disabling

The stateful workflow client is enabled by default. You may want to disable it if your workers are memory constrained, or to rule it out while debugging.

• Python
• .NET
• Java
• Go

from dapr.ext.workflow import WorkflowRuntime

runtime = WorkflowRuntime(disable_stateful_history=True)

builder.Services.AddDaprWorkflow(options =>
{
    options.RegisterWorkflow<MyWorkflow>();
    options.DisableStatefulHistory = true;
});

WorkflowRuntime runtime = new WorkflowRuntimeBuilder()
    .registerWorkflow(MyWorkflow.class)
    .withStatefulHistoryDisabled(true)
    .build();

import (
	"context"
	"log"

	"github.com/dapr/durabletask-go/backend"
	dtclient "github.com/dapr/durabletask-go/client"
	"github.com/dapr/durabletask-go/task"
	"github.com/dapr/go-sdk/client"
)

daprClient, err := client.NewClient()
if err != nil {
	log.Fatal(err)
}

registry := task.NewTaskRegistry()
if err := registry.AddWorkflow(MyWorkflow); err != nil {
	log.Fatal(err)
}

worker := dtclient.NewTaskHubGrpcClient(daprClient.GrpcClientConn(), backend.DefaultLogger(),
	dtclient.WithStatefulHistoryDisabled(),
)
if err := worker.StartWorkItemListener(context.Background(), registry); err != nil {
	log.Fatal(err)
}

A worker that disables the feature does not advertise it, so the sidecar sends the full history on every turn and the worker keeps no cache.

Tuning the cache

The defaults suit most applications and you should not normally need to change them.

Every bound is safe to hit: an evicted entry costs one GetInstanceHistory call the next time that instance runs.

• Python
• .NET
• Java
• Go

from dapr.ext.workflow import WorkflowRuntime

runtime = WorkflowRuntime(
    history_cache_ttl=600,
    history_cache_max_instances=10_000,
    history_cache_max_bytes=256 * 1024 * 1024,
)

builder.Services.AddDaprWorkflow(options =>
{
    options.RegisterWorkflow<MyWorkflow>();
    options.HistoryCacheTtl = TimeSpan.FromMinutes(10);
    options.HistoryCacheMaxInstances = 10_000;
    options.HistoryCacheMaxBytes = 256L * 1024 * 1024;
});

WorkflowRuntime runtime = new WorkflowRuntimeBuilder()
    .registerWorkflow(MyWorkflow.class)
    .withHistoryCacheTtl(Duration.ofMinutes(10))
    .withHistoryCacheMaxInstances(10_000)
    .withHistoryCacheMaxBytes(256L * 1024 * 1024)
    .build();

import (
	"log"
	"time"

	"github.com/dapr/durabletask-go/backend"
	dtclient "github.com/dapr/durabletask-go/client"
	"github.com/dapr/go-sdk/client"
)

daprClient, err := client.NewClient()
if err != nil {
	log.Fatal(err)
}

worker := dtclient.NewTaskHubGrpcClient(daprClient.GrpcClientConn(), backend.DefaultLogger(),
	dtclient.WithWorkflowHistoryCacheTTL(10*time.Minute),
	dtclient.WithWorkflowHistoryCacheMaxInstances(10_000),
	dtclient.WithWorkflowHistoryCacheMaxBytes(256*1024*1024),
)

dtclient.WithWorkflowHistoryCacheSweepInterval(30 * time.Second)

Version compatibility

The stateful workflow client needs a Dapr v1.19 or later sidecar and a worker built with one of these SDKs:

• Python, Java, and .NET: SDK 1.19 or later.
• Go: Go SDK v1.16.0 or later, or durabletask-go v0.15.0 or later when you use it directly.
• JavaScript: not supported. The JavaScript SDK workflow engine does not use the shared durabletask client library, so its workers receive the full history on every turn.

The feature is negotiated per connection, so mixed versions degrade to the previous behavior with no configuration and no errors:

• A newer SDK with an older sidecar. The sidecar ignores the capability it does not recognize and never sends a delta. The worker receives full histories, exactly as before.
• An older SDK with a newer sidecar. The worker advertises nothing, so the sidecar sends full histories to it.
• Mixed workers on one sidecar. Support is tracked per connection, so workers that support the feature receive deltas while those that do not receive full histories, at the same time.

Next steps

Learn how the sidecar and the workflow SDK communicate in the workflow architecture overview.

Related links

• Workflow architecture
• Workflow payload size
• Workflow features and concepts
• Workflow overview
• How to author a workflow

7 - Workflow patterns

Dapr Workflows simplify complex, stateful coordination requirements in microservice architectures. The following sections describe several application patterns that can benefit from Dapr Workflows.

Task chaining

In the task chaining pattern, multiple steps in a workflow are run in succession, and the output of one step may be passed as the input to the next step. Task chaining workflows typically involve creating a sequence of operations that need to be performed on some data, such as filtering, transforming, and reducing.

In some cases, the steps of the workflow may need to be orchestrated across multiple microservices. For increased reliability and scalability, you’re also likely to use queues to trigger the various steps.

While the pattern is simple, there are many complexities hidden in the implementation. For example:

• What happens if one of the microservices are unavailable for an extended period of time?
• Can failed steps be automatically retried?
• If not, how do you facilitate the rollback of previously completed steps, if applicable?
• Implementation details aside, is there a way to visualize the workflow so that other engineers can understand what it does and how it works?

Dapr Workflow solves these complexities by allowing you to implement the task chaining pattern concisely as a simple function in the programming language of your choice, as shown in the following example.

• Python
• JavaScript
• .NET
• Java
• Go

import dapr.ext.workflow as wf


def task_chain_workflow(ctx: wf.DaprWorkflowContext, wf_input: int):
    try:
        result1 = yield ctx.call_activity(step1, input=wf_input)
        result2 = yield ctx.call_activity(step2, input=result1)
        result3 = yield ctx.call_activity(step3, input=result2)
    except Exception as e:
        yield ctx.call_activity(error_handler, input=str(e))
        raise
    return [result1, result2, result3]


def step1(ctx, activity_input):
    print(f'Step 1: Received input: {activity_input}.')
    # Add step-specific logic here (e.g. data transformation)
    return activity_input + 1


def step2(ctx, activity_input):
    print(f'Step 2: Received input: {activity_input}.')
    # Add step-specific logic here (e.g. data transformation)
    return activity_input * 2


def step3(ctx, activity_input):
    print(f'Step 3: Received input: {activity_input}.')
    # Add step-specific logic here (e.g. data transformation)
    return activity_input ^ 2


def error_handler(ctx, error):
    print(f'Executing error handler: {error}.')
    # Add logic here to undo partial changes (e.g., release inventory)

import { DaprWorkflowClient, WorkflowActivityContext, WorkflowContext, WorkflowRuntime, TWorkflow } from "@dapr/dapr";

async function start() {
  // Update the gRPC client and worker to use a local address and port
  const daprHost = "localhost";
  const daprPort = "50001";
  const workflowClient = new DaprWorkflowClient({
    daprHost,
    daprPort,
  });
  const workflowRuntime = new WorkflowRuntime({
    daprHost,
    daprPort,
  });

  const hello = async (_: WorkflowActivityContext, name: string) => {
    return `Hello ${name}!`;
  };

  const sequence: TWorkflow = async function* (ctx: WorkflowContext): any {
    const cities: string[] = [];

    const result1 = yield ctx.callActivity(hello, "Tokyo");
    cities.push(result1);
    const result2 = yield ctx.callActivity(hello, "Seattle");
    cities.push(result2);
    const result3 = yield ctx.callActivity(hello, "London");
    cities.push(result3);

    return cities;
  };

  workflowRuntime.registerWorkflow(sequence).registerActivity(hello);

  // Wrap the worker startup in a try-catch block to handle any errors during startup
  try {
    await workflowRuntime.start();
    console.log("Workflow runtime started successfully");
  } catch (error) {
    console.error("Error starting workflow runtime:", error);
  }

  // Schedule a new orchestration
  try {
    const id = await workflowClient.scheduleNewWorkflow(sequence);
    console.log(`Orchestration scheduled with ID: ${id}`);

    // Wait for orchestration completion
    const state = await workflowClient.waitForWorkflowCompletion(id, undefined, 30);

    console.log(`Orchestration completed! Result: ${state?.serializedOutput}`);
  } catch (error) {
    console.error("Error scheduling or waiting for orchestration:", error);
  }

  await workflowRuntime.stop();
  await workflowClient.stop();

  // stop the dapr side car
  process.exit(0);
}

start().catch((e) => {
  console.error(e);
  process.exit(1);
  // Add logic here to undo partial changes (e.g., refund payment)
});

// Expotential backoff retry policy that survives long outages
var retryOptions = new WorkflowTaskOptions
{
    RetryPolicy = new WorkflowRetryPolicy(
        firstRetryInterval: TimeSpan.FromMinutes(1),
        backoffCoefficient: 2.0,
        maxRetryInterval: TimeSpan.FromHours(1),
        maxNumberOfAttempts: 10),
};

try
{
    var result1 = await context.CallActivityAsync<string>("Step1", wfInput, retryOptions);
    var result2 = await context.CallActivityAsync<byte[]>("Step2", result1, retryOptions);
    var result3 = await context.CallActivityAsync<long[]>("Step3", result2, retryOptions);
    return string.Join(", ", result4);
}
catch (TaskFailedException) // Task failures are surfaced as TaskFailedException
{
    // Retries expired - apply custom compensation logic
    await context.CallActivityAsync<long[]>("MyCompensation", options: retryOptions);
    throw;
}

public class ChainWorkflow extends Workflow {
    @Override
    public WorkflowStub create() {
        return ctx -> {
            StringBuilder sb = new StringBuilder();
            String wfInput = ctx.getInput(String.class);
            String result1 = ctx.callActivity("Step1", wfInput, String.class).await();
            String result2 = ctx.callActivity("Step2", result1, String.class).await();
            String result3 = ctx.callActivity("Step3", result2, String.class).await();
            String result = sb.append(result1).append(',').append(result2).append(',').append(result3).toString();
            ctx.complete(result);
        };
    }
}

    class Step1 implements WorkflowActivity {

        @Override
        public Object run(WorkflowActivityContext ctx) {
            Logger logger = LoggerFactory.getLogger(Step1.class);
            logger.info("Starting Activity: " + ctx.getName());
            // Add step-specific logic here (e.g. data transformation)
            return null;
        }
    }

    class Step2 implements WorkflowActivity {

        @Override
        public Object run(WorkflowActivityContext ctx) {
            Logger logger = LoggerFactory.getLogger(Step2.class);
            logger.info("Starting Activity: " + ctx.getName());
            // Add step-specific logic here (e.g. data transformation)
            return null;
        }
    }

    class Step3 implements WorkflowActivity {

        @Override
        public Object run(WorkflowActivityContext ctx) {
            Logger logger = LoggerFactory.getLogger(Step3.class);
            logger.info("Starting Activity: " + ctx.getName());
            // Add step-specific logic here (e.g. data transformation)
            return null;
        }
    }

func TaskChainWorkflow(ctx *workflow.WorkflowContext) (any, error) {
	var input int
	if err := ctx.GetInput(&input); err != nil {
		return "", err
	}
	var result1 int
	if err := ctx.CallActivity(Step1, workflow.ActivityInput(input)).Await(&result1); err != nil {
		return nil, err
	}
	var result2 int
	if err := ctx.CallActivity(Step2, workflow.ActivityInput(input)).Await(&result2); err != nil {
		return nil, err
	}
	var result3 int
	if err := ctx.CallActivity(Step3, workflow.ActivityInput(input)).Await(&result3); err != nil {
		return nil, err
	}
	return []int{result1, result2, result3}, nil
}
func Step1(ctx workflow.ActivityContext) (any, error) {
	var input int
	if err := ctx.GetInput(&input); err != nil {
		return "", err
	}
	fmt.Printf("Step 1: Received input: %s", input)
	return input + 1, nil
}
func Step2(ctx workflow.ActivityContext) (any, error) {
	var input int
	if err := ctx.GetInput(&input); err != nil {
		return "", err
	}
	fmt.Printf("Step 2: Received input: %s", input)
	return input * 2, nil
}
func Step3(ctx workflow.ActivityContext) (any, error) {
	var input int
	if err := ctx.GetInput(&input); err != nil {
		return "", err
	}
	fmt.Printf("Step 3: Received input: %s", input)
	return int(math.Pow(float64(input), 2)), nil
}

As you can see, the workflow is expressed as a simple series of statements in the programming language of your choice. This allows any engineer in the organization to quickly understand the end-to-end flow without necessarily needing to understand the end-to-end system architecture.

Behind the scenes, the Dapr Workflow runtime:

• Takes care of executing the workflow and ensuring that it runs to completion.
• Saves progress automatically.
• Automatically resumes the workflow from the last completed step if the workflow process itself fails for any reason.
• Enables error handling to be expressed naturally in your target programming language, allowing you to implement compensation logic easily.
• Provides built-in retry configuration primitives to simplify the process of configuring complex retry policies for individual steps in the workflow.

Fan-out/fan-in

In the fan-out/fan-in design pattern, you execute multiple tasks simultaneously across potentially multiple workers, wait for them to finish, and perform some aggregation on the result.

In addition to the challenges mentioned in the previous pattern, there are several important questions to consider when implementing the fan-out/fan-in pattern manually:

• How do you control the degree of parallelism?
• How do you know when to trigger subsequent aggregation steps?
• What if the number of parallel steps is dynamic?

Dapr Workflows provides a way to express the fan-out/fan-in pattern as a simple function, as shown in the following example:

# Start the workflow
dapr workflow run DataProcessingWorkflow \
  --app-id processor \
  --input '{"items": ["item1", "item2", "item3"]}'

# Monitor parallel execution
dapr workflow history <instance-id> --app-id processor --output json

• Python
• JavaScript
• .NET
• Java
• Go

import time
from typing import List
import dapr.ext.workflow as wf


def batch_processing_workflow(ctx: wf.DaprWorkflowContext, wf_input: int):
    # get a batch of N work items to process in parallel
    work_batch = yield ctx.call_activity(get_work_batch, input=wf_input)

    # schedule N parallel tasks to process the work items and wait for all to complete
    parallel_tasks = [ctx.call_activity(process_work_item, input=work_item) for work_item in work_batch]
    outputs = yield wf.when_all(parallel_tasks)

    # aggregate the results and send them to another activity
    total = sum(outputs)
    yield ctx.call_activity(process_results, input=total)


def get_work_batch(ctx, batch_size: int) -> List[int]:
    return [i + 1 for i in range(batch_size)]


def process_work_item(ctx, work_item: int) -> int:
    print(f'Processing work item: {work_item}.')
    time.sleep(5)
    result = work_item * 2
    print(f'Work item {work_item} processed. Result: {result}.')
    return result


def process_results(ctx, final_result: int):
    print(f'Final result: {final_result}.')

import {
  Task,
  DaprWorkflowClient,
  WorkflowActivityContext,
  WorkflowContext,
  WorkflowRuntime,
  TWorkflow,
} from "@dapr/dapr";

// Wrap the entire code in an immediately-invoked async function
async function start() {
  // Update the gRPC client and worker to use a local address and port
  const daprHost = "localhost";
  const daprPort = "50001";
  const workflowClient = new DaprWorkflowClient({
    daprHost,
    daprPort,
  });
  const workflowRuntime = new WorkflowRuntime({
    daprHost,
    daprPort,
  });

  function getRandomInt(min: number, max: number): number {
    return Math.floor(Math.random() * (max - min + 1)) + min;
  }

  async function getWorkItemsActivity(_: WorkflowActivityContext): Promise<string[]> {
    const count: number = getRandomInt(2, 10);
    console.log(`generating ${count} work items...`);

    const workItems: string[] = Array.from({ length: count }, (_, i) => `work item ${i}`);
    return workItems;
  }

  function sleep(ms: number): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, ms));
  }

  async function processWorkItemActivity(context: WorkflowActivityContext, item: string): Promise<number> {
    console.log(`processing work item: ${item}`);

    // Simulate some work that takes a variable amount of time
    const sleepTime = Math.random() * 5000;
    await sleep(sleepTime);

    // Return a result for the given work item, which is also a random number in this case
    // For more information about random numbers in workflow please check
    // https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-code-constraints?tabpane=csharp#random-numbers
    return Math.floor(Math.random() * 11);
  }

  const workflow: TWorkflow = async function* (ctx: WorkflowContext): any {
    const tasks: Task<any>[] = [];
    const workItems = yield ctx.callActivity(getWorkItemsActivity);
    for (const workItem of workItems) {
      tasks.push(ctx.callActivity(processWorkItemActivity, workItem));
    }
    const results: number[] = yield ctx.whenAll(tasks);
    const sum: number = results.reduce((accumulator, currentValue) => accumulator + currentValue, 0);
    return sum;
  };

  workflowRuntime.registerWorkflow(workflow);
  workflowRuntime.registerActivity(getWorkItemsActivity);
  workflowRuntime.registerActivity(processWorkItemActivity);

  // Wrap the worker startup in a try-catch block to handle any errors during startup
  try {
    await workflowRuntime.start();
    console.log("Worker started successfully");
  } catch (error) {
    console.error("Error starting worker:", error);
  }

  // Schedule a new orchestration
  try {
    const id = await workflowClient.scheduleNewWorkflow(workflow);
    console.log(`Orchestration scheduled with ID: ${id}`);

    // Wait for orchestration completion
    const state = await workflowClient.waitForWorkflowCompletion(id, undefined, 30);

    console.log(`Orchestration completed! Result: ${state?.serializedOutput}`);
  } catch (error) {
    console.error("Error scheduling or waiting for orchestration:", error);
  }

  // stop worker and client
  await workflowRuntime.stop();
  await workflowClient.stop();

  // stop the dapr side car
  process.exit(0);
}

start().catch((e) => {
  console.error(e);
  process.exit(1);
});

// Get a list of N work items to process in parallel.
object[] workBatch = await context.CallActivityAsync<object[]>("GetWorkBatch", null);

// Schedule the parallel tasks, but don't wait for them to complete yet.
var parallelTasks = new List<Task<int>>(workBatch.Length);
for (int i = 0; i < workBatch.Length; i++)
{
    Task<int> task = context.CallActivityAsync<int>("ProcessWorkItem", workBatch[i]);
    parallelTasks.Add(task);
}

// Everything is scheduled. Wait here until all parallel tasks have completed.
await Task.WhenAll(parallelTasks);

// Aggregate all N outputs and publish the result.
int sum = parallelTasks.Sum(t => t.Result);
await context.CallActivityAsync("PostResults", sum);

public class FaninoutWorkflow extends Workflow {
    @Override
    public WorkflowStub create() {
        return ctx -> {
            // Get a list of N work items to process in parallel.
            Object[] workBatch = ctx.callActivity("GetWorkBatch", Object[].class).await();
            // Schedule the parallel tasks, but don't wait for them to complete yet.
            List<Task<Integer>> tasks = Arrays.stream(workBatch)
                    .map(workItem -> ctx.callActivity("ProcessWorkItem", workItem, int.class))
                    .collect(Collectors.toList());
            // Everything is scheduled. Wait here until all parallel tasks have completed.
            List<Integer> results = ctx.allOf(tasks).await();
            // Aggregate all N outputs and publish the result.
            int sum = results.stream().mapToInt(Integer::intValue).sum();
            ctx.complete(sum);
        };
    }
}

func BatchProcessingWorkflow(ctx *workflow.WorkflowContext) (any, error) {
	var input int
	if err := ctx.GetInput(&input); err != nil {
		return 0, err
	}
	var workBatch []int
	if err := ctx.CallActivity(GetWorkBatch, workflow.ActivityInput(input)).Await(&workBatch); err != nil {
		return 0, err
	}
	parallelTasks := workflow.NewTaskSlice(len(workBatch))
	for i, workItem := range workBatch {
		parallelTasks[i] = ctx.CallActivity(ProcessWorkItem, workflow.ActivityInput(workItem))
	}
	var outputs int
	for _, task := range parallelTasks {
		var output int
		err := task.Await(&output)
		if err == nil {
			outputs += output
		} else {
			return 0, err
		}
	}
	if err := ctx.CallActivity(ProcessResults, workflow.ActivityInput(outputs)).Await(nil); err != nil {
		return 0, err
	}
	return 0, nil
}
func GetWorkBatch(ctx workflow.ActivityContext) (any, error) {
	var batchSize int
	if err := ctx.GetInput(&batchSize); err != nil {
		return 0, err
	}
	batch := make([]int, batchSize)
	for i := 0; i < batchSize; i++ {
		batch[i] = i
	}
	return batch, nil
}
func ProcessWorkItem(ctx workflow.ActivityContext) (any, error) {
	var workItem int
	if err := ctx.GetInput(&workItem); err != nil {
		return 0, err
	}
	fmt.Printf("Processing work item: %d\n", workItem)
	time.Sleep(time.Second * 5)
	result := workItem * 2
	fmt.Printf("Work item %d processed. Result: %d\n", workItem, result)
	return result, nil
}
func ProcessResults(ctx workflow.ActivityContext) (any, error) {
	var finalResult int
	if err := ctx.GetInput(&finalResult); err != nil {
		return 0, err
	}
	fmt.Printf("Final result: %d\n", finalResult)
	return finalResult, nil
}