Plantuml Syntax for Activity Diagram Examples

If you've ever needed to diagram a workflow or business process as code without dragging boxes around in a GUI PlantUML activity diagrams are one of the fastest ways to do it. The syntax is simple enough to learn in an afternoon, yet powerful enough to model real branching logic, parallel tasks, and loops. Knowing the right syntax means your diagrams render correctly, communicate clearly, and stay maintainable as your processes change.

What Does PlantUML Activity Diagram Syntax Actually Mean?

PlantUML is a text-based tool that generates UML diagrams from plain-text descriptions. Activity diagram syntax in PlantUML is a set of keywords and symbols you write inside a code block to describe the flow of actions, decisions, and transitions in a process. Instead of drawing arrows and shapes, you type statements like start, stop, if, while, and fork then PlantUML renders the diagram for you.

This matters because activity diagrams live inside your version control system alongside your code. When a process changes, you edit a text file and regenerate the image. No proprietary binary files. No "who has the latest version?" problems. If your team already uses sequence diagram syntax for UML, adding activity diagrams follows the same workflow.

How Do You Write a Basic Activity Diagram in PlantUML?

Every PlantUML activity diagram starts and ends with the same framing keywords. Here's the skeleton:

@startuml opens the diagram block
start marks the beginning of the activity flow
stop marks the end of the flow
@enduml closes the diagram block

Between start and stop, you describe each step as a plain-text action. PlantUML connects them automatically in the order you write them. A simple example looks like this:

@startuml
start
:Open the application;
:Log in with credentials;
:View the dashboard;
stop
@enduml

Each action is wrapped in colons and ends with a semicolon. That's the foundation everything else builds on.

How Do You Add Decision Points (If/Else) to an Activity Diagram?

Most real workflows branch. In PlantUML, you model branching with the if/then/else/endif keywords. The condition goes inside parentheses after if, and each branch leads to its own set of actions.

@startuml
start
:Enter payment details;
if (Is payment valid?) then (yes)
 :Process the order;
 :Send confirmation email;
else (no)
 :Display error message;
 :Prompt user to retry;
endif
stop
@enduml

You can nest if blocks inside each other for more complex logic. Just be careful to close each one with its matching endif. Mismatched blocks are the number one source of rendering errors in activity diagrams.

How Do You Model Loops in PlantUML Activity Diagrams?

Loops represent repeated actions. Use the while/endwhile keywords with a condition:

@startuml
start
:Read file line;
while (More lines?) is (yes)
 :Process current line;
 :Read next file line;
endwhile (no)
:Close the file;
stop
@enduml

PlantUML draws the loop with a recognizable back-arrow from endwhile back to while, so anyone reading the diagram immediately sees the repetition. This is especially useful for documenting batch processing or retry logic.

How Do You Show Parallel Activities With Fork and Join?

When two or more tasks happen at the same time, use fork/fork again/end fork. This creates parallel swim lanes in the diagram.

@startuml
start
:Receive order;
fork
 :Send to warehouse;
 :Pack items;
fork again
 :Generate invoice;
 :Email invoice to customer;
end fork
:Mark order as complete;
stop
@enduml

The end fork acts as a synchronization point both branches must finish before the flow continues. This is a standard UML concurrency pattern, and PlantUML renders it clearly with horizontal bars at the fork and join points.

What About Notes, Partitions, and Colors?

PlantUML supports several formatting options that make activity diagrams easier to read:

Notes attach a note to an action with the note right or note left keyword after a step
Partitions group related actions under a label with partition Name { }
Colors add color to an action by including a #colorname inside the action block

@startuml
start
partition "Authentication" {
 :Enter username;
 :Enter password;
 #lightgreen:Validate credentials;
}
note right: Uses OAuth 2.0
:Access dashboard;
stop
@enduml

Partitions are particularly helpful when documenting processes that span multiple teams or systems. They visually separate responsibility areas without needing separate diagrams.

What Are the Most Common Mistakes With PlantUML Activity Diagram Syntax?

Based on common forum questions and PlantUML issue reports, here are the errors people hit most often:

Missing semicolons every action and condition must end with a semicolon. Omitting one causes the parser to merge lines or throw errors.
Mismatched keywords every if needs an endif, every while needs an endwhile, every fork needs an end fork. Count your openers and closers.
Using old syntax older PlantUML versions used different keywords (like |swimlane|). The modern syntax uses partition. Make sure your PlantUML installation is up to date.
Confusing activity diagrams with state machines activity diagrams show workflow steps and decisions; state machine diagrams show object states and transitions. If you need the latter, check the state machine diagram syntax specification instead.
Overcomplicating a single diagram if your activity diagram has more than 20–25 steps, break it into sub-activities or use detach and kill to manage flow endpoints.

How Do You Reuse and Link Activity Diagrams Together?

PlantUML lets you include one diagram file inside another using the !include directive. This is useful for large systems where a high-level activity diagram references detailed sub-processes defined in separate files:

@startuml
start
:Receive customer request;
!include sub-processes/validate-request.puml
:Route to fulfillment;
stop
@enduml

You can also link a shape to another diagram or a URL using <a href="..."> inside an action block. This turns steps into clickable links when the diagram is rendered as SVG or HTML.

What Tips Help You Write Better PlantUML Activity Diagrams?

Start with a text outline of your process before writing syntax. List the steps, then identify where branches and loops happen.
Use meaningful labels on branches. Instead of just "yes"/"no," write "payment accepted" and "payment declined" so the diagram tells the full story.
Keep actions short. One sentence per action block. Long descriptions make diagrams unreadable at smaller render sizes.
Render often. Use the PlantUML online server to preview after every few changes. Catching a missing endif early saves time.
Version your diagram files in Git alongside the code they document. Diagrams that live in a shared drive get stale fast.

If your team also uses sequence diagrams for API interactions, the same PlantUML workflow applies you can find related syntax patterns in this sequence diagram reference guide.

Quick Reference: PlantUML Activity Diagram Keywords

start / stop begin and end the activity
:action; define a step
if (cond) then (label) else (label) endif branching
while (cond) is (label) endwhile (label) loops
fork / fork again / end fork parallel activities
partition "Name" { } group actions visually
note right / note left attach notes
detach end a branch without stopping the whole diagram
kill terminate a specific parallel branch
#color color an action node

PlantUML Activity Diagram Checklist Before You Ship

Does every if have a matching endif?
Does every while have a matching endwhile?
Does every fork have a matching end fork?
Is every action line wrapped in colons and ending with a semicolon?
Are branch labels descriptive enough to stand alone?
Have you rendered the diagram and checked it visually?
Is the diagram file committed to version control?

Run through this list each time you create or update an activity diagram. It takes 30 seconds and catches the vast majority of syntax errors before they reach a code review.