Use Case Template: How I Write One on a Real Project

Contents hide

1 The Use Case Template Fields, and What Each One Is Actually Doing

2 A Real Example With the Friction Included

If you have been asked to document a system interaction and you are not sure how to structure it, a well-formed use case template will get you there faster than anything else. I have used the same core structure across projects in water licensing, hospital administration, university admissions, and environmental regulation. The format has stayed consistent not because I am attached to it, but because the same problems keep appearing when it is missing: ambiguity about who does what, alternate flows nobody thought to document, and steps written from the system’s perspective when they should be written from the user’s. Those problems are expensive to find in testing and even more expensive to find in production.

This article gives you the template, explains what each field is doing and why it belongs there, and walks through a real project example where the situation was anything but clean. If you are working in a waterfall or hybrid environment and need to hand developers something they can build from, this is the format that works.

The Use Case Template Fields, and What Each One Is Actually Doing

Each field in a use case serves a specific purpose. Here is what goes in each one and why it matters.

Use case name. A short verb-noun phrase describing the goal the actor is trying to achieve. “Submit claim” or “Reset password” are good examples. The name should make sense to a business stakeholder without explanation.
Use case ID. A unique identifier for traceability. I use a prefix connected to the relevant functional area, for example UC-PAY-001 for a payment use case. This matters when you need to link use cases to test cases or change requests in a requirements traceability matrix.
Actor. The person or system that initiates the interaction. Be specific about the role. “Claims officer” and “system administrator” are both more useful than “user” because they tell you something about the permissions and context involved.
Trigger. The event that causes this use case to begin. A trigger might be a user action, a system event, or a time-based condition. Being explicit about the trigger defines the boundary of the use case and prevents scope creep into adjacent interactions.
Preconditions. What must be true before the use case can begin. For example: the actor must be logged in, the account must be active, the relevant record must already exist. Preconditions stop you from having to document setup steps inside the use case itself.
Main flow. The sequence of numbered steps that describes the successful path. Written alternating between what the actor does and what the system does. Keep each step atomic: one action per step. If a step contains the word “and”, it probably needs to be split.
Alternate flows. Everything that can happen that is not the main flow. This is the section that gets skipped most often and causes the most problems later. An alternate flow is not an error. It is a legitimate variation: the book is unavailable, the payment method is declined, the user lacks the required permission. Each alternate flow should reference the step in the main flow where it branches off.
Exception flows. System errors, timeouts, and failure conditions. These are distinct from alternate flows because they represent failure states rather than variations. For example: the system fails to connect to the payment gateway and displays an error message with a reference number.
Postconditions. What is true once the use case has completed successfully. The record has been updated, the email has been sent, the account status has changed. Postconditions are valuable for testing because they define what a tester should verify after executing the use case.
Business rules. Constraints and policies that govern the interaction but do not belong inside the flow steps. Documenting business rules separately keeps the flow clean and makes the rules easier to find and maintain.

A Real Example With the Friction Included

On a programme I worked on for a government agency that managed environmental licences, I was asked to document the use cases for a new online licensing portal. One of the interactions was the submission of a licence variation request, where a licence holder could request a change to the conditions attached to their existing licence.

On the surface, this seemed straightforward. The licence holder logs in, selects their licence, submits a variation request, and the system routes it to an assessor. In practice it was considerably more complicated, and the complications only became visible once I started writing the use case properly.

The first issue was the trigger. The project team had been discussing this interaction as if there was one type of variation request. When I asked what event triggered the use case, the policy team gave me a different answer from the IT team. The policy team said a variation could be triggered by the licence holder, by a compliance event, or by a regulatory change. The IT team had only designed for licence holder-initiated requests. That discrepancy needed to be resolved before any use case could be written, and it took two weeks of back and forth to reach an agreed position.

The second issue was the alternate flows. The initial assumption was that a variation request would always go to a single assessor. When I asked what happened if the assessor was unavailable, there was no answer. When I asked what happened if the variation involved a condition requiring ministerial approval, there was no answer. When I asked what happened if the licence holder submitted a request for a licence already under compliance review, the policy team looked at each other across the table. None of these were edge cases. They were predictable scenarios that would occur regularly in practice. The alternate flows section forced them to the surface.

Here is what the completed use case looked like for the primary scenario, simplified for this article.

Field	Content
Use case name	Submit licence variation request
Use case ID	UC-LIC-007
Actor	Licence holder
Trigger	Licence holder selects “Submit variation request” from the licence management screen
Preconditions	Licence holder is authenticated. Licence is in Active status. Licence is not currently under compliance review.
Main flow	1. System displays variation request form with licence details pre-populated. 2. Licence holder selects the condition to be varied and enters the requested change. 3. Licence holder uploads supporting documentation if required. 4. Licence holder submits the request. 5. System validates the submission and assigns a reference number. 6. System routes the request to the designated assessor. 7. System sends confirmation to the licence holder with the reference number and expected timeframe.
Alternate flow A	At step 6: designated assessor is unavailable. System routes to the assessor’s nominated delegate. If no delegate is assigned, system routes to the team leader and sends an alert.
Alternate flow B	At step 2: requested variation involves a condition requiring ministerial approval. System flags the request for escalation. Assessor is notified that ministerial approval is required before assessment can proceed.
Exception flow	At step 5: system validation fails due to missing mandatory fields. System displays inline error messages identifying the missing fields. Licence holder corrects and resubmits.
Postconditions	Variation request is recorded with a unique reference number. Licence status is updated to “Variation pending”. Licence holder and assessor have both received notification.
Business rules	A variation request cannot be submitted for a licence under compliance review. Supporting documentation is mandatory for requests involving conditions in categories A and B. The assessor has 20 business days to complete the assessment from the date of submission.

