PlantUML Activity Diagrams: Modeling Workflows as Code

An activity diagram models a workflow or process: the sequence of actions, the decisions that branch it, the loops that repeat, and the points where work happens in parallel. It is UML's answer to the flowchart, and it is the right tool when you want to document a business process or the control flow of a feature in a way that captures concurrency and swimlane responsibility, which a plain flowchart handles less formally.

PlantUML has two activity-diagram syntaxes, and this tutorial uses the newer one, which is more readable and actively maintained - the older syntax is deprecated and you should avoid it in new diagrams. You will learn the start and stop nodes, actions, if/else branching, loops, parallel forks, and swimlanes. Since PlantUML is a text format, any workflow here can be rebuilt as an editable diagram in Atlas Diagram Studio at /diagrams, and the wider tour lives at /guides/plantuml-complete-guide. For the visual-flowchart counterpart, the diagram-as-code guide at /guides/diagram-as-code-guide is a useful companion.

Actions, start, and stop

In the modern syntax, wrap the diagram in @startuml and @enduml, then mark the beginning with the start keyword and the end with stop. An action - a single step of work - is written as text between colons and a semicolon, so :Receive order; draws a rounded action box. A minimal workflow is just start, a few colon-delimited actions in sequence, and stop; PlantUML connects them top to bottom with arrows automatically, so you never draw the connectors yourself.

You can label the implied arrow between actions by placing text in parentheses or using an arrow note, and you can end a path with end instead of stop to mark a flow-final rather than an activity-final node. The mental model is that you are writing the steps in the order they happen, and PlantUML handles the layout. This is what makes the modern syntax pleasant: a linear process reads almost like a numbered list, and the visual diagram falls out of it.

Branching and looping

Decisions use an if/then/else structure that reads naturally. Write if (payment valid?) then (yes) followed by the actions on the yes path, then else (no) with the actions on the no path, and close with endif. The condition goes in the first parentheses and the branch labels in the following ones, so the rendered diamond and its outgoing arrows are labelled exactly as you wrote them. For more than two branches, PlantUML offers elseif, letting you chain conditions without deeply nesting.

Loops come in two shapes. A while loop repeats as long as a condition holds: while (more items?) is (yes) with the repeated actions inside and endwhile to close. A repeat loop runs the body first and tests afterward, using repeat, the body actions, and repeat while (condition) - the do-while pattern. Choosing the right loop matters because it changes whether the body always runs at least once, and PlantUML draws each with the correct back-edge so the diagram matches the real control flow.

Parallel work and swimlanes

Two of PlantUML's strongest activity-diagram features are parallel forks and swimlanes, which capture things a simple flowchart cannot. Use these when concurrency or responsibility matters.

• Parallel fork: fork begins concurrent paths, fork again separates each parallel branch, and end fork joins them.
• Split processing: split and split again behave similarly for splitting flow, with end split to merge.
• Swimlanes: prefix actions with a lane name in pipes, like |Warehouse| :Pack order; to assign steps to a responsible party.
• Colour a swimlane by adding a colour after its name, which helps readers scan who owns what.
• Notes: attach note right of an action to annotate a step without cluttering the flow.
• Detach and goto: advanced connectors let you model flows that jump or terminate a single path without stopping the whole diagram.

From workflow text to a polished diagram

Swimlanes deserve special mention because they turn an activity diagram into a responsibility map. By prefixing actions with a lane, you show not just what happens but who does it - Customer, Warehouse, Billing - which is exactly what a business-process audience needs. PlantUML lays the lanes out as vertical columns and routes the flow across them as ownership changes, making hand-offs between teams visible, which is often where processes actually break down.

Once the workflow is captured as PlantUML text and versioned with the process it documents, you have a maintainable source. When you need a version for a slide, a client, or a workshop where non-engineers will edit it, rebuild it in Atlas Diagram Studio at /diagrams for styling and real-time collaboration, or start a first draft from a description using the AI diagram generator at /diagram-tools/ai-diagram-generator. The state-diagram tutorial at /guides/plantuml-state-diagram-tutorial covers the related task of modelling an object's lifecycle rather than a process, and the sequence tutorial at /guides/plantuml-sequence-diagram-tutorial covers timed interactions.