Workflow Diagram · IOModel Documentation

Sequence behavior on a timeline, mapped onto the objects diagram, with step-by-step playback.

A workflow diagram visualizes behavior: the ordered messages exchanged between objects during a process. It is generated from a workflow definition (a .wf file) and rendered as a sequence diagram — participants as lanes, messages as arrows over time.

In Studio you can also read the same workflow on the workflow objects diagram (wf-objects-diagram): the structural objects diagram with sequence steps mapped onto links. Playback animates each step on both surfaces at once.

Diagram source format

Workflow source text follows the Mermaid sequence diagram grammar: one construct per line, optional sequenceDiagram header, participant declarations, messages as <from><arrow><to>: <label>, and Mermaid-style fragments (alt, opt, loop, par, critical, box, rect) closed with end. Line comments use %%.

The example below is valid in both Mermaid and Studio:

sequenceDiagram
  participant Customer
  participant API
  Customer ->> API: Submit order
  API -->> Customer: Order accepted

Compatible with Mermaid

You can paste or author diagrams that follow the public Mermaid sequence syntax. Studio parses the same line-oriented body Mermaid documents for sequenceDiagram:

Construct	Syntax (summary)	Notes
Header	`sequenceDiagram`	Optional in `.wf`; ignored on parse, not re-emitted when saving from Visual.
Participants	`participant <id>` or `participant <id> as <label>`	Order in the file sets column order left to right. Participants also appear when first used in a message.
Messages	`A ->> B: Text`	See Message arrows for all ten arrow literals.
Fragments	`alt`, `opt`, `loop`, `par`, … `end`	See Fragments for each frame type and section keywords.
Notes	`note left of <id>: …` / `note right of <id>: …`	Single-line note text in source.

Message arrows

Every message line uses the same template:

<from><arrow><to>: <label>

<from> and <to> are participant ids. Spaces are optional (A ->> B : Hello equals A->>B:Hello). Self-messages (A->>A: retry) are allowed and render as a loop on that participant’s lane.

Studio accepts exactly these arrow literals (longest match wins, so C-->A is participant C, arrow -->, participant A — not a merged id):

Arrow	Line	Arrowhead	Typical use
`->`	Solid	None	Signal or flow without a directed arrowhead
`-->`	Dotted	None	Weak, return, or asynchronous line without a filled head
`->>`	Solid	Filled	Default request — synchronous call or send
`-->>`	Dotted	Filled	Default reply — response or callback
`<<->>`	Solid	Both ends	Bidirectional exchange on one line
`<<-->>`	Dotted	Both ends	Bidirectional, non-primary link
`-x`	Solid	Cross	Lost message, failure, or cancellation
`--x`	Dotted	Cross	Dotted failure / negative ack
`-)`

In the visual editor, arrows containing -- (-->, -->>, <<-->>, --x, --)) render as dotted lines; the rest are solid.

Example mixing request, reply, and async:

  Client ->> API: Submit order
  API ->> Worker: Enqueue job
  Worker -) API: Accepted (async)
  API -->> Client: Order id

Any other arrow token (for example Mermaid half-arrows or central () connections) is not supported yet and produces a parse error.

Fragments

Fragments group messages inside labeled frames on the diagram (and in the steps view). Syntax matches Mermaid fragments: open with a keyword, optional title on the same line, put participant / message lines inside, close with end on its own line. Fragments can be nested — each end closes the innermost open frame.

Keyword	Meaning	Section separators	Title
`alt`	Alternative paths (if / else)	`else` — one or more alternative branches	Optional after `alt`, e.g. `alt Payment declined`
`opt`	Optional block (may not run)	None — single block only	Optional, e.g. `opt Retry`
`loop`	Repeated steps	None	Optional, e.g. `loop Poll until ready`
`par`	Parallel branches	`and` — starts the next branch	Optional on `par` and on each `and`
`critical`	Critical region with guarded options	`option` — circumstance-specific branch	Optional on

Rules:

else only immediately inside an open alt; otherwise the parser reports `else` without matching `alt`.
and only inside par; otherwise `and` without matching `par`.
option only inside critical; otherwise `option` without matching `critical`.
A frame must contain at least one message (or a participant line) before end; empty alt … end is an error.
Titles may be quoted: alt "HTTP 4xx".

Alternative (alt / else):

  alt Card approved
  Client ->> API: Capture payment
  else Card declined
  Client ->> API: Show error
  end

Optional (opt):

  opt Cache hit
  API -->> Client: Cached response
  end

Loop (loop):

  loop Every 5s
  Worker ->> API: Heartbeat
  API -->> Worker: OK
  end

Parallel (par / and):

  par
  API ->> Email: Send receipt
  and
  API ->> Analytics: Track event
  end

Critical (critical / option):

  critical Process payment
  API ->> Gateway: Charge
  option Gateway timeout
  API -->> Client: Payment pending
  end

Grouping (box) and highlight (rect):

  box Backend services
  participant API
  participant Worker
  API ->> Worker: Run job
  end

  rect rgb(240, 248, 255)
  Client ->> API: Login
  end

