Foundation Series: How To Read a Formal Use Case

Use cases represent the activities that people do when interacting with a system to achieve their goals. Use cases are a very effective tool for communicating and documenting what a system is intended to accomplish. Formal use cases are use cases with a specific structure to represent the information. Knowing how to read a formal use case is important.

Formal Use Case

We wrote previously about formal use cases, covering the pros and cons with a brief overview, as part of our use case series. In this article, we focus on the elements of a formal use case, and how to interpret them.

When using a structured requirements approach to creating software, use cases represent the activities of classes of users, as they relate to the software being developed. Each goal, or market requirement, will have one or more use cases that support it. The easy way to think about it is that for a company to achieve a goal, someone has to do something (Make the Sale, Answer the Support Call, Update Account Information, etc). The use cases capture those somethings.
Here are the elements of a formal use case, with explanations:

Meta data

This is the information that identifies when the use case was first written and by whom. It may also include revision information, who made the changes, what was changed, and when and why it was changed. Revision history is a common meta data element in most business documents – we just normally don’t call it “meta data.” That’s an example of software jargon.

Title

The title of a use case is more than just a heading like “My Summer Vacation.” The title is intended to provide enough information to identify what the use case represents without reading the use case. This can be useful when getting an overview of a planned project, validating requirements, or when scanning use cases as part of reviewing materials. The title should provide enough information for someone conversant in the domain, while being short. The ideal length is between 4 and 8 words and is a sentance fragment. Anything longer than a sentance is a horrible title. The format is subject verb object. Someone does something to or with something else.
Some examples:

• Pilot performs pre-flight safety check.
• Author adjusts plot element timelines.
• Accountant reconciles accounts-receivable ledger.

Description

A brief description of the activity represented in the use case. One to five sentances – no more than a single paragraph – describing the activity or process represented by the use case. The description does not include the full details, but does provide the “next level of insight” into understanding what the use case covers. Someone who is not experienced in the domain can get a base understanding of the contents of the use case from reading a description.
Some examples:

• A pilot peforms an FAA mandated list of equipment and operational inspections prior to every flight. All inspections must pass before the flight is allowed to take off per corporate policy.
• An author will review the timelines, or sequences of events for each plot and subplot within their novel. The author is assuring that the sequence of intended events is internally consistent, and achieves the desired pacing effects for the book. Any needed changes to the timeline are made.
• Accountants regularly validate that the entries in the accounts-receivable ledger are consistent with the recent sales and current payments. This validation is required for all GAAP public reporting on a quarterly basis, and may be required more frequently for internal management accounting purposes.

Primary Actor

The primary actor is the person who is the subject of the use case, performing the verb of the use case on the object. A use case may have multiple actors but has one most important person. The term actor represents the person who takes action – not someone playing a role. Other actors may be involved, either as participants, or as infrequent or secondary performers of the use case.
Some examples:

• Primary Actor: Pilot. Secondary Actors:Flight Crew, Sr. Maintenance Technician
• Primary Actor: Author.
• Primary Actor: Financial Accountant. Secondary Actor: Financial Accounting Manager

Triggers

A trigger is the outside event that triggers the beginning of a use case. This is an event that initiates a use case. Many use cases do not have an obvious trigger – and the trigger will be documented as “User decides to do X.” This invisible decision represents the trigger.

Some examples:

• Pilot receives flight plan.
• Author initiates review of the novel.
• It is the first day of the last month of the quarter.

Preconditions

Preconditions are the set of things that must be true for the use case to occur. These represent a contract of sorts – the use case will not happen unless all of the preconditions are met. If a situation is optional, it is not a precondition.

Some examples:

• Flight plan has been approved.
• None. (In our example, the author can review timelines before during or after completing a draft of the novel.)
• Accounts receivable entries have been made in the ledger.

Post-conditions

Post-conditions represent the other side of the contract. If the normal course (see below) of the use case has been completed, then these things must be true.

Some examples:

