Ask three people how an order moves through your company and you may get three answers. One says the invoice goes out before packing, another says after shipping, and nobody knows what happens when an item is out of stock. A whiteboard flowchart helps until two things happen at once and the arrows suggest an order that does not exist.
A UML activity diagram is made for this: steps, decisions, parallel work, and who does each part. This post builds one order fulfillment example piece by piece, with a symbol cheat sheet, the token rules behind it, common mistakes, and how activity diagrams compare with flowcharts, BPMN and state diagrams.
What an activity diagram shows
An activity diagram shows a behavior as actions connected by flows. The rules come from the UML 2.5.1 specification, published by the Object Management Group (OMG) in December 2017 and still the current formal version at the time of writing (November 2026). Clause 15 (Activities) and Clause 16 (Actions) define the notation.
Use one when the order of work is the question: a business process that crosses teams, the scenario behind a use case, or a pipeline with branches and parallel stages. Use a state machine when the question is which state an order is in, a sequence diagram when it is which service calls which, and a class diagram when it is how the data is structured.
Activity diagram symbols
UML reuses two shapes for four control nodes: decision and merge are both diamonds, and fork and join are both bars. Count the flows going in and out to tell them apart.
| Symbol | Looks like | What it means |
|---|---|---|
| Initial node | Small filled circle | Where the flow starts |
| Action | Rounded rectangle with a verb phrase | One step of work |
| Control flow | Arrow, optionally with a [guard] | Order of execution |
| Decision node | Diamond, one flow in, several out | Sends each token one way, chosen by guards |
| Merge node | Diamond, several flows in, one out | Combines alternative paths without waiting |
| Fork node | Bar, one flow in, several out | Starts all outgoing flows concurrently |
| Join node | Bar, several flows in, one out | Waits for every incoming flow, then continues |
| Activity final | Bull's eye: filled circle inside a ring | Ends the whole activity |
| Flow final | Circle with an X | Ends only the flow that reaches it |
| Object node | Rectangle with a noun, or a pin on an action | Data passed between actions |
| Partition | Lane named at one end | Groups one participant's actions |
In the specification, fork and join are "simply a line segment"; tools thicken it into a bar. The specification also notes that partitions are "colloquially known as" swimlanes.
How tokens move through the diagram
UML defines these symbols with tokens, like pieces on a game board. When the activity starts, one control token sits on the initial node. An action runs once every incoming flow offers it a token, then offers a token on every outgoing flow. A decision sends each token down at most one outgoing flow, the one whose guard is true; a merge passes every token straight through; a fork copies the token onto all outgoing flows; a join waits until each incoming flow offers a token, then emits one. The first token to reach an activity final node ends the activity, including anything still running.
Two consequences surprise people who learned flowcharts first:
- Two arrows into an action mean wait for both, an implicit join. If the arrows come from the two branches of a decision, only one ever carries a token, and the action never starts. Alternative paths must meet at a merge first.
- Two arrows out of an action mean do both, an implicit fork. It is legal, but readers miss it; draw a fork bar instead.
Building the example step by step
- Draw the partitions first: Customer, Warehouse and Billing. Lanes force the ownership questions early.
- Start the flow. An initial node in the Customer lane leads to Place order.
- Add the decision. In the Warehouse lane, a decision checks stock, with the guards [in stock] and [out of stock]. Guards should exclude each other and cover every case; UML's predefined [else] guard catches the rest.
- Merge the paths. Out-of-stock orders go through Backorder items, then both paths meet at a merge. The merge is required: a fork accepts exactly one incoming flow, and an action with two incoming flows would wait for both.
- Fork the parallel work. A fork bar starts Pack items (Warehouse) and Create invoice (Billing). Concurrent means neither waits for the other, not that they run at the same moment.
- Join before shipping. A join bar waits until both have finished; only then does Ship order run.
- End the activity. An activity final node follows Ship order. Control nodes are not work, so they can sit in any lane; this one sits in the Customer lane, right above Ship order.
In PlantUML, the same flow is plain text: |Customer| for lanes, if, else and endif for decisions, and fork, fork again and end fork for parallel work. The layout is automatic, so you trade control for speed.
Common mistakes
| Mistake | What goes wrong | Fix |
|---|---|---|
| A fork without a join | The first branch to reach the activity final ends the activity and stops the other | Join the branches, or end each one with a flow final |
| A decision for parallel work | Only one branch ever runs | Use a fork bar |
| A merge where you need a join | The next action can run twice, once per token | Use a join bar |
| A join after a decision | Only one branch carries a token, so the join waits forever | Use a merge diamond |
| Unlabeled or overlapping guards | Readers guess; UML leaves the order of guard evaluation undefined | Guards that exclude each other, plus [else] |
| Vague action names | Processing says nothing about the work | A verb and an object: Pack items |
The third and fourth rows are mirror images: a merge never waits, and a join can wait forever. Before you share a diagram, trace one token through every branch.
Activity diagrams, flowcharts, BPMN and state diagrams
| Activity diagram | Flowchart | BPMN | State machine diagram | |
|---|---|---|---|---|
| Shows | Steps of one behavior, with data and parallel work | Steps and decisions | Processes between participants, with events and messages | One object's states and the events that change them |
| Parallel work | Fork and join bars | No symbol in the everyday set | Parallel gateway | Orthogonal regions |
| Who does what | Partitions (swimlanes) | Lanes in cross-functional flowcharts | Pools and lanes | Not shown |
| Standard | UML 2.5.1 (OMG) | ISO 5807 (1985), loosely followed | BPMN 2.0.2 (OMG) | UML 2.5.1 (OMG) |
| Best for | Software behavior, use case flows, pipelines | Quick sketches for any audience | Process automation, flows between organizations | Order or subscription lifecycles |
Activity diagrams and BPMN are cousins: both define behavior with tokens, and BPMN 2.0.2 also specifies execution semantics for process engines. Choose BPMN for executable processes and messages between organizations (see the BPMN diagram example), a state machine for one object's lifecycle (see the state diagram example), a flowchart for readers who will never learn UML, and an activity diagram when parallel work and precise meaning matter.
The order fulfillment activity diagram
Diagram contents
- Customer
- Warehouse
- Billing
- Place order
- In stock?
- Backorder items
- Pack items
- Ship order
- Create invoice
- [in stock]
- [out of stock]
How to read it:
- Three swimlanes: Customer, Warehouse and Billing, each holding its own actions.
- Start at the filled circle: the customer places the order, and the flow drops into the Warehouse lane.
- The decision In stock? has two guarded exits: [in stock] runs to the merge, [out of stock] detours through Backorder items in orange. The Y and N marks are the editor's built-in exit markers; the guards carry the UML meaning.
- The small diamond is the merge where both paths rejoin.
- The first bar is the fork that starts Pack items and Create invoice; the second is the join that makes Ship order wait for both.
- The bull's eye above Ship order ends the activity, and the table below the lanes repeats each control node's token rule.
Drawing activity diagrams clearly
- Pick one direction. Horizontal lanes flowing left to right suit wide pages; vertical lanes flowing down suit long processes.
- Name actions with a verb and an object: Pack items, Create invoice. An action that needs a paragraph is a sub-activity; draw it as a call behavior action, marked with UML's small rake symbol, and detail it on its own diagram.
- Put guards on the flows. A question inside the diamond helps readers, but the bracketed guards carry the meaning.
- Draw every merge and join. Implicit joins and forks are legal but invisible.
- Keep lanes few. Three to five stay readable; at eight, split the process.
- Leave out what does not change the flow, such as logging or retries inside a step, and add object nodes only when the data matters.
For lanes without the rest of UML, see the swimlane diagram example.
Build it in Archboard
- Sign in with Google or GitHub and create a diagram.
- Add three Frame nodes from the Core pack as horizontal lanes: Customer, Warehouse and Billing.
- Add a small Ellipse Shape from the Core pack with a dark fill as the initial node.
- Add five Process nodes from the Flowchart pack in their lanes: Place order, Backorder items, Pack items, Create invoice and Ship order.
- Add a Decision node from the Flowchart pack labeled In stock?, and a small Diamond Shape from the Core pack for the merge. Label the exits [in stock] and [out of stock].
- For the fork and join, add two thin, tall Square Shape nodes from the Core pack with a dark fill.
- For the activity final, add an Icon from the Core pack with the record-circle-outline icon, a dot inside a ring.
- Connect the nodes, then add two Core Text annotations and a Markdown block from the Core pack with the legend table.
If the flow exists as a Mermaid flowchart, the Mermaid to diagram tool gives you an editable first draft to refine with these nodes. For a plain flowchart with lanes, start with the flowchart maker.
The example uses 15 diagram nodes, within the Free plan's limit of 15 per diagram.
FAQ
What is an activity diagram in UML? A behavior diagram that shows a process as actions connected by flows, with decisions, fork and join for parallel work, and swimlanes for who does what. UML 2.5.1 defines it in Clause 15.
What is the difference between a fork and a decision? A decision sends each token down only one outgoing flow, chosen by guards. A fork sends a copy down every outgoing flow, so the branches run concurrently. Decisions are diamonds; forks are bars.
What is the difference between an activity final and a flow final node? An activity final, a bull's eye, ends the whole activity and every flow in it. A flow final, a circle with an X, ends only the flow that reaches it.
How do swimlanes work in an activity diagram? Swimlanes are UML activity partitions. Each lane groups the actions of one person, team or system; flows cross lanes freely, and lanes do not change how tokens move.
Is an activity diagram the same as a flowchart? No, though they look alike. Activity diagrams add fork and join, object nodes for data, partitions, and token rules that give every symbol a precise meaning.