Studio-specific behavior

Topic	Behavior
`autonumber`	Lines like Mermaid’s `autonumber` are accepted but not stored in `.wf`; toggle message numbers in the Visual editor toolbar instead.
`config`	Optional header keys (`maxMessageLineSymbols`, `minParticipantsDistance`) before participants — an iomodel layout extension, not in stock Mermaid.
Participants	In the model, participants resolve to objects; unresolved references surface when structure changes.
Not yet supported	`activate` / `deactivate`, `break`, `create` / `destroy`, `actor`, stereotype JSON, `links`, central `()` arrows, half-arrows, and other extensions outside the table above.

Mermaid docs as reference

For arrow types, fragment keywords, and message patterns, use the Mermaid sequence diagram syntax as the authoritative reference; Studio implements the subset above.

What it shows

Participants (which are model objects).
Ordered messages with arrows and replies.
Optional grouping and an autogenerated steps list.
The same steps overlaid on the objects diagram when you switch layout mode.
Animated playback that walks through messages one step at a time.

sequenceDiagram
  Customer ->> API: Submit order
  API ->> Billing: Charge payment
  Billing -->> API: Payment confirmed
  API -->> Customer: Order accepted

Layout modes

The visual workflow editor toolbar offers three layouts:

Mode	What you see
Sequence	Classic sequence diagram only
Split	Sequence on the left, workflow objects diagram on the right
Objects	Workflow objects diagram full width

Use Split when you want behavior and structure side by side. Use Objects when the architectural context matters more than the timeline.

Workflow objects diagram

The workflow objects diagram (wf-objects-diagram) is the same canvas as Explore / the Objects diagram: objects as nodes, YAML links as edges, automatic layout. The workflow is overlaid on top — each sequence message is mapped to a link between the participant objects.

How messages map to links

Situation	On the objects diagram
Message `A ->> B` and a YAML link exists between those objects	The link carries the sequence step (highlighted, numbered when selected)
Reply message `B -->> A`	Maps to the same link as `A ->> B` (reply direction is normalized)
Several messages between the same pair	One link can represent multiple sequence steps
Message with no matching YAML link	A virtual link is drawn in a distinct color — behavior exists in the workflow but not yet in the model

Virtual links are a signal to align structure with behavior: open the link sidebar and use Create model link to add the missing YAML relationship.

View vs editor on the objects pane

Mode	Objects shown	Links shown
View	Workflow participants and their parent containers only	Links that appear in the workflow
Editor	Full model	All YAML links; mapped sequence steps highlighted on their links

Linked selection

Selecting a message in the sequence diagram selects the corresponding link (or virtual link) on the workflow objects diagram, and vice versa. The link sidebar opens two tabs:

Workflow steps — which sequence messages use this link
Edit link — change the underlying YAML link (or create one from a virtual link)

Unresolved participants (no model object yet) appear as top-level gray nodes on the objects pane until you bind them to real objects.

Playback and animation

Click Play in the workflow toolbar to enter playback mode. A Play panel opens on the right with transport controls and a scrollable step list.

Controls

Control	Effect
Play / Pause	Auto-advance through steps
Stop	Exit playback and clear highlights
Previous / Next	Move one step manually
Show all steps	Keep every step played so far visible on the workflow objects diagram (not only the current one)

Each row in the step list shows the step number, participants, arrow type, and message text. Click a row to jump to that step.

What animates

During playback, the current step is emphasized on both diagrams:

Sequence — the active message and its participants are highlighted; earlier steps stay visible in muted tones.
Workflow objects diagram — the active step renders as a highlighted arrow (or on its mapped link). Previous steps remain in softer colors. With Show all steps, multiple played arrows are laid out to reduce overlap.

Branches, parallel, and async

Construct	Playback behavior
`alt` / `else`	Radio buttons on each branch let you choose which path playback follows; unselected branches are dimmed
`par`	All branches run in parallel — several steps can be active at once
Async arrows (`-)` , `--)`)	The next step can start without waiting for the async message to finish

For alt, the first branch is selected by default. Change the selection before or during playback to explore a different path.

Behavior on structure

Playback connects the timeline to the architecture: you see which objects talk on the sequence diagram and how they are wired on the workflow objects diagram at the same time.

Sequence diagram and steps list

The sequence diagram shows participants as lanes and messages as arrows over time. Use it to read ordering, fragments, and reply/async arrow styles.

Participants are model objects

Map messages to objects

Each participant resolves to a real object in the model.

Keep behavior aligned

If a participant references a renamed or missing object, it appears unresolved.

Embed in specs

Reference the workflow from a specification page to give a process end-to-end context.

Behavior derived from the model

Because participants are objects, the workflow diagram stays consistent with structure. Update the model, and the workflow continues to reference the same objects.

Name messages as actions from the sender’s perspective (Charge payment, Confirm order). Clear message labels make the sequence read like a story.

Last updated on