Glossary

Temporal conceptualizes software development in a unique way. There are very few products that share overlapping methodologies and concepts with Temporal.

Therefore, the following terms are re-defined within the context of the Temporal product, and used throughout the documentation and reference material to describe aspects of it.

Activity

An Activity is a business-level function that implements your application logic, such as calling a service or transcoding a media file.

  • An Activity usually implements a single well-defined action; it can be short or long running.
  • An Activity can be implemented as a synchronous method or fully asynchronously involving multiple processes.
  • An Activity can be retried indefinitely according to the provided exponential retry policy.
  • If for any reason an Activity is not completed within the specified timeout, an error is reported to the Workflow which decides how to handle it. There is no limit for an Activity duration.
  • Activities support an Activity Heartbeat that helps to identify timeouts faster in case the Activity execution fails.

Activity Heartbeat

An Activity Heartbeat provides the status of an Activity Task that is being executed to the Temporal server.

  • Activity Heartbeats help ensure that Activity execution failures and timeouts are identified quickly.
  • Activity Heartbeats are implemented in code and are recorded at the discretion of the Workflow implementation.
  • Custom Activity progress information can be included in an Activity Heartbeat and can be used when the Activity is retried.

Activity Id

A unique Id that identifies an Activity that is executing. The Id can be generated by the system or it can be provided by the Workflow code that invoked the Activity. An Activity Id can be used to complete the Activity asynchronously.

Activity Task

A Task that contains invocation information for an Activity that is delivered to an Activity Worker through and a Task Queue.

Archival

Archival is a feature that automatically moves Event Histories from normal persistence to a blob store after the Workflow retention period.

  • The purpose of Archival is to be able to keep Event Histories as long as needed while not overwhelming the persistence store.
  • There are two reasons why you may want to keep Event Histories after the retention period has passed:
    1. Compliance: For legal reasons, Event Histories may need to be stored for a long period of time.
    2. Debugging: Older Event Histories can be referenced to help with debugging.

Client Stub

A Client Stub is a client-side proxy in the Java SDK which is used to make remote invocations on an entity that it represents.

  • To start a Workflow, for example, a Stub object which represents the Workflow is created through a special API. Then the Stub is used to start, query, or signal the corresponding Workflow.
  • The Go SDK does not make use of Client Stubs.

Command

Any action requested by the Workflow durable function is called a Command.

  • Scheduling an Activity, canceling a child Workflow, or starting a timer are all Commands for example.
  • A Workflow Task contains an optional list of Commands.
  • A Worker executing a Workflow generates a list of Commands as a result to a Workflow Task. This list is sent to the Temporal service as part of the Workflow Task completion request.
  • Every Command is recorded in the Event History as an Event. For example, the StartTimer command is recorded as a corresponding TimerStarted event.

Event

There are two types of Events that Temporal tracks for each Workflow:

  1. Command Events.
  2. Everything else.
  • Command Events are events that correspond to Commands produced by the Workflow Worker.
  • All other events represent various external occurrences that the [Workflow] is expected to react to such as an Activity completion, a timer firing, a cancellation request, etc.
  • All Events are recorded in the Event History.

Event History

The Event History is an append-log of Events for your application.

  • Event History is durably persisted by the Temporal service, enabling seamless recovery of your application state from crashes or failures.
  • It also serves as an audit log for debugging.

Local Activity

A Local Activity is an Activity that is invoked directly in the same process by Workflow code.

  • While a Local Activity consumes less resources than a normal Activity, it is subject to shorter durations and a lack of rate limiting.

Namespace

