Use cases

What is a use case?

Use case is a format for specifying behavior of a system by describing interactions of actors with it (or within it).

A system is any entity that exhibits behavior. It could be a computer application, an organization or an application component.

Actors are the interacting entities. Actors include:

A use case describes the behavior of the system in reaction to a request of an actor (the primary actor). Primary actor invokes the use case to achieve a certain goal. The system reacts to the request, delivering the goal to the primary actor, while protecting the interests of all the stakeholders.

A stakeholder is someone with vested interest in the system. It might be an actor, or someone not directly interacting with the system yet still indirectly influenced by actions of the system.

Depending on the request of the primary actor and other factors the system may respond in different ways, the use case describes all these possible scenarios. The main success scenario describes the typical successful interaction. Variations are then described as extensions to the main success scenario.

Example: Sample use case
Transfer funds in local currency
Primary actor: Teller
Main success scenario:
  1. 1. User identifies debit account.
  2. 2. User identifies credit account.
  3. 3. User enters amount.
  4. 4. System calculates fee.
  5. 5. User confirms the transaction.
  6. 6. System verifies the transaction.
  7. 7. System transfers the amount from debit account to credit account.
  8. 8. System transfers the fee from debit account to fee account.
Extensions:
  • 3a. The amount is above transfer purpose limit 1000:
  •   3a1. User is required to enter transfer purpose.
  • 6a. The debit account available balance is less than amount + fee:
  •   6a1. System displays error "Insufficient funds on debit account." and continues to step 1.

Types of documentation

Specify the type of documentation you write. It is usually one of the following types: business process documentation, functional specification, design documentation.

Business process documentation

Business process describes the activities carried out within the process in an organization. The activities follow from legislation or business needs of the organization. The activities are described without references to computer systems (which may however support them). Typical actors are organizations, departments, positions, people.

The lifecycle of a business process typically spans tens of years, while computer systems have a lifecycle of single years. A description of organization's business processes should therefore be free of any references to specific computer systems that might be in production at the time of writing the documentation. Such a business process documentation not bound to any specific computer systems will then be still valid after those computer systems retire and will be replaced by their successors - on the contrary, it will become an important source of information for the implementation of those replacement systems.

A use case describing a business process has type "Organization" and an icon of a house: Organization .

Example: Business process
Organization Fulfill an order
Type: Organization
Primary actor: Customer
Main success scenario:
  1. 1. Customer compiles an order, choosing products from the catalog.
  2. 2. Customer sends the order to the company.
  3. 3. Sales department allocates the products ordered in the warehouse stock.
  4. 4. Sales department confirms receiving the order to the customer and sends it to the shipping department.
  5. 5. Shipping department packages the products ordered and ships the package to the customer's delivery address.
Common mistake: References to specific computer systems and their functionality
Organization Fulfill an order
Type: Organization
...
Main success scenario:
  1. 1. Customer compiles an order in the web application Order+, choosing products from the catalog.
  2. 2. Customer confirms the order in Order+.
  3. 3. Order+ sends the order to SAP.
  4. 4. SAP allocates the products ordered in the warehouse stock and confirms receiving the order to the customer.

Functional specification

Functional specification defines the functionality of a computer system (application). Functional specification must meet the following criteria: correctness, completeness, consistency and implementability. It is a contract between the product owner (sponsor, customer) and the developer (supplier) of the system to be built that specifies its functionality. The correctness and completeness are guaranteed by the product owner, while consistency and implementability are guaranteed by the developer.

The product owner formulates user requirements on the system. The developer analyzes them and writes the functional specification as the output of the analysis.

The functionality of the system supports the activities of the organization's business processes. A functional specification defines what the system does (the functionality), not how it does it (that is the subject of the design documentation). Typical actors in a functional specification are computer systems and their users.

Functional specification of a computer system is the most common application of use cases, which often leads to the fact that these two terms are used interchangeably, and by the term "use cases" is actually meant the functional specification. Use cases are, however, only one of the possible formats in which a functional specification can be written, and vice versa, use cases can be used not only to write functional specifications (but also business process documentation or a design document).

A use case describing the functionality of a computer system has type "System" and an icon of a box: System .

Example: Functional specification
System Confirm order
Type: System
Primary actor: Customer
Main success scenario:
  1. 1. User confirms the order.
  2. 2. System allocates the goods ordered in the stock.
  3. 3. System sends an e-mail confirming the receipt of the order to the customer's address.
  4. 4. System sets the order status to Confirmed.
Common mistake: References to design details, typically GUI
System Confirm order
Type: System
...
Main success scenario:
  1. 1. User clicks on the Confirm order button.
  2. ...
  3. 9. User checks the "Show all" checkbox.

Design documentation

Design documentation describes how is the functionality implemented in a computer system, and so documents the developers’ decisions made during the implementation. It defines the development technologies and the way they are used. Typical actors are the components of a computer system at various levels, from subsystems to the individual implementation units or elements of the user interface.

