Skip to main content

Temporal Workflow Execution Overview

This page provides an overview of Workflow Execution:

What is a Workflow Execution?​

While the Workflow Definition is the code that defines the Workflow, the Workflow Execution is created by executing that code. A Temporal Workflow Execution is a durable, reliable, and scalable function execution. It is the main unit of execution of a Temporal Application.

Each Temporal Workflow Execution has exclusive access to its local state. It executes concurrently to all other Workflow Executions, and communicates with other Workflow Executions through Signals and the environment through Activities. While a single Workflow Execution has limits on size and throughput, a Temporal Application can consist of millions to billions of Workflow Executions.

Durability

Durability is the absence of an imposed time limit.

A Workflow Execution is durable because it executes a Temporal Workflow Definition (also called a Temporal Workflow Function), your application code, effectively once and to completion—whether your code executes for seconds or years.

Reliability

Reliability is responsiveness in the presence of failure.

A Workflow Execution is reliable, because it is fully recoverable after a failure. The Temporal Platform ensures the state of the Workflow Execution persists in the face of failures and outages and resumes execution from the latest state.

Scalability

Scalability is responsiveness in the presence of load.

A single Workflow Execution is limited in size and throughput but is scalable because it can Continue-As-New in response to load. A Temporal Application is scalable because the Temporal Platform is capable of supporting millions to billions of Workflow Executions executing concurrently, which is realized by the design and nature of the Temporal Service and Worker Processes.

Replays​

A Replay is the method by which a Workflow Execution resumes making progress. During a Replay the Commands that are generated are checked against an existing Event History. Replays are necessary and often happen to give the effect that Workflow Executions are resumable, reliable, and durable.

For more information, see Deterministic constraints.

If a failure occurs, the Workflow Execution picks up where the last recorded event occurred in the Event History.

Commands and awaitables​

A Workflow Execution does two things:

  1. Issue Commands.
  2. Wait on an Awaitables (often called Futures).
Command generation and waiting

Command generation and waiting

Commands are issued and Awaitables are provided by the use of Workflow APIs in the Workflow Definition.

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. (For more information, see Deterministic constraints.) 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.

A Workflow Execution may only ever block progress on an Awaitable that is provided through a Temporal SDK API. Awaitables are provided when using APIs for the following:

  • Awaiting: Progress can block using explicit "Await" APIs.
  • Requesting cancellation of another Workflow Execution: Progress can block on confirmation that the other Workflow Execution is cancelled.
  • Sending a Signal: Progress can block on confirmation that the Signal sent.
  • Spawning a Child Workflow Execution: Progress can block on confirmation that the Child Workflow Execution started, and on the result of the Child Workflow Execution.
  • Spawning an Activity Execution: Progress can block on the result of the Activity Execution.
  • Starting a Timer: Progress can block until the Timer fires.

What is a Command?​

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. The Workflow Execution can await on some of the Events that come as a result from some of the Commands.

Commands are generated by the use of Workflow APIs in your 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.

Commands are generated by the use of Workflow APIs in your code

Commands are generated by the use of Workflow APIs in your code

Commands are described in the Command reference and are defined in the Temporal gRPC API.

Status​

A Workflow Execution can be either Open or Closed.

Workflow Execution statuses

Workflow Execution statuses

Open​

An Open status means that the Workflow Execution is able to make progress.

  • Running: The only Open status for a Workflow Execution. When the Workflow Execution is Running, it is either actively progressing or is waiting on something.

Closed​

A Closed status means that the Workflow Execution cannot make further progress because of one of the following reasons:

  • Cancelled: The Workflow Execution successfully handled a cancellation request.
  • Completed: The Workflow Execution has completed successfully.
  • Continued-As-New: The Workflow Execution Continued-As-New.
  • Failed: The Workflow Execution returned an error and failed.
  • Terminated: The Workflow Execution was terminated.
  • Timed Out: The Workflow Execution reached a timeout limit.

Workflow Execution Chain​

A Workflow Execution Chain is a sequence of Workflow Executions that share the same Workflow Id. Each link in the Chain is often called a Workflow Run. Each Workflow Run in the sequence is connected by one of the following:

A Workflow Execution is uniquely identified by its Namespace, Workflow Id, and Run Id.

The Workflow Execution Timeout applies to a Workflow Execution Chain. The Workflow Run Timeout applies to a single Workflow Execution (Workflow Run).

What is a Memo?​

A Memo is a non-indexed set of Workflow Execution metadata that developers supply at start time or in Workflow code and that is returned when you describe or list Workflow Executions.

The primary purpose of using a Memo is to enhance the organization and management of Workflow Executions. Add your own metadata, such as notes or descriptions, to a Workflow Execution, which lets you annotate and categorize Workflow Executions based on developer-defined criteria. This feature is particularly useful when dealing with numerous Workflow Executions because it facilitates the addition of context, reminders, or any other relevant information that aids in understanding or tracking the Workflow Execution.

Use Memos judiciously

Memos shouldn't store data that's critical to the execution of a Workflow, for some of the following reasons:

  • Unlike Workflow inputs, Memos lack type safety
  • Memos are subject to eventual consistency and may not be immediately available
  • Excessive reliance on Memos hides mutable state from the Workflow Execution History

What is a State Transition?​

A State Transition is a unit of progress made by a Workflow Execution. Each State Transition is recorded in a persistence store.

Some operations, such as Activity Heartbeats, require only one or two State Transitions each. With an Activity Heartbeat, there are two: the Activity Heartbeat and a Timer.

Most operations require multiple State Transitions.

For example, a simple Workflow with two sequential Activity Tasks (and no retries) produces 11 State Transitions: two for Workflow start, four for each Activity, and one for Workflow completion.

NEXT STEPS

For more information on Workflow Execution, please refer to the following subpages: