Temporal Design Patterns

Warning: This catalog is under active development. Content and structure may change.

Temporal provides a set of durable execution primitives that you can compose into common, reusable, and proven patterns. Having these patterns in your toolbox helps you solve recurring problems in a battle-tested way.

Task orchestration patterns

Child Workflows

Decomposes complex Workflows into smaller, reusable units. Each child has an independent Workflow ID, history, and lifecycle.

Parallel Execution

Executes multiple Activities concurrently for maximum throughput with error handling and controlled parallelism.

Pick First (Race)

Starts multiple Activities in parallel and uses the first result, cancelling the rest.

Task Orchestration Patterns Overview

Pattern selection guide for composing and coordinating multiple units of work within a Workflow.

Workflow messaging patterns

Signal with Start

Starts a Workflow when Signaling it if it does not already exist. If already running, it receives the Signal directly.

Request-Response via Updates

Synchronous request-response with validation. Updates modify state and return results directly.

Workflow Messaging Patterns Overview

Pattern selection guide for sending data into running Workflows and receiving responses or triggering behavior changes.

Entity & lifecycle patterns

Entity Workflow

Models long-lived business entities as individual Workflows that persist for the entity's entire lifetime, handling all state transitions through Signals and Updates.

Continue-As-New

Prevents unbounded history growth by completing the current execution and starting a new one with fresh history.

Updatable Timer

Dynamically adjustable timers that respond to Signals or Updates. Extend, shorten, or cancel timers based on external events.

Entity & Lifecycle Patterns Overview

Pattern selection guide for modeling long-lived stateful entities and managing Workflow history growth over time.

External interaction patterns

Polling External Services

Strategies for polling external resources with varying frequencies: frequent, infrequent, and periodic patterns.

Long-Running Activity

Long-running Activities report progress via heartbeats and enable resumption after failures with cancellation support.

Delayed Start

Creates Workflows immediately but defers execution until a specified delay expires. Fits one-time scheduled operations and grace periods.

Delayed Callback (Webhooks)

Integrates webhooks durably: receive inbound webhooks via Signals, fire delayed outbound callbacks with durable timers, and complete Activities asynchronously via task tokens.

Approval

Human-in-the-loop Workflows that block until external approval decisions are made. Uses Signals to capture approval data with metadata.

External Interaction Patterns Overview

Pattern selection guide for waiting on or interacting with systems and actors outside the Workflow.

Distributed transaction patterns

Saga Pattern

Manages distributed transactions with compensating actions. Each step has a compensation that undoes its effects if subsequent steps fail.

Early Return

Synchronous initialization with asynchronous completion. Returns results immediately while processing continues in the background.

Distributed Transaction Patterns Overview

Pattern selection guide for distributed transactions, with a decision tree for choosing between Saga and Early Return.

Error handling & retry patterns

Fixed Count of Retries

Cap the number of Activity retry attempts to control cost when each attempt consumes a paid or limited resource.

Fixed Wall-Time Retries

Bound the total elapsed time across all retry attempts to enforce a business SLA, regardless of how many individual attempts occur.

Non-Retryable Errors

Mark error types that will never succeed — such as validation failures or missing records — so Temporal fails fast instead of retrying indefinitely.

Delayed Retry

Override the next retry interval for a specific failure using nextRetryDelay on ApplicationFailure. Use when an error carries information about how long to wait before retrying.

Fast/Slow Retries

Try aggressively with a short interval first, then shift to a long interval when fast retries are exhausted, keeping the Workflow alive until the downstream system recovers.

Retry Alerting via Metrics

Emit a custom metric from inside the Activity when the attempt count crosses a threshold, surfacing silent persistent failures to on-call teams before an SLA breach.

Resumable Activity

Park the Workflow after retries are exhausted and wait for a human to signal a correction, then resume execution from where it left off.

Error Handling & Retry Patterns Overview

Pattern selection guide and decision tree for choosing the right retry strategy based on your error type, cost constraints, and recovery requirements.

Batch processing patterns

Fan-Out with Child Workflows

Distributes a large record set across parallel Child Workflows for concurrent processing with automatic scaling.

Batch Iterator

Pages through unbounded datasets using Continue-As-New to prevent history overflow while maintaining exactly-once processing guarantees.

Sliding Window

Maintains a fixed number of concurrently active Child Workflows, starting a new one each time an existing one completes.

MapReduce Tree

Recursively splits a dataset into a binary tree of Child Workflows, processes leaves in parallel, then aggregates results back up the tree.

QoS & throughput patterns

Downstream Rate Limiting

Caps Activity execution rate against a downstream service by routing throttled Activities to a dedicated Task Queue backed by Workers configured with a throughput limit.

Priority Task Queues

Assigns a priority level to Workflows and Activities so that time-sensitive work executes ahead of lower-priority work within a single Task Queue.

Fairness

Distributes Worker capacity evenly across tenants or users so that a burst from one caller does not starve the others.

QoS & Throughput Patterns Overview

Pattern selection guide for controlling execution rate, protecting downstream services from overload, and ensuring fair capacity distribution across tenants.

Performance & latency patterns

Local Activities

Run Activity functions in-process inside the Workflow Task, eliminating all server scheduling round-trips. Best for short, idempotent Activities on a latency-sensitive path.

Early Return + Local Activities

Extends Early Return by running Phase 1 Activities as Local Activities. The client receives its response after Phase 1 completes entirely in-process, achieving the lowest possible first-response latency.

Eager Workflow Start

Dispatch the first Workflow Task directly to a co-located Worker, bypassing the Temporal Matching Service. Requires the starter and Worker to share the same process and client connection.

Performance & Latency Patterns Overview

Pattern selection guide for reducing Workflow latency, with a comparison of the round-trips each pattern removes and their combined effect.

Worker configuration patterns

Worker-Specific Task Queues

Routes Activities to specific Workers using unique Task Queues for Worker affinity and host-specific processing.

Activity Dependency Injection

Injects external dependencies into Activities at Worker startup, keeping Workflow code deterministic and Activities testable.

Worker Configuration Patterns Overview

Pattern selection guide for configuring how Workers are set up, how work is routed, and how Activities access external dependencies.