Activities and actions

Activities represent work in a stage. Actions let callers and triggers update workflow state, queue effects, and resolve that work.

An activity is a unit of work scoped to one stage visit. Its actions are the named responses available while that work is active. A caller invokes an action; the engine fires an action with a condition as an automated trigger. See Stages and transitions for how activities fit into a stage visit.

Firing an action commits its operations atomically. It may also set an activity outcome in that commit. Transitions evaluate the resulting state; actions do not move the instance directly. Effects run after the commit for external work.

Declare the work, when it applies, when it is ready, and the actions available while it is active:

defineActivity({
  name: 'review',
  title: 'Review article',
  filter: '$fields.needsReview',
  requirements: {assigned: 'defined($fields.reviewer)'},
  actions: [
    defineAction({name: 'approve', status: 'done'}),
  ],
})

An activity filter decides whether the activity exists for a stage visit. Ordered GROQ requirements keep an existing activity visible while blocking its caller-fired actions until every requirement passes.

defineActivity({
  name: 'review',
  requirements: [
    {
      type: 'groq',
      name: 'assigned-reviewer',
      title: 'Assigned reviewer required',
      query: '$assigned',
    },
  ],
  actions: [defineAction({name: 'approve', status: 'done'})],
})

Both properties use conditions, but they answer different questions.

An included activity remains active until an action resolves it as done, skipped, or failed. Resolving an activity does not move the instance; a transition controls movement.

Actions are commands attached to an activity. They can change workflow state, queue external work, start child workflows, and optionally resolve the activity.

Omit when for a caller-fired action. Add when for an automated trigger.

The first example records approval, resolves the review, and queues a notification. The second adds a condition so the engine can trigger it automatically:

defineAction({
  name: 'approve',
  ops: [
    {type: 'field.set', target: {field: 'approval'}, value: {type: 'actor'}},
  ],
  effects: [
    {
      name: 'notify-reviewer',
      bindings: {to: '$fields.reviewer'},
      input: {body: 'Your article was approved'},
    },
  ],
  status: 'done',
})

defineAction({
  name: 'escalate',
  when: '$fields.dueDate < $now',
  effects: [{name: 'notify-editor', bindings: {to: '$fields.editor'}}],
})

Triggers run in declaration order. Re-entering the stage starts a new visit and allows them to fire again.

Use status for the outcome of the work, not the business decision:

• done — the work completed, including approve, decline, send back, or hold.
• skipped — the work did not apply.
• failed — the work could not complete.

For a business decision, resolve the activity as done and write the decision to a field that a transition condition reads.

Actions can combine immediate operations, queued effects, child workflows, and an optional activity status.

Action evaluation can preview what firing a caller action would do to the flow in the current state. Use it to place or label controls without duplicating transition logic.

const evaluation = await engine.evaluate({instanceId})
const approve = evaluation.currentStage.activities
  .flatMap(({actions}) => actions)
  .find(({action}) => action.name === 'approve')

if (approve?.firing?.exitsStage) {
  console.log(`Approve exits through ${approve.firing.transition}`)
}

The preview is advisory and describes the current projection. It is omitted when a faithful replay needs unavailable inputs, including caller parameters or dataset-driven spawn results, and for automated triggers.

Activity and action conditions use the GROQ variables defined by Conditions. Caller-fired sites can also bind the current actor and permissions; cascade-fired sites cannot.

This is the object passed to defineActivity(...) in a stage’s activities array.

This is the object passed to defineAction(...) in an activity’s actions array.