What Temporal workflow design and development involves
The core design question in Temporal is which business steps belong in workflow code and which belong in activities. Workflow code is replayed from recorded history after a worker restarts, so it must be deterministic: no direct network calls, random values or clock reads that change between runs. Activities hold the work that touches external systems, such as payment APIs, databases or email, and they can be retried, so each one needs an idempotency key or a check for prior completion. The boundary between the two shapes every retry, timeout and compensation decision, so it is expensive to correct after go-live.
Teams usually look for outside help in three situations. The first is a first durable process, where choices about timeouts, retry policies and signal handling carry risk that is hard to see before production. The second is a backlog of cron jobs or queue handlers that fail in ways nobody can fully reconstruct, which a durable workflow can make visible and recoverable. The third is a team new to the Temporal SDK, which has its own determinism rules, worker sizing and test tooling to learn. A nightly batch that has failed silently for weeks is often a sounder first candidate than a greenfield design.
For the in-house versus partner decision, the short answer depends on the team. Teams with strong backend engineers can build simple, linear workflows themselves, especially where the failure cases are few and well understood. Partners are usually brought in for the first production design, a review of failure paths such as partial completion, compensation and long waits, and a test strategy covering workflow replay and activity behavior. Ask any partner how the work will leave your team able to add the next workflow without them.
Hosting is a separate decision from design. The Temporal Server is MIT licensed according to its GitHub repository, so you can run it yourself in infrastructure you control. Temporal Cloud is a separate managed option sold by Temporal Technologies. Workflow code is largely the same under either choice, but the operational work differs, so confirm the hosting model before the design is finalized. The cost comparison is covered in the implementation plan and cost ownership sections of this page.
What the work includes
The scope below covers the design and code that sit inside a Temporal workflow project. The scope is agreed in writing before work starts, and the deliverables list each workflow and activity by name.
Process decomposition into workflows and activities
We split each business process into workflows that hold orchestration logic and activities that perform side effects such as API calls, database writes and messages. The split decides how state is recorded, how failures resume and how workflow code is later versioned. We check the decomposition with you before code is written, so each boundary is a decision you can review.
Retry policies and timeouts per activity
Each activity gets its own retry policy, start-to-close and schedule-to-close timeouts, and a list of non-retryable error types. A payment call and a report render rarely need the same settings. We document the chosen values in the design record so operations teams can see why a step retries and when it stops.
Signals and queries for external input
Signals deliver external events such as an approval or a cancellation into a running workflow, and queries let callers read workflow state without changing it. We define the signal and query names, payload shapes and expected callers up front. The design record states which systems may send each signal, which is a common gap in first implementations.
Child workflows for fan-out and bounded sub-processes
Child workflows isolate sub-processes that have their own lifecycle, such as per-item processing in a batch or a bounded review step. We set parent close policies and limits on fan-out so history size stays manageable. The deliverables show which child workflows exist, how many may run at once, and what happens to them when the parent ends.
Idempotent activity design with idempotency keys
Activities can run more than once after a worker crash or a timeout, so each side effect needs an idempotency key derived from the workflow and activity identity. We check that downstream systems honor the key, or that the activity records its own completion. Where a downstream system cannot honor a key, we document the risk and the compensating step.
Test suites with the SDK test tools
We write unit and replay-oriented tests with the test environment of the SDK for your chosen language, covering happy paths, retries, timeouts, signals and compensation. Tests run in your continuous integration pipeline. Ask for the list of covered workflows and the failure cases each test exercises before you accept the suite.
Handover of code, tests and design record
You receive the source code, the test suite and a design record that explains each workflow, activity, timeout and signal. The record also lists open decisions and the versioning approach for later changes. Confirm the repository location, access, and the owner who will maintain the code after handover before work begins.
What drives effort and duration
This table lists the design factors that change how much build, test and review work a Temporal workflow project needs, why each one matters and how to keep it under control.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Number and complexity of business processes | Each process needs its own workflow type, state model, error paths and tests. Branching logic and long-lived state multiply the paths a developer must reason about and verify. | Start with the processes that deliver the most value, keep each workflow to one business outcome, and move reusable steps into shared activities. |
| Activities that call external systems | Every external call is a failure point that needs retry policy, timeouts, idempotency keys and error mapping. Each external system also adds credentials, sandbox access and contract testing. | Group calls behind a small number of well-defined activities, confirm sandbox availability early, and agree idempotency behavior with each system owner before coding. |
| Workflow duration and execution volume | Long-running workflows must survive worker restarts, code changes and history growth, which affects design, versioning and archival decisions. High execution counts drive visibility store sizing and query patterns. | Use continue-as-new for long histories, split very large fan-outs into child workflows, and confirm the expected execution count and retention period with your platform team. |
| Signals and queries required by the business | Each signal changes workflow state and must be handled in every reachable branch. Each query exposes state that must be read safely and tested under replay. | List every external event and status question the business needs up front, then limit signals and queries to those cases rather than adding them as ad hoc requests. |
| Number of languages and SDKs involved | Each SDK has its own idioms for determinism, retries and testing. Teams working across languages need separate coding standards, libraries and skills, and shared contracts must be kept in sync. | Choose one primary SDK for workflow code where possible, and document any second SDK for specific workers with shared payload schemas. |
| Compensation and saga paths | Each step that needs an undo path requires a compensating activity, ordering rules and tests for partial failure. Compensation paths often fail in production because they were tested least. | Define compensation for each state-changing step during design, and agree with the business which failures require manual intervention instead of automated rollback. |
| Quality of existing API contracts for activities | Activities wrap systems that may have undocumented behavior, inconsistent error codes or missing idempotency. Poor contracts force defensive code and extra test cases in every activity. | Review each target API's error model, rate limits and idempotency support before design starts, and record gaps as known risks with an owner. |
| Test coverage expectations | Workflow tests need a test environment, time skipping, mocked activities and replay tests for code changes. Higher coverage targets increase the number of scenarios and the fixture work for each one. | Agree on the scenarios that must be covered, such as retries, timeouts, signals and compensation, and automate replay tests in continuous integration from the first sprint. |
| Number of environments | Each environment needs its own Temporal namespace or cluster, worker deployment, configuration, secrets and external system connections. Promotion between environments adds deployment and verification steps. | Limit the number of environments that run workers, use namespaces to separate teams and stages where your model allows, and confirm with your platform team what each environment provides. |
Project phases and outputs
The sequence moves a business process from mapped requirements to tested Temporal workflows and activities, with a handover package the owning team can operate.
Map the process and workflow boundaries
We interview process owners and engineers, map each business process from trigger to completion, and identify long-running waits, human approvals, external calls and compensation needs. The output is a decision record for each workflow boundary, stating what belongs in one workflow, what becomes a child workflow and what stays outside Temporal. The step closes when your owners sign the boundary decisions.
Design workflows, activities and failure paths
For each activity we define inputs, outputs, idempotency keys and the external systems it touches, then set retry policies and timeouts. A failure-path review walks through timeouts, partial completion, duplicate delivery and downstream outages. The outputs are a retry and timeout table per activity and a list of signals, queries and compensations, reviewed with your engineers before any code is written.
Build workflows and activities with unit and replay tests
Engineers implement the approved design in your chosen Temporal SDK, keeping workflow code deterministic and moving side effects into activities. Unit tests cover branching and activity behavior, and replay-based tests run recorded histories against the current code to catch non-deterministic changes. The step closes when the test suite passes in your repository and the build is reproducible in your CI.
Run integration tests against a non-production service
We deploy the workers and workflows against a non-production Temporal service that matches your target topology, whether self-hosted or Temporal Cloud. Tests cover happy paths, retries, timeouts, worker restarts, signals and queries, and cancellation. The output is a test report listing each scenario, its result and any open defects, and it closes when your owners accept the open items.
Write runbooks and hand over
We write a runbook entry for each workflow covering stuck or failed executions, how to inspect event history, when to reset or terminate, and who to contact. Your engineers take part in a supervised handover where they operate a set of scripted failure scenarios. The step closes when the runbook, source repository, test report and decision records are delivered and your team has run the failure drills.
What teams keep in-house and what they outsource
This table shows who usually owns each part of a Temporal workflow project and which skills each part needs, so you can plan staffing before the first workflow is written.
| Work area | Usual owner | Skills needed |
|---|---|---|
| Business process ownership and acceptance criteria | In-house: process owners and product leads | Deep knowledge of the business process, exception rules and what a correct outcome looks like |
| Activity contract design and idempotency | Shared: in-house engineers with partner review | Distributed systems thinking, API design, understanding of retries and duplicate delivery |
| Workflow state modeling and failure-path design | Often outsourced for the first workflows, then transferred | Distributed systems thinking, state machine design, compensation and timeout planning |
| SDK language expertise (Go, Java, Python, TypeScript, .NET) | Shared, with the partner covering the initial patterns | Fluency in the chosen SDK language, its concurrency model and its Temporal SDK idioms |
| Test strategy (unit, replay and integration tests) | Shared: partner designs the strategy, in-house owns the suite | Test framework skills in the SDK language, Temporal test environment usage, CI integration |
| Operational model and knowledge transfer | In-house platform or SRE team, with partner-led training | Familiarity with Temporal's operational model, task queues, workers, visibility and incident handling |
What usually goes wrong
Most Temporal incidents trace back to a small set of design mistakes made early, before the first production run. Each card below names a failure pattern and the checks that catch it before go-live.
Non-deterministic code inside workflows
Workflow code is replayed from its event history, so reading the current time, generating random values or calling external systems directly can produce a different path on replay. Move these calls into activities or use the SDK's deterministic equivalents, and require reviewers to flag direct I/O in workflow files. Replay tests against recorded histories catch regressions before deployment.
Activities without idempotency
Temporal retries activities when they fail or time out, so a payment or record write can execute twice if the first attempt succeeded but its response was lost. Pass a stable idempotency key derived from the business identifier, and check that every side-effecting activity looks up prior results before acting. Failure injection tests that kill workers mid-call expose duplicates.
Default retry policies on fail-fast activities
Default retry settings retry indefinitely with backoff, which suits transient network errors but delays failures such as invalid account data or a rejected request. Classify non-retryable error types explicitly and set maximum attempts for each activity type. Review every activity's retry policy in code review, and test that a permanent error surfaces within the expected window.
Missing timeouts that leave executions waiting
Without start-to-close, schedule-to-start and heartbeat timeouts, an activity or a wait for a signal can stay open for days when a dependency stops responding. Set timeouts per activity and per wait, and add heartbeats to long-running activities so stalled workers are detected. Failure injection that pauses a downstream service shows whether the timeouts fire.
Signals used in place of a state model
Teams often send signals to push a workflow through steps without defining which states are valid, so out-of-order or duplicate signals leave executions in undefined positions. Write the state machine on paper first, list the signals each state accepts, and reject or queue the rest explicitly. Tests should send signals in every unexpected order.
Unbounded histories from loops
A long-running loop that never calls continue-as-new keeps adding events to one workflow history until it grows too large to operate. Track history length in design reviews, use continue-as-new at a planned iteration count or event threshold, and carry only the state needed across the restart. Load tests that run the loop to its expected maximum confirm the behavior.
Child workflow trees that are hard to observe
Deeply nested child workflows spread one business process across many executions that operators must correlate by hand. Give each child a deterministic workflow ID that includes the business key, limit nesting depth, and use search attributes consistently. Confirm in the visibility store that a single business identifier returns the full tree during a support drill.
Workflows tested only on the happy path
Tests that run only the successful sequence miss the retry, timeout, cancellation and version-change paths where most production failures occur. Build test suites that cover each failure branch, run replay tests on histories captured from earlier releases, and schedule failure injection in staging that restarts workers and drops dependencies. Treat a failing replay test as a release blocker.
How the work differs by starting point
Design effort starts with the process itself. Cron jobs and queue consumers often keep business state in tables, flags and retry scripts, so the work is to name each step, decide where state lives and identify which steps must be idempotent.
- Step boundaries: Split each job into activities that call external systems, and keep branching decisions in workflow code.
- Retry and timeout policy: Replace ad hoc retry loops with per-activity policies, and confirm which failures are safe to retry.
- Idempotency: Check that each side effect, such as a payment or a notification, can be repeated or guarded by a unique key.
- Triggers: Decide which schedules stay in Temporal and which queue messages become signals or workflow starts.
Confirm first: how the business expects duplicate or late runs to behave today.
The starting point is the current state model. Each existing state, transition and compensation rule must be restated as workflow code, which often exposes rules that were implicit. Moving executions that are already running is a separate task covered in the Migration to Temporal topic.
- State mapping: Map each existing state and transition to a workflow step, timer or signal.
- Event handling: Confirm how the current engine handles duplicate, out-of-order and late events, and carry those rules into the design.
- Data shape: Define workflow inputs and activity results as serializable payloads, with no references to in-process objects.
- Cutover scope: Decide whether new starts move to Temporal first while existing executions finish in the old engine.
Confirm first: whether any in-flight instances must move, and which teams will sign off on the mapped rules.
Platform decisions are already made, so the effort shifts to fitting new workflows into the namespaces, task queues and conventions in use. The main risk is that each team rebuilds shared pieces that already exist.
- Namespace and task queue layout: Confirm whether the new process gets its own namespace or shares one, and which task queues its workers poll.
- Shared components: Reuse existing interceptors, logging, codecs and default retry settings.
- Versioning practice: Check how the team already handles changes to workflow code while executions are running.
- Search attributes and capacity: Confirm that new search attributes fit the visibility store in use and that worker capacity covers the new load.
Confirm first: the server and SDK versions in use, because they determine which features are available to the new workflows.
Each Temporal SDK has its own conventions, libraries and test tooling. A single language lets one set of patterns cover every workflow. Several languages add interface boundaries, so the design must make shared contracts explicit.
- Shared contracts: Define workflow types, signal names, query names and payload formats in a common place so callers in other languages do not break them.
- Worker ownership: Decide which team runs workers for each language and how those workers are built and deployed.
- Testing: Confirm the test harness and replay tests for each language, so coverage does not depend on one team.
- Skills after go-live: Name the people who will maintain each language's workflow code.
Confirm first: which languages are already in use and which teams will own workflows in each one.
In a regulated environment the workflow design is also an evidence question. Workflow history records inputs, decisions and signals, and payloads may contain personal or account data. These design choices determine what auditors can see and what must be protected.
- Payload minimization: Pass record identifiers where the design allows, so personal data stays in the system of record.
- Encryption: Plan payload encryption with a codec, and confirm who can reach the codec server and its keys.
- Audit trail: Map which workflow events, signals and human actions must be retained, and for how long.
- Access control: Confirm which roles can start, signal, query or cancel workflows, and how that access is logged.
Confirm first: the data classes handled by each workflow and the audit requirements that apply, agreed with the compliance owner before the design is fixed.
What you need to provide
Design work goes faster and costs less when the client has the inputs ready before the first workshop. Each item below has an owner on your side, and a gap in any one of them usually shows up later as rework in workflow code, retry policies or test cases. Start by naming a process owner for every workflow in scope. This person signs off the business intent, decides which outcomes are acceptable, and answers questions about what should happen when a step fails. Without one named person, timeouts and compensation logic tend to encode guesses.
Next, provide written business rules and a list of exception cases. These become the branches, timers and compensating actions in the workflow definition. Ask the process owner to list what should happen when a payment is declined after approval, when a document never arrives, or when a human approval is not given within the agreed window. For every external system an activity will call, supply API documentation and sandbox access. Idempotent activities depend on knowing which calls accept an idempotency key and how the system reports duplicates. The integration or application owner for each system should confirm this, and should confirm rate limits as well.
On the engineering side, choose the SDK language (Go, Java, TypeScript, Python, .NET or PHP, as supported by Temporal at the time of build) and name the team members who will maintain the workflow and worker code after go-live. Those people should join design reviews, not only receive a handover. Decide where Temporal will run: a non-production self-hosted environment with its own persistence store, or a decision to use Temporal Cloud for development and testing. This choice affects test harness design and how closely staging matches production. The platform or infrastructure lead owns it.
Finally, decide how workflow payloads that contain personal or regulated data will be handled. Temporal records workflow inputs, activity results and event history, so customer identifiers, health data or card-related fields can persist longer than the business process itself. Your privacy or compliance lead should decide whether payloads carry references instead of raw values, whether a payload codec with encryption is required, and who may view history in the Web UI. Confirm that decision with the data protection owner before the first activity is written, because changing it later means rewriting data already stored in running histories.
Frequently asked questions
What drives the cost of Temporal workflow design?
Scope size and failure handling drive most of the cost. The number of processes moving to Temporal, the number of steps in each, and the number of external systems each step calls all add design and build effort. Retry policies, timeouts, compensation steps and idempotent activities each need design and review. Cost also depends on who pays for what. Design workshops, development, test automation and handover documentation are one-time work. Worker hosting, the Temporal Service and any Temporal Cloud usage recur. The Temporal pricing page lists Temporal Cloud pay-as-you-go pricing starting at 50 US dollars per million actions. Ask any quote to separate one-time and recurring costs.
How long does the first Temporal workflow take to build?
No single duration applies, because process complexity sets the pace. A short sequence of activities that calls one internal API is far quicker to design than a multi-week approval process with human tasks, timers and compensation logic. Time also depends on access to your systems and test environments, and on how quickly process owners approve rules. Ask for a schedule in the written scope that lists the workflows, their dependencies, and the points where your staff must review designs. Your team's availability often sets the pace more than the code does.
Can our own developers build Temporal workflows without a partner?
Yes, an internal team can build them if it already writes services in a language with a Temporal SDK and has time to learn the model. The hardest parts are conceptual. Workflow code must be deterministic, so developers need to know what can and cannot run inside a workflow. Failure paths need explicit design beyond default retries. Your staff should include a developer who owns workflow code, a platform engineer for workers and the cluster, a process owner who approves business rules, and a security reviewer for data carried in payloads. Confirm these roles and their time before you decide.
Can our team maintain Temporal workflow code after handover?
Yes, if handover includes what a maintainer needs. That means source code in your repository, a catalog of workflows, design notes for each one, coding conventions, test suites and a versioning guide. Maintainability also depends on how the code handles change. Versioned workflow code, replay tests and pinned SDK versions let your team make later updates safely. Confirm the handover list in the scope, who receives repository and cluster access, and whether training sessions are included. Server and SDK upgrades are separate work, which you can agree as support or a retainer.
How is testing handled for Temporal workflows and activities?
Testing covers workflow logic, activity behavior and failure paths. Workflow logic can be unit tested with the SDK's test utilities, which let timers and signals run without waiting in real time. Activities are tested against real or staged dependencies, and idempotency is checked by running an activity twice with the same input. Replay tests run recorded workflow histories against new code to catch nondeterministic changes before deployment. Integration tests run in a development cluster with injected failures such as timeouts and worker restarts. Confirm which environments, test data and failure scenarios the scope includes.
What happens to running executions when workflow code changes?
Running executions must stay compatible with the code that replays them. Temporal rebuilds workflow state by replaying event history, so changing the order or type of commands in a workflow can break an execution that is already running. Teams manage this with patching or versioning in the workflow code, replay tests, and worker deployment strategies that keep old workers available until old executions finish. Old code paths can be removed only after you confirm no open executions still need them. Ask how the scope covers existing executions, long-running timers and the rollout plan.
How DeployOpen delivers Temporal workflow work
DeployOpen designs and builds Temporal workflows and activities inside infrastructure you control, working from your business processes to tested code that runs on a self-hosted Temporal Service or Temporal Cloud. Each engagement follows a written scope, with deliverables agreed before work starts.
How we scope
- We map each business process to candidate workflows, activities and the external systems they call before any code is written.
- The written scope names which workflows, signals, queries and child workflows are in, and which are deferred to a later phase.
- We confirm retry policies, timeouts and idempotency requirements per activity so the quote reflects the actual integration work.
How we build
- Activities are written to be idempotent, with deduplication keys and clear handling for partial failures on downstream calls.
- Workflow logic is covered by tests that run against the Temporal test framework for your chosen SDK, including replay checks on changed code.
- Code is delivered in your version control system with reviews, and workflow versioning decisions are documented alongside it.
How we hand over
- Handover includes workflow and activity documentation, a retry and timeout reference, and runbooks for stuck or failed executions.
- Your engineers receive walkthroughs of how signals, queries and child workflows are used, and where each one should and should not be used.
- Test suites, deployment configuration and open items are delivered with a list of decisions your team owns after go-live.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the build.
- Support can cover workflow changes, worker SDK upgrades and replay testing when your processes change while executions are running.
- Confirm with us in the quote which Temporal Server and SDK versions are covered, and how upgrades are tested before they reach production.
