Process Versioning
Updating a workflow that is already running is risky. If you change the scheme while instances are in flight, some may be mid-transition, some may be waiting on a timer, and others may be in states that no longer exist in the new definition. Without versioning, every deployment forces a choice between aborting running instances or locking the process definition until they all finish.
Process versioning lets you publish a new process definition without forcing running instances to change. By default, each running process keeps the definition it started with, while new processes receive the latest published definition. When an in-flight process should move to the new definition, the runtime can update it explicitly or lazily before returning its available commands.
With process versioning, you deploy workflow changes on your schedule, not when all running instances happen to finish. A compliance officer adds an approval step to a procurement process; orders already in flight continue under the old rules, and new orders follow the updated flow.
What it is
Think of process versioning like publishing a document revision. When you publish a new version of a document, readers who already have the old copy keep it - they do not get interrupted mid-sentence. New readers automatically receive the latest published version. You decide when to stop distributing the old version.
Process versioning works the same way. Each time you save a process definition through the Visual Designer, the system creates a new version. Existing running processes keep the version they started with by default, and new processes start on the latest version. An eligible running process can also migrate after its old scheme is marked obsolete.
For developers: the runtime exposes SetSchemeIsObsoleteAsync(schemeCode) to mark existing scheme records for a given code as obsolete. To enable lazy migration, call SwitchAutoUpdateSchemeBeforeGetAvailableCommandsOn() when configuring the runtime and set IsAutoSchemeUpdate="true" on safe activities. Before GetAvailableCommandsAsync returns commands, the runtime updates an obsolete process only when its current activity permits the update. You can also call UpdateSchemeIfObsoleteAsync(processId) explicitly. See Update a Running Scheme for configuration and migration details.
Why it matters
Process versioning delivers these outcomes:
Zero-downtime workflow updates - publish scheme changes any time. Running instances are unaffected. There is no deploy-freeze window, no need to wait for all instances to finish before rolling out a change.
Auditable change history - each save creates a distinct scheme record. Old versions remain in the persistence store for audit or rollback (if not explicitly cleaned up). You can trace which scheme version a completed instance ran on.
Controlled cutover -
SetSchemeIsObsoleteAsyncis a deliberate action. You can save a new scheme, verify it, and deprecate the old one when you are ready. The Designer does this automatically on save, or you can control the timing from code.Automatic or selective migration - eligible running instances can update lazily when the application requests available commands, or you can update instances individually or in bulk via
UpdateSchemeIfObsoleteAsync.
Who it is for
Evaluator (CEO, CTO, PM): process versioning removes the deployment risk from workflow changes. Your team can update process logic without coordinating instance completion times, reducing release cycle time and operational overhead. Process changes ship when they are ready, not when the last running instance finishes.
Developer: versioning is automatic - every scheme save creates a new record. You manage the cutover with SetSchemeIsObsoleteAsync. With the runtime setting enabled, requesting available commands also updates obsolete instances whose current activity has IsAutoSchemeUpdate enabled. See Update a Running Scheme for configuration details.
Enterprise architect: scheme records are stored in the same persistence store as process instances. Each record has a unique GUID identifier and an IsObsolete flag. There are no auto-incrementing version numbers, external version registries, or additional infrastructure. The scheme definition is always consistent with the stored scheme record - no drift between what is deployed and what is persisted.
When to use it
Use process versioning whenever your process definitions change over time. It is the default behavior of the runtime - every save through the Designer creates a new version. Typical examples:
Adding steps to a live process - a procurement workflow needs an additional manager approval. Save the updated scheme; new purchase orders follow the new path, existing ones continue under the old rules.
Fixing rule conditions or timer values - an approval condition was too restrictive, or a timer duration was too short. Update the scheme, mark the old version obsolete, and new instances use the corrected values.
Phased rollouts - save a new scheme version, validate it with test instances, then mark the old version obsolete when you are ready to cut over all new instances.
Regulatory or compliance updates - a policy change requires a different approval chain. Update the scheme and deprecate the old version. Existing instances keep their original approval chain for audit compliance.
How it compares
Workflow Engine's process versioning is built into the runtime at the persistence layer. The comparison below shows the difference between relying on this built-in mechanism versus building your own.
| Approach | What it requires | Result |
|---|---|---|
| Build your own versioning (external) | Custom migration scripts, version tables, or branch-per-version workflows. Manual mapping of running instances to scheme versions. | Engineering effort to build and maintain. Risk of drift between deployed and persisted schemes. |
| Workflow Engine process versioning | Each save creates a scheme record. SetSchemeIsObsoleteAsync controls the cutover, and runtime/activity settings control lazy migration. | The runtime keeps each instance bound to a stored scheme until the application updates it. |
Workflow Engine keeps each process instance bound to an explicit stored scheme version. The application decides whether an existing instance stays on that version or migrates at a configured checkpoint.
Frequently asked questions
Does process versioning automatically affect running process instances?
Not by default. Running instances remain on their stored scheme until the application calls UpdateSchemeIfObsoleteAsync, or until GetAvailableCommandsAsync triggers lazy migration with the runtime setting enabled. Lazy migration also requires IsAutoSchemeUpdate on the current activity.
Can I update a running instance to the latest scheme version?
Yes. Call UpdateSchemeIfObsoleteAsync(processId) on the runtime. The update proceeds when the stored scheme is obsolete and the current activity has IsAutoSchemeUpdate enabled. Pass ignoreAutoSchemeUpdate: true to bypass the activity flag. Alternatively, enable automatic update before GetAvailableCommandsAsync to migrate eligible instances as users interact with them.
What happens if all scheme versions are marked obsolete?
The runtime creates a new scheme record automatically. CreateNewProcessAsync catches the SchemeNotFoundException when no non-obsolete scheme exists and generates a fresh scheme definition using the runtime's scheme generator. New instances are created on the generated scheme. There is no manual intervention required, and no exception is thrown.
Do I need a specific license or edition to use process versioning?
No. Process versioning is built into the core runtime and is included with all Workflow Engine editions. Every scheme save creates a new versioned record - there is no configuration required and no additional license.
Can I delete old scheme versions?
Yes. The persistence provider exposes DropUnusedWorkflowProcessSchemeAsync() to remove scheme records that are not referenced by any running or completed process instance. This is useful for housekeeping in long-running deployments. Use with care - deleted schemes cannot be used for audit traceability.