If you've ever tried to explain a workflow or process to a teammate and words just weren't enough, you already know why activity diagrams matter. They turn complex steps into clear, visual flows. And PlantUML lets you build them using plain text no dragging boxes around, no expensive software. A few lines of code, and you've got a diagram that anyone on your team can read, edit, or version-control alongside your source code.

This guide walks you through real PlantUML code examples for activity diagrams, from basic syntax to advanced branching and parallel tasks. You'll see exactly what the code looks like and what it produces, so you can copy, paste, and adapt it for your own projects.

What Is a PlantUML Activity Diagram?

An activity diagram in PlantUML is a text-based diagram that shows the flow of actions in a process. Think of it like a flowchart, but with more features including decision points, parallel actions, swimlanes, and signal handling. PlantUML reads your plain-text code and renders it as a visual diagram.

The key advantage here is that your diagram lives as code. You can store it in Git, review changes in pull requests, and generate diagrams automatically in your CI pipeline. If you're already using PlantUML for other diagram types, the activity diagram syntax will feel familiar. If you're just getting started, check out our PlantUML code examples collection for broader context.

How Do You Write a Basic Activity Diagram in PlantUML?

The simplest activity diagram starts with the @startuml tag, defines a start point, lists your actions, and ends with a stop point. Here's a minimal example:

@startuml
start
:Wake up;
:Brush teeth;
:Eat breakfast;
:Commute to work;
stop
@enduml

Each action is wrapped in colons and ends with a semicolon. The start and stop keywords create the standard filled circle and bullseye symbols you'd see in UML notation.

What About Adding Conditions and Branches?

Most real workflows involve decisions. In PlantUML, you use the if/then/else syntax to create branches:

@startuml
start
:Is it raining?;
if (yes) then
 :Take umbrella;
else (no)
 :Wear sunglasses;
endif
:Leave the house;
stop
@enduml

You can nest conditions too, though readability drops fast. If you find yourself nesting three or four levels deep, consider breaking the process into sub-diagrams or simplifying the logic.

How Do You Show Parallel Actions in PlantUML?

Activity diagrams support fork and join bars those thick horizontal lines that show multiple actions happening at the same time. In PlantUML, you use fork, fork again, and end fork:

@startuml
start
:Receive order;
fork
 :Process payment;
fork again
 :Prepare shipping label;
fork again
 :Pick items from warehouse;
end fork
:Ship package;
stop
@enduml

This is useful for modeling concurrent tasks in a business workflow. The diagram will render a horizontal bar where the fork splits and another where it joins back together.

How Do You Add Swimlanes to Separate Responsibilities?

Swimlanes divide your diagram into lanes, each representing a different actor or team. You define them by placing lane names before the actions that belong to each lane:

@startuml
|#AntiqueWhite|Customer|
|#LightBlue|System|
|#PaleGreen|Warehouse|

|Customer|
start
:Place order online;

|System|
:Validate order;
:Send confirmation email;

|Warehouse|
:Pick items;
:Pack box;
:Hand to courier;

|System|
:Send tracking number;

|Customer|
:Receive package;
stop
@enduml

Each |LaneName| declaration switches the context. All actions after it belong to that lane until you switch again. Colors are optional but make the diagram much easier to scan.

How Do You Handle Loops and Repeated Steps?

When a process repeats, use the while keyword:

@startuml
start
:Check inbox;
while (New messages?) is (yes)
 :Read message;
 :Reply or archive;
endwhile (no)
:Close email;
stop
@enduml

The text after while becomes the condition label, and the text after is or endwhile becomes the label on the arrows. Make sure the loop has a clear exit condition otherwise, you'll confuse anyone reading the diagram.

Can You Group Actions or Add Notes?

Yes. You can attach notes to specific actions and group related steps into sections:

@startuml
start
:Initialize database connection;
note right: Use connection pooling for performance

partition "Data Migration" {
 :Read legacy records;
 :Transform format;
 :Insert into new database;
}

:Verify migration count;
stop
@enduml

Notes use note right, note left, or note over. The partition keyword wraps related steps in a labeled box, which helps when your diagram grows large.

What Are Common Mistakes When Writing Activity Diagrams?

  • Missing semicolons. Every action line must end with a semicolon. Skip one, and PlantUML may throw an error or render the diagram incorrectly.
  • Unmatched fork/end fork blocks. Every fork needs a closing end fork. Mismatched blocks produce broken diagrams.
  • Overly long diagrams. If your activity diagram has 30+ steps, readers will lose track. Break it into smaller diagrams or use partition blocks to add structure.
  • Forgetting the start/stop keywords. Without them, your diagram renders without entry and exit points, which makes it incomplete by UML standards.
  • Confusing activity diagrams with sequence diagrams. Activity diagrams show workflow steps. If you need to show object interactions over time, a sequence diagram is more appropriate. For class-level relationships, see our class diagram syntax guide.

How Do Activity Diagrams Compare to State Diagrams?

Activity diagrams focus on what happens step by step in a process. State diagrams focus on the states an object goes through and what triggers transitions between them. They serve different purposes, though both use flow-like visuals.

Use an activity diagram when you want to show a workflow like an order fulfillment process or a user registration flow. Use a state diagram when you want to show the lifecycle of an object like an order moving from "placed" to "shipped" to "delivered." You can explore state diagram syntax in our state machine diagram guide.

What Are the Best Tips for Clean Activity Diagrams?

  1. Keep action labels short. Three to six words is ideal. Long sentences clutter the diagram fast.
  2. Use consistent naming. If one step says "Submit form," don't switch to "User submits the form" elsewhere.
  3. Color-code swimlanes. It takes one extra line per lane and makes the diagram significantly easier to read.
  4. Version-control your .puml files. Store them alongside your source code so changes to the process are tracked together.
  5. Render frequently. Use the PlantUML online server or a local PlantUML installation to check your output as you write.
  6. Use partition for long workflows. It groups related steps and gives readers visual anchors.

Practical Checklist Before You Share Your Diagram

  • ✅ Start and stop nodes are present
  • ✅ Every action line ends with a semicolon
  • ✅ Decision branches cover all outcomes (not just "yes")
  • ✅ Fork/join blocks are properly matched
  • ✅ Swimlane assignments are correct (the right team owns each step)
  • ✅ Diagram has been rendered and reviewed visually
  • ✅ File is saved as .puml and committed to version control
  • ✅ Labels are concise and consistent

Next step: Pick one real workflow from your current project even a simple one like "how we deploy to production" and model it in PlantUML this week. Start with the basic start-action-stop structure, add one decision branch, and share it with your team for feedback. Real diagrams improve real processes; perfect diagrams that never get written don't help anyone.