Use Cases
The Use Cases page of a project: how each actor reaches a goal with the system, with the actor, the goal, the trigger, the conditions before and after, the steps of the main flow and the alternate and exception flows that leave it, the review lifecycle and the versions.
By the end of this page you will have written down how each actor of a project reaches a goal with the system, step by step, as a use case a developer can build and a tester can walk; know every field a use case carries and what reads it downstream; and know how a use case moves from a draft to approved, how it is deleted, and where every version of it, steps included, is kept.
A use case is one journey through the system: Nadeesha, the returning shopper, redeems a
voucher at checkout. It names the persona who acts and anyone else in the room, the goal, what
triggers it, what must be true before the first step and after the last, how often it happens,
and the steps: what the actor does and what the system does in reply, in a main flow that
goes right from the trigger to the goal, with alternate flows (another way to the goal) and
exception flows (a failure the system must handle) that leave a numbered main step and carry
a label such as 2a. Use cases number on their own sequence (CRM-UC-4) and every save of one
is kept as a version, steps included. A
requirement says what the system shall do; a use case says
how a person gets something done with it, and the stories that cover a flow are drafted from its
steps once the inline assists land.
Before you begin
| You want to | You need |
|---|---|
| Open the Use Cases page | use-case:view-any on the project, which every default role carries. A client guest sees the agreed use cases only. |
| Add a use case | use-case:create. Project managers and business analysts have it by default. |
| Edit or move a use case | use-case:update. |
| Delete a use case | use-case:delete. |
| Name an actor | The persona to be on the project's persona list. |
The page lives under a project: open the project and choose Use Cases in the sidebar, badged with how many use cases you may see.
Read the use cases
The table lists one use case per row:
| Column | What it shows |
|---|---|
| Reference | The use case's key, such as CRM-UC-4. |
| Use Case | The title, with the goal beneath it. Press the title to open the detail flyout. |
| Actor | The persona who acts, or No actor named. |
| Status | Draft, in review, approved or deprecated, as a badge. Hidden from a guest. |
| Priority | The MoSCoW letter: M, S, C or W. |
| Steps | How many steps the use case carries, every flow counted. |
| Frequency | How often it happens, in the words the analyst wrote, or Not said. |
| Updated | How long ago the record last changed. |
| Row menu | View Use Case, Edit Use Case, Move to, Activity, Delete Use Case. |
Sort by reference, title, status, priority, frequency or updated by pressing a column heading; press it again to flip the direction. The list opens in the project's own order.
Above the table, narrow the list with the search box (words in the reference, the title or the goal), the status and priority lists and the actor list, which offers the project's personas. The filters travel in the page address, so a filtered list can be shared; Clear Filters on the empty state drops them all.
Add a use case
- Press New Use Case.
- Type the Title: a verb and a goal, such as Redeem a voucher at checkout. This alone is enough to save; Heimdall will propose the rest from a persona and a goal.
- Pick the Actor from the project's personas and the Priority, and name the Other Actors in the room, separated by commas.
- Write the Goal and the Trigger, each in one line.
- Under Before and after, write the Preconditions, the Postconditions and the Frequency.
- Under Steps, press Add Step once per step and type what the actor does and the
System response. A step of the main flow is numbered from one in the order it sits. For a
branch, change the flow to Alternate flow or Exception flow, type its Label (such as
2a) and say which main step it Leaves. - Press Create Use Case.
The use case takes the next number of the use cases' sequence (the first of CRM is
CRM-UC-1), starts as a draft, appears in the table at once, writes its first version with its
steps inside it, and use_case.created goes out to every endpoint subscribed to it.
Write the main flow first, then the branches
The main flow is the path where everything goes right, numbered one, two, three. Each thing that can go differently at a step is a branch that leaves that step: an alternate flow when the actor still reaches the goal another way, an exception flow when they do not. A branch that names no main step, or one the main flow does not have, is refused, so a flow never dangles.
Open a use case
Press a use case's title, or View Use Case in its row menu, to open the detail flyout: the reference, status and priority at the top, the title, then the actor and the other actors, the goal and the trigger, the preconditions and the postconditions, the steps with their numbers and labels (a branch says which flow it belongs to and which main step it leaves), the frequency and the dates, and the Versions section with every save of the use case. From the flyout:
- Edit opens the editor on this use case.
- Move to changes the status in one step, offering only the moves the lifecycle allows.
- Restore this version under any earlier version puts it back, steps included; see revisions and versions.
- Activity opens the use case's history: every change, who made it and where it came from.
- Delete opens the confirmation.
A link such as /projects/<id>/use-cases?show=<use case id> opens the page with that use case's
flyout already open; Heimdall's View buttons use it.
Edit a use case
- Press Edit Use Case in the row menu, or Edit in the flyout.
- Change what you need, the step rows included: Add Step appends a row, the arrows reorder the rows and the cross removes one. The actor must be a persona of the project, and every branch must name a main step the flow has.
- Press Save Changes.
The save writes a new version of the use case, steps included, and use_case.updated goes out
with the columns that changed, each with its old and new value. A save that changes only the
steps writes a version and announces nothing, since no column of the record moved. The status
does not change from the editor; it moves from the list or the flyout.
Move a use case along its lifecycle
A use case reaches In review and Approved through its approval alone: Submit for review on the approval bar puts it in review, and the approvers' verdicts move it out, to approved when the request carries and back to where it stood when it is rejected or withdrawn. Move to in the row menu or the flyout offers the other moves the lifecycle allows from where the use case stands, and is refused while a request is open:
| From | To |
|---|---|
| Draft | Deprecated |
| In review | Draft, deprecated |
| Approved | Draft, deprecated |
| Deprecated | Draft |
An approval stamps when the use case was agreed and at which version, and a client guest sees it
from that moment on and loses it when it is deprecated. Every move writes a version with the
reason moved and use_case.status_changed goes out with the status before and after; an
approval writes one with the reason approval.
Delete a use case
Delete Use Case in the row menu or Delete in the flyout opens the confirmation. Deleting
removes the use case with its steps, every version it kept and its activity history; its number
is never handed out again. use_case.deleted goes out. Prefer Deprecated for a use case the
client withdrew: it keeps the record and the flows.
All the fields
What happens next
- Every save, move and restore writes a version, steps included, and an entry in the project's activity history.
use_case.created,use_case.updated,use_case.status_changed,use_case.steps_changed,use_case.restoredanduse_case.deletedgo out to the webhook endpoints subscribed to theuse_case.*family.- Stories will be drafted one per flow from a use case's steps, requirements and test cases will link to use cases, and the context pack of a story will carry the steps it covers, as those modules land.
Heimdall on this page
Heimdall reads use cases and their versions through the same tools the MCP server offers, and carries the open project as its context.
On the editor, Ask Heimdall beside each long field drafts it, improves it, shortens it, makes it testable or rewrites it as Given, When, Then; the draft waits under the field until you take it or drop it. See inline assists.
The brief import will draft use cases with their flows into a review queue, and the inline assists will draft a story per flow from the steps.
From the API and MCP
Use Cases API
List, read, add, change, move and delete use cases, replace their steps, and read and restore their versions.
Planning tools
list_use_cases and get_use_case: the MCP tools that read use cases and their steps.
Permissions
| Action | Permission |
|---|---|
| See the use cases | use-case:view-any, use-case:view; a client guest sees the agreed use cases only |
| Add a use case | use-case:create |
| Edit or move a use case | use-case:update |
| Delete a use case | use-case:delete |
| Read or restore its versions | use-case:view to read, use-case:update to restore; never a client guest |
Frequently asked
Related
- Traceability — the Links panel in the flyout: what this implements, verifies, depends on or relates to, read from either side
- Comments and mentions — the Discussion panel in the flyout: questions, answers, mentions, followers
- Attachments — the Files panel in the flyout: wireframes, specifications and samples pinned on the record
- Personas — the people a use case is acted by
- Functional requirements — what the system shall do, which a use case walks through
- Revisions and versions — every save kept, any version put back
- Status reference — every flow, status and priority
use_case.*webhook events
How is this guide?
Last updated on
Brief import
Paste a brief, let Heimdall draft epics, stories, requirements, rules, terms, personas, risks and decisions from it, and accept, edit, merge or reject each suggestion from a review queue; nothing lands until you say so.
RAID Log
The RAID Log page of a project: risks scored by probability and impact with their mitigation and contingency, assumptions, issues and dependencies, each with its area, owner, dates and status, the risk matrix, the lifecycle and the versions.