Durable Execution
Workflow Engine stores confirmed process checkpoints through IPersistenceProvider. A checkpoint can include the current activity and state, transition history, dirty persistent parameters, and timer registrations. After an interruption, the runtime uses the last persisted checkpoint and applies a defined recovery policy. The default policy assigns Error or Terminated according to the process's available continuation paths, while IProcessRestorer can re-execute, resume, or delete the process. Applications can use idempotency or coordination patterns when external operations must stay consistent with persisted workflow progress.
Long-running business processes should not lose their confirmed progress because an application restarts or a server stops. Without persisted checkpoints, the application must reconstruct each process instance, its pending commands, and its timers itself.
Durable execution is Workflow Engine's checkpoint-and-recovery model. It stores confirmed workflow progress in a database so an idled process can continue from its last persisted activity when the next command or timer arrives.
Durable execution preserves the last persisted checkpoint. If an interruption occurs during an action, recovery follows the configured policy rather than resuming from the exact interrupted instruction. Exactly-once effects in external systems require application-level idempotency or coordination.
What it is
Think of durable execution as saving a process at defined checkpoints. Between periods of active work, the database holds enough workflow state to load the process again without keeping its call stack, execution thread, or local variables in memory.
A checkpoint can include the current activity and state, completed transition history, dirty persistent parameters, process status, and timer registrations. Temporary parameters and local variables inside action code are not part of that durable state.
Each WorkflowRuntime uses an IPersistenceProvider to store durable process data. As a process advances, the runtime records its current activity and state, transition history when enabled, and changed persistent parameters. Together, these records form the checkpoint used to load the process again or apply recovery after an interruption.
An idled process does not need a special startup replay. Its persisted state is loaded when a command, timer, or API operation accesses it. Timer schedules are stored in persistence rather than in server memory. In single-server mode, timers are not lost if the server goes down: the runtime processes overdue timers after it starts again. In multi-server mode, another active server processes due timers while the failed server is unavailable.
Interrupted process recovery
A process can remain in Running when a server stops after execution has started but before the runtime releases the process status. The default recovery flow does not automatically execute the interrupted activity again. It sets the process to:
Errorwhen the current activity has command transitions or the process has active timers;Terminatedwhen neither command transitions nor active timers provide a way to continue.
A registered IProcessRestorer can choose another policy for matching schemes and recovery statuses. It can execute the current or a specified activity, resume after that activity without executing it, or delete the process. The application must select a policy that is safe for the actions performed by that scheme.
For developers: configure a supported persistence provider on WorkflowRuntime; process checkpoints and timer records are then stored by the runtime. See the Persistence concept for the data model; customize interruption recovery by registering an IProcessRestorer.
Why it matters
Durable execution delivers these outcomes:
- Processes can wait without occupying an execution thread or consuming per-process application memory - an idled process remains in persistence and is loaded only when a command, timer, or API call starts the next transition.
- Application restarts retain committed progress - the runtime reloads the last stored activity, state, persistent parameters, status, history, and timer records as needed.
- Planned shutdowns minimize interrupted work - the runtime waits for active operations and background services by default before stopping.
- Interrupted execution has an explicit recovery path - default recovery removes a stale
Runningstatus, whileIProcessRestorercan apply a scheme-specific re-execution or resume decision. - Timers and transition history remain available - persisted timer registrations and enabled history records do not depend on one application process remaining alive.
- Persistence behavior is configurable - parameter purposes and activity flags control which data belongs to a checkpoint when a workflow has intentionally transient data or steps.
Durable execution preserves confirmed workflow progress through the persistence provider. For actions that also update external systems, use idempotency keys, an inbox or outbox pattern, or compensating business operations to coordinate those effects with workflow recovery.
Who it is for
Evaluator (CEO, CTO, PM): durable execution makes long-running business processes resilient to application restarts by preserving confirmed progress and providing a defined recovery path after interruptions.
Developer: the runtime manages process checkpoints and timer storage, while developers control which parameters persist and can apply idempotency, retry, or compensation patterns to actions that update external systems.
Enterprise architect: durable workflow records live in the selected persistence database, so Workflow Engine can build on its transaction guarantees and the organization's established replication, backup, recovery-time, and availability strategy.
Long-running workflows and processes
A long-running workflow can remain active for hours, days, months, or years. Most of that time the process is idled, waiting for a human decision, a timer, or a callback. The database stores the process checkpoint during that wait; the runtime does not keep an execution thread allocated for the entire lifetime.
Workflow Engine does not impose an age-based expiration on an active process instance. Its practical lifetime still depends on application cleanup policies, database retention and backups, and the continued availability of the scheme and application code needed to process future operations.
Each long-running process is identified by its ProcessId. Its persisted records describe the current activity and state, persistent parameters, process status, transition history, and pending timers, subject to the configured persistence controls.
| Execution model | Persisted unit | Behavior after restart | Typical use |
|---|---|---|---|
| Workflow Engine process | Process checkpoint, parameters, history, and timers | Loads the last checkpoint; a process left in Running passes through recovery | Approvals, onboarding, and callback-driven orchestration |
| Database transaction | Changes committed by one transaction | A committed transaction remains; an interrupted transaction rolls back according to the database | Short atomic data changes |
| Durable queue or scheduler | Message or job record | Redelivery or rescheduling follows that system's policy; workflow state requires an application model | Background jobs and message delivery |
| In-memory request or worker | No durable unit unless the application creates one | In-flight work is lost or restarted according to application code | Short operations that can be retried as a whole |
When to use it
Durable execution is part of each process run with a configured persistence provider. It is especially relevant in these scenarios:
- Human approval and document workflows - a process can wait for days or months between commands without keeping application resources allocated.
- Callback-driven integrations - a persisted checkpoint remains available while another system prepares and submits a result.
- Timer-driven workflows - the next timer execution remains registered across deployments and restarts; overdue timers are processed when a timer manager becomes active again.
- Payment and order orchestration - workflow checkpoints record confirmed business progress. Applications can use idempotency, inbox or outbox handling, or compensation to coordinate updates across payment, inventory, and fulfillment systems.
- Multi-server deployments - shared persistence lets active runtime instances coordinate timers and recover processes associated with a server that becomes unavailable.
For workflows that coordinate application data or third-party services, combine persisted checkpoints with the consistency, idempotency, and retry patterns appropriate to each integration.
Controlling what gets persisted
Durable execution uses a persistence provider, but a scheme or API call can control which parts of a checkpoint are written.
Parameter purpose. Each process parameter has a ParameterPurpose:
Persistencestores the parameter in the database so it remains available to later operations.Temporarykeeps a parameter for the current transition process and does not write it to persistence.
Code that works with a ProcessInstance can pass ParameterPurpose.Persistence to SetParameter or SetParameterAsync.
Activity-level persistence flags. Each activity has three independent flags:
- DisablePersistParameters skips the persistent parameter write at that checkpoint.
- DisablePersistState skips the current activity and state update at that checkpoint.
- DisablePersistTransitionHistory skips the transition history record at that checkpoint.
DisablePersist sets all three persistence flags together, while the individual flags let you configure state, parameters, and transition history independently.
Command parameter persistence. A CommandParameter has an IsPersistent flag. WorkflowCommand.SetParameter(name, value) uses persist: false by default; pass persist: true when the value must remain available after the transition process finishes.
Parameters supplied by runtime operations. CreateInstanceParams, SetStateParams, and ResumeParams provide AddPersistentParameter and AddTemporaryParameter for values passed to process creation, a SetStateAsync call that executes the target activity, or a ResumeAsync call. The SetActivityWithExecutionAsync overload accepts a persist list for parameters supplied to direct activity execution. A RestoreDecision provides the same choice for values passed to custom recovery. AddPersistentParameter marks the supplied name with ParameterPurpose.Persistence; AddTemporaryParameter adds no persistence marker, so an existing scheme-defined parameter purpose still applies. Values marked persistent are saved when the corresponding execution writes a checkpoint.
| Mechanism | What it controls | Scope |
|---|---|---|
ParameterPurpose | Whether a process parameter is persistent or temporary | Individual parameter |
ActivityDefinition.DisablePersist* | Whether state, parameters, or history are written at a checkpoint | Destination activity |
CommandParameter.IsPersistent | Whether a command-supplied parameter is marked persistent | Command execution |
CreateInstanceParams.Persist | Which initial values are marked with ParameterPurpose.Persistence | Process creation |
SetStateParams.Persist | Which supplied values are marked with ParameterPurpose.Persistence | SetStateAsync with target activity execution |
ResumeParams.Persist | Which supplied values are marked with ParameterPurpose.Persistence | ResumeAsync execution |
SetActivityWithExecutionAsync(..., persist, ...) | Which supplied values are marked with ParameterPurpose.Persistence | Direct activity execution |
RestoreDecision.Persist | Which supplied values are marked with ParameterPurpose.Persistence | Custom recovery execution |
SetPersistentProcessParameterAsync | One persistent value that is updated and saved directly | Runtime API call |
How it compares
A durable queue or scheduler preserves an individual work item. Workflow Engine preserves the configured checkpoint of the whole multi-step process: where it is waiting, which persistent data it holds, which transitions have completed, and which timers are scheduled. This difference determines whether recovery handles one work item or the state of a coordinated process.
| Approach | Durable record | Behavior after interruption | Application responsibility |
|---|---|---|---|
| Custom state machine | Application-defined checkpoint tables and records | Application code reloads a checkpoint and applies its retry or recovery rules | Design and maintain checkpoint storage, history, timers, concurrency, and recovery |
| Queue or scheduler | Message or job data plus delivery or schedule state | The system redelivers or reschedules the work item according to its policy | Maintain business process state and history across related work items |
| Workflow Engine durable execution | Configured process checkpoint with activity, state, persistent parameters, status, enabled transition history, and timers | An idled process loads when new work arrives; a process left in Running follows its recovery policy | Configure the persistence provider, persistence controls, and optional IProcessRestorer |
Use a queue or scheduler when the durable unit is an independent message or job. Use Workflow Engine durable execution when several activities, waits, commands, and timers must continue as one coordinated process.
See also
Persistence
How Workflow Engine stores schemes, process instances, parameters, history, and timers.
Clustering
How multiple runtime instances coordinate timers and recover work when a server stops.
Timers and Scheduling
How persisted timers advance process instances when their scheduled time arrives.
Multi-Database Support
Which databases have built-in persistence providers and how they store workflow state.
Frequently asked questions
What process data survives an application restart?
Durable execution reloads the last committed activity and state, process status, persistent parameters, enabled transition history, and timer registrations. Temporary parameters, action-local variables, and an in-flight call stack are not persisted.
Does durable execution resume an interrupted activity automatically?
No. Durable execution preserves the last checkpoint. Default recovery changes a process left in Running to Error or Terminated; an IProcessRestorer can explicitly re-execute or resume from a selected activity.
Does durable execution guarantee exactly-once action execution?
No. Durable execution cannot put workflow persistence and an external side effect into one transaction. Actions that call external systems should use idempotency, inbox or outbox handling, or compensating operations.
Is there a maximum lifetime for a Workflow Engine process?
Durable execution does not apply an age-based expiration to process instances. Practical lifetime depends on database retention, backups, application cleanup policies, and the availability of the scheme and application code.
Is durable execution available in every Workflow Engine edition?
Core durable execution and single-server recovery are available in every edition. Multi-server coordination and recovery require the Ultimate edition; see Workflow Engine Editions.