What a migration to Temporal involves
Most migrations start from one of four places: cron-driven batch jobs, queue-based retry chains, homegrown state tables that record where a process stopped, or an existing workflow engine such as Apache Airflow. Each has its own failure model. A cron job re-runs from the top, a queue chain depends on message redelivery, and a state table is only as correct as the code that writes it. When a process becomes a Temporal workflow, its sequence of steps lives in code, retries and timeouts are declared on each activity, and the workflow history records progress so a worker can resume after a crash. Inventory each process by its trigger, its steps and where it keeps state before choosing what to move first.
The main risk sits in in-flight state. Rewriting a batch job in a Temporal SDK is usually the smaller task. The harder questions concern what happens to runs already in progress at the moment you switch: a half-processed file, a queue message that was acknowledged but not finished, or a row in a homegrown state table that says step four is pending. For each process, decide whether in-flight work drains on the old path, restarts in Temporal with idempotent activities, or is converted by a script that starts an equivalent workflow. Write that decision down, and test the cutover with executions stopped mid-run, not only with clean inputs.
Whether to do this in-house depends mostly on prior Temporal experience and on how many processes are moving. Teams that have already run Temporal in production and have a small number of processes often keep most of the work, bringing in a partner only for design review. Teams without that experience usually bring in a partner for workflow design and cutover planning, while their own engineers handle the application logic they know best. Ask any partner how they will handle in-flight executions, who signs off on the cutover and which parts of the work are fixed in writing before the project starts.
The second migration type moves a running Temporal deployment between self-hosted Temporal and Temporal Cloud. It is planned differently because open executions hold state in the source deployment, and the namespace, client endpoints, worker connection settings, authorization and payload codec all have to be checked on the destination. Confirm with Temporal's current documentation and your account team which migration path applies to your namespace and server version, and what it does to executions still open at cutover. Plan the switch namespace by namespace, decide how workers move, and test that access roles and the codec server still work after the change.
What the work includes
The engagement moves each legacy process onto Temporal in controlled steps, from inventory through cutover. The cards below list what is produced at each stage so you can compare them with your own plan.
Process inventory and first workflows
We list the cron jobs, queue consumers, homegrown state machines and other engine flows in scope, then select the first workflows to move. Selection weighs run frequency, duration, failure cost and how much state each process holds. Confirm which processes must keep running during the migration and which owners sign off on each choice.
Process to Temporal mapping
Each legacy process is mapped to workflows, activities, timers and signals. Steps with side effects become activities, waits become timers, and external events become signals. The mapping shows where existing retry logic and idempotency must be preserved, and where the legacy code hides state that Temporal will now persist.
Workers built or refactored
Existing job code is refactored into Temporal workers, or new workers are written where the legacy code cannot be reused. Deliverables include tested workflow and activity code, configuration for task queues and concurrency, and a container build for each worker. Confirm the SDK language and version your teams can support after handover.
Migration pattern per process
Each process gets one pattern: parallel run, strangler cutover, or drain-and-switch. Parallel run compares outputs from old and new paths, strangler cutover moves new work first while in-flight work finishes on the old path, and drain-and-switch stops intake, waits for completion and then starts Temporal. The pattern record states the reason and the exit criteria.
Cutover and rollback runbooks
Runbooks give the step order for each cutover, the checks at each step, the named decision owner and the rollback trigger. They cover what happens to workflows already running on the legacy path. Review them with your operations team before the first production cutover, not after.
Self-hosted to Temporal Cloud moves
Where the target includes moving between self-hosted Temporal and Temporal Cloud, we plan the namespace, worker connection, and handling of running workflows during the switch. Confirm with your team whether a move is needed at all, since it changes the operational and cost picture. Scope the move separately from the first migration.
Migration inventory and design records
The migration inventory lists every process, its pattern, owner, status and cutover date. Each workflow has a design record covering its states, timers, signals, retries, idempotency and versioning approach. Keep these records current, since they become the reference for future changes.
Verification report and handover notes
The verification report records replay results, parallel-run comparisons, rollback rehearsals and the outcome of each cutover. Handover notes cover operating the workers, monitoring, on-call paths and open risks. Ask for both documents to be signed off by your owners before the engagement closes.
What drives cost and duration
Each row names one factor that changes migration effort, why it does so for Temporal, and how to reduce it before the quote is written.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Number and complexity of processes | Each process needs its own workflow design, activity split, retry policy, tests and cutover decision, so effort grows with the count and with branching, loops and human steps. | Inventory every cron job, queue consumer and state machine first, then group processes that share logic so they move as one workflow family. |
| Duration of longest-running executions | Executions that run for days, months or years must survive worker deploys and code changes, which pushes work toward versioning and a parallel run rather than a simple switch. | Measure the longest current runtime of each process, then drain short ones first and plan a parallel run for long ones before choosing a cutover date. |
| Activities that call external systems | Each external call needs timeouts, retry rules and error mapping, and calls that cannot be retried safely need compensation logic. | List every outbound dependency per process, note its rate limits and failure modes, and ask the partner to confirm which calls need idempotency keys. |
| Idempotency of existing side effects | If payments, emails or ledger postings are not idempotent today, replays or retries can duplicate them, so the move may include new deduplication work. | Audit existing side effects and add idempotency keys or lookup-before-write checks before the workflow takes over those calls. |
| Data volume of workflow histories | Large event histories slow replay, increase persistence and visibility storage, and affect how long executions can run before they need continue-as-new or child workflows. | Keep payloads small, store large documents outside workflow history, and confirm storage sizing with the persistence and visibility stores you plan to use. |
| Number of namespaces and environments | Each namespace needs its own retention, access roles and worker fleet, and each environment needs its own cutover rehearsal and data handling. | Limit namespaces to real isolation boundaries, and script environment setup so that development, test and production follow the same steps. |
| Compliance requirements on payloads | Workflow payloads that hold personal, financial or health data may need encryption through a codec server, access controls and retention rules that the current process may not have. | Classify payload fields before design, decide which are encrypted or kept out of history, and ask the partner to map each control to your assessor's evidence needs. |
| Rewrite or lift of existing logic | A lift keeps current business rules and changes only the orchestration layer, while a rewrite redesigns the flow and needs more design and testing time. | Decide per process whether to lift or rewrite, and keep a shared test suite that compares old and new outputs during the parallel run. |
Migration phases and outputs
The sequence moves each process from its legacy scheduler or queue to Temporal without losing work already in progress.
Inventory legacy processes and in-flight state
DeployOpen works with your team to list every cron job, queue consumer, homegrown state machine and workflow engine job in scope, along with its triggers, retries, dependencies and the state of work already in progress. Output: a process inventory with owners, a record of in-flight state for each process and a list of open questions for your engineers.
Choose target architecture and migration pattern
For each process, the team agrees the target design: whether it becomes a Temporal workflow, stays on its existing scheduler while Temporal takes over specific steps, or is retired. Decisions cover workflow boundaries, activity idempotency, namespace layout and whether the service runs self-hosted or on Temporal Cloud. Output: an architecture decision record and a chosen migration pattern for each process, reviewed by your architects.
Prove the approach on one process
DeployOpen builds a proof of concept for one low-risk process with limited blast radius, modest volume and a clear success check. It runs alongside the legacy job, compares outputs and exercises failure cases such as worker restarts and downstream timeouts. Output: a working workflow, a comparison report and a go or no-go recommendation for the wider plan.
Build and test workflows and workers
Workflows, activities and workers are implemented to the agreed design, with unit tests and replay tests run against recorded histories from the proof of concept. Replay checks confirm that code changes stay compatible with executions already running. Output: tested workflow and worker code in your repository, a replay test suite and deployment artifacts for each environment.
Cut over with parallel run or drain
Each process moves in stages. Some run in parallel with the legacy path while outputs are compared. Others drain: the legacy scheduler stops accepting new work, in-flight items finish, and new starts go to Temporal. Output: a cutover runbook per process, a tested rollback path and a dated record of each switch with its approver.
Verify outcomes against the legacy system
Business outputs, data writes, notifications and error counts are compared between Temporal and the legacy path over the verification window set in the written scope. Each discrepancy is traced to a cause and either fixed or accepted in writing. Output: a verification report per process that your process owners sign off before decommissioning begins.
Decommission old schedulers and queues
After sign-off and once no legacy work remains in flight, old cron entries, queue consumers and state tables are disabled, archived and removed in an agreed order. Credentials and access are revoked and runbooks are updated. Output: a decommissioning record, archived legacy configuration and updated operational documentation for your on-call team.
Which parts stay in-house and which are outsourced
This table shows who usually leads each migration area, the skills it needs and where teams most often fall short, so you can decide which work to keep and which to hand to a partner.
| Area | Usually led by | Skills required | Typical gap |
|---|---|---|---|
| Process inventory | Client team, with partner support for scoping | Domain knowledge of each job, owner and data flow; basic Temporal familiarity for scoping | Teams often lack a complete list of cron jobs, queues and hidden state machines |
| Workflow design | Partner leads; client domain experts approve business rules | Temporal SDK experience, business rule knowledge, retry and timeout design | Business rules must stay with client experts, who are often not available for design reviews |
| Activity idempotency changes | Shared: client engineers own side effects, partner reviews patterns | Knowledge of external systems and records, SDK retry behavior, idempotency keys | Existing jobs assume a single run, so duplicate calls to external systems often surface late |
| Worker code | Client engineers, with partner pairing | Client language expertise, Temporal SDK, build and deployment pipelines | Teams underestimate worker shutdown, versioning and deployment compatibility |
| Temporal cluster or Cloud setup | Partner often leads; client platform team operates | Database and Kubernetes operations, network isolation, security review, Temporal server knowledge | Self-hosted clusters need persistence and visibility stores, and default settings need explicit hardening |
| Data and history handling during cutover | Partner leads with client data owners | Workflow history and state knowledge, database operations, data classification and retention review | Plans for running executions and their history are often missing, and retention sign-off comes late |
| Testing and replay checks | Partner leads; client domain experts validate outcomes | SDK replay testing, production-like test environments, written acceptance criteria | Nondeterministic code often fails replay only after realistic runs, late in the project |
| Production cutover | Client platform team owns; partner supports | Change management, runbooks, rollback planning, Kubernetes and database operations | Cutover plans often lack a tested rollback path for workflows already in flight |
| Ongoing ownership | Client team owns; partner available under a retainer | Server and SDK upgrades, on-call, monitoring, change control for workflow code | Knowledge concentrates in a few engineers, and upgrade and patch duties are often unassigned |
What usually goes wrong
Most Temporal migration failures happen during the cutover window, when old and new systems both run the same work. Each risk below has a specific prevention step to settle before the first workflow moves.
Non-idempotent activities running twice
During cutover, an activity can run twice if a worker stops after an external side effect but before Temporal records completion, or if the legacy and Temporal paths both pick up the same task. Activities that charge a card, post a ledger entry or send a notice need idempotency keys built from workflow and activity identifiers. Review each migrated activity for this before any traffic moves.
Workflows still on the legacy path
After the switch, some records can keep flowing through the old cron job, queue consumer or state machine, so one business process runs in two places. Add a dual-run guard that gives each record exactly one owner, and use a cutover checklist that names the legacy switch-off step for every process. Confirm the owner of in-flight records before enabling the new path.
Duplicated timers and schedules
Cron entries, queue delays and Temporal timers or schedules can each fire the same business event. Inventory every scheduled trigger in the legacy system, disable it in the same change that enables the Temporal schedule, and check the schedule's overlap policy so a slow run cannot start a second copy. Record an owner for each schedule.
Executions outliving worker code changes
Long-running workflows replay their recorded history against current code, so a changed branch or reordered call can fail or diverge for executions that started earlier. Use versioning or patching for changed logic, and run replay tests against captured histories before each worker deployment. Ask how old executions will finish before any old worker version is retired.
Sensitive data in plaintext history
Workflow inputs, activity results and signal payloads are stored in event history in the persistence database and can appear in the Web UI. Migrated processes often carry account numbers, health details or personal identifiers that previously sat in a narrower store. Plan codec-based payload encryption with a codec server, and decide which fields should never enter history at all.
Unauthorized API access by default
A self-hosted Temporal Service with no Authorizer configured uses the default noopAuthorizer, which allows every API request with no authentication or access control. Migration scripts, test tooling or a reachable frontend could then act on any namespace. Configure an Authorizer and a ClaimMapper for namespace roles, and keep Temporal services on hosts not reachable from the public internet, before any workload moves.
How the work changes by starting point
Scheduled scripts usually hold little durable state, so the inventory focuses on schedules, hidden dependencies and side effects that run twice if a retry lands on a half-finished job.
- Inventory: list every crontab, scheduler entry and host it runs on, plus the scripts' outputs, locks and files they write.
- State handling: decide where progress is recorded for multi-step jobs, since a script that restarts from the top needs idempotent activities.
- Cutover: run the Temporal schedule beside the cron entry in a non-production namespace, then disable the cron entry once outputs match.
- Verification: compare outputs and side effects for a set of runs, including failure and rerun cases.
- Confirm with Temporal documentation: how schedules are defined and paused, and how to retire a schedule without affecting running executions.
Queue consumers often carry retry, backoff and dead-letter behavior in application code, so the work is mainly moving that logic into Temporal retry policies and proving the message semantics still hold.
- Inventory: map each queue, consumer, retry rule, dead-letter queue and the ordering or deduplication assumptions producers rely on.
- State handling: decide whether messages in flight are drained, replayed or left on the old queue, and how a workflow ID maps to a business key.
- Cutover: drain producers or dual-route for a window, and confirm no message is processed by both systems.
- Verification: replay a sample of historical messages and compare results, retries and dead-letter counts.
- Confirm with Temporal documentation: how retry policies and non-retryable errors are configured, and how workflow ID reuse behaves.
A state machine stored in database tables already holds durable state, so the migration centers on converting transitions into workflow code and deciding what happens to rows that are mid-transition.
- Inventory: document every state, transition, timer, compensating action and the tables and columns that record them.
- State handling: choose whether open records are migrated into new workflow executions, closed at cutover, or finished by the old engine.
- Cutover: migrate open records by state in batches, with each batch started from a known state and reconciled.
- Verification: reconcile counts and final states between the old tables and workflow histories, and test each transition path.
- Confirm with Temporal documentation: how to start executions from external data, and the limits and behavior of timers and signals for long waits.
Moving from another engine means translating its process definitions, retry semantics and persistence model, and the in-flight instances often cannot simply be copied across.
- Inventory: list process definitions, versions, timers, human tasks, subprocesses and the instances still running on the old engine.
- State handling: decide whether running instances finish on the old engine, are restarted from a defined point, or are rebuilt from business data.
- Cutover: run both engines for new starts by process type, moving one type at a time and retiring the old engine only after its instances end.
- Verification: compare outcomes for paired test cases and confirm that compensation and timeout paths behave the same.
- Confirm with Temporal documentation: whether any import path from the source engine exists. Do not assume one; confirm the supported approach first.
Moving between your own cluster and Temporal Cloud is a platform move, so the workflow code may stay the same while namespaces, endpoints, certificates, identity and data residency change.
- Inventory: list namespaces, workers, client certificates, retention settings, search attributes and every service that connects to the frontend.
- State handling: determine how running workflows are handled, since in-flight executions may not move as-is between clusters or namespaces.
- Cutover: route new starts to Temporal Cloud by namespace, then move workers, and keep the self-hosted cluster available until its executions finish.
- Verification: confirm connectivity, authentication, search attributes and retention behavior before shifting traffic.
- Confirm with Temporal documentation: which options exist for moving in-flight executions between clusters or namespaces, and what the current Temporal Cloud onboarding requires.
When the source is a self-hosted cluster on Kubernetes or in an air-gapped network, the work includes chart and image versions, offline artifacts and network paths that the migration must not break.
- Inventory: record server, Helm chart and SDK versions, persistence and visibility stores, and every image or package needed offline.
- State handling: confirm the persistence store can be reached by the target cluster, and decide whether executions move or the old cluster drains.
- Cutover: upgrade the source to a supported state first, then stand up the target with matching versions and drain traffic in steps.
- Verification: test failover, worker reconnection and visibility queries in the isolated network before cutover.
- Confirm with Temporal documentation: Helm chart and server compatibility, schema upgrade order, and the supported approach for moving executions between clusters.
What the client needs to provide
Before DeployOpen can scope a migration to Temporal, the client needs to name decision owners and give the team access to the systems being replaced. Each process moving off a cron job, queue or homegrown state machine needs a named business owner who can confirm expected outcomes, accept behavior changes and sign off on its cutover. Engineering owners for the legacy code, scheduler definitions and queue configurations should be named alongside them. Read access to the code, crontab or scheduler entries, queue settings and retry policies should be in place before scoping starts.
Scoping also depends on a current inventory of work in motion. Ask for a count of in-flight jobs and long-running instances per process, including how long the longest ones run and what they wait on. Those executions decide whether a process can be drained, paused, or must run to completion on the old system. Provide incident history and runbooks for these processes, since they show the failure modes the new workflows must handle. A non-production environment that resembles production in data volume, queue layout and integrations is needed to rehearse the move, and it should be available early.
Three platform decisions must be made before scoping closes. The first is hosting: self-hosted Temporal in your infrastructure or Temporal Cloud. This choice determines who operates the persistence and visibility stores and affects how a later move between the two can be planned without losing running workflows. The second is data classification for workflow payloads, because inputs and results are stored by the Temporal service and may need encryption through a codec. The third is an identity and access model for Temporal namespaces, covering which teams and service accounts may start, signal, query or administer workflows, and which identity provider issues those roles.
Finally, name who decides cutover windows and who holds rollback authority. A common split gives the business owner approval of each window and gives the platform owner rollback authority, with written conditions that trigger a rollback. Confirm both people, their deputies and how each decision will be recorded before the first cutover rehearsal. DeployOpen will reflect these roles in the migration plan so that no one has to decide them during an incident.
Frequently asked questions
What does moving our cron jobs to Temporal cost?
The cost follows from the written scope, and DeployOpen does not publish a price list. The main cost drivers are the number of processes to move, how long each one runs, how many executions must keep running across cutover, how many systems trigger or receive results from each process, and how much state the legacy system holds. One-time costs cover discovery, workflow design, activity and retry design, testing and cutover. Recurring costs cover the Temporal hosting you choose, either your own infrastructure and databases or Temporal Cloud usage, plus any support retainer. Ask for a quote with line items per process group, the assumptions about legacy integrations, and the work you expect your own team to provide.
How long does a Temporal migration take from start to finish?
Duration depends mainly on the number of processes to move and the length of the longest execution, and the written scope sets the timeline. Processes that run for days or months need a cutover plan that lets existing executions finish on the old system or continue on Temporal, which adds design and test time. Each process also needs its own review of activities, retry policies and idempotency. Ask for the timeline per process group, the number of test cycles assumed, and the cutover windows your operations team can accept before you sign.
Can our own engineers migrate to Temporal without a partner?
Yes, if your team already has Temporal experience and workflow design skills. Those skills include using the Temporal SDK for your application language, writing deterministic workflow code, designing idempotent activities with clear retry and timeout settings, and handling signals, queries and child workflows. Your team also needs to version workflow code safely, deploy and scale workers, and run the Temporal Service with its persistence and visibility stores. If one or more of these skills is missing, a first migration is often the point where an outside review or pairing session pays off.
What does a migration need from our engineering and operations staff?
A migration needs named owners across several groups. Process owners explain business rules, exceptions and what a correct outcome looks like. Developers who know the legacy code provide the logic that moves into workflows. Platform engineers plan hosting, networking and worker deployment. Security reviews access, secrets and payload encryption. Operations sets on-call duties, runbooks and monitoring. Your staff also need time for design reviews, access to test environments with realistic data, and availability during cutover windows. Confirm each of these commitments in the written scope so that they are scheduled before build work starts.
Can running workflows move between self-hosted Temporal and Temporal Cloud?
Confirm the supported path with Temporal for your server version and your specific executions before you plan the move. Moving running executions between a self-hosted cluster and Temporal Cloud is an operational question, and the answer depends on versions, namespaces and the state of each execution. Check how long-running histories, pending timers, signals and child workflows are handled. Test the move on copies of representative executions, and document what happens to in-flight work during cutover. Also plan how workers will switch to the new endpoint and how you will roll back if a test fails.
What happens to the legacy system after cutover?
The legacy system stays in place until the last process handed off to Temporal has finished, then it is retired on a schedule you agree. Start by disabling new triggers so that the legacy scheduler no longer starts work. Keep the old system available for rollback during an agreed window. After that, archive the logs and data your audit requirements call for, remove credentials and network paths, and update monitoring, dashboards and runbooks. Decommissioning is a separate task, so ask whether it is included in the written scope.
How DeployOpen scopes, delivers and hands over migrations
DeployOpen plans, builds, documents and supports Temporal migrations inside infrastructure you control, starting from a written scope that names the processes to move. Engagements are fixed-scope, with ongoing support available as a retainer.
How we scope
- Inventory the cron jobs, queues, homegrown state machines and workflow engine processes that are candidates for Temporal.
- Record which long-running processes must finish on the old engine and which can be restarted safely.
- Decide whether the target is self-hosted Temporal or Temporal Cloud, and which migration direction the written scope covers.
- Agree the cutover approach for in-flight executions, including how running workflows are drained or carried across.
How we build
- Design workflows and activities for each migrated process, with idempotent activities and explicit retry and timeout policies.
- Set up the Temporal Service, persistence and visibility stores in your environment, with the versions you approve in writing.
- Run replay and integration tests against representative histories before any production traffic moves.
- Restrict network access to trusted internal networks and set authorization and encryption settings before go-live.
How we hand over
- Deliver runbooks for cutover, rollback, worker deployment and retirement of the legacy scheduler or state store.
- Document the workflow inventory, namespace layout, configuration and the upgrade path agreed in the written scope.
- Walk your operations and development teams through workflow code, dashboards and incident procedures.
- Provide evidence of tests run and migration decisions so your own auditors can review the work.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after go-live, scoped in writing.
- Plan Temporal Server upgrades one minor version at a time, with schema changes applied before server upgrades when release notes require them.
- Review Helm chart and SDK compatibility when versions change, so workers and the service stay aligned.
- Confirm with your team which support tier, such as Temporal Cloud support add-ons, fits your uptime and response needs.
