Recipe: Self-Documenting Workflow
This recipe makes an automation draw its own picture. The automation already publishes its resolved step graph as structured data; you transform that into Mermaid and store it as the source of a diagram, so the diagram always reflects what the workflow actually does — not a stale drawing someone made once and forgot.
The problem it solves
Architecture diagrams rot. Someone sketches the flow at the start, the workflow changes ten times, and the picture lies. Meanwhile the real topology — which steps run, in what order, with which edges — is sitting inside the automation, readable as data. This recipe closes the gap: the diagram is generated from the workflow, so it cannot drift.
Elements
| Element | Role |
|---|---|
automation | The orchestration whose topology you want to render. |
diagram | A Mermaid-backed planning surface that renders the topology visually. |
python (or any action) | Reads the automation’s flow data and writes the Mermaid source. |
How the workflow exposes its own shape
An automation is a directed graph of steps. When you GET an element that has outbound wires, the response carries a _flow block; for an orchestration whose spec.steps[] is non-empty, _flow additionally includes the resolved steps and edges plus connected_elements. That is a single, already-resolved representation of “what fires when this runs” — you do not have to re-parse the raw spec.
A diagram is the mirror image: its canonical data is a spec.mermaid text source (with a kind such as flowchart or bpmn), and the workbench renders that Mermaid as a native canvas. The diagram does not introspect other elements on its own — Mermaid text is the input you provide.
Flow
- Build your
automationas normal — reference action, agent, and data elements as steps; use itsconditionandloopchildren for control flow. - Read the workflow’s shape: GET the automation and take the
_flow.stepsand_flow.edgesfrom the response. - Translate that graph into Mermaid in an action element — a
pythonstep that maps each step to a node and each edge to a-->line, emitting aflowchart(orbpmn) source string. - Store the result on a
diagramby settingspec.kindandspec.mermaidto the generated source. The workbench renders it immediately. - Re-run steps 2–4 whenever the automation changes — trigger the action on a
schedule, or call it from the automation’s own final step so every run leaves an up-to-date picture behind.
What this shows
The platform keeps a workflow’s topology as queryable data (_flow), and it keeps a diagram’s content as portable Mermaid text (spec.mermaid). Those two facts compose into a documentation pipeline with no manual drawing step: the source of truth for the picture is the workflow itself. Point the regeneration at a schedule and the diagram becomes a living mirror of the system, correct by construction.