Map States & Approval Workflows in Confluence with Mermaid
The issue workflow lives in a wiki page that says "the approval chain is: team lead, then manager, then finance". The config says otherwise, the Jira post-function disagrees, and the incident report asks "who actually approved this?" — with three different answers on screen. A prose paragraph cannot hold a workflow; a diagram can, if it is the workflow.
Quick answer: document state machines and approval chains in Confluence as Mermaid stateDiagram-v2, rendered by Mermaid Plus for Confluence. Every legal state, every transition, every human decision on a labeled arrow — in editable text that stays true. This post gives you three copy-paste examples: an issue lifecycle, a spending approval chain, and a retry loop with a timeout.
Why a state diagram beats a static workflow picture
A workflow drawn once as a flowchart is a picture of one run. A state diagram is the definition — it must answer the questions your process actually gets asked:
- What can this be? The full set of legal states, no missing statuses
- Who moves it? The actor on each transition, visible as the arrow label
- Where can it get stuck? The transitions that loop back — retries, resubmissions, timeouts
That last question is the one where prose fails hardest. "It should loop" is not a workflow definition; a drawn self-loop with a retry label is. State diagrams force you to draw the loops, and that is exactly where real processes hide.
Copy-paste 1: the issue lifecycle
Start with a lifecycle every team recognizes — the issue statuses and the moves between them. This is the diagram to put beside the "workflow" section of a space:
stateDiagram-v2
%% title: Issue lifecycle with verification
[*] --> Open
Open --> In Progress : assign
In Progress --> In Review : link PR
In Review --> In Progress : changes requested
In Review --> Resolved : merge
Resolved --> [*]
Six states, four transitions, one loop. The loop (In Review --> In Progress : changes requested) is the line prose would have buried as "and then, if needed, it goes back". In a state diagram it is a visible arrow — contributors see it, reviewers see it, the config owner checks it matches the Jira workflow.
Copy-paste 2: the approval chain
Approval chains are state machines where a human sits on each transition. Draw the chain top-down and mark the decision on each arrow — the reader can spot where a workflow waits on a person:
stateDiagram-v2
%% title: Spending approval chain
[*] --> Draft
Draft --> Submitted : submit
Submitted --> TeamApproved : team lead approves
Submitted --> Rejected : team lead rejects
TeamApproved --> ManagerApproved : manager approves
TeamApproved --> Rejected : manager rejects
ManagerApproved --> FinanceApproved : finance approves
ManagerApproved --> Rejected : finance rejects
FinanceApproved --> Booked : post to ledger
Rejected --> Draft : resubmit with changes
Booked --> [*]
The chain reads top-down like a ladder: each approval stage unlocks the next, and every rejection has a visible escape hatch (Rejected --> Draft : resubmit). When the config changes — a new approval stage, a skip rule for small amounts — the edit is one more row in the diagram, reviewed in the same change as the workflow config.
Copy-paste 3: retries and timeouts
Workflows that retry are where state diagrams earn their keep. A retry is not prose — it is a state with a loop that must eventually exit, or the process runs forever. Show the exit condition on the loop:
stateDiagram-v2
%% title: Job retry loop with backoff and timeout
[*] --> Queued
Queued --> Running : worker picks up
Running --> Success : done
Running --> Retrying : transient error
Retrying --> Running : attempt 1..3, backoff 10s
Retrying --> Failed : 3 attempts exhausted
Failed --> Queued : reschedule
Success --> [*]
The loop (Running -- Retrying -- Running) carries two facts prose usually loses: how many attempts, and what the backoff is. The Failed --> Queued : reschedule arrow shows the manual escape — the process does not die, it re-enters. On a page next to runbooks, this is the diagram the on-call reads first.
The diagram that behaves like the workflow
A state diagram's real advantage is that it behaves like the thing it describes: it is editable text, so it can be reviewed, diffed, and kept honest. In Mermaid Plus for Confluence, the macro shows the source beside the rendered SVG — the workflow owner reviews the diagram in the same change that updates the workflow config, and the wiki stops telling the three-part story that prompted this post.
Keep the states exhaustive and the transitions labeled with actors, and the diagram becomes the single source of truth for "what state can this be in, and who moves it". That is the question every process owner wishes they could answer — now it is visible.
Where this lives beside your other Confluence diagrams
State diagrams cover the workflow half; the other diagram types cover the seams. Keep the state machine on the workflow page (this post), the step-by-step process as a flowchart (CI/CD pipeline diagrams), and the system structure as a class diagram on the architecture page (class diagrams for your codebase). One space, four diagram types, each answering the question it is best at.
FAQ
What is the difference between a Mermaid state diagram and a flowchart? A flowchart shows steps; a state diagram shows the states a thing can be in and the events that move it. For workflows with clear statuses, stateDiagram-v2 self-documents better — every transition must be explicit, so the diagram cannot hand-wave the loops.
Can a state diagram express concurrent or retrying states?
Yes. Group parallel statuses inside a composite (state X { ... }), and draw a retry as a transition back to an earlier state with a label like 'attempt 1..3, backoff 10s'. Example 3 shows a retry that exits after three attempts.
How do I document an approval chain? Model each stage as a state and each approve/reject decision as a labeled transition. The ladder reads top-down, and the rejection escape hatch ('resubmit') is a visible arrow — example 2 shows a three-stage spend approval.
Do state diagrams replace flowcharts in Confluence? No — they complement. Use a flowchart for step order, a state diagram for legal states and the actor on each move. Teams usually keep both: a flowchart for the happy path, a state diagram for the workflow definition.
Render every Mermaid diagram type — state, flowchart, class, ER, gitGraph and 24 more — in Mermaid Plus for Confluence, free for up to 10 users.
Try Mermaid Plus for Confluence
All 29 Mermaid diagram types with live preview and one-click templates — free for up to 10 users.
Get it on the Atlassian Marketplace