Sequence diagrams in Confluence

A sequence diagram shows the messages that people and systems exchange, in the order they happen.

Last updated

When to use it

Use a sequence diagram to explain an interaction over time: an API call, a login with an identity provider, a checkout across three services. Each participant has a vertical line and each message is an arrow between two lines, read from top to bottom. It is the usual diagram of API specs and incident reviews.

Example

This is the code of the API request template: a client call that is authenticated and answered from the database.

sequenceDiagram
  autonumber
  participant Client
  participant API
  participant Auth as Auth service
  participant DB as Database
  Client->>API: GET /orders
  API->>Auth: Validate token
  Auth-->>API: Token valid
  API->>DB: SELECT orders
  DB-->>API: Rows
  API-->>Client: 200 OK (orders)

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 sequence diagrams ready to use:

  • API request: A client call that is authenticated and answered from the database.
  • Login with an identity provider: Redirect, credentials, tokens, and the failure path.
  • Checkout: Order, payment and stock reservation across three systems.
  • Support ticket: A ticket that loops between customer, agent and engineering.
  • Order saga: Payment, stock and shipping steps, undone in reverse when shipping fails.
  • Cache-aside: Read from the cache, fall back to the database and refill the cache.

Syntax

The code of a sequence diagram starts with sequenceDiagram. 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.