Versions

Definitions are stored with their version (anvil_workflow_definitions). Every record keeps the version it started with and runs on it, so a changed definition never breaks records in progress.

Changing a definition

1. Change the definition.
2. Increase Workflow::version().
3. Run php spark anvil:workflow:check: it stores the new version.

anvil:workflow:check (and the engine) refuse a changed definition with the same version: the stored definition of a version never changes.

New records start on the new version; running records stay on theirs until they are moved.

Moving running records

Move records of an older version to the current version, with a mapping of renamed or removed states:

php spark anvil:workflow:migrate order-approval --from 1 --map checked:approved --dry-run
php spark anvil:workflow:migrate order-approval --from 1 --map checked:approved

• --dry-run shows what would happen: how many records move from which state to which.
• States that exist in the new version are kept; states that do not must be mapped (--map old:new,old2:new2), otherwise nothing changes and the command names the missing state.
• A mapped state is written to the state column and starts counting its deadline anew.
• All tenants are moved in one transaction; the move is audited (workflow.migrated).
• Open tasks are not changed by the move.

What needs a new version

Everything the definition produces: states, transitions, actors, tasks, deadlines, labels, keys of building blocks. Changing the code of a registered building block does not – but think about records in progress when its behaviour changes.

Diagrams

php spark anvil:workflow:diagram order-approval --version 2

prints a Mermaid state diagram of a version, e.g. for the documentation of an application or a review with the department.