Diagrams as Code with PlantUML

5 min readSep 7, 2020

This article will use the PlantUML syntax and features to visualise ideas from “Diagrams as Code”. Confirming that requirements are satisfied by defining interactions between participants in plain text to satisfy a business goal.

Link to Github and let’s start.

DaRealPunjabi/plantuml-diagrams

This post covers some of the basic aspects of visualising ideas with diagrams. PlantUML diagrams are “Diagrams as Code”…

github.com

Prerequisite

The following posts require a suitable editor e.g. Visual Studio Code and GraphViz. Both items are free to use.
Within Visual Studio Code install the free PlantUML (jebbs) plugin.

Installation

brew cask install visual-studio-codebrew install graphviz

PlantUML Elements

The above elements can be used is PlantUML diagrams.

Sequence Diagrams

A Sequence Diagram desrcibes the interaction between participants to achieve a goal.

Participants

The following is the list of elements (participants) that can be used in a sequence diagram:

actor, boundary, collections, control, database and entity

A lifeline with:

an actor element is used when the sequence diagram is owned by a use case
a boundary element indicates a system boundary that provides interaction between the other elements
a collection element indicates interaction with a list of objects
a control element indicates a controlling entity that orchestrates interaction
a database element is used to represent the management of data elements. A persistent information component representing a technology file system.
an entity element is used to represent the management of all data elements related to the entity. A persistent information component representing a business concept.

Create Re-usable Participants

Taking the UML definition apart piece by piece

\' participants will not show in a diagram if they are not
   referenced in that particular diagram '/
hide unlinked/' Will display following participants in an container named
   External System '/
box 'External System'/' Will display text Commercial Customer when this participant is
   used '/
actor "Commercial Customer" as commercial_customer

Basic Synchronous Flow Sequence Diagram

/' Automatically add number to messages '/
autonumber/' Synchronous message from caller to receiver '/
commercial_customer -> mobile_app/' Activate the receiver - start lifeline of a receiver '/
commercial_customer -> mobile_app ++/' Add message text '/
commercial_customer -> mobile_app ++ : Select service/' Message to self - Method invoked within receiver lifeline '/
dsp_identity -> dsp_identity : Validate credentials/' Receiver is done processing with optional message '/
return response

Basic Asynchronous Flow Sequence Diagram

/' Asynchronous message from caller to receiver '/
svc_dispatch_agreement -\ otb_commercial_customer : Request consent/' Asynchronous flows can be made more explicit by placing
   the message in parallel process group with an immediate reply '/
par
  svc_dispatch_agreement -> svc_dispatch_agreement : Immediate reply
end

Alternate Flow Sequence Diagram

The alt group is used when a choice needs to be made between two or more message sequences. It models the “if-then-else” logic.

/' Alternate flow '/
alt condition 1else condition 2else condition 3end

Entity Relationship Diagram

An Entity Relationship Diagram (ERD) describes entities (things, ideas and concepts that can be detailed) with attributes and the relationships between them.

Participants

An ERD contains entities but may also include a rectangles to collate dependent entities for greater readability.

/' Define a customer domain '/
rectangle "Customer Domain" {/' Define an entity with attrbiutes '/
  entity "Customer" as c01 {
    * Identifying attributes
    customerId <<auto generated>> integer
    --
    * Mandatory attributes
    firstName : varchar(255)
    birthDate : date
    --
    * Optional attributes
    middleNames : varchar(255)
 }

Connect entities with relationships.

Type         Symbol
Zero or One    |o--
Exactly One    ||--
Zero or Many   }o--
One or Many    }|--/' Model a many to many customer to party relationship via a customerparty linked entity '/
c01 ||-right-|{ c02
c02 }|-right-|| c03

Activity Diagram

An Activity Diagram describes the flow of activities through various states showing how activities depend on each other in performing a task.

Participants

An activity digram is defined by the following elements:

initial, stop and final nodes denoting starting and terminating points of a flow
decision points used to represent a conditional branch point with one input and multiple outputs
merge points used to represent several inputs with one output
forks used to represent a flow that branches into two or more parallel flows
joins used to represent two or more parallel flows that combine into a common flow

/' Define initial, stop and final node '/
start/' Define decision points with if, while and repeat '/
if (Data available) then (Yes)
while (Data available)
repeat while (Data available) is (Yes)/' fork for parallel processing '/
fork
forkagain