# Map States & Approval Workflows in Confluence with Mermaid

September 24, 2026 ·

<!-- -->

6 min read

[NGPilot](https://ngpilot.com)

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](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-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[​](#why-a-state-diagram-beats-a-static-workflow-picture "Direct link to 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[​](#copy-paste-1-the-issue-lifecycle "Direct link to 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 --> [*]
```

![Issue lifecycle with verification](/assets/images/issue-lifecycle-with-verification-788699067eace7cab22b2c5e56b99ff2.svg)

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[​](#copy-paste-2-the-approval-chain "Direct link to 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 --> [*]
```

![Spending approval chain](/assets/images/spending-approval-chain-a43050f8dcaf468b5637797039f3dda3.svg)

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[​](#copy-paste-3-retries-and-timeouts "Direct link to 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 --> [*]
```

![Job retry loop with backoff and timeout](/assets/images/job-retry-loop-with-backoff-and-timeout-a1f3e446a7ee130248d86a419b0a630e.svg)

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[​](#the-diagram-that-behaves-like-the-workflow "Direct link to 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](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-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[​](#where-this-lives-beside-your-other-confluence-diagrams "Direct link to 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](/blog/mermaid-ci-cd-pipeline-diagram-confluence.md)), and the system structure as a class diagram on the architecture page ([class diagrams for your codebase](/blog/mermaid-class-diagram-document-codebase-confluence.md)). One space, four diagram types, each answering the question it is best at.

## FAQ[​](#faq "Direct link to 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](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-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](https://marketplace.atlassian.com/apps/1236814/mermaid-plus-diagrams-for-confluence?utm_source=ngpilot.com\&utm_medium=website\&utm_campaign=mermaid-plus-for-confluence)

## Related guides

* [How to Create Mermaid Diagrams in Jira](/blog/how-to-create-mermaid-diagrams-jira.md)
* [Export Jira Issues to Excel or CSV](/blog/export-jira-issues-to-excel.md)
* [Bulk Download Jira Attachments](/blog/bulk-download-jira-attachments.md)
* [How to Migrate Confluence Content](/blog/how-to-migrate-confluence-content.md)
* [How to Add a Block Quote in Confluence](/blog/block-quote-confluence.md)

Explore NGPILOT[Browse Solutions](/solutions.md)[All Apps](/apps.md)[Atlassian Marketplace →](https://marketplace.atlassian.com/vendors/1226848/?utm_source=ngpilot.com\&utm_medium=blog\&utm_campaign=hub-links)

**Tags:**

* [confluence](/blog/tags/confluence.md)
* [mermaid](/blog/tags/mermaid.md)
* [state-diagram](/blog/tags/state-diagram.md)
* [workflow](/blog/tags/workflow.md)
* [approval](/blog/tags/approval.md)
* [how-to](/blog/tags/how-to.md)