Stages and transitions

Stages mark where an instance is. Transitions define where it can move.

An instance is in exactly one stage at a time. It begins at the definition’s initialStage; the current stage controls which scoped fields, activities, actions, guards, and outgoing transitions are in play.

A stage does not necessarily contain work. It may receive an instance, wait for external state, route immediately, or represent an outcome. A stage with no outgoing transitions is structurally terminal: reaching it completes the instance.

A stage declares:

defineStage({
  name: 'review',
  title: 'Review',
  fields: [
    defineField({type: 'string', name: 'decision'}),
  ],
  activities: [
    defineActivity({
      name: 'editorial-review',
      actions: [
        defineAction({name: 'approve', status: 'done'}),
      ],
    }),
  ],
  transitions: [
    defineTransition({
      name: 'to-published',
      to: 'published',
      when: '$allActivitiesDone',
    }),
  ],
})

A stage combines location-specific state with optional behavior. Fields explains stage scope and Activities and actions explains the work model.

Entering a stage resolves its scoped fields, creates its activities, and registers its guards. Re-entering the same stage creates a new visit; earlier visits remain in history.

Activities are active from stage entry until an action assigns a terminal status. A stage with no activities is still valid, and activity completion alone never moves the instance; movement is always expressed by a transition.

A transition is a directed edge to another stage. Its when condition decides when it fires using the transition’s GROQ variables.

defineTransition({
  name: 'to-review',
  to: 'review',
  when: 'defined($fields.reviewer)',
})

If when is omitted, authoring expands it to $allActivitiesDone. Use when: 'true' for an unconditional route.

Transitions contain no operations or effects. Actions write the routing decision into fields; transitions read that state through conditions. Arrival work is a triggered action in the destination stage. Work that must happen before an edge fires belongs to an action in the source stage.

A transition’s when runs during the cascade without a caller. The table lists its available variables; see Conditions → Variables for their value shapes.

After each committed operation, the engine evaluates every outgoing transition in declaration order. The first truthy condition fires. It exits the current stage, enters the target, and reevaluates the new state.

Triggered actions and transitions can make one another eligible, so the engine continues the cascade until the instance settles or reaches a terminal stage. The complete edge shape is described above in Transitions are pure edges.

This is the object passed to defineStage(...) in a workflow’s stages array.

This is the object passed to defineTransition(...) in a stage’s transitions array. It declares a pure edge from that stage to another stage.