State diagrams in Confluence

A state diagram shows the states one thing can be in and the events that move it from one state to the next.

Last updated

When to use it

Use a state diagram for anything with a lifecycle: an order, an issue, a subscription, a network connection, a circuit breaker. It answers “what can happen next from here”, so it finds missing cases, such as a state with no way out, before the code does.

Example

This is the code of the Issue workflow template: backlog to done, with review and blocked states.

stateDiagram-v2
  [*] --> Backlog
  Backlog --> Selected : prioritise
  Selected --> InProgress : start
  InProgress --> InReview : open pull request
  InReview --> InProgress : changes requested
  InReview --> Done : approved and merged
  InProgress --> Blocked : waiting on dependency
  Blocked --> InProgress : unblocked
  Done --> [*]

Vellnar Diagrams draws it like this:

Change a line and the diagram changes with it. Nobody needs the original drawing file, because there is none: the code is the diagram.

Add it to a Confluence page

  1. Edit a Confluence page and type /mermaid where the diagram should go.
  2. Select Mermaid diagram. The editor opens with the template list.
  3. Pick a template, or choose Start blank and paste the code above. The preview follows every keystroke.
  4. Choose Save. The diagram appears on the page.

The documentation covers the editor, the settings and the exports.

Templates

The Templates button in the editor has 6 state diagrams ready to use:

  • Order lifecycle: From draft to delivered, with cancellation and returns.
  • Issue workflow: Backlog to done, with review and blocked states.
  • Connection states: Connecting, connected and reconnecting with timeouts.
  • Document approval: A draft that goes through review before publishing.
  • Circuit breaker: Closed, open and half-open states that stop calls to a failing service.
  • Subscription billing: A subscription from trial to active, past due and cancelled.

Syntax

The code of a state diagram starts with stateDiagram-v2. The Mermaid documentation describes every element of the syntax. Vellnar Diagrams draws it with Mermaid 12.3; if a line has an error, the editor marks the line and keeps the last valid diagram on screen.

More

  • Mermaid in Confluence: how diagrams as code work in a page, and every diagram type.
  • Security: the app asks for no permissions and sends nothing outside Atlassian.