Basic examples
The sequence -> is used to draw a message between two
participants.
Participants do not have to be explicitly declared.
To have a dotted arrow, you use -->
It is also possible to use <- and <--.
That does not change the drawing, but may improve readability.
Note that this is only true for sequence diagrams, rules are different for the other diagrams.
Declaring participant
If the keyword participant is used to declare a participant, more control on that participant is possible.
The order of declaration will be the (default) order of display.
Using these other keywords to declare participants will change the shape of the participant representation:
* actor
* boundary
* control
* entity
* database
* collections
* queue
@startuml
participant Participant as Foo
actor       Actor       as Foo1
boundary    Boundary    as Foo2
control     Control     as Foo3
entity      Entity      as Foo4
database    Database    as Foo5
collections Collections as Foo6
queue       Queue       as Foo7
Foo -> Foo1 : To actor
Foo -> Foo2 : To boundary
Foo -> Foo3 : To control
Foo -> Foo4 : To entity
Foo -> Foo5 : To database
Foo -> Foo6 : To collections
Foo -> Foo7: To queue
@endumlRename a participant using the as keyword.
You can also change the background link::color[color] of actor or participant.
@startuml
actor Bob #red
' The only difference between actor
'and participant is the drawing
participant Alice
participant "I have a really\nlong name" as L #99FF99
/' You can also declare:
   participant L as "I have a really\nlong name"  #99FF99
  '/