Temporal is backed by a multi-tenant service and the unit of isolation is called a Namespace.

  • By default a Temporal service is provisioned with a "default" Namespace. All APIs and tools, such as the UI and CLI, default to the "default" Namespace if it is not specified. So, if you are not planning to use multiple Namespaces, we recommend using the default one.
  • Task Queue names as well as Workflow Ids correspond to a specific Namespace. For example, when a Workflow is started, it is started within a specific Namespace.
  • Temporal guarantees a unique Workflow Id within a Namespace, and supports running Workflow Executions to use the same Workflow Id if they are in different Namespaces.
  • Various configuration options like the retention period or Archival destination are configured per Namespace as well through a special CRUD API or through tctl.
  • In a multi-cluster deployment, Namespace is a unit of fail-over.
  • Each Namespace can only be active on a single Temporal cluster at a time. However, different Namespaces can be active in different clusters and can fail-over independently.

Query

From the caller's point of view, a Query is a synchronous operation that is used to report the state of a Workflow.

  • Query logic is implemented as code within a Workflow.
  • A Query is inherently read only and cannot affect a Workflow state.

Run Id

A Run Id is UUID that a Temporal service assigns to each Workflow run.

  • Temporal guarantees that only one Workflow Execution with a given Workflow Id can be open at a time. But after the Workflow Execution has completed, if allowed by a configured policy, you might be able to re-execute a Workflow after it has closed or failed, using the same Workflow Id.
  • Each such re-execution is called a run. Run Id is used to uniquely identify a run even if it shares a Workflow Id with others.

Signal

A Signal is an external asynchronous request to a Workflow.

  • A Signal can be used to deliver notifications or updates to a running Workflow at any point in its existence.

Task

A Task is the context needed to execute a specific Activity or Workflow state transition.

Task Queue

A Task Queue is a queue that a Worker subscribes to and polls to pick up tasks to execute.

  • Each Task Queue is capable of queuing Activity Tasks and Workflow Tasks.
  • Task Queues rely on the same persistent storage as the rest of the Temporal service (Task Queues are not based on other technologies such as Kafka).

Task Token

A Task Token is a unique correlation Id for a Temporal Activity.

Worker

A Worker is a service that hosts the Workflow and Activity implementations.

  • A single Worker actually contains both an Activity Worker and a Workflow Worker, abstracting the logical separation and having the ability to execute both types of tasks.
  • The Worker polls the Temporal service for Tasks, performs those Tasks, and communicates Task execution results back to the Temporal service.
  • Worker services are developed, deployed, and operated by Temporal customers.

Workflow

A fault-oblivious stateful function that orchestrates activities.

  • A Workflow has full control over which Activities are executed, and in which order.
  • A Workflow must not affect the external world directly, only through Activities.
  • What makes Workflow code a Workflow is that its state is preserved by Temporal. Therefore any failure of a Worker process that hosts the Workflow code does not affect the Workflow Execution. The Workflow continues as if these failures did not happen. At the same time, Activities can fail any moment for any reason.
  • Because Workflow code is fully fault-oblivious, it is guaranteed to get notifications about Activity failures or timeouts and act accordingly.
  • There is no limit to the duration of a Workflow.

Workflow Execution

An instance of a Workflow.

  • It is possible for a Workflow Execution to be comprised of multiple Workflow runs. When a Workflow's Event History grows too large it, the next invocation can be called with a "Continue as New" flag to create a new run automatically.

Workflow Id

A unique identifier for a Workflow Execution.

  • Temporal guarantees the uniqueness of an Id within a Namespace.
  • An attempt to start a Workflow with a duplicate Id results in an already started error if there is another open Workflow execution. However, this behavior depends on the WorkflowIdReusePolicy flag; If set to ALLOW_DUPLICATE, it is possible to start a new execution with the same the same Workflow Id.

Workflow Task

A Workflow Task is a Task that contains invocation information for a Workfow.

  • Every time a new external event that might affect a Workflow state is recorded, a Workflow Task that contains it, is added to a Task Queue and then picked up by a Workflow Worker.
  • After the new event is handled, the Workflow Task is completed with a list of Commands.
  • Handling of a Workflow Task is usually very fast and is not related to the duration of operations that the Workflow invokes.