Sequence basics
What a sequence diagram shows, when to draw one instead of a process, and how to make and edit one in the app.
A sequence diagram shows one interaction between people and systems: who takes part, and the messages they send each other, in order. Time runs down the page. Use one for a sign-in, a payment, an API call or a webhook: anything where the order of messages matters more than who owns each step.
Each element below comes with the sequence code that draws it.
Participants and lifelines
A participant is a person or a system that sends or receives messages. Each one is a column, with its head at the top and a dashed lifeline running down. A participant is drawn as a box, an actor as a stick figure for a person, and a database as a cylinder for a data store.
actor Shopper
participant Shop
database Orders DB
Shopper->Shop: Place order
Shop->Orders DB: Save orderParticipants appear left to right in the order the code first names them. Put the one who starts the interaction first.
Messages: call, reply and async
A message is an arrow from one lifeline to another, labelled with what is sent. There are three kinds:
- A call (
->) is a solid line with a filled head. The sender waits for an answer. - A reply (
-->) is a dashed line back to the caller. It answers an earlier call. - An async message (
->>) is a solid line with an open head. Nobody waits, as with an event or a queue.
participant Client
participant API
participant Queue
Client->API: Create order
API-->Client: 201 Created
API->>Queue: Order createdA participant can send a message to itself, such as a step it does on its own.
Activation bars
An activation bar is a narrow box on a lifeline. It shows that the participant is busy, usually handling a request while it waits on others. Add ++ to the message that starts the bar and -- to the one that ends it.
participant Client
participant API
database DB
Client->API ++: GET /orders/42
API->DB: Load order 42
DB-->API: Order
API-->Client --: 200 OKAdd bars for the main service handling a request, not on every message.
Fragments
A fragment is a frame around some messages, with a tab naming its kind and a condition. Use one when messages only happen in some cases, or happen more than once.
| Kind | What it means |
|---|---|
alt | Alternatives: one branch is taken. Each branch after the first starts with else. |
opt | Optional: happens only if the condition holds. |
loop | Repeats while the condition holds. Say the limit, such as "up to 3 times". |
par | Parallel: the branches run at the same time. Each branch after the first starts with and. |
break | Leaves the enclosing block early, such as after the last failed retry. |
critical | Runs without interruption. |
group | A labelled box, with no meaning of its own. |
participant Shop
participant Payments
Shop->Payments: Charge card
alt card accepted
Payments-->Shop: Payment confirmed
else card declined
Payments-->Shop: Declined
endOnly alt and par have more than one branch. Write each condition as a short state, such as "cache hit" or "card declined".
Notes, dividers and numbering
- A note carries a fact the arrows can't, such as a timeout or a security rule. It sits over one or more participants, or to the left or right of one.
- A divider splits a long interaction into phases, with a label across the whole diagram.
- Numbering puts 1, 2, 3 in front of the messages, so you can refer to them.
autonumber
participant App
participant Auth server
== Sign in ==
App->Auth server: Authorization request
Auth server-->App: Authorization code
note over App, Auth server: State checked on every requestWhen to use a sequence diagram
Draw a BPMN process when the question is "what work happens, who does it, and what comes next". Draw a sequence diagram when the question is "what do these systems say to each other, in what order, and what happens when one fails".
- A process follows the work through decisions and hand-offs, often over days. A sequence diagram follows the messages in one interaction, often over seconds.
- A process has one lane per role. A sequence diagram has one column per person or system, and shows every request and answer between them.
- A process is good for people agreeing how work runs. A sequence diagram is good for developers agreeing how a feature or an integration behaves.
The two work well together. A service task in a process, such as "Charge card", can have a sequence diagram of its own that shows the calls behind it.
Keep each sequence diagram to one scenario: about 3 to 8 participants and up to 30 messages. Draw a second diagram for a detailed part, or for a second scenario such as sign-up next to sign-in.
Make a sequence diagram
- From the Diagrams panel. Select New diagram (the + button) and choose Sequence diagram.
- From the search menu. Press ⌘ K (Ctrl K on Windows and Linux) and run New sequence diagram.
- From a template. Select Templates in the rail. Under Sequence diagram are Sign in with Google, Checkout payment, API with cache and Webhook delivery. Selecting one creates a new diagram from it.
- From a file. In the Diagrams panel, open New diagram and choose Import Mermaid or PlantUML file…. See Import a file.
A new diagram is called "Untitled sequence". Its empty canvas offers three ways to begin: Describe it opens the assistant, Add participant adds the first column, and Use a template opens the Templates panel. You can also type the diagram in the Sequence code pane beside the canvas.
Work on the canvas
The app lays out every sequence diagram for you: columns left to right, messages top to bottom. You change what's there and in what order, and the layout follows. Every edit is a small, named change that shows up in the version history and can be undone.
Move around
- Pan: drag an empty part of the canvas, or scroll. To pan from anywhere, hold Space and drag, or drag with the middle mouse button.
- Zoom: pinch on a trackpad, or hold ⌘ (Ctrl on Windows and Linux) and scroll. + and - zoom too, and ⌘ 0 fits the diagram to the view.
When you pan down a long diagram, the participants' heads stay pinned along the top, so you always know which column is which.
Select
Click a participant, message, note, fragment or divider to select it. Shift-click adds an element to the selection or takes it out (on a Mac, ⌘-click works too). ⌘ A selects everything. Clicking empty canvas, or pressing Esc, clears the selection.
The arrow keys move the selection: ↑ and ↓ go through messages, notes, fragments and dividers in reading order, and ← and → go between participants.
Add elements
The palette along the bottom of the canvas has Participant, Actor, Database, Message, Note, Fragment and Divider. Each one adds after what you've selected:
- A participant, actor or database goes to the right of the selected participant, or at the end.
- A message goes after the selected message, onward from where that one arrived. From a selected participant, it goes to its neighbour, at the end.
- A note goes on the selected participant, or over both ends of the selected message.
- A divider goes after the selected message, note or fragment, or at the end.
- Fragment wraps the selected messages. See Wrap messages in a fragment.
The new element opens for naming straight away; type and press Enter. A new note opens its text in Properties instead.
From the keyboard, press P participant, A actor, D database, S message or N note. With a message selected, R adds its reply: a reply arrow back the other way, right after it.
Right-clicking empty canvas offers Add participant, Add actor, Add database, Add message and Add divider too.
Wrap messages in a fragment
Select the messages, then press F, choose Fragment in the palette, or choose Wrap in fragment… in the selection bar. The Wrap in menu lists Alternatives (alt), Optional (opt), Loop, Parallel (par), Break, Critical and Group, each with its own letter key. The fragment opens for naming its condition, except a parallel one, which has none to start with.
The messages must sit next to each other, in the same place. If they don't, the canvas says to select adjacent messages.
With a fragment selected, Add else branch (for alt) or Add parallel branch (for par) adds a branch, and Unwrap removes the frame and keeps the messages in it.
Move and reorder
Hold ⌥ (Alt on Windows and Linux) and press an arrow key to move the selection:
- a participant moves left or right, one column at a time;
- a message, note, divider or fragment moves up or down past its neighbour. At the edge of a fragment it steps out of it, and it moves past a whole fragment rather than into it.
You can also drag: drag a participant's head left or right, or a message, note, divider or fragment up or down. Move left, Move right, Move up and Move down are in the selection bar too.
Use the selection bar
When you select an element, a bar of tools floats above it. What it starts with depends on the element:
| Selected | Tools |
|---|---|
| Participant | Add message, Add note, Move left, Move right |
| Message | Add reply, Add message, Flip direction, Wrap in fragment…, Add note, Move up, Move down |
| Fragment | Add else branch or Add parallel branch, Unwrap, Move up, Move down |
| Note or divider | Move up, Move down |
Every element then has Ask assistant, Comment, Rename (not for notes), Properties and Delete. With several elements selected, the bar offers Wrap in fragment…, Ask assistant, Comment and Delete.
Flip direction swaps a message's sender and receiver.
Right-click an element, long-press it on a touch screen, or press ⇧ F10 for a menu with the same tools.
Rename and edit notes
Double-click a participant, message, fragment or divider, or select it and press Enter or F2, to rename it in place. For a message that's its text, and Shift Enter starts a new line. For a fragment it's the first condition. Press Enter to save or Esc to cancel.
A note's text is edited in Properties. Double-clicking a note, or pressing Enter on it, opens it there.
Delete, comment and undo
- Delete: select elements and press ⌫ (Backspace) or Delete. Deleting a participant also deletes its messages. Deleting a fragment deletes what's in it; to keep the messages, use Unwrap instead.
- Comment: select elements and press M. Comments work as they do on a process. See Comment on the diagram.
- Ask the assistant: select elements and press ⌘ L (Ctrl L). The assistant takes "this" or "these" to mean them.
- Undo: ⌘ Z (Ctrl Z) undoes, and ⇧ ⌘ Z (Shift Ctrl Z) redoes. See Undo and redo.
See and change every property
The Properties panel shows every field the diagram stores for what you've selected. Open it with Properties in the selection bar, or ⌥ ⌘ P (Alt Ctrl P). Each change is one undo step.
| Selected | Fields |
|---|---|
| Nothing (the diagram) | Title, and Numbering to number the messages. It also lists the participants. |
| Participant | Name, Kind (Box, Actor or Database), Alias, the short name the code uses for it, and Order, to move it left or right. |
| Message | The Message text, the Arrow (Call, Reply or Async), From, To, and Activation: whether it starts the receiver's bar or ends the sender's. |
| Fragment | Kind, the condition of each branch, and buttons to add or remove branches. |
| Note | Text, Position (Left of, Over or Right of), and On: the participant it's on. A note over several participants has From and To. |
| Divider | Label. |
Each element shows its id at the bottom, with Copy.
Check your diagram
The Problems panel checks a sequence diagram every time it changes, as it does a process. See Modeling checks for how the panel works.
- Errors: a message, note or activation refers to a participant that doesn't exist, or a fragment other than alt or par has more than one branch.
- Warnings: an alt has only one branch (use opt, or add an else), or a bar is ended on a participant that isn't active.
- To finish: a participant sends and receives no messages, a fragment or branch is empty, or a call gets no reply where the exchange is synchronous, that is, where the receiver replies to the sender somewhere else in the diagram.
Next
Learn to write sequence code, or let the assistant draft a diagram for you.