Skip to main content

​
Workflow Execution Lifecycle

This page follows a typical sequence of events in the execution of a simple workflow, showing how requests flow between User Applications, Frontend, History, Matching services, and Workers.

​
Example Workflow

We’ll trace the execution of this simple workflow: 
function myWorkflow() {
  result = callActivity(myActivity);
  return result;
}
The diagrams below show the detailed interaction between services. For high-level architecture, see Architecture Overview.
In the diagrams below:
  • “Initialize history” and “Append event to history” refer to durable writes to the persistence layer
  • “Persist Mutable State and history tasks” refers to atomic database transactions

​
Step 1: Start Workflow Execution

The user application sends a StartWorkflowExecution request:
  • Workflow History is initialized with [WorkflowExecutionStarted, WorkflowTaskScheduled]
  • A Transfer Task is created to add a Workflow Task to the Matching service

​
State After Step 1

  • History service StartWorkflow handler: service/history/api/startworkflow/api.go
  • Queue processors: service/history/history_engine.go:303
  • Transfer task processor: service/history/queues/queue_immediate.go:150

​
Step 2: Worker Polls and Processes Workflow Task

A worker dequeues the Workflow Task and advances workflow execution:
  • The workflow code executes and becomes blocked on the activity call
  • A WorkflowTaskStarted event is appended to history

​
State After Step 2

  • History service RecordWorkflowTaskStarted handler: service/history/handler.go:319

​
Step 3: Worker Completes Workflow Task with ScheduleActivity Command

The workflow launches an activity, causing the worker to send a ScheduleActivityTask command:
  • Events are appended: WorkflowTaskCompleted, ActivityTaskScheduled
  • A Transfer Task is created to add an Activity Task to Matching

​
State After Step 3

  • History service ScheduleActivityTask command handler: service/history/workflow_task_handler.go:338

​
Step 4: Worker Polls and Executes Activity

A worker dequeues the Activity Task and executes the activity:
  • An ActivityTaskStarted event is appended
  • The activity code runs (can have side effects)

​
State After Step 4

  • History service RecordActivityTaskStarted handler: service/history/handler.go:287

​
Step 5: Worker Completes Activity Task

Once the activity completes, the worker sends the result back:
  • Events are appended: ActivityTaskCompleted, WorkflowTaskScheduled
  • A new Workflow Task is created to allow the workflow to process the result

​
State After Step 5

  • History service RespondActivityTaskCompleted handler: service/history/handler.go:361

​
Step 6: Worker Processes Final Workflow Task

The worker dequeues the Workflow Task and advances the workflow:
  • The workflow finds it has reached its end (received activity result)
  • The worker will send a CompleteWorkflowExecution command
This step has the same sequence diagram as Step 2 above.

​
Step 7: Worker Completes Workflow Execution

The worker sends RespondWorkflowTaskCompleted with a CompleteWorkflowExecution command:
  • Events are appended: WorkflowTaskCompleted, WorkflowExecutionCompleted
  • Additional tasks are created for visibility, archival, and retention

​
Final State

  • History service RespondWorkflowTaskCompleted handler: service/history/handler.go:478

​
Alternative Path: Activity Failure and Retry

If an activity fails, it can be automatically retried:

​
State After Activity Failure

  • History service RespondActivityTaskFailed handler: service/history/handler.go:400
  • Activity retry timer handling: service/history/timer_queue_active_task_executor.go:426

​
Key Takeaways

Every state change is recorded as an immutable event in Workflow History. The complete history can be used to reconstruct any past state.
Each request (from user or worker) triggers a state transition that atomically:
  • Appends new events to history
  • Updates Mutable State
  • Creates new tasks (Transfer or Timer)
History Service generates tasks that are processed asynchronously by Queue Processors, providing natural buffering and backpressure.
Workflows only make progress when workers poll for and complete tasks. The cluster never directly executes user code.

​
Further Reading

History Service

Deep dive into History Service internals

Matching Service

How task queues work

Event Sourcing

Event sourcing implementation details

Architecture Overview

High-level system architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us