Temporal Design Patterns

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.

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.

Idempotent Distributed Transactions

Coordinates multi-step operations across external services with safe retries, automatic rollback on failure, and protection against duplicate submissions.

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.

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.

Event Accumulator

Buffers a stream of incoming Signals and processes them together in batches based on size or time thresholds.

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.

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.

Approval

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

Delayed Start

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

Delayed Callback

Durable webhook and callback handling: fire delayed outbound callbacks with durable timers and complete work asynchronously via task tokens.

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.

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.

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.

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.