If you've ever tried to map out a process or workflow visually, you know how quickly things get messy without the right notation. PlantUML activity diagrams let you express branching logic, parallel tasks, and decision flows in plain text no dragging boxes around. Having a solid code reference nearby means you spend less time guessing syntax and more time documenting how your system actually works.

What is a PlantUML activity diagram, and how does the code syntax work?

A PlantUML activity diagram describes the flow of actions in a process. You write simple text lines, and PlantUML renders them into a visual diagram. The basic structure starts with @startuml and ends with @enduml. Between those tags, you define activities, decisions, forks, joins, and transitions using short keywords.

Here's the simplest possible activity diagram:

@startuml
start
:Do something;
stop
@enduml

That code produces a single-action flowchart with a clear start and end point. Every activity is wrapped in colons and ends with a semicolon. This is the foundation everything else builds on it.

How do you add decisions and branching in PlantUML activity diagrams?

Decisions use the if/then/else/endif syntax. This mirrors how you'd write conditional logic in code, which makes it intuitive for developers.

if (Is it raining?) then (yes)
  :Bring umbrella;
else (no)
  :Wear sunglasses;
endif

You can nest conditions inside other conditions. You can also chain multiple branches by adding more elseif lines. Just remember: every if needs a matching endif, or PlantUML will throw an error.

A common mistake is forgetting the label text in parentheses after then or else. Without it, the diagram still renders, but the arrows won't have readable labels, which makes the flow harder to follow.

How do you show parallel activities with fork and join?

When two or more tasks happen at the same time, use fork, fork again, and end fork.

fork
  :Send email notification;
fork again
  :Log the event;
end fork

The fork block splits the flow into parallel branches. fork again adds each additional parallel path. end fork synchronizes them back together like a join bar in traditional UML. This is useful for modeling concurrent processes like sending a message while writing to a database.

What's the syntax for swimlanes in PlantUML activity diagrams?

Swimlanes group activities by the actor or system responsible. You define them with the |ActorName| syntax on its own line.

|Customer|
:Place order;
|System|
:Process payment;
:Send confirmation;

Each time you declare a new swimlane name, subsequent activities appear in that lane. This is especially helpful when documenting workflows that cross team boundaries for example, what the frontend does versus what the backend handles.

How do you add notes, colors, and styling to activity diagrams?

Notes attach extra context to an activity. You write them right after the activity line:

:Deploy to production;
note right: Requires approval from DevOps lead

For colors, you can prefix an activity with a color code:

#lightgreen:Approved;
#pink:Rejected;

This makes status-heavy diagrams like approval workflows much easier to scan. Use color sparingly though. Too many colors create noise instead of clarity.

How do you handle loops and repeated steps?

Loops use the while/endwhile syntax:

while (More items in cart?) is (yes)
  :Process next item;
endwhile (no)

The condition goes inside the first set of parentheses, and the exit label goes in the second. If you swap these or leave one out, the diagram may not render correctly. For a deeper look at different diagram notations, our UML diagram syntax cheatsheet for software architects covers multiple diagram types in one place.

What are the most common mistakes when writing PlantUML activity diagrams?

  • Missing semicolons. Every activity line must end with ;. Without it, PlantUML won't know where the activity text ends.
  • Unclosed blocks. Every if needs endif, every while needs endwhile, every fork needs end fork.
  • Overcomplicating one diagram. If your activity diagram has 40+ steps, break it into smaller linked diagrams. Referencing sub-activities keeps each diagram readable.
  • Ignoring swimlanes. Without them, a cross-team workflow looks like one actor does everything. Adding lanes clarifies ownership instantly.
  • Using vague activity names. "Do stuff" tells the reader nothing. Write "Validate user email address" instead.

How does this compare to other UML diagram types?

Activity diagrams focus on process flow the order of operations, decisions, and parallel tasks. If you need to show how objects communicate over time, a sequence diagram is a better fit. For a practical walkthrough of that, see our guide to sequence diagram notation examples for beginners.

If your goal is to map system modules and their connections rather than step-by-step workflows, reading component diagram connectors will be more relevant to what you're building.

Activity diagrams sit in the middle ground: they show behavior rather than structure. Use them when someone asks "what happens when a user clicks Submit?" and you need to answer with a visual.

What does a full real-world PlantUML activity diagram look like?

Here's a practical example for an e-commerce checkout flow:

@startuml
|Customer|
:Add items to cart;
:Click checkout;
|System|
:Validate cart contents;
if (Cart empty?) then (yes)
  :Show error message;
  stop
else (no)
  :Calculate total;
endif
:Request payment;
|Payment Gateway|
:Process transaction;
if (Payment successful?) then (yes)
  |System|
  :Send confirmation email;
  :Update inventory;
else (no)
  :Return error to user;
endif
stop
@enduml

This example combines swimlanes, decisions, and clear activity names. You can paste this directly into the official PlantUML online server to see the rendered output immediately.

Quick reference checklist for PlantUML activity diagram syntax

  • start / stop begin and end the flow
  • :Activity text; define an action (semicolon required)
  • if/then/else/endif branching decisions
  • while/endwhile loops
  • fork/fork again/end fork parallel activities
  • |LaneName| swimlane separation
  • #color: color-coded activities
  • note right/left attach context notes
  • @startuml / @enduml always wrap your diagram

Next step: Pick one real process from your current project a deployment pipeline, an onboarding flow, or a support ticket lifecycle and write it out in PlantUML using the syntax above. Start with the start/stop skeleton, add your activities, then layer in decisions and swimlanes. Keep it under 15 steps for your first version. You can always expand later.