Messages
Messages are the basic action of sequence diagrams. They are portrayed by arrows going from a sender to a receiver.
Lifelines will not be declared in this section unless required for an explanation. This will keep our code blocks smaller and easier to read.
Declaration
In PlantUML, you declare messages by drawing an arrow with the characters on your keyboard. Place the arrow between the sender and the receiver with the arrow pointing at the receiver.
Example: Message Declaration
@startuml
'Example:Message Declaration
'Send a few basic messages.
Sean -> Maria
Maria -> Zarek
@enduml
Direction
Arrows can be drawn right to left or left to right. This is nice as it allows you to customize how you want to format your messages. You can always keep senders on one side of your messages like the top of our example. You can also let your arrows go back and forth while your senders stay in the same place on consecutive lines like the bottom of our example. There is also the unadvised option of not picking a method. Do what makes sense for you and your team.
Example: Message Direction
@startuml
'Example: Message Direction
'Send a few messages back and forth between Sean and Maria.
'Keep Sean on the left of the code.
Sean -> Maria
Sean <- Maria
Sean -> Maria
'Send a few messages back and forth between Maria and Zarek.
'Keep the arrow pointing to the right in the code.
Maria -> Zarek
Zarek -> Maria
Maria -> Zarek
@enduml
Properties
The minimum requirements for a message are sender, line_type, head_type, and receiver. As we did with lifelines, we will keep all message properties except message_text in the below order throughout this book. Remember the order is sender to receiver, as shown above, not necessarily left to right. The message_text property is always furthest to the right.
sender - the entity sending the message, usually a participant's lifeline
line_type - determines if the message arrow has a solid or dashed line
arrow_color - sets the color of the message arrow
arrow_head - determines the shape of the arrowhead
receiver - the entity receiving the message at the pointy end of the arrow, usually a participant’s lifeline
message_text - the text that appears with the message arrow
Senders & Receivers
Senders and receivers are usually the participants with lifelines discussed in the previous section. There are a few exceptions. Messages that come from or go to places outside the scope of the current diagram have gates as their sender or receiver at the edge of the diagram. Other messages may get lost, or we may not know where they originated. Per UML standards, these lost and found messages are sent or received from a circle. PlantUML has no standalone command for this, so we must combine gates with our circle. UML calls for a solid circle, but PlantUML only supports an open circle. At the time of this writing, PlantUML does not properly display the messages found originating from the right side gate.
Senders and receivers that are not lifelines with names must touch the arrow_head. See the list of senders and receivers below.
A message can have the same sender and receiver.
name - the name of a lifeline
[ - signifies a gate touching the left side of the sequence diagram can be a sender or receiver
] - signifies a gate touching the right side of the diagram can be a sender or receiver
o- used as the sender of a found message or the receiver of a lost message; this is a lower-case letter o
? - a special character used to shorten the length of a message arrow
Example: Sender & Receiver
@startuml
'Example: Messages Sender & Receiver
'Make Sean receive a message from a left gate
[-> Sean : Text
'Send a message from Sean to Maria.
Sean -> Maria : Text
'Send a message from Maria to herself.
Maria -> Maria: Text
'Send a message from Sean to a left gate.
Sean ->[ :Text
'Send a found message to Maria from the left.
[o-> Maria : Text
'Send a lost message from Maria to the right.
Maria ->o] : Text
'Send a message with a shortened arrow from Sean to the right.
Sean ->? : Text
'Send a message with a shortened arrow to Maria from the left.
?-> Maria : Text
@enduml
Line Type
There are two basic line_types, solid and dashed. Solid lines are for basic messages. Dashed lines are for replies and lifeline creation messages. Creation messages are covered in the Participants Creating New Lifelines section of Lifelines.
"-" - creates a solid line
"--" - creates a dashed line
Example: Line Type
@startuml
'Example: Messages Line Type
'Send a message from Sean to Maria.
Sean -> Maria : Text
'Send a reply from Maria to Sean.
Sean <-- Maria : Text
@enduml
Arrow Colors
You can define arrow_color with a standard color name or hex code placed between the line_type and arrow_head. Enclose the color with square brackets. Note that the circle for lost and found messages will be the same color as the arrow.
Example: Arrow Color
@startuml
'Example: Messages Arrow Color
'Send a message with a cyan-colored arrow from Sean to Maria.
Sean -[#cyan]> Maria : Text
'Send a reply message with a purple arrow from Maria to Sean.
Sean <[#561D5E]-- Maria : Text
'Send a lost message with a red arrow from Zarek to the right
Zarek -[#FF0000]>o] : Text
@enduml
Arrow Heads
UML standards for sequence diagrams describe three options for arrow_heads. A filled arrow_head represents a synchronous message. An open arrow_head represents an asynchronous message. An X or cross represents an object deletion message. For more on object deletion messages see ExecutionSpecification. PlantUML provides us with several more options for increased personalization. These will be attached to a reply line_type in the following list for easier visualization. Be mindful the backslashes in the example as they are still escape characters in the message_text.
-- > filled arrow_head right
-- >> open arrow_head right
-- \ top half of filled arrow_head right
-- / bottom half of filled arrow_head right
-- \\ top half of open arrow_head right
-- // bottom half of open arrow_head right
< -- filled arrow_head left
<< -- open arrow_head left
/ -- top half of filled arrow_head left
\ -- bottom half of filled arrow head left
// -- top half of open arrow_head left
\\ -- bottom half of open arrow_head left
-- X object deletion message
< -- > bidirectional arrows are possible with all arrow_heads
Example: Arrow Heads
@startuml
'Example: Messages Arrow Head
Sean --> Maria : -->
Sean -->> Maria : -->>
Sean --\ Maria : --\\
Sean --/ Maria : --/
Sean --\\ Maria : --\\\\
Sean --// Maria : --//
Maria <-- Zarek : <--
Maria <<-- Zarek : <<--
Maria /-- Zarek : /--
Maria \-- Zarek : \--
Maria //-- Zarek : //--
Maria \\-- Zarek : \\--
Maria --X Zarek : --X
Sean <--> Zarek : <-->
@enduml
Message Text
Place message_text at the end of the message after a colon. You can format message_text with creole syntax for emphasis and markup language for color and emphasis. You can define colors with a standard color name or hex code. Use for manual line breaks. For automatic line breaks, see maxMessageSize in the Skin Parameters section. See Text Formatting for a list of creole and markup options.
@startuml
'Example: Message Text
'Send a bold message from Sean to Maria.
'Use creole.
Sean -> Maria : **Text**
'Send a reply to Sean with purple text.
'Use markup.
Sean <-- Maria : <color #561D5E>Text</color>
'Send a message from Maria to Zarek with stricken purple text.
'Use creole for bold and markup for the color.
Maria -> Zarek : <color #561D5E>--Text--</color>
'Send a reply to Maria with a bold red message.
'Use only markup.
Maria <-- Zarek : <b><color:#FF0000>Text</color></b>
'Send a multiline message from Zarek to Sean.
Zarek -> Sean : Multiline \nText
@enduml
Last updated
Was this helpful?