Alice->Bob: Authentication Request
Bob->Alice: Authentication Response
Bob->L: Log transaction
@endumlYou can use the order keyword to customize the display order of participants.
Declaring participant on multiline
You can declare participant on multi-line.
@startuml
participant Participant [
    =Title
    ----
    ""SubTitle""
]
participant Bob
Participant -> Bob
@enduml[Ref. QA-15232]
Message to Self
A participant can send a message to itself.
It is also possible to have multi-line using \n.
[Ref. QA-1361]
Text alignment
Text alignment on arrows can be set to left, right or center using skinparam sequenceMessageAlign.
You can also use direction or reverseDirection to align text depending on arrow direction. Further details and examples of this are available on the link::skinparam[skinparam] page.
Change arrow style
You can change arrow style by several ways:
* add a final x to denote a lost message
* use \ or / instead of < or > to have only the bottom or top part of the arrow
* repeat the arrow head (for example, >> or //) head to have a thin drawing
* use -- instead of - to have a dotted arrow
* add a final "o" at arrow head
* use bidirectional arrow <->
Message sequence numbering
The keyword autonumber is used to
automatically add an incrementing number to messages.
@startuml
autonumber
Bob -> Alice : Authentication Request
Bob <- Alice : Authentication Response
@endumlYou can specify a startnumber with autonumber <start> , and
also an increment with autonumber <start> <increment>.
@startuml
autonumber
Bob -> Alice : Authentication Request
Bob <- Alice : Authentication Response
autonumber 15
Bob -> Alice : Another authentication Request
Bob <- Alice : Another authentication Response
autonumber 40 10
Bob -> Alice : Yet another authentication Request
Bob <- Alice : Yet another authentication Response
@endumlYou can specify a format for your number by using between double-quote.
The formatting is done with the Java class DecimalFormat
(0 means digit, # means digit and zero if absent).
You can use some html tag in the format.
@startuml
autonumber "[000]"
Bob -> Alice : Authentication Request
Bob <- Alice : Authentication Response
autonumber 15 "(##)"
Bob -> Alice : Another authentication Request
Bob <- Alice : Another authentication Response
autonumber 40 10 "Message 0  "
Bob -> Alice : Yet another authentication Request
Bob <- Alice : Yet another authentication Response
@endumlYou can also use autonumber stop and
autonumber resume <increment> <format> to respectively pause and resume
automatic numbering.
@startuml
autonumber 10 10 "[000]"
Bob -> Alice : Authentication Request
Bob <- Alice : Authentication Response
autonumber stop
Bob -> Alice : dummy
autonumber resume "Message 0  "
Bob -> Alice : Yet another authentication Request
Bob <- Alice : Yet another authentication Response
autonumber stop
Bob -> Alice : dummy
autonumber resume 1 "Message 0  "
Bob -> Alice : Yet another authentication Request
Bob <- Alice : Yet another authentication Response
@endumlYour startnumber can also be a 2 or 3 digit sequence using a field delimiter such as ., ;, ,, : or a mix of these. For example: 1.1.1 or 1.1:1.
Automatically the last digit will increment.
To increment the first digit, use: autonumber inc A. To increment the second digit, use: autonumber inc B.
@startuml
autonumber 1.1.1
Alice -> Bob: Authentication request
Bob --> Alice: Response
autonumber inc A
'Now we have 2.1.1
Alice -> Bob: Another authentication request
Bob --> Alice: Response
autonumber inc B
'Now we have 2.2.1
Alice -> Bob: Another authentication request
Bob --> Alice: Response
autonumber inc A
'Now we have 3.1.1
Alice -> Bob: Another authentication request
autonumber inc B
'Now we have 3.2.1
Bob --> Alice: Response
@endumlYou can also use the value of autonumber with the %autonumber% variable:
@startuml
autonumber 10
Alice -> Bob
note right
  the autonumber works everywhere.
  Here, its value is ** %autonumber% **
end note
Bob --> Alice: //This is the response %autonumber%//
@enduml[Ref. QA-7119]
Splitting diagrams
The newpage keyword is used to split a diagram into several images.
You can put a title for the new page just after the newpage
keyword.  This title overrides the previously specified title if any.
This is very handy with Word to print long diagram on several pages.
(Note: this really does work. Only the first page is shown below, but it is a display artifact.)
Grouping message
It is possible to group messages together using the following
keywords:
* alt/else
* opt
* loop
* par
* break
* critical
* group, followed by a text to be displayed
It is possible to add a text that will be displayed into the
header (for group, see next paragraph 'Secondary group label').
The end keyword is used to close the group.
Note that it is possible to nest groups.
@startuml
Alice -> Bob: Authentication Request
alt successful case
    Bob -> Alice: Authentication Accepted
else some kind of failure
    Bob -> Alice: Authentication Failure
    group My own label
    Alice -> Log : Log attack start
        loop 1000 times
            Alice -> Bob: DNS Attack
        end
    Alice -> Log : Log attack end
    end
else Another type of failure
   Bob -> Alice: Please repeat
end
@endumlSecondary group label
For group, it is possible to add, between`[` and ], a secondary text or label that will be displayed into the header.
@startuml
Alice -> Bob: Authentication Request
Bob -> Alice: Authentication Failure
group My own label [My own label 2]
    Alice -> Log : Log attack start
    loop 1000 times
        Alice -> Bob: DNS Attack
    end
    Alice -> Log : Log attack end
end
@enduml[Ref. QA-2503]
Notes on messages
It is possible to put notes on message using the note left
or note right keywords just after the message.
You can have a multi-line note using the end note
keywords.
Some other notes
It is also possible to place notes relative to participant with note left of , note right of or note over keywords.
It is possible to highlight a note by changing its background link::color[color].
You can also have a multi-line note using the end note keywords.
@startuml
participant Alice
participant Bob
note left of Alice #aqua
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 #FFAAAA: This is displayed\n over Bob and Alice.
note over Bob, Alice
This is yet another
example of
a long note.
end note
@endumlChanging notes shape [hnote, rnote]
You can use hnote and rnote keywords
to change note shapes :
* hnote for hexagonal note;
* rnote for rectangle note.
@startuml
caller -> server : conReq
hnote over caller : idle
caller <- server : conConf
rnote over server
 "r" as rectangle
 "h" as hexagon
endrnote
rnote over server
 this is
 on several
 lines
endrnote
hnote over caller
 this is
 on several
 lines
endhnote
@enduml[Ref. QA-1765]
Note over all participants [across]
You can directly make a note over all participants, with the syntax:
* note across: note_description
@startuml
Alice->Bob:m1
Bob->Charlie:m2
note over Alice, Charlie: Old method for note over all part. with:\n ""note over //FirstPart, LastPart//"".
note across: New method with:\n""note across""
Bob->Alice
hnote across:Note across all part.
@enduml[Ref. QA-9738]
Several notes aligned at the same level [/]
You can make several notes aligned at the same level, with the syntax /:
* without / (by default, the notes are not aligned)
@startuml
note over Alice : initial state of Alice
note over Bob : initial state of Bob
Bob -> Alice : hello
@enduml- 
with
/(the notes are aligned) 
@startuml note over Alice : initial state of Alice / note over Bob : initial state of Bob Bob -> Alice : hello @enduml
[Ref. QA-354]
Creole and HTML
link::creole[It is also possible to use creole formatting:]
@startuml
participant Alice
participant "The **Famous** Bob" as Bob
Alice -> Bob : hello --there--
... Some ~~long delay~~ ...
Bob -> Alice : ok
note left
  This is **bold**
  This is //italics//
  This is ""monospaced""
  This is --stroked--
  This is __underlined__
  This is ~~waved~~
end note
Alice -> Bob : A //well formatted// message
note right of Alice
 This is displayed
 __left of__ Alice.
end note
note left of Bob
 This is displayed 
 **left of  Alice Bob**.
end note
note over Alice, Bob
 This is hosted by 
end note
@enduml    Divider or separator
If you want, you can split a diagram using == separator to
divide your diagram into logical steps.
Lifeline Activation and Destruction
The activate and deactivate are used to denote
participant activation.
Once a participant is activated, its lifeline appears.
The activate and deactivate apply on
the previous message.
The destroy denote the end of the lifeline of a
participant.
@startuml
participant User
User -> A: DoWork
activate A
A -> B: << createRequest >>
activate B
B -> C: DoWork
activate C
C --> B: WorkDone
destroy C
B --> A: RequestCreated
deactivate B
A -> User: Done
deactivate A
@endumlNested lifeline can be used, and it is possible to add a link::color[color] on the lifeline.
@startuml
participant User
User -> A: DoWork
activate A #FFBBBB
A -> A: Internal call
activate A #DarkSalmon
A -> B: << createRequest >>
activate B
B --> A: RequestCreated
deactivate B
deactivate A
A -> User: Done
deactivate A
@endumlAutoactivation is possible and works with the return keywords:
Return
Command return generates a return message with optional text label.
The return point is that which caused the most recent life-line activation.
The syntax is return label where label if provided is any string acceptable for conventional messages.
Participant creation
You can use the create keyword just before the first
reception of a message to emphasize the fact that this message is
actually creating this new object.
Shortcut syntax for activation, deactivation, creation
Immediately after specifying the target participant, the following syntax can be used:
- 
Activate the target (optionally a link::color[color] may follow this) - 
--Deactivate the source - 
**Create an instance of the target - 
!!Destroy an instance of the target 
@startuml
alice -> bob ++ : hello
bob -> bob ++ : self call
bob -> bib ++  #005500 : hello
bob -> george ** : create
return done
return rc
bob -> george !! : delete
return success
@endumlThen you can mix activation and deactivation, on same line:
Incoming and outgoing messages
You can use incoming or outgoing arrows if you want to focus on a part of the diagram.
Use square brackets to denote the left “[” or the right “]” side of the diagram.
@startuml
[-> A: DoWork
activate A
A -> A: Internal call
activate A
A ->] : << createRequest >>
A<--] : RequestCreated
deactivate A
[<- A: Done
deactivate A
@endumlYou can also have the following syntax:
Short arrows for incoming and outgoing messages
You can have short arrows with using ?.
@startuml
?-> Alice    : ""?->""\n**short** to actor1
[-> Alice    : ""[->""\n**from start** to actor1
[-> Bob      : ""[->""\n**from start** to actor2
?-> Bob      : ""?->""\n**short** to actor2
Alice ->]    : ""->]""\nfrom actor1 **to end**
Alice ->?    : ""->?""\n**short** from actor1
Alice -> Bob : ""->"" \nfrom actor1 to actor2
@enduml[Ref. QA-310]
Anchors and Duration
With teoz it is possible to add anchors to the diagram and use the anchors to specify duration time.
@startuml
!pragma teoz true
{start} Alice -> Bob : start doing things during duration
Bob -> Max : something
Max -> Bob : something else
{end} Bob -> Alice : finish
{start} <-> {end} : some time
@endumlYou can use the -P link::command-line[command-line] option to specify the pragma:
java -jar plantuml.jar -Pteoz=true
[Ref. issue-582]
Stereotypes and Spots
It is possible to add stereotypes to participants using <<
and >>.
In the stereotype, you can add a spotted character
in a colored circle using the syntax (X,color).
@startuml
participant "Famous Bob" as Bob << Generated >>
participant Alice << (C,#ADD1B2) Testable >>
Bob->Alice: First message
@endumlBy default, the guillemet character is used to display the stereotype.
You can change this behavious using the skinparam guillemet:
More information on titles
You can use link::creole[creole formatting] in the title.
@startuml
title __Simple__ **communication** example
Alice -> Bob: Authentication Request
Bob -> Alice: Authentication Response
@endumlYou can add newline using \n in the title description.
@startuml
title __Simple__ communication example\non several lines
Alice -> Bob: Authentication Request
Bob -> Alice: Authentication Response
@endumlYou can also define title on several lines using title
and end title keywords.
Participants encompass
It is possible to draw a box around some participants, using box
and end box commands.
You can add an optional title or a
optional background color, after the box keyword.
@startuml
box "Internal Service" #LightBlue
participant Bob
participant Alice
end box
participant Other
Bob -> Alice : hello
Alice -> Other : hello
@endumlIt is also possible to nest boxes - to draw a box within a box - when using the teoz rendering engine, for example:
Skinparam
You can use the link::skinparam[skinparam] command to change colors and fonts for the drawing.
You can use this command: * In the diagram definition, like any other commands, * In an link::preprocessing[included file], * In a configuration file, provided in the link::command-line[command line] or the link::ant-task[ANT task].
You can also change other rendering parameter, as seen in the following examples:
@startuml
skinparam sequenceArrowThickness 2
skinparam roundcorner 20
skinparam maxmessagesize 60
skinparam sequenceParticipant underline
actor User
participant "First Class" as A
participant "Second Class" as B
participant "Last Class" as C
User -> A: DoWork
activate A
A -> B: Create Request
activate B
B -> C: DoWork
activate C
C --> B: WorkDone
destroy C
B --> A: Request Created
deactivate B
A --> User: Done
deactivate A
@enduml@startuml
skinparam backgroundColor #EEEBDC
skinparam handwritten true
skinparam sequence {
ArrowColor DeepSkyBlue
ActorBorderColor DeepSkyBlue
LifeLineBorderColor blue
LifeLineBackgroundColor #A9DCDF
ParticipantBorderColor DeepSkyBlue
ParticipantBackgroundColor DodgerBlue
ParticipantFontName Impact
ParticipantFontSize 17
ParticipantFontColor #A9DCDF
ActorBackgroundColor aqua
ActorFontColor DeepSkyBlue
ActorFontSize 17
ActorFontName Aapex
}
actor User
participant "First Class" as A
participant "Second Class" as B
participant "Last Class" as C
User -> A: DoWork
activate A
A -> B: Create Request
activate B
B -> C: DoWork
activate C
C --> B: WorkDone
destroy C
B --> A: Request Created
deactivate B
A --> User: Done
deactivate A
@endumlAppendix: Examples of all arrow type
Normal arrow
@startuml
participant Alice as a
participant Bob   as b
a ->     b : ""->   ""
a ->>    b : ""->>  ""
a -\     b : ""-\   ""
a -\\    b : ""-\\\\""
a -/     b : ""-/   ""
a -//    b : ""-//  ""
a ->x    b : ""->x  ""
a x->    b : ""x->  ""
a o->    b : ""o->  ""
a ->o    b : ""->o  ""
a o->o   b : ""o->o ""
a <->    b : ""<->  ""
a o<->o  b : ""o<->o""
a x<->x  b : ""x<->x""
a ->>o   b : ""->>o ""
a -\o    b : ""-\o  ""
a -\\o   b : ""-\\\\o""
a -/o    b : ""-/o  ""
a -//o   b : ""-//o ""
a x->o   b : ""x->o ""
@endumlItself arrow
@startuml
participant Alice as a
participant Bob   as b
a ->     a : ""->   ""
a ->>    a : ""->>  ""
a -\     a : ""-\   ""
a -\\    a : ""-\\\\""
a -/     a : ""-/   ""
a -//    a : ""-//  ""
a ->x    a : ""->x  ""
a x->    a : ""x->  ""
a o->    a : ""o->  ""
a ->o    a : ""->o  ""
a o->o   a : ""o->o ""
a <->    a : ""<->  ""
a o<->o  a : ""o<->o""
a x<->x  a : ""x<->x""
a ->>o   a : ""->>o ""
a -\o    a : ""-\o  ""
a -\\o   a : ""-\\\\o""
a -/o    a : ""-/o  ""
a -//o   a : ""-//o ""
a x->o   a : ""x->o ""
@endumlIncoming and outgoing messages (with '[', ']')
Incoming messages (with '[')
@startuml
participant Alice as a
participant Bob   as b
[->      b : ""[->   ""
[->>     b : ""[->>  ""
[-\      b : ""[-\   ""
[-\\     b : ""[-\\\\""
[-/      b : ""[-/   ""
[-//     b : ""[-//  ""
[->x     b : ""[->x  ""
[x->     b : ""[x->  ""
[o->     b : ""[o->  ""
[->o     b : ""[->o  ""
[o->o    b : ""[o->o ""
[<->     b : ""[<->  ""
[o<->o   b : ""[o<->o""
[x<->x   b : ""[x<->x""
[->>o    b : ""[->>o ""
[-\o     b : ""[-\o  ""
[-\\o    b : ""[-\\\\o""
[-/o     b : ""[-/o  ""
[-//o    b : ""[-//o ""
[x->o    b : ""[x->o ""
@endumlOutgoing messages (with ']')
@startuml
participant Alice as a
participant Bob   as b
a ->]      : ""->]   ""
a ->>]     : ""->>]  ""
a -\]      : ""-\]   ""
a -\\]     : ""-\\\\]""
a -/]      : ""-/]   ""
a -//]     : ""-//]  ""
a ->x]     : ""->x]  ""
a x->]     : ""x->]  ""
a o->]     : ""o->]  ""
a ->o]     : ""->o]  ""
a o->o]    : ""o->o] ""
a <->]     : ""<->]  ""
a o<->o]   : ""o<->o]""
a x<->x]   : ""x<->x]""
a ->>o]    : ""->>o] ""
a -\o]     : ""-\o]  ""
a -\\o]    : ""-\\\\o]""
a -/o]     : ""-/o]  ""
a -//o]    : ""-//o] ""
a x->o]    : ""x->o] ""
@endumlShort incoming and outgoing messages (with '?')
Short incoming (with '?')
@startuml
participant Alice as a
participant Bob   as b
a ->     b : //Long long label//
?->      b : ""?->   ""
?->>     b : ""?->>  ""
?-\      b : ""?-\   ""
?-\\     b : ""?-\\\\""
?-/      b : ""?-/   ""
?-//     b : ""?-//  ""
?->x     b : ""?->x  ""
?x->     b : ""?x->  ""
?o->     b : ""?o->  ""
?->o     b : ""?->o  ""
?o->o    b : ""?o->o ""
?<->     b : ""?<->  ""
?o<->o   b : ""?o<->o""
?x<->x   b : ""?x<->x""
?->>o    b : ""?->>o ""
?-\o     b : ""?-\o  ""
?-\\o    b : ""?-\\\\o ""
?-/o     b : ""?-/o  ""
?-//o    b : ""?-//o ""
?x->o    b : ""?x->o ""
@endumlShort outgoing (with '?')
@startuml
participant Alice as a
participant Bob   as b
a ->     b : //Long long label//
a ->?      : ""->?   ""
a ->>?     : ""->>?  ""
a -\?      : ""-\?   ""
a -\\?     : ""-\\\\?""
a -/?      : ""-/?   ""
a -//?     : ""-//?  ""
a ->x?     : ""->x?  ""
a x->?     : ""x->?  ""
a o->?     : ""o->?  ""
a ->o?     : ""->o?  ""
a o->o?    : ""o->o? ""
a <->?     : ""<->?  ""
a o<->o?   : ""o<->o?""
a x<->x?   : ""x<->x?""
a ->>o?    : ""->>o? ""
a -\o?     : ""-\o?  ""
a -\\o?    : ""-\\\\o?""
a -/o?     : ""-/o?  ""
a -//o?    : ""-//o? ""
a x->o?    : ""x->o? ""
@endumlSpecific SkinParameter
LifelineStrategy
- 
nosolid (by default)
 
@startuml skinparam lifelineStrategy nosolid Bob -> Alice : hello Alice -> Bob : ok @enduml
[Ref. QA-9016]
- 
solid In order to have solid life line in sequence diagrams, you can use:
skinparam lifelineStrategy solid 
@startuml skinparam lifelineStrategy solid Bob -> Alice : hello Alice -> Bob : ok @enduml
[Ref. QA-2794]
style strictuml
To be conform to strict UML (for arrow style: emits triangle rather than sharp arrowheads), you can use:
* skinparam style strictuml
[Ref. QA-1047]
Hide unlinked participant
By default, all participants are displayed.
But you can hide unlinked participant.
@startuml
hide unlinked
participant Alice
participant Bob
participant Carol
Alice -> Bob : hello
@enduml[Ref. QA-4247]
Slanted or odd arrows
You can use the (nn) option (before or after arrow) to make the arrows slanted, where nn is the number of shift pixels.
[Available only after v1.2022.6beta+]
[Ref. QA-14145]
@startuml
!pragma teoz true
A ->(50) C: Starts\nwhen 'B' sends
& B ->(25) C: \nBut B's message\n arrives before A's
@enduml[Ref. QA-6684]
@startuml
!pragma teoz true
S1 ->(30) S2: msg 1\n
& S2 ->(30) S1: msg 2
note left S1: msg\nS2 to S1
& note right S2: msg\nS1 to S2
@enduml[Ref. QA-1072]