The first draft of this use case had six alternate flows. After three review sessions with the policy team and two with the IT team, the final version had fourteen. That gap between the first draft and the final version represents real risk that would otherwise have been discovered in user acceptance testing or after go-live.

Use Case vs User Story vs Process Map

These three tools are complementary rather than competing. Understanding when to reach for each one is part of knowing how to apply the use case template well.

Tool	What it documents	Best suited to	Level of detail
Use case	How a specific actor interacts with a system to achieve a goal, including variations and exceptions	Complex interactions, waterfall and hybrid projects, system documentation	High
User story	What a user wants to achieve and why, in a single sentence	Agile delivery, sprint planning, backlog management	Low to medium
Process map	The end-to-end flow of a business process across people, systems, and time	Current state analysis, process improvement, training documentation	Medium to high

On most complex projects I use all three. Process maps to understand the current state, use cases to document system interactions in the future state, and user stories and acceptance criteria to feed the development backlog. Even on agile projects I reach for use cases when a particular interaction is complex enough that a user story does not capture the full picture. They sit alongside user stories well when used selectively. For a broader view of where use cases sit within the full set of BA artefacts, the article on business analyst deliverables in waterfall covers the complete picture.

The Mistakes I See Most Often

Writing from the system’s perspective throughout. A use case should alternate between what the actor does and what the system does. When every step starts with “System”, you have lost the user’s perspective and the document becomes a functional specification rather than a requirements artefact.
Skipping the alternate flows. This is the most common and most costly mistake. The main flow describes what you hope will happen. The alternate flows describe what actually happens. If you only document the main flow, you are capturing roughly 40 percent of the real interaction on a complex system.
Using vague language in the steps. Steps like “System processes the request” or “User completes the form” tell you nothing useful. Every step should be specific enough that a developer knows what to build and a tester knows what to verify.
Conflating preconditions with main flow steps. If a step in your main flow says “User logs in”, that is almost certainly a precondition rather than a step in this use case. Keep the use case focused on the interaction you are documenting and push setup conditions into the preconditions field.
Not reviewing with stakeholders. A use case written in isolation and never validated with the people who do the work will contain assumptions that are wrong. The alternate flows only became complete on the licensing project after multiple review sessions. The first draft was not the real picture.

The use case template is the right tool when you need to be precise about what a system must do in response to a specific user action, when you need to document what happens when things do not go as expected, and when you need a format that can be handed to a developer and used directly as a specification. Getting the alternate flows right is not optional work you do if there is time left over. It is the point of the whole exercise, and it is where the real value of the template lives.

Frequently asked questions

What is a use case template used for?

A use case template provides a structured format for documenting how a specific user interacts with a system to achieve a goal. It captures the main flow of the interaction, variations, exceptions, preconditions, and postconditions. It is used to ensure that all stakeholders have a shared, unambiguous understanding of what the system needs to do.

What is the difference between a use case and a user story?

A user story describes what a user wants to achieve and why, in a single sentence. A use case describes the full sequence of interactions between a user and a system required to achieve that goal, including what happens when things go wrong. User stories are suited to agile delivery, while use cases are suited to more detailed, structured requirements documentation.

How detailed should a use case be?

Detailed enough that a developer can build from it and a tester can verify against it without needing to ask clarifying questions. Each step should describe a single, specific action, and alternate flows should cover every realistic variation from the main path. Business rules should be documented separately from the flow steps to keep the use case readable.

What is an alternate flow in a use case?

An alternate flow documents a variation from the main flow that is not a system error. It is a legitimate path through the interaction that occurs under specific conditions, such as when a payment method is declined or a required approver is unavailable. Alternate flows are distinct from exception flows, which document system errors and failure states.

Can use cases be used in agile projects?

Yes, selectively. Use cases are most useful in agile projects when a particular interaction is complex enough that a user story does not capture the full picture, such as interactions with multiple actors, significant alternate flows, or strict compliance requirements. They should not replace user stories as the primary backlog format in a fast-moving agile team.

Try Ash, Your Virtual BA

If you have written your use cases and now need to capture the full functional scope in a structured requirements document, Ash is the logical next step. Ash works through 15 categories of requirements with you, asks the questions a senior BA would ask, and produces a Business Requirements Document you can download as a Word file. It takes the system interactions you have documented in your use cases and turns them into a complete requirements baseline. Try Ash Virtual BA.