• The plane has been confirmed to be safe and ready for the approved flight plan.
• The timeline is updated to reflect the author’s desired result.
• All accounting entries have been reconciled or identified as being incorrect.

Normal Course

The preferred, desired, or most common sequence of events that represent the use case. This sequence of events must be followable in the solution. If no alternate courses are defined, then this sequence of events must be followed (with no alternatives) in the solution. The normal course is documented as a series of single actor, single action sentences, each with a number.

An example:

1. Accountant accesses current quarter accounts-receivable ledger information.
2. Each of the following steps is repeated for every entry in the ledger.
3. Accountant confirms transaction record matches appropriate other ledger (sales, billing, etc).
4. Accountant updates ledger to indicate that the entry was confirmed.

Alternate Courses

Alternate course are supported alternatives to the normal course. Each variation is identified as an alternative, and each step that varies from the normal course will be explicitly defined within the alternative course. Each variant step is identified with a number, and all unidentified steps are explicitly defined to be the same as they are in the normal course.

An example:

A1: Incorrect ledger entry identified.

A1.3. Accountant confirms that the ledger record does not match the appropriate other ledger.

A1.4. Accountant updates ledger to reflect inconsistency.

A1.5. Accountant identifies proper value to reflect in the ledger.

A1.6. Accountant updates the ledger with the proper value.

A common naming convention is to begin the numbering with the letter “A” to represent that it is an alternate course, followed by a number indicating which alternative it is. In the example above, we have a single alternate course, “A1: Incorrect ledger entry identified”. In this example, steps 1 and 2 of the normal course are identical, steps 3 and 4 are replaced with new steps, and steps 5 and 6 have been added.

If another alternate course were defined, it would be numbered “A2”, and if it provided an alternate for step 3 in the normal course, that step would be numbered “A2.3.”

[Update]

Another situation that happens with alternate courses is that a single step in the normal course can be replaced with multiple steps in an alternate course. To represent this, we add a letter, denoting that the steps are all combined to replace a single step. In the example above, we replaced step 4 and added steps 5 and 6. An alternate course may also be documented as follows:

Another example:

A1: Incorrect ledger entry identified.

A1.3. Accountant confirms that the ledger record does not match the appropriate other ledger.

A1.4.a. Accountant updates ledger to reflect inconsistency.

A1.4.b. Accountant identifies proper value to reflect in the ledger.

A1.4.c. Accountant updates the ledger with the proper value.

Exception Courses

An exception course identifies how the system should behave when something goes wrong in the normal course (or an alternate course). If there are multiple exception behaviors, they will be called out as separate exception courses.

An example:

E1: Unable to access accounts receivable ledger

E1.1. Accountant fails to access accounts receivable ledger information.

E1.2. System presents error message to accountant explaining access failure and reported cause of failure.

An exception course is identified with the letter “E”, and otherwise follows the same numbering conventions as the alternate courses.

Includes

Sometimes use cases are broken down into smaller, reusable use cases (such as login steps, using a search window to find an account, etc). A reference to another use case from the includes section indicates that the referenced use case is a subset of this use case.

An example:

The use case of “Accountant Prepares Quarterly Report” could include the use case of “Accountant reconciles accounts-receivable ledger”.

References/Traces

Each use case is written to support one or more market requirements (goals). The specific goals that are being supported will be identified as references, or traces.

Each use case is also supported by one or more functional requirements. References or traces to each of these requirements will be identified in this section. These references allow product / program managers to understand the impacts of changes and delays in implementation on the overall product delivery schedule.

Assumptions

All assumptions that are implicit in the rest of the use case will be explicitly documented here.

Examples:

• Pilot is certified to run a safety-check.
• Airport allows pilot to run her own safety-check.

Notes

Any text that helps the author or potentially helps the reader is documented as notes. These are not requirements documented in the use case, any more than notes in the margin of a book are part of the book.

Conclusion

With this understanding, reading any formal use case will be a breeze.

– – –

Check out the index of the Foundation series posts for other introductory articles.