A use case describing the design of computer system has type "Design" and an icon of a screw: Design .

Example: Design documentation
System Confirm order
Type: Design
Primary actor: Customer
Main success scenario:
  1. 1. The user clicks on the Send order button.
  2. 2. The client application calls sendOrder service on the backend.
  3. 3. Backend reads the order from the database.
  4. ...

Summary of documentation types

Important Each of these three types of documentation pursues a different purpose and uses its own specific means. Establish the purpose of your documentation: which of the above three types applies? A documentation usually has a single purpose, and therefore should contain only use cases of the corresponding type. When writing the use cases always use consistently only the means that match the type of the documentation. Mixing multiple types of use cases in a single documentation is almost always wrong.

If you write a functional specification describe the functionality of the computer system and avoid describing business processes or determining design details.

If you write business process documentation describe the business processes and avoid references to computer systems and applications and their functionality.

Use case attributes

Goal

Goal is what the primary actor is trying to achieve by executing the use case. Goal is the name of the use case and so should be concise, accurate and brief. Goal is an activity of the primary actor and therefore should always start with a verb.

Example: Use case goals
  • Withdraw cash in local currency
  • Identify account
  • Exchange cash
  • Order goods
  • Provide mortgage

Primary actor

The primary actor executes the use case to achieve some goal. The actor can be a person, organization, department, position, a computer application, a component of a computer application, etc. In a functional specification the actor typically corresponds to a user role in the application. There are relationships between the actors that can be expressed by inheritance.

Example: Actors
  • System
  • Branch teller system
  • Interbank settlement system
  • User
  • Teller
  • Cash teller
  • Last sample bank
  • Mortgage department
  • Head of the Mortgage department

Scope

Scope of a use case is the system whose behavior the use case describes.

The system may be any entity that exhibits behavior. It may be a computer system (application), an organization (or department), or application component.

Example: Scopes
  • Use case Process order describes the business process of a company named First selling. Its scope is the First selling company (an organization).
  • Use case Create order specifies the functionality of the customer ordering system within the company. Its scope is the ordering system (a computer application).

Important Fill in the scope for each use case - specify the system for which the behavior is described in the use case.

Visibility

A use case describes the system either from the outside (black-box) or from the inside (white-box).

Use case with visibility black-box describes the behavior of the system from the outside - the system acts as an undivided entity. The description from the outside shows the behavior of the system as a whole from the perspective of an actor (the primary actor) standing outside of the system. A functional specification should always be written with black-box visibility. The use case type icon is gray.

Use case with visibility white-box describes the interactions of the components within the system. Business process documentation and design documentation can be written with white-box visibility (or black-box, as well, depending on the author's intent). The use case type icon is white.

Example: Black-box visibility
System Process Order
Type: Organization
Scope: First selling co.
Visibility: Black-box
Main success scenario:
  1. 1. Customer sends an order.
  2. 2. Company receives the order and confirms it to the customer.
  3. 3. Company ships goods ordered via post mail.
  4. 4. Customer receives the goods and pays for it.
  5. 5. Company receives payment for the order.
Example: White-box visibility
System Process Order
Type: Organization
Scope: First selling co.
Visibility: White-box
Main success scenario:
  1. 1. Customer sends an order.
  2. 2. Sales department assigns the goods ordered from inventory and confirms receiving the order to the customer.
  3. 3. Shipping department picks up the goods from the warehouse, packages it and delivers it to the post mail.
  4. 4. Customer receives the goods and pays for it.
  5. 5. Billing department receives the payment and matches it to the order.

Important Determine the visiblity in each use case, specify it explicitly and keep to that decision consistently in the whole use case.

Level

A use case consists of a sequence of steps. Some of the steps are composed of a sequence of sub-steps, and thus constitute a separate use case at a lower level. Conversely, a use case can be a step in a use case on a higher level.

User goal is a basic level of a use case. It is the lowest level that brings real benefit to the user. User goal generally meets the following criteria:

User goals are therefore usually unambiguously given for each system. Use cases at lower levels can be nested in many sub-levels and use cases at higher levels can be defined on many higher levels, but the level of the user goals is just one.

The unambiguity of the user goal level is the core of the graphical indication of use case level: while the sea extends to depths and the skies to heights, they both meet at one single level - the sea surface. User goal is marked with the icon of a sea surface (waves). The subordinate use cases are marked with the icon of a fish. The subordinate use cases at the lowest level are marked with the icon of a shell. Use cases above the user goal level are marked with the icon of a kite. Use cases on the highest summary level are marked with the icon of a cloud.

An overview of the primary actors and their user goals is the shortest and yet at its level of detail complete description of the functionality of a system. It is usually used as the basis for project planning a progress measurement in an implementation project.

Example: Levels
  • Cloud Use services of bank's branch
  • Kite Use non-cash services of bank's branch
  • Sea Transfer funds in local currency, Perform direct debit in local currency
  • Fish Identify account, Identify client, Calculate fee
  • Clam Validate account number, Validate personal id number