Skip to main content

Temporal Workflow

This guide provides a comprehensive overview of Temporal Workflows and covers the following:

Intro to Workflows​

Conceptually, a workflow defines a sequence of steps. With Temporal, those steps are defined by writing code, known as a Workflow Definition, and are carried out by running that code, which results in a Workflow Execution.

In day-to-day conversations, the term Workflow might refer to Workflow Type, a Workflow Definition, or a Workflow Execution.

  1. A Workflow Definition is the code that defines your Workflow.
  2. The Workflow Type is the name that maps to a Workflow Definition. It's an identifier that makes it possible to distinguish one type of Workflow (such as order processing) from another (such as customer onboarding).
  3. A Workflow Execution is a running Workflow, which is created by combining a Workflow Definition with a request to execute it. You can execute a Workflow Definition any number of times, potentially providing different input each time (i.e., a Workflow Definition for order processing might process order #123 in one execution and order #567 in another execution). It is the actual instance of the Workflow Definition running in the Temporal Platform.

You'll develop those Workflows by writing code in a general-purpose programming language such as Go, Java, TypeScript, or Python. The code you write is the same code that will be executed at runtime, so you can use your favorite tools and libraries to develop Temporal Workflows.

Temporal Workflows are resilient. They can run—and keep running—for years, even if the underlying infrastructure fails. If the application itself crashes, Temporal will automatically recreate its pre-failure state so it can continue right where it left off.

Each Workflow Execution progresses through a series of Commands and Events, which are recorded in an Event History.

How Workflow replay works​

When a Workflow pauses or encounters an error, the goal of Temporal is to bring the Workflow back to the exact same state it was in before the pause occurred. To make that possible, Temporal keeps the Event History. This is a complete, ordered log of everything that has already happened in a Workflow.

The Event History could look like this for example:

  • Started Timer for 5 minutes
  • Scheduled Activity X
  • Activity X completed with result Y
  • Received Signal Z

This history is the source of truth for everything that happens in the Workflow.

Resuming a Workflow​

When it's time to continue the Workflow, Temporal doesn't restore memory from a snapshot. It starts the Workflow code from the beginning, replays the Event History step by step, and uses that history to guide the code back to the exact state as before. So the Workflow code is re-run, but uses the recorded events instead of redoing work.

Because the Workflow is re-executed to rebuild its state:

  • It has to make the same decisions when given the same history, which makes a Workflow deterministic.
  • It shouldn't depend on values that can change between runs.

For example:

  • A direct call to Date.now() could return a different value on replay.
  • A random number could change.
  • A network call could return something new.

If those values changed, the Workflow could take a different path and fail to match the recorded history. To solve this, Temporal provides replay-safe versions of common operations:

  • Time is read from the Workflow context so it matches the recorded history.
  • Timers are recorded as events and don’t “wait” again during replay.
  • Randomness and similar values can be captured once and reused.

These APIs make sure the Workflow receives the same values during replay as it did originally. Activities handle everything that interacts with the outside world, like:

  • API calls
  • Database queries
  • LLM invocations
  • File I/O

When a Workflow calls an Activity, the Activity runs once, its result is recorded in the Event History. During replay, that result is reused, not recomputed. So Activities aren't executed again during replay.