== Sequence Diagram
== 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.
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml
== 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
@enduml
Rename 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
@enduml
You can use the `+order+` keyword to customize the display order of participants.
@startuml
participant Last order 30
participant Middle order 20
participant First order 10
@enduml
== Use non-letters in participants
You can use quotes to define participants.
And you can use the `+as+` keyword to give an alias to those participants.
@startuml
Alice -> "Bob()" : Hello
"Bob()" -> "This is very\nlong" as Long
' You can also declare:
' "Bob()" -> Long as "This is very\nlong"
Long --> "Bob()" : ok
@enduml
== Message to Self
A participant can send a message to itself.
It is also possible to have multi-line using `+\n+`.
@startuml
Alice->Alice: This is a signal to self.\nIt also demonstrates\nmultiline \ntext
@enduml
== Text alignment
=== Text of response message below the arrow
You can put the text of the response message below the arrow, with the `+skinparam responseMessageBelowArrow true+` command.
@startuml
skinparam responseMessageBelowArrow true
Bob -> Alice : hello
Alice -> Bob : ok
@enduml
[[#FFD700#TODO]] Link to Text Alignment on 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 `+<->+`
@startuml
Bob ->x Alice
Bob -> Alice
Bob ->> Alice
Bob -\ Alice
Bob \\- Alice
Bob //-- Alice
Bob ->o Alice
Bob o\\-- Alice
Bob <-> Alice
Bob <->o Alice
@enduml
== Change arrow color
You can change the color of individual arrows using the following notation:
@startuml
Bob -[#red]> Alice : hello
Alice -[#0000FF]->Bob : ok
@enduml
== Message sequence numbering
The keyword `+autonumber+` is used to
automatically add number to messages.
@startuml
autonumber
Bob -> Alice : Authentication Request
Bob <- Alice : Authentication Response
@enduml
You 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
@enduml
You 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
@enduml
You 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
@enduml
== Page Title, Header and Footer
The `+title+` keyword is used to add a title to the page.
Pages can display headers and footers using `+header+` and `+footer+`.
@startuml
header Page Header
footer Page %page% of %lastpage%
title Example Title
Alice -> Bob : message 1
Alice -> Bob : message 2
@enduml
== 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.)
@startuml
Alice -> Bob : message 1
Alice -> Bob : message 2
newpage
Alice -> Bob : message 3
Alice -> Bob : message 4
newpage A title for the\nlast page
Alice -> Bob : message 5
Alice -> Bob : message 6
@enduml
== 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
@enduml
== Secondary 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. https://forum.plantuml.net/2503[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.
@startuml
Alice->Bob : hello
note left: this is a first note
Bob->Alice : ok
note right: this is another note
Bob->Bob : I am thinking
note left
a note
can also be defined
on several lines
end note
@enduml
== 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
@enduml
== Changing notes shape
You can use `+hnote+` and `+rnote+` keywords
to change note shapes.
@startuml
caller -> server : conReq
hnote over caller : idle
caller <- server : conConf
rnote over server
"r" as rectangle
"h" as hexagon
endrnote
@enduml
== 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.
@startuml
== Initialization ==
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
== Repetition ==
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml
== Reference
You can use reference in a diagram, using the keyword `+ref over+`.
@startuml
participant Alice
actor Bob
ref over Alice, Bob : init
Alice -> Bob : hello
ref over Bob
This can be on
several lines
end ref
@enduml
== Delay
You can use `+...+` to indicate a delay in the diagram.
And it is also possible to put a message with this delay.
@startuml
Alice -> Bob: Authentication Request
...
Bob --> Alice: Authentication Response
...5 minutes later...
Bob --> Alice: Good Bye !
@enduml
== Text wrapping
To break long messages, you can manually add `+\n+` in your text.
Another option is to use `+maxMessageSize+` setting:
@startuml
skinparam maxMessageSize 50
participant a
participant b
a -> b :this\nis\nmanually\ndone
a -> b :this is a very long message on several words
@enduml
== Space
You can use `+|||+` to indicate some spacing in the diagram.
It is also possible to specify a number of pixel to be used.
@startuml
Alice -> Bob: message 1
Bob --> Alice: ok
|||
Alice -> Bob: message 2
Bob --> Alice: ok
||45||
Alice -> Bob: message 3
Bob --> Alice: ok
@enduml
== 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
@enduml
Nested 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
@enduml
Autoactivation is possible and works with the return keywords:
@startuml
autoactivate on
alice -> bob : hello
bob -> bob : self call
bill -> bob #005500 : hello from thread 2
bob -> george ** : create
return done in thread 2
return rc
bob -> george !! : delete
return success
@enduml
== 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.
@startuml
Bob -> Alice : hello
activate Alice
Alice -> Alice : some action
return bye
@enduml
== 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.
@startuml
Bob -> Alice : hello
create Other
Alice -> Other : new
create control String
Alice -> String
note right : You can also put notes!
Alice --> Bob : ok
@enduml
== Shortcut syntax for activation, deactivation, creation
Immediately after specifying the target participant, the following syntax can be used:
* `++++` Activate the target (optionally a #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
@enduml
== 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
@enduml
You can also have the following syntax:
@startuml
participant Alice
participant Bob #lightblue
Alice -> Bob
Bob -> Carol
...
[-> Bob
[o-> Bob
[o->o Bob
[x-> Bob
...
[<- Bob
[x<- Bob
...
Bob ->]
Bob ->o]
Bob o->o]
Bob ->x]
...
Bob <-]
Bob x<-]
@enduml
== 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. https://forum.plantuml.net/310[QA-310]]__
== Anchors and Duration
With `+teoz+` usage 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
@enduml
== 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
@enduml
By default, the __guillemet__ character is used to display the stereotype.
You can change this behavious using the skinparam `+guillemet+`:
@startuml
skinparam guillemet false
participant "Famous Bob" as Bob << Generated >>
participant Alice << (C,#ADD1B2) Testable >>
Bob->Alice: First message
@enduml
@startuml
participant Bob << (C,#ADD1B2) >>
participant Alice << (C,#ADD1B2) >>
Bob->Alice: First message
@enduml
== 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
@enduml
You 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
@enduml
You can also define title on several lines using `+title+`
and `+end title+` keywords.
@startuml
title
Simple communication example
on several lines and using html
This is hosted by
end title
Alice -> Bob: Authentication Request
Bob -> Alice: Authentication Response
@enduml
== 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
@enduml
== Removing Foot Boxes
You can use the `+hide footbox+` keywords to remove the foot boxes
of the diagram.
@startuml
hide footbox
title Foot Box removed
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
@enduml
== 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
@enduml
== Changing padding
It is possible to tune some padding settings.
@startuml
skinparam ParticipantPadding 20
skinparam BoxPadding 10
box "Foo1"
participant Alice1
participant Alice2
end box
box "Foo2"
participant Bob1
participant Bob2
end box
Alice1 -> Bob1 : hello
Alice1 -> Out : out
@enduml
== Appendice: 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 ""
@enduml
=== Incoming 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 ""
@enduml
==== Outgoing 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] ""
@enduml
=== Short 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 ""
@enduml
==== Short 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? ""
@enduml
== Specific SkinParameter
=== By default
@startuml
Bob -> Alice : hello
Alice -> Bob : ok
@enduml
=== lifelineStrategy 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. https://forum.plantuml.net/2794[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+`
@startuml
skinparam style strictuml
Bob -> Alice : hello
Alice -> Bob : ok
@enduml
__[Ref. https://forum.plantuml.net/1047[QA-1047]]__
== Hide unlinked participant
By default, all participants are displayed.
@startuml
participant Alice
participant Bob
participant Carol
Alice -> Bob : hello
@enduml
But you can `+hide unlinked+` participant.
@startuml
hide unlinked
participant Alice
participant Bob
participant Carol
Alice -> Bob : hello
@enduml
__[Ref. https://forum.plantuml.net/4247[QA-4247]]__