ZenUML Sequence Diagrams in Confluence: Copy-Paste Guide
Sequence diagrams die in Confluence in one of two ways: someone draws one in a diagramming tool, exports a PNG, pastes it into a page — and three sprints later the flow has changed but the image has not. Or someone writes the flow as prose ("the client calls the order service, and if payment is approved…"), which is accurate but impossible to read under time pressure.
ZenUML splits the difference: the diagram is code, so it edits like code and renders like a diagram — branches, error paths, and parallel work included. This guide shows the syntax with copy-paste examples you can drop into Confluence today.
Quick answer: To create ZenUML sequence diagrams in Confluence, install Enhanced Markdown for Confluence and use a ```zenuml fence in its Markdown macro. ZenUML renders UML sequence diagrams with real control flow — if/else, try/catch, par, while — in the browser, fully inside Confluence. Free for up to 10 users.
The First Diagram — Checkout with a Branch
Paste this into a ```zenuml fence:
```zenuml
participant User
participant Checkout
participant PaymentProvider
User->Checkout: submit order
Checkout->PaymentProvider: charge card
if (payment approved) {
Checkout-->User: confirmation page
} else {
Checkout->PaymentProvider: retry with backoff
Checkout-->User: "will confirm by email"
}
```
What you get for six lines of logic: labeled participants, a synchronous call (->), returns (-->), and an if/else rendered as proper frames — auto-numbered, so a reader can follow the request/response pairing without guessing.
The Syntax in One Table
| Token | Meaning | Example |
|---|---|---|
participant X | Declare a participant | participant Checkout |
@Actor X / @Database X | Annotate the participant's role | @Database PaymentDB |
A->B: msg | Synchronous call | Checkout->PaymentProvider: charge |
A-->B: msg | Return / reply | Checkout-->User: 201 Created |
if (x) { } else { } | Branch frames | if (approved) { ... } |
while (x) { } | Loop frame | while (retries left) { ... } |
par { } and { } | Parallel blocks | fan-out and join |
try { } catch (E) { } | Error path | reservation failure |
The annotators are worth adopting on day one: @Actor Alice and @Database OrdersDB change the participant's icon, so a reader sees who is a human and who is a store before reading a single message.
Error Paths as First-Class Citizens
The example that sells most teams: an order flow where reservation can fail. In a drawing tool this is a second diagram to maintain; in ZenUML it is four lines:
```zenuml
participant Client
participant OrderService
participant InventoryService
Client->OrderService: POST /orders
OrderService->InventoryService: reserve(SKU-991, qty=2)
try {
InventoryService-->OrderService: reservation #R-4821
OrderService-->Client: 201 Created, order #A-1088
} catch (OutOfStockError) {
OrderService-->Client: 409 Conflict, "insufficient stock"
}
```
The happy path and the failure path live in the same block of text, review together in a PR, and — the actual point — get updated in the same commit when the API contract changes.
Parallel Work with par/and
Batch jobs and fan-outs read cleanly with par:
```zenuml
participant Scheduler
participant BillingService
participant EmailService
Scheduler->BillingService: run monthly invoices
par {
BillingService->BillingService: render PDF statements
}
and {
BillingService->EmailService: queue invoice emails
}
BillingService-->Scheduler: 1,204 invoices, 3 failures
```
par and and nest inside if and try too, so a real integration flow — branches, retries, parallel calls — stays one readable diagram instead of three screenshots stitched together.
ZenUML or Mermaid sequenceDiagram?
Both render in the same macro; they optimize for different moments:
| Situation | Reach for |
|---|---|
| Simple request/response flow, documentation flavor | Mermaid sequenceDiagram |
| Business logic with branches and error paths | ZenUML |
| Diagram also lives in a GitHub README | Mermaid (GitHub renders it natively) |
| Spec where the diagram must match the code's control flow | ZenUML |
Install Enhanced Markdown for Confluence, paste the checkout example into a ```zenuml fence, and watch the branch render while you type. Free for up to 10 users.
Related Guides
- Create Mermaid Diagrams in Confluence — the same macro's full diagram family
- Mermaid Sequence Diagrams in Confluence — the
sequenceDiagramroute for simpler flows - How to Write Markdown in Confluence — the base syntax everything lives in