Skip to content

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 and flows, 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 cosmetic or layout-only save, does not pile up versions.

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. In-flight instances are untouched; new ones pick up the edit. No extra steps.
  • 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 (the pre-1.0 behavior). 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 current version id is held in a cached pointer, 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.

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.

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 published 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.

Legacy instances

Instances created before versioning have no pinned version and fall back to the live workflow, exactly as before. They are unaffected by the feature until migrated (see the roadmap).