Use Case Description Template in Confluence (Actors, Flows, Exceptions)
Write a use case description on one Confluence page: actors, preconditions, the main flow as numbered steps, alternate flows, exceptions and postconditions. Build it once and copy it for every new use case.
Step by step
Use case description
- Use case template. A use case diagram shows who does what. The description explains how it happens, step by step, and what can go wrong. Here we build one on a single Confluence page that you can reuse.
The page
- New page. Open the business requirements page and click Create, then pick Page. Name it after the use case, with a verb and a noun: Use case - Place an order. Press Enter to move from the title into the page body.
The sections
- Actors. Type ## and a space to make a heading, then Actors. The primary actor starts the use case: Shopper. A supporting actor helps along the way: Payment provider.
- Preconditions. Add a ## Preconditions heading for what must already be true before the use case starts: The shopper is signed in and has items in the basket.
- Main flow. Add ## Main flow, the happy path. Type 1. and a space to start a numbered list. Then write one step per line, the actor and then the system, from Shopper clicks checkout to System confirms the order and sends an email. Confluence numbers the 4 lines for you. Press Enter twice to end the list.
- Alternate flows. Add ## Alternate flows: other ways to reach the same goal. Number each one after the step it branches from: 3a. Shopper pays with a gift card. The flow goes on at step 4.
- Exceptions. Add ## Exceptions: what goes wrong, and what the system does about it: 3b. The card is declined. The system keeps the basket and asks for another card.
- Postconditions. Last, add ## Postconditions: what is true when the use case ends well. The order is saved and the stock goes down.
Publish
- Publish. Click Publish, then click Publish again to confirm. The page is published. Click Dismiss to close the message so it doesn't cover the page.
Read it back
- Main flow. Read back, the main flow tells a story, and each numbered step is something a tester can check.
- Exceptions. Because it is numbered 3b, the exception points back to step 3, so developers know exactly where to handle it.
Recap
- Actors, flows, exceptions. One page per use case: actors, preconditions, a numbered main flow, alternate flows and exceptions tied to a step, then postconditions. Copy the page to start your next use case.
Common mistakes
- Step labels that no longer match. If you add a step, Confluence renumbers the main flow list, but labels you typed yourself, like 3a and 3b, stay the same. After you edit the main flow, check that every alternate flow and exception still points at the right step.
- Putting problems inside the main flow. A line like "If the card is declined..." in the main flow muddies the happy path. Keep the main flow for success only, and move each problem to Exceptions with its step number, like 3b.
- Writing preconditions as steps. "Shopper signs in" is something that happens, not something already true. Write a precondition as a state, like The shopper is signed in. If signing in is part of the use case, put it in the main flow.
- Not ending the numbered list. If you don't press Enter twice after the last main flow step, the next lines become step 5 and onwards. End the list before you add the Alternate flows heading.
When a business analyst uses this
On a checkout redesign, a business analyst writes one Confluence page per use case next to the business requirements and walks through the main flow and exceptions with stakeholders in a workshop. Testers then turn each numbered step and exception, like 3b, into test cases before sign-off.
Questions people ask
What is the difference between an alternate flow and an exception in a use case?
An alternate flow is another way to reach the same goal, like paying with a gift card. An exception is when something goes wrong, like a declined card, and it says what the system does about it.
What are preconditions and postconditions in a use case?
Preconditions are what must already be true before the use case starts, like the shopper being signed in with items in the basket. Postconditions are what is true when it ends well, like the order being saved and the stock going down.
How do you make a heading in Confluence by typing?
In the Confluence Cloud editor, type ## and a space at the start of a line to get a heading. Typing 1. and a space starts a numbered list.
