Web Sequence Diagrams

Table of contents

  1. Simple signals
  2. Changing the order of participants
  3. Actors
  4. Signal to self
  5. Expressing loops and conditionals
  6. Notes in the diagram
  7. States
  8. Lifeline activation and destruction
  9. Including saved diagrams in other diagrams
  10. Referencing other sequences
  11. Parallel sequences
  12. Automatic numbering
  13. Changing the bottom of participants

Simple signals

Draw a signal from one participant to another like this. The participants are automatically created when they are used.

To include a colon in a participant name, enclose it in quotes.

":Alice"->":Bob": Hello
# This is a comment.

Alice->Bob: Filled arrow
Alice->>Bob: Open arrow
Bob-->Alice: Dotted line
Bob-->>Alice: Dotted Line, open arrow
Bob-->Alice: Double arrow
Alice->(1)Bob: Slightly delayed
Bob->(5)Alice: Highy delayed

Changing the order of participants

If you want to participants to be shown in a different order than they are used, declare them first using the participant keyword. You can also rename them this way to save typing.
participant Bob
participant Alice
participant "I have a really\nlong name" as L

Alice->Bob: Authentication Request
Bob->Alice: Authentication Response
Bob->L: Log transaction


Declare a participant using the actor keyword and it will appear with a person drawn above it.
actor User
participant Terminal

User->Terminal: Login

Signal to self

A participant can send a signal to itself. This will result in an arrow that turns back on itself.

You may break the text into multiple lines by using "\n".

Alice->Alice: This is a signal to self.\nIt also demonstrates \nmultiline \ntext.

Grouping signals together

You can group signals together using the alt/else, opt, loop, par, and seq keywords. All of them can take a text description that will be displayed in the group header. Use the end keyword to signal the end of a group. The groups may be nested to any depth.

The else part is optional and can be repeated more than once for each condition.

Alice->Bob: Authentication Request
alt successful case
Bob->Alice: Authentication Accepted
else some kind of failure
Bob->Alice: Authentication Failure
    loop 1000 times
        Alice->Bob: DNS Attack
else Another type of failure
Bob->Alice: Please repeat

Notes in the diagram

You can add notes to the diagram. Notes can be placed to the left or right of a participant, or placed over one or more participants.

If a note contains more than one line, it will not be word-wrapped. Instead, it will be formatted exacty as written.

participant Alice
participant Bob

note left of Alice 
This is displayed 
left of Alice.
end note
note right of Alice: This is displayed right of Alice.
note over Alice: This is displayed over Alice.
note over Alice, Bob: This is displayed over Bob and Alice.

Extended text descriptions (premium)

Subscribers can explain sequences that follow simply by indenting your explanations with a space.

 You can explain the sequences that follow
 simply by indenting your explanations 
 with a space.
Alice->Bob: Wow!


Premium feature

A rounded box can be useful to show state information. The syntax is identical to the note keyword, except that state is used.
participant Client
participant Server
parallel {
    state over Server: LISTEN
    state over Client: CLOSED
Client->Server: SYN
parallel { 
    state over Client: SYN-SENT
    state over Server: SYN_RECEIVED
Server->Client: ACK

Lifeline activation and destruction

Use the + and - with signals to denote object activation. While activated, the participant's lifeline will be highlighted. + will activate the receiver, and - will deactivate the sender.

Use * with signals to create a participant.

A->*B: hello.

You can use the destroy keyword to destroy a participant. The participant's lifeline will end at the previous signal.

User->+A: DoWork
A->*+B: <<createRequest>>
B->*+C: DoWork
C-->B: WorkDone
destroy C
B-->-A: RequestCreated
A->User: Done

Alternate syntax

Ge more control over activations using the activate and deactive keywords. The commands apply to the previous signal.
Alice->Bob: Do some work!
activate Bob

Bob->Bob: Work routine
activate Bob
deactivate Bob

Bob->Alice: All done!
deactivate Bob

Only arrows can cause activations

Activations and deactivations attach themselves to the previoius signal. Neigher a note nor a state can cause a deactivation. If you want to deactivate spontaneously, use a signal-to-self.
A->+B: Activate please
B->-B: I'm deactivating now\n by myself

One arrow can activate/deactivate many participants at a time.

Using the explict syntax gives more flexibility.
activate A
activate B

deactivate A
deactivate B
activate C

deactivate C

Include other diagrams

Premium feature

You can refer to other diagrams that you have saved in your account without retyping the text. Use the word include followed by the filename in quotes.
title LTE Call Flow

include "LTE Attach procedure"
include "LTE Call Setup"

Reference other sequences

Premium feature

You can summarize or refer to sequences by drawing a box over one or more participants.
ref over Mobile, Base Station
    Refer to 3GPP 44.060
end ref
You can optionally have a signal going into the box or one coming out.
Alice->ref over Bob, Mary: input
    refer to other diagram
end ref -->Alice: output

Parallel sequences

Premium feature

You can make different things happen at the same time using the parallel keyword.
parallel {
    Client->Proxy: Request
    Proxy->Server: Forwarded Request
    note right of Server: Web proxy in operation

Server->(3)Proxy: Reply
parallel {
    Proxy->(3)Client: Crossed messages
Use the serial keyword within a parallel block to describe two parallel sequences of operations.
parallel {
    serial {
        Alice->Bob: Hello
        Bob->Alice: Hello    

    serial {
        Eve->Carol: Hello
        Carol->Eve: Hello


Premium feature

Autonumbering will automatically prefix all signals with a number. To use it, include the line autonumber followed by the number to start with. To turn off autonumbering, use "autonumber off"
autonumber 2
UE->GANC: Register Request
GANC->UE: Register Reject

Footer types

Premium feature

Change the way the bottom of your diagram looks using option footer=
option footer=none
option footer=bar