How to Draw an Activity Diagram Using Plantuml Syntax,

If you've ever needed to show how a process flows step by step, with decisions and parallel tasks an activity diagram is one of the clearest ways to do it. And PlantUML lets you create these diagrams using plain text, so you can version-control them, share them in code reviews, and generate visuals without dragging boxes around in a drawing tool. Learning how to draw an activity diagram using PlantUML syntax saves time, keeps your documentation consistent, and makes your process logic readable to anyone on your team.

What is a PlantUML activity diagram?

A PlantUML activity diagram is a UML diagram rendered from text-based code. Instead of using a visual editor like Lucidchart or draw.io, you write simple syntax that describes each step, decision point, and flow of a process. PlantUML then converts that text into an image showing the diagram.

Activity diagrams are used to model workflows, business processes, algorithms, and user journeys. They show the sequence of actions, branching conditions, and concurrency all in a format that's easy to read and maintain.

How do you write a basic activity diagram in PlantUML?

You start with the @startuml and @enduml tags. Between them, you describe the flow using arrows to connect activities. Here's a simple example:

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

Each line with colons represents an activity or action. The start and stop keywords mark the beginning and end of the flow. Arrows (-->) are added automatically between sequential activities, but you can also define them explicitly.

A note on the new syntax vs. the legacy syntax

PlantUML supports two styles for activity diagrams. The "new" syntax (sometimes called the activity-beta syntax) uses keywords like if, else, while, fork, and partition. The older syntax used different notation. Most current tutorials and tools use the new syntax, which is what this article covers. If you see diagrams with |swimlane| or different arrow notation, that's the legacy style.

How do you add decisions and branching?

Most real processes have conditions. In PlantUML, you use the if keyword followed by a condition, then then and else branches. Here's how it looks:

@startuml
start
:Enter payment details;
if (Payment valid?) then (yes)
:Process order;
else (no)
:Show error message;
endif
stop
@enduml

You can nest if statements to handle more complex decision trees. Just make sure each if has a matching endif.

How do you model parallel activities or concurrent flows?

When two or more things happen at the same time, you use fork and fork again. This creates a fork bar (a thick horizontal line) that splits the flow into parallel branches, and an end fork bar that joins them back together.

@startuml
start
:Receive order;
fork
  :Send confirmation email;
fork again
  :Update inventory;
fork again
  :Notify warehouse;
end fork
:Mark order as processed;
stop
@enduml

This is useful for modeling real-world workflows where multiple teams or systems act simultaneously after a trigger event.

How do you add swimlanes or partitions?

Swimlanes group activities by the actor, team, or system responsible for them. In PlantUML, you use the partition keyword:

@startuml
start
partition "Customer" {
  :Browse products;
  :Add item to cart;
}
partition "Payment System" {
  :Process payment;
}
partition "Warehouse" {
  :Pick and pack item;
}
stop
@enduml

This makes it immediately clear who is responsible for each step, which is especially helpful in DevOps pipeline documentation and cross-functional process maps.

How do you add loops and repeat logic?

For activities that repeat until a condition is met, PlantUML provides while and repeat keywords:

while (More items to process?) is (yes)
:Process next item;
endwhile (no)

Or using repeat for do-while style loops:

repeat
:Attempt connection;
repeat while (Connected?) is (no) not (yes)

Loops come up often in batch processing, retry logic, and polling workflows.

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

Missing semicolons after activity text. Every :action; needs a semicolon at the end. Without it, PlantUML will throw a syntax error or render something unexpected.
Forgetting endif or endwhile. Every conditional or loop block must be closed. Unclosed blocks will break your diagram.
Using the wrong arrow syntax. In the new activity diagram syntax, you typically don't need manual arrows between sequential steps. Adding --> unnecessarily creates disconnected nodes.
Mixing legacy and new syntax. Combining the two styles in one diagram leads to rendering errors. Pick one and stick with it.
Not using start and stop. While PlantUML can infer the flow without them, including them makes the diagram easier to follow, especially for longer workflows.

Can you add notes, colors, and styling?

Yes. Notes give context to individual steps, and styling makes diagrams easier to scan. Here are a few examples:

Notes: :Verify identity; | note right: Check against government database
Colors: You can set colors on partitions or individual activities using skin parameters like skinparam activityBackgroundColor #f0f0f0.
Stereotypes: Use stereotypes like :<font color=red>Critical error; to highlight specific steps.

For styling your other UML diagrams with similar techniques, see our PlantUML state machine diagram cheatsheet.

When should you use an activity diagram instead of other UML diagrams?

Activity diagrams are best for showing how a process flows the order of actions, conditions, loops, and parallel work. If you need to show system structure or component relationships instead, a class diagram for microservices architecture or a component diagram would be more appropriate.

Use activity diagrams when you need to:

Document a business workflow or user journey
Visualize an algorithm's logic before coding
Describe a deployment or release process
Map out error handling and retry flows in a system
Communicate process logic to non-technical stakeholders

How do you render your PlantUML activity diagram?

Once you've written your syntax, you need a way to render it. Common options include:

PlantUML Online Server: Paste your code at the official PlantUML server and get an instant image.
VS Code extensions: The PlantUML extension for VS Code previews diagrams in real time as you type.
IntelliJ IDEA plugin: JetBrains IDEs have PlantUML integration for inline diagram previews.
Command line: Run java -jar plantuml.jar diagram.puml to generate PNG or SVG files.
CI/CD pipelines: Include PlantUML rendering in your build process to keep diagrams updated with code changes.

Quick reference: PlantUML activity diagram syntax cheat sheet

start / stop Begin and end the flow
:Action text; Define an activity
if (condition?) then (yes) / else (no) / endif Branching
while (condition?) is (yes) / endwhile (no) While loops
repeat / repeat while Do-while loops
fork / fork again / end fork Parallel activities
partition "Name" { } Swimlanes
note right/left: Text Annotations
|lane name| Alternative swimlane syntax (legacy)

Practical next step: build your first activity diagram today

Try this checklist to get started:

Pick a real process you're working on even something simple like your team's code review workflow.
Write out the steps in plain language first, noting any decisions or parallel work.
Open the PlantUML online server in your browser.
Translate each step into PlantUML syntax using the examples above.
Render the diagram, check for errors, and refine the layout.
Share the .puml source file with your team not just the image so others can maintain it.

Start with the simplest version that communicates the process. You can always add swimlanes, notes, and styling later once the core flow is correct. The biggest productivity gain from PlantUML activity diagrams isn't prettier pictures it's keeping your process documentation in sync with your code.