Versioning¶
A workflow is editable, but instances of it can run for a long time. Without versioning the engine would read the live workflow on every step, so editing a workflow would change the behavior of instances already running on it, and an edit that removed a node a token was sitting on would break them. Versioning pins each instance to the definition it started on.
How it works¶
When an instance starts it is pinned to an immutable version: a snapshot of the workflow's executable definition (its tenant, start node, nodes, flows and declared initial variables, but not the diagram layout). From then on the engine runs the instance against that snapshot, so editing the workflow afterwards never affects it. A new instance picks up the current definition.
Snapshots are stored as revisions of an orchestra_workflow_version content
entity, one per workflow, and an instance records the revision id it pinned.
Identical definitions share a snapshot (deduped by a hash of the executable
shape), so reverting a workflow to an earlier shape, or a save that only
moved the diagram, does not pile up versions.
Wording¶
The pin covers the wording too. A node's label is part of the executable definition, so renaming one cuts a new version: instances already running keep the label they started with, and only new instances show the new one.
Translations are the exception, and deliberately so. A language override is not part of the executable shape, so retranslating a label cuts no version. The text captured on the current snapshot is refreshed in place instead, and the instances pinned to it show the corrected wording straight away. A wording fix therefore reaches a running instance when it is made in a translation, and not when it is made in the workflow's own language.
Modes¶
The behavior is set by Workflow versioning on the Orchestra settings page
(or the versioning_mode setting), one of:
- Automatic (default): editing a workflow snapshots a new version the next time an instance starts on it, or when you migrate running instances to it. Merely editing, or viewing the versions or instances pages, never cuts a version. In-flight instances are untouched; new ones pick up the edit.
- Manual: instances run the last published version. Editing a workflow changes nothing, for running or new instances, until you publish it again. This is the deploy-style model: iterate on a draft freely, then publish when ready. The first start of a never-published workflow publishes it once to bootstrap.
- Off: no pinning. Instances always run the live workflow. Choose this only if you never edit a workflow while instances of it are running.
Whatever the mode, an instance always keeps the version it started on; the mode only affects which version a new instance pins.
Performance¶
Pinning is designed to stay cheap on the start path: the version a workflow pins is recorded, so starting an instance is a single lookup with no hashing or extra entity load. The snapshot's hash is only computed, and a new revision only considered, the first time an instance starts after an edit (in automatic mode) or when you publish (in manual mode). Advancing a token reads an immutable snapshot, which caches permanently, so it is no costlier than reading the live config.
Listing versions or instances only compares the live shape's hash to the stored versions to show which one is current, so viewing a page never cuts a version. A version is materialized only when an instance pins to it (a start or a migration).
Versions and migration¶
Each workflow has a Versions tab listing its versions, when each was created, and how many running instances are pinned to each. In manual mode the tab also has a Publish current definition button. In automatic mode, if you have edited the workflow but no instance has started or migrated onto the new shape yet, the tab says the current shape is not versioned yet and offers Migrate running instances to the current shape, which cuts that version at that point rather than on merely viewing the page.
To move running instances from an old version onto a newer one, use Migrate instances here on the target version. Migration remaps each running instance's live tokens onto the target: nodes whose id is unchanged map automatically, and for any node that was renamed or removed you choose where its tokens go. It validates first and refuses the whole migration if a live token would be left on a node that does not exist in the target, so an instance is never half-migrated. Instances already on the target are left alone.
The same migration is available from the command line, for deploy scripts, headless sites or bulk runs:
drush orchestra:migrate-versions WORKFLOW [--to=VERSION] [--map=old:new,old2:new2] [--dry-run]
--to defaults to the current published version; --map carries the
renamed/removed-node mappings; --dry-run reports how many instances would move
and which live nodes still need a mapping, without changing anything.
A single instance can also be moved on its own. On the process instance list
(orchestra_inbox / orchestra_ui), an instance pinned behind its workflow's
current version shows a Migrate to current operation that migrates just
that instance, and the list's Migrate selected to current bulk action runs
the same per-instance migration over the selection as a batch. An instance
whose migration needs a node mapping (a renamed or removed node) is reported and
left for the per-workflow Migrate instances here form, which collects the
mapping; the same list also offers per-instance Cancel and Delete.
The list's Version column makes the pinning visible: each row shows the version the instance is pinned to, marked N (current) when it is the workflow's current version (in automatic mode the version matching the live shape, in manual the published version; the same marking as the versions page), so an instance behind it, the candidate for the migrate operations above, stands out at a glance. The list's columns sort, and a collapsed Filter narrows it by workflow and state (and, for an administrator, tenant); the filter lives in the URL, so a filtered view can be shared.
Instances that pin nothing¶
An instance pins no version when it started under the Off mode, the one mode that never pins. Such an instance falls back to the live workflow, and the instance list shows it as Live in its Version column. The migrate operations above are the way to put it on a version: pinning is never applied retroactively.
The reverse cannot happen: a version an instance pins is never pruned out from under it. Retention skips any snapshot revision an instance references, along with each workflow's current and published version, so a pinned instance keeps the shape it started on for as long as it runs.