Skip to main content

Lifecycles and workflows

State machines​

A stateMachines entry says which moves a record may make between the states of a column. The generated application enforces it and draws it.

  • Action buttons. A record shows one button per move this person may make out of its current state, labelled by the state it enters. GET /api/bus/{entity}/{id}/actions lists them.
  • Pressing a move. POST /api/bus/{entity}/{id}/transition saves any unsaved form values, writes the new state, stamps <state>_at where the table has that column, then runs every workflow bound to entering that state.
  • The state is set only by moves. Create assigns the initial state, and an ordinary save that changes the state is refused.
  • Final states close a record. It can no longer be edited or deleted by anyone.
RefusalCode
A move the machine does not draw409 INVALID_TRANSITION
A move this person's roles may not make403 TRANSITION_FORBIDDEN
A bound workflow failed422 WORKFLOW_FAILED

When a bound workflow fails, the move is undone: the state, its timestamp and the version are put back, and the reason is stored on the record. Every press, whether made, refused or failed, is recorded in sys_record_transitions.

Processes (sagas)​

A sagas entry is a multi-step process compiled to BPMN and executed by the backend. A process can be bound to a status, so it runs when a record enters that state, or started by a rule's trigger-workflow action. Its run log records what actually happened.

Editing in the running application​

The Rules and workflows screen edits status machines and processes in the running application. A status machine drawn there is enforced at once, and who may press each move is set on the move itself.