Flow Workflow Tasks

Flow tasks enable programmatic interaction with Flow workflows (state machines) from within workflow steps.

Flow/Transition

Execute a flow transition programmatically. This allows workflows to trigger state transitions in Flow workflows.

task: "Flow/Transition@1"
name: executeTransition
inputs:
  entityId: "{{ orderId }}"
  entityName: "Order"
  transitionName: "manual_forceComplete"
outputs:
  - name: result
    mapping: "result"

Inputs

Parameter	Type	Required	Description
entityId	string	Yes	ID of the entity to transition
entityName	string	Yes	Entity type (e.g., Order, Commodity)
transitionName	string	Yes	Name of the transition to execute
executionMode	string	No	Exactly Async or Sync. Async queues the transition as a background job and returns queued/jobId; Sync runs it immediately and returns the new state. Without it the transition runs immediately (Sync), whatever the Flow's own executionMode.

An invalid value fails the task with Invalid executionMode '<value>' for Flow/Transition. Expected Async or Sync.

Outputs

Output	Description
success	Whether the transition ran (Sync) or was queued (Async)
previousState	State the entity was in before the transition
newState	State after the transition. Empty when the transition was queued
error	Error message when the transition failed
queued	true when the transition was queued as a background job
jobId	Background job ID. Empty when not queued

Async and Sync Execution

Manual transitions default to Sync: they run immediately and return the new state, whatever the Flow's own executionMode. Set executionMode: Async to queue the transition as a background job instead. Before queuing, the task still returns an error immediately if no active Flow for the entity defines the transition. A queued call reports success: true before the transition runs: newState is empty, later steps should not assume the entity has moved, and a transition that turns out not to be valid from the entity's state at run time is recorded only in the workflow execution log.

Each background transition that runs writes a workflow execution log entry (success or failure); errors before a transition runs (for example the Flow was deactivated) appear only in server logs. Flow jobs are not retried automatically; a job interrupted by a server crash or restart is re-run from the entity's current state.

The GraphQL mutation executeFlowTransition accepts the same optional executionMode argument (Async or Sync) and returns queued and jobId in addition to success, previousState, newState and error.

Example: Trigger Flow Transition After Import

activities:
  - name: importAndTransition
    steps:
      - task: "Order/Import@1"
        name: importOrder
        inputs:
          data: "{{ importData }}"
        outputs:
          - name: order
            mapping: "order"

      - task: "Flow/Transition@1"
        name: activateOrder
        inputs:
          entityId: "{{ importAndTransition.importOrder.order.orderId }}"
          entityName: "Order"
          transitionName: "draft_to_active"