== 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]]__