Workflow Protocol on Dapr Docs

Workflow Protocol - Management API

Mon, 01 Jan 0001 00:00:00 +0000

Workflow Management API

The Workflow Management API allows Dapr clients to control the lifecycle of workflow instances. These APIs are exposed via the standard Dapr gRPC endpoint and are typically made available via the SDKs.

gRPC Service Definition

The management APIs are part of the Dapr service in dapr.proto.runtime.v1. While multiple versions (Alpha1, Beta1) may exist, the following describes the current implementation logic.

StartWorkflow

Starts a new instance of a workflow.

Workflow Protocol - Execution API

Mon, 01 Jan 0001 00:00:00 +0000

Workflow Execution API (Task Hub Protocol)

The Workflow Execution API is a low-level gRPC protocol used by Dapr Workflow SDKs to act as “Workers”. The SDK connects to the Dapr sidecar via this protocol to poll for work and report completion.

The service is named TaskHubSidecarService.

Service Definition (gRPC)

service TaskHubSidecarService {
 rpc GetWorkItems(GetWorkItemsRequest) returns (stream WorkItem);
 rpc CompleteOrchestratorTask(OrchestratorResponse) returns (CompleteBatchResponse);
 rpc CompleteActivityTask(ActivityResponse) returns (CompleteBatchResponse);
 // ... other management methods
}

Worker Lifecycle

Connection: The SDK opens a long-running bidirectional stream to GetWorkItems.
Polling: The SDK receives WorkItem messages from the stream.
Execution:
- If the work item is an Orchestration, the SDK retrieves and replays the history events to determine the next actions.
- If the work item is an Activity, the SDK executes the activity logic.
Completion:
- For Orchestrations, the SDK calls CompleteOrchestratorTask with a list of actions to take.
- For Activities, the SDK calls CompleteActivityTask with the result or failure information.

gRPC Service: `TaskHubSidecarService`

GetWorkItems

Opens a stream to receive work items for orchestrations and activities.

Workflow Protocol - Orchestration Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Orchestration Lifecycle

This document describes the lifecycle of an orchestration at the protocol level, specifically how the Dapr engine and the SDK interact to execute workflow logic reliably.

Replay-based Execution

Dapr Workflows use event sourcing and replay to maintain state. Instead of saving the entire state of the worker process (stack, variables, etc.), Dapr saves a history of events that have occurred.

The Replay Loop

Work Item Arrival: The Dapr engine sends an OrchestratorWorkItem to the SDK via the GetWorkItems stream. This work item contains the full history of the workflow instance plus any new events (e.g., an activity completion or an external event).
Reconstruction: The SDK starts executing the orchestration function from the very beginning.
Deterministic Execution: As the function executes, it encounters “tasks” (e.g., calling an activity, sleeping).
- For each task, the SDK checks the provided History to see if that task has already completed.
- If the task is in the history, the SDK returns the recorded result immediately without actually re-executing the task logic.
- If the task is NOT in the history, the SDK records that this task needs to be scheduled and suspends execution of the orchestration function (typically by throwing a special exception or returning a pending promise).
Reporting: Once the orchestration function is suspended or completes, the SDK sends a CompleteOrchestratorTask request to Dapr. This request contains a list of Actions (e.g., ScheduleTask, CreateTimer) that the engine should perform.
State Commitment: The Dapr engine receives the actions, updates the workflow history in the state store, and schedules any requested tasks (e.g., by sending work to an activity worker).

Step-by-Step Example

Imagine a workflow: Activity A -> Activity B.

Workflow Protocol - Activity Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Activity Lifecycle

Activities are the basic units of work in a Dapr Workflow. Unlike orchestrations, activities are not replayed and do not need to be deterministic. They are executed exactly once per “schedule” (though retries may occur).

Execution Flow

Scheduling: An orchestration requests an activity by sending a ScheduleTask action to the Dapr engine.
Work Item Dispatch: The Dapr engine enqueues an activity task. When an activity worker (SDK) is available, the engine sends an ActivityWorkItem via the GetWorkItems stream.
Execution: The SDK receives the ActivityWorkItem, which contains:
- name: The name of the activity to execute.
- input: The input data for the activity.
- instance_id: The ID of the workflow instance that scheduled the activity.
- task_id: A unique identifier for this specific activity execution.
- task_execution_id: A unique identifier for the specific attempt of this activity. This is useful for implementing idempotency in activity logic.
- completion_token: An opaque token used to correlate the response with this specific work item.
Reporting: After the activity logic finishes, the SDK sends a CompleteActivityTask request back to Dapr.
- Success: The SDK provides the serialized output in the result field.
- Failure: The SDK provides failure_details (error message, type, stack trace).

Task Execution IDs

The task_execution_id (also known as the Task Execution Key) is a unique, runtime-generated string (typically a UUID) that identifies a specific attempt to execute an activity task.

Workflow Protocol - State & History

Mon, 01 Jan 0001 00:00:00 +0000

State and History Management

Dapr Workflows are event-sourced, meaning the state of a workflow is derived from a sequence of events. This document describes how Dapr stores and manages this history and state.

Backend Storage: Dapr Actors

By default, the Dapr Workflow engine uses Dapr Actors as its storage backend. Each workflow instance is mapped to a unique actor instance. This provides:

Concurrency Control: Actors ensure that only one operation is happening on a workflow instance at a time.
Reliability: Actor state is persisted in the configured Dapr State Store.
Timers: Dapr Actors provide durable reminders which are used to implement workflow timers.

Workflow State Schema

The state of a workflow instance (actor) consists of several components:

Workflow Protocol - Versioning

Mon, 01 Jan 0001 00:00:00 +0000

Workflow Versioning

Dapr Workflow supports versioning of workflow definitions, allowing you to update workflow logic while existing instances continue to run on their original logic.

Named Workflow Versioning

When registering a workflow with the Dapr engine, you can provide a version name. This allows multiple versions of the same workflow to coexist.

Default Version: One version of a workflow can be marked as the default. If a client starts a workflow by name without specifying a version, the default version is used.
Specific Version: Clients can request a specific version of a workflow when starting a new instance.

Registration API

SDKs register versioned workflows using the AddVersionedOrchestrator (or similar) method in their task registry.

Workflow Protocol on Dapr Docs

Workflow Protocol - Management API

Workflow Management API

gRPC Service Definition

StartWorkflow

Workflow Protocol - Execution API

Workflow Execution API (Task Hub Protocol)

Service Definition (gRPC)

Worker Lifecycle

gRPC Service: TaskHubSidecarService

GetWorkItems

Workflow Protocol - Orchestration Lifecycle

Orchestration Lifecycle

Replay-based Execution

The Replay Loop

Step-by-Step Example

Workflow Protocol - Activity Lifecycle

Activity Lifecycle

Execution Flow

Task Execution IDs

Workflow Protocol - State & History

State and History Management

Backend Storage: Dapr Actors

Workflow State Schema

Workflow Protocol - Versioning

Workflow Versioning

Named Workflow Versioning

Registration API

gRPC Service: `TaskHubSidecarService`