Workflows and activities

Active contributors: wxing1292, alex, yichaoyang

Purpose

The core durable-execution model. A workflow is a deterministic function whose state is reconstructible from a history of events; an activity is the unit of side-effecting work the workflow schedules. Together they are everything Temporal exposes to most users.

What's involved

graph TD
    Code[Workflow code in user worker]
    SDK[Temporal SDK runtime]
    FE[Frontend]
    H[History]
    M[Matching]
    Worker[User worker]

    Code -->|run on poll| SDK
    SDK -->|StartWorkflow / Signal / etc.| FE
    FE --> H
    H -->|create Transfer Task| M
    Worker -->|PollWorkflowTask| FE
    FE --> M
    M -->|deliver task| Worker
    Worker -->|RespondWorkflowTaskCompleted| FE
    FE --> H

Server-side, a workflow execution is the conjunction of:

• Workflow History Events — the immutable event log.
• Mutable State — the persisted summary used to make decisions.
• History Tasks — pending Transfer / Timer / Visibility / Outbound work.
• (For workflows migrated to CHASM) the CHASM tree owned by the workflow Library.

Workflow lifecycle

The full sequence-diagram walkthrough is at docs/architecture/workflow-lifecycle.md. At a high level:

stateDiagram-v2
    [*] --> Created : StartWorkflowExecution
    Created --> Running : first WorkflowTaskCompleted
    Running --> Running : tasks, signals, updates, timers
    Running --> Completed : CompleteWorkflowExecution
    Running --> Failed : FailWorkflowExecution
    Running --> Cancelled : CancelWorkflowExecution
    Running --> Terminated : TerminateWorkflowExecution
    Running --> ContinuedAsNew : ContinueAsNew
    Completed --> [*]
    Failed --> [*]
    Cancelled --> [*]
    Terminated --> [*]
    ContinuedAsNew --> Created : new RunID

Reset is a special case: it forks a workflow back to an earlier event and produces a new RunID with a branched history (see service/history/workflow_rebuilder.go).

Activities

Activities are scheduled via the ScheduleActivityTask command. Server-side they are tracked in Mutable State as part of the workflow execution. Their lifecycle:

stateDiagram-v2
    [*] --> Scheduled : ScheduleActivityTaskCommand
    Scheduled --> Started : RecordActivityTaskStarted
    Started --> Completed : RespondActivityTaskCompleted
    Started --> Failed : RespondActivityTaskFailed
    Failed --> Scheduled : retry policy
    Started --> TimedOut : timeout
    TimedOut --> Scheduled : retry
    Started --> Cancelled : RespondActivityTaskCanceled

There are also standalone activities (no parent workflow) implemented as a CHASM Library at chasm/lib/activity/.

Source map

Surface	File / package
Public gRPC API	temporal.api.workflowservice.v1.WorkflowService (in go.temporal.io/api)
Frontend handler	service/frontend/workflow_handler.go
History RPC handler	service/history/handler.go
Per-RPC implementations	service/history/api/ — sub-package per RPC
Mutable State	service/history/workflow/mutable_state_impl.go
Workflow Task handling	service/history/api/respondworkflowtaskcompleted/workflow_task_completed_handler.go
Activity scheduling	service/history/api/recordactivitytaskheartbeat/ and siblings
Worker-side dispatch (Matching)	service/matching/matching_engine.go
CHASM-based workflow	chasm/lib/workflow/

Speculative workflow tasks

Updates and Queries deliver a Workflow Task to a worker without writing it to history (it would balloon history with non-event interactions). The mechanism — speculative workflow tasks — is documented at docs/architecture/speculative-workflow-task.md.

Worker commands

The complete list of commands a worker can return for a Workflow Task is in temporal.api.enums.v1.CommandType. The internal dispatch logic is at docs/architecture/worker-commands.md and service/history/worker_commands_task_dispatcher.go.

Related pages

• Architecture
• History service
• Matching service
• Workflow execution primitive
• Updates and queries
• Worker versioning