1 Introduction

  • PlantUML is an open source tool that can create a variety of diagrams, including sequence diagrams.
  • Each sequence diagram is created from a set of instructions contained in a text file. Any editor that does not introduce formatting characters (e.g., notepad, wordpad) may be used to create or edit the files. Most useful tools is VS Code.
  • Each sequence diagram will have its own text file. PlantUML creates corresponding graphic file(s) based on the instructions found in the text file.
  • Requirements
  • The only requirement to run PlantUML is to have a Java Runtime Environment (JRE) installed on your PC.
  • PlantUML can be downloaded at: http://plantuml.sourceforge.net/index.html
  • Download the latest compiled jar file as well as the reference manual to a folder of your choosing on your PC.

2 PlantUML Text File

  • This file contains processing instructions starting with @startuml on the first line and @enduml on the last line.
  • These instructions are in theme file can be included in your sequence diagrams text file using the instruction: !include ConexxusSkinParam.txt

  • Formattings

    • PlantUML ignores blank lines and whitespace at the beginning of a line. Liberal use of whitespace to offset logical blocks in the text file can enhance readability.

  • Comments

    • Comments can be included in the file by starting the line with a single quote (').
    • To put a comment on several lines you can start with /' and end the quote with '/
      • 'This is a short comment /' This is how you can span multiple lines of comments '/ 

3 Theme File

  • So that all sequence diagrams are consistent, use PlantUML defaults along with the instructions:

4 Diagramming - General

  • Sections

    • Title
      • keyword usage image
        title Title parts_usecase

  • Declarations

    • Although PlantUML does not require you to define interfaces / participants (i.e., entities), it is recommended best practice to define all participants together and before they are used.
    • If the participant name is long or needs spaces, declare the participant using a short name and the display name. The short name can be used in diagram specific processing instructions.
    • To control the layout of the diagram, you can add spaces in the display name to better position the participants.
    • participant POS as " POS " participant OPT as " OPT " participant LH as "Loyalty Host"

  • Notes

    • Text for notes can be split over multiple lines by inserting new lines (\n) into the note text. Alternatively, the keyword note may be used, followed by the note text on one or more lines, followed by keyword end note.
    • note right of OPT: right of OPT\non two lines
    • note over POS over POS on two lines end note

  • Dividers

    1. Use a divider to separate a sequence diagram into logical or functional sections. A divider is specified by “==” on both sides of the text to display.
    2. Splitting Diagrams
      • When a sequence diagram is too long to fit on a page without losing readability, split it into one or more graphic files using the keyword newpage.
      • Each additional graphic file generated will have 00x appended (e.g., example.png, example_001.png, example_002.png).
      • Place a divider at the bottom of the first page and at the top of the second page to make it clear that the diagram is split.
    3. If whitespace between messages is required in the diagram, use one or more "|||".

5 Diagramming - Sequence

  • Represent the messages and orders of the interacts.
    keyword usage image
    -> Message parts_usecase
    <-- Return parts_usecase

  • Messages

    • Messages between participants are specified by defining the two participants,
      • the direction,
      • the line type, and
      • the corresponding text to display above the message.
    • Mandatory messages are rendered with solid lines, indicated in the instructions by “->”.
    • Optional steps are rendered with dashed lines, indicated in the instruction by “-->”.

  • Lifelines

    • Use the keywords activate and deactivate to control the lifeline of a participant.
    • The lifeline should be inactive (will be shown as dashed) when not in use.
    • These keywords act on the previous message. Therefore place the activate keyword after the message that starts the lifeline and the deactivate keyword after the message the ends the lifeline.
    • Messages normally connect two (and only two) participants. Messages should not pass through another active participant.

  • Groupings

    • Messages can be grouped together in a box by using the keyword group, specifying the text to include in the grouping, ending with the keyword end. The explanation can be formatted to force a new line with ‘\n’.

  • Vertical boxes

    • Participants may be grouped together in a vertical box to draw attention to functionality, purpose or architectural considerations. Use the keywords box and end box in the participant declarations to define where the box should be drawn.
    • box "B and C may be integrated into \n one device" participant B as " B " participant C as " C " end box participant D as " D "

References

  • https://www.conexxus.org/sites/default/files/UsingPlantUML.pdf