Running PlantUML

Is PlantUML installed as a package? Then we can run it like this: plantuml input.puml.

If we have the jar file we can run the jar file like normal: java -jar plantuml.jar input.puml.

Any file extension can be used. Using .txt probably makes it easier for people to open the text files. On the other hand, when we use .puml it is immediately clear what the file contains. We can call PlantUML with any number of file and directory paths as argument.

PlantUML.com has a good command-line options page. It also explains how to get the source from an output PNG. It is embedded there as text. That can also be used as a way to only regenerate a file if it is necessary.

SVG instead of PNG

Add -tsvg.

plantuml -tsvg input.puml

Horizontal instead of vertical

To get a horizontal diagram we can add left to right direction at the top, like this:

@startuml
left to right direction

Lines and arrows going both ways

We can't specify lines and arrows twice in separate directions. We must specify them both in one go. Like this: A <--> B

I find it to be the least error prone to do all of them at the end, rather than some in between.

Mixing UML concepts in one graph

allowmixing can be added to allow mixing UML concepts that are not supposed to be mixed. In the diagram below I am mixing components with classes.

System diagram example

Here is an example system diagram specification:

@startuml
left to right direction
allowmixing
'This line is only a comment

title
  Example system / component diagram for discussing a simple fail-over design
end title

cloud "Internal" as IN

node "Load Balancer" as ILB

package "App Nodes" as NODES {
  node "Node 1" as N1
  node "Node 2" as N2
  node "..." as NE
  node "Node n" as NN
}

database "MySql" {
  frame "Main database" {
    class "activity" as AT <<T, white>> {
      node_identifier VARCHAR
      timestamp DATETIME
    }
  }
}

node "Load Balancer" as ELB

cloud "External" as EX

IN <--> ILB
ILB <--> NODES
N1 <--> AT
N2 <--> AT
NN <--> AT
NODES <--> ELB
ELB <--> EX

@enduml

It leads to the following diagram:

Sequence diagram example, simple

Diagram:

Source:

@startuml
title
Sequence diagram for the redirect model
end title

Client -> Server: Requests /YYYY/MM/slug
Server --> Client: Responds with:\nStatus code 301 (Moved Permanently)\nResponse header Location: /posts/YYYY/MM/slug

Client -> Server: Requests /posts/YYYY/MM/slug
Client <-- Server: Responds with: /posts/YYYY/MM/slug

@enduml

Sequence diagram example, advanced

Here is an example sequence diagram for discussing how to add a migration plan to an existing integration/converter service. There is a section for normal operations, where

• messages come in
• these are converted to the external service message format
• every n seconds the messages that have not been sent out to the external service yet are sent out
• responses are stored
• every n seconds the responses that have not been sent out to the internal service yet are sent out

Not shown here is are components like the fail-over and retry mechanisms.

The section marked Migration shows an always-on migration that runs in the background. The idea is that the second external service will be sent all messages that were previously sent to the first external service. By doing this in the background the final step in the migration will be seamless, without downtime. This is only possible if the expectations of the second external service are already well known. If it is a new service we should expect problems to occur.

Diagram:

Source:

@startuml
participant InternalService
box "Integration/Converter Service" #white
boundary    API
database    Messages as Messages
control     OutgoingScheduler as OS
control     IncomingScheduler as IS
database    Responses
database    MigrationStatus
control     MigrationScheduler as MS
end box
participant ExternalA as ExtA
participant ExternalB as ExtB

group Normal operations
InternalService --> InternalService : Lock message
InternalService -> API : Message as XML
API --> Messages : XML,\nXML -> Format A
OS --> OS : Every 30s
OS --> Messages: Check new,\nFIFO batch
OS -> ExtA :
ExtA -> Responses :
IS --> IS : Every 30s
IS --> Responses: Check new,\nFIFO batch
IS -> InternalService :
InternalService --> InternalService: Unlock message
end

group Migration
MS --> MS : Every 30s\nif migrate_from_a_to_b==true
MS --> MigrationStatus : Check non-migrated messages\nFIFO batch
MS --> Messages :
MS --> Responses : Check if ExternalService A accepted the message
MS -> ExtB : XML -> Format B
ExtB -> MS:
MS --> MigrationStatus : Mark as migrated/failed
end

@enduml

Integrated with Pelican

We can integrate PlantUML with Pelican using the plugin called plantuml. If you already have the entire plugin repository locally all you need to do is add plantuml to your plugin list. We can embed the PlantUML diagram specification inside our content, and it will be processed and replaced with the image file.

This is the opening text:

::uml:: format="png" alt="describe the diagram here"

Then we add the UML specification, and close with:

::end-uml::