Workflow concepts

A workflow has four layers that are easy to confuse during troubleshooting:

• A definition is the named, editable container identified by its code.
• A version is a saved graph of nodes and connections. Publishing makes one version active.
• A run is one execution of one published version with its own payload, status and current node.
• A task is a manual decision created when a run reaches a Human Task node.

Changing a draft does not rewrite an earlier run. This separation lets an operator inspect what actually ran even after the workflow has been edited.

Nodes and connections

A trigger starts the graph. Conditions and switches choose a labelled output. Actions perform work or update the run payload. Wait and Human Task nodes pause execution. An End node completes that route.

Connections carry control between nodes. Labels matter: a condition uses YES and NO, an approval task uses its enabled decisions, and a normal action uses NEXT. A node shown on the canvas is not part of the executable path until it is connected.

Payload and variables

Every run carries a JSON payload. Magento event triggers add normalized workflow_event, event, entity and data sections. The exact entity fields depend on the event mapper. A Set Variable node writes a workflow value into the current run payload; it does not by itself change a Magento order, customer or product.

Entity updates, comments, email and webhooks are separate action nodes because they have effects outside the in-memory workflow state.

Synchronous design, asynchronous execution

The graph reads left to right, but live event execution is queued. The event consumer matches a published definition and creates work; the run consumer advances the workflow. A wait is resumed by cron, and a human task resumes after a decision. For that reason, a successful save or publish is not evidence that the queues are healthy.