workflow-execution/commands

12 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Workflow Commands vs direct execution

When Workflow code calls Temporal APIs, the SDK records Commands like ScheduleActivityTask or StartTimer instead of executing them directly. Commands describe what should happen next and are sent to the Server, where they are converted to Events and Tasks.

Workflow code statements that produce Commands in .NET

Four statements in .NET Workflow code produce Commands sent to the Temporal Service: (1) Workflow.ExecuteActivityAsync(GetDistanceAsync) produces ScheduleActivityTask, (2) Workflow.DelayAsync(TimeSpan.FromMinutes(30)) produces StartTimer, (3) Workflow.ExecuteActivityAsync(SendBillAsync) produces ScheduleActivityTask, (4) return confirmation produces CompleteWorkflowExecution. All other operations like totaling prices, evaluating distance, and populating records run in the Worker without contacting the Temporal Service.

Command definition in Temporal

A Command is a requested action issued by a Worker to the Temporal Service after a Workflow Task Execution completes. The Temporal Service acts on these Commands such as scheduling an Activity or scheduling a timer.

Workflow code statements that produce Commands

Four statements in a Workflow Definition produce Commands sent to the Temporal Service: activities.getDistance() produces ScheduleActivityTask; Workflow.sleep() produces StartTimer; activities.sendBill() produces ScheduleActivityTask; return produces CompleteWorkflowExecution. Everything else is internal computation (setting timeouts, calculating totals, evaluating logic) that runs in the Worker without contacting the Temporal Service.

Workflow Task definition

A Workflow Task advances a Workflow Execution by one step.

Workflow Task Execution definition and performance

A Workflow Task Execution occurs when a Worker picks up a Workflow Task and uses it to make progress on the execution of a Workflow Definition. Workflow Task Execution is typically very fast (milliseconds). The Worker replays code and makes decisions based on the Event History. No actual I/O operations occur during replay because Activity results come from history. The time spent in a Workflow Task is unrelated to how long Activities or Timers take.

Timers are deterministic and persisted

Temporal SDKs offer Timer APIs so that Workflow Executions are deterministic in their handling of time values. Timers are persisted, meaning that even if your Worker or Temporal Service is down when the time period completes, as soon as your Worker and Temporal Service become available, the call that is awaiting the Timer in your Workflow code will resolve, causing execution to proceed.

Timers are reliable and resource efficient

Timers are reliable and efficient. Workers consume no additional resources while waiting for a Timer to fire, so a single Worker can await millions of Timers concurrently.

Timer duration range and precision

The duration of a Timer is fixed, and a Workflow might specify a value as short as one second or as long as several years. Although it is possible to specify an extremely precise duration, such as 36 milliseconds or 15.072 minutes, Workflows should not rely on sub-second accuracy for Timers.

Timer duration treated as minimum with rounding

Timer duration should be considered a minimum time, one which will be rounded up slightly due to the latency involved with scheduling and firing the Timer. For example, setting a Timer for 11.97 seconds is guaranteed to delay execution for at least that long, but will likely be closer to 12 seconds in practice.

Command generation and Worker supervision

Commands are generated whenever the Workflow Function is executed. The Worker Process supervises the Command generation and makes sure that it maps to the current Event History. The Worker Process batches the Commands and then suspends progress to send the Commands to the Temporal Service whenever the Workflow Function reaches a place where it can no longer progress without a result from an Awaitable.

Command definition and lifecycle

A Command is a requested action issued by a Worker to the Temporal Service after a Workflow Task Execution completes. The action that the Temporal Service takes is recorded in the Workflow Execution's Event History as an Event. Commands are generated by the use of Workflow APIs in code. During a Workflow Task Execution there may be several Commands that are generated. The Commands are batched and sent to the Temporal Service as part of the Workflow Task Execution completion request, after the Workflow Task has progressed as far as it can with the Workflow function. There will always be WorkflowTaskStarted and WorkflowTaskCompleted Events in the Event History when there is a Workflow Task Execution completion request.

Give your agent this brain