Use-Case-Modeling Guidelines

Example Use-Case Modeling Guidelines

Version <n.m>

Last Update <yyyymmdd>

1. Introduction

1.1 Purpose

The purpose of this set of guidelines is to ensure consistency of the Use-Case model. It provides guidance in how to document a Use-Case as well as general help on related topics often found problematic for Requirement Specifiers and System Analysts.

1.2 Scope

These guidelines may be used as is, or tailored, to meet the needs of most projects.

1.3 Definitions, Acronyms and Abbreviations

1.4 References

1.5 Overview

This set of guidelines is organized into two sections, the first describes our preferred way of modeling the Use-Cases, the second part provides guidelines for the content of the Use-Case model and for naming the elements within the model.

2. General Use-Case Modeling Guidelines

2.1 General Style

The Use Cases will be written using the template provided with the Rational Unified Process, with certain style and layout modifications to suit applicable project documentation standards. Click here to see the HTML version of this template.

2.2 Use of the <<Communicates>> relationship

The association between an Actor and a Use-Case is called a Communicates relation. It is recommended that this association is made uni-directional. By using this modeling strategy we will distinguish between :

q Active Actor
The Actor is considered active in an Actor-Use Case pair when the Actor is initiating (or triggering) the execution of the Use-Case. The arrow on the communicates relation points to the Use-Case.

q Passive Actor
The Actor is considered passive in an Actor-Use Case pair when the Use-Case is initiating the communication. Passive Actors will typically be external systems or devices that our system needs to communicate with. The arrow on the communicates relation points to the Actor.

This recommendation is made because the notion of active and passive actors adds value to the reader of the Use-Case model.

2.3 Use of the <<Include>> and <<Extend>> relationships

In the first instance, it is recommended that you avoid the use of these relationships. This recommendation is made because the misuse of these relationships has much more potential to clutter and confuse than they have to help simplify the Use-Case Model. The best practice is to avoid this type of decomposition initially, and consider using these relationships at a later stage in the process. These relationships can be used to:

2. Factor out behavior from the base use case that is not necessary for the understanding of the primary purpose of the use case, only the result of it is important.

3. To show that there may be a set of behavior segments of which one or several may be inserted at an extension point in a base use case.

But they should only be used where they add value by helping to simplify and manage the use-case model.

2.3.1 Use of the <<Include>> relationship

The include-relationship describes a behavior segment that is inserted into a use-case instance that is executing the base use case. It is a mechanism similar in nature to a sub-routine, and is most often used to factor out common behavior.

2.3.2 Use of the <<Extend>> relationship

The extend-relationship is a more difficult relationship to take advantage of, primarily because the extension use-case is not known to the base use case. As a general comment, there are few places where this relationship is useful in most business systems. Keep in mind however, that there are always exceptions to the rules, and that this mechanism can be useful in certain circumstances.

2.4 Use of Actor-Generalization

In general, Actor-Generalization can be used to better define the different roles played by the users of the system to be developed. This is useful in applications with different "categories" of end-users. In this way, only relevant functionality will be presented to each category of users, and we are able to control the access rights based on this grouping.

Rule of thumb : Each use-case will only be initiated by one Actor. This "rule" may be overridden, in which case the use-case description must justify the decision.

Example from the University's Business Domain: Librarian and Professor are examples of two existing roles (actors) in the University Domain. These roles have some common tasks and some tasks that are unique to their role in the Business. The preferred way of modeling this is shown below. Image Detail Above in Content

2.5 Use of Interaction Diagrams

In some cases, it is beneficial to include - in addition to the textual flow of events - an Interaction diagram to illustrate the "high level" flow of events of the use case. It is recommended you draw a sequence diagram for this in Rational Rose. Include only the communication between the actors and the boundary objects (covering both the input and the output messages) and treat the system as a black box. Use boundary objects with logical names as defined in the use case flow of events, without assigning them to classes at this point.

It is not necessary for every use case to have a corresponding interaction diagram: It is an optional deliverable.

2.6 Use of Activity Diagrams

Where an activity diagram adds value in helping to define, clarify and complete the flow of events in the use case, it is recommended these are modeled in Rational Rose. A good rule of thumb is to consider Activity Diagrams for complex use-cases (containing several alternate and / or exceptional flows). The activity diagram shows a decision tree of the flows in the use-case.

It is not necessary for every use case to have a corresponding activity diagram: It is an optional deliverable.

3. How to Describe a Use Case

For general information and additional guidelines on Use Cases, See the Rational Unified Process.

3.1 Actor Guidelines

For general information and additional guidelines on Actors, See the Rational Unified Process.

3.1.1 Each concrete Use Case will be involved with at least one Actor

Is each concrete use case involved with at least one actor? If not, something is wrong; a use case that does not interact with an actor is superfluous, and you will either remove it or identify the corresponding actor.

In some cases, more than one actor may play a part in the use case interaction. Be sure to check that the use of multiple actors in the one use case is valid (see Actor Generalization).

3.1.2 Intuitive and Descriptive Actor Name(s)

Do the actors have intuitive and descriptive names? Can both users and customers understand the names? It is important that actor names correspond to their roles. If not, change them.

You should refer to the Use Case Model to ensure that you are using the correct actor name for every actor in your use case.

3.1.3 Consistent Use of Actor Name(s)

The use case specification will be written using actor name(s) consistently. Care will be taken to ensure actor naming is clear and unambiguous.

Do not refer generically to "the actor"; instead use the actual name used to uniquely identify or define the actor. The actor name can be thought of as the role being played in a set of system interactions.

3.2 Use Case Name

The use-case name will be unique, intuitive, and explanatory so that it clearly and unambiguously defines the observable result of value gained from the use case.

A good check for the use-case name is to survey whether customers, business representatives, analysts and developers all understand the names and descriptions of the use cases. Remember: You are defining an observable result of value from the actors perspective.

Each use-case name will describe the behavior the use case supports. The name will combine both the action being performed and the key element being "actioned". Most often, this will be a simple Verb/ Noun combination. The use case should be named from the perspective of the actor that triggers the use case. Examples include: "Register for a course", "Select a course to teach".

3.3 Use Case Brief Description

3.3.1 At least 1 paragraph

The use case will contain a brief description. This description will be at least 1 paragraph and no more than 3 paragraphs in length. The description will cover an explanation of the key purpose, value proposition and concepts of the use case.

3.3.2 An example (Optional)

Where it adds value, a short example "story" can be included with the brief description that helps to provide further context. This example will usually follow the Basic Flow, and where helpful will include data values.

3.4 Consistent use of the imperative: Will

System requirements within the use cases will be written using the imperative. The term "Will" has been chosen in favor of "Shall" and "Must" to describe requirements consistently. The use of passive terms that imply the requirement is optional or undefined such as "should", "possibly", "etc", "might" or "may" will be avoided.

3.5 Use of Glossary Terms

All Business Terms used in a use case will be defined in the project's Glossary. If a Business Term exists in a use case that does not exist in the glossary, the term needs to either:

1. Be added to the glossary, including a brief description (max. one paragraph).

2. Be changed in the use case to reflect the correct Business Term defined in the glossary.

3.6 Use of "Action" Terms

3.6.1 Define where the system is responsible for presenting the Action Option

The use case will explicitly state where the system is responsible for presenting an action as an available option for the actor to select. In most cases, the available options should be presented as part of the basic flow, and be referenced as the entry point in the first statement in the corresponding alternative flow.

3.6.2 Consistent use of the term throughout the Use Case

The use of terms such as New, Modify, Cancel, Delete, OK, and Print will be consistent throughout the use case: The same logical action will not be referred to using different terminology. Special care will be taken to ensure that the Action Terms used in the Alternative Flows match those used in the basic flow.

3.7 Separate paragraphs for Actor and System behavior

Each time the interaction between the actor and the system changes focus (between the actor and the system), the next segment of behavior will start with a new paragraph. Begin first with an actor and then the system.

The sentence must begin with 'The <actor-name> will xxxxx', or 'The system will xxxx'. Always state the actor name correctly, in full, rather than any abbreviation.

3.8 Alternate and Sub-Flows

Each Alternate and Sub-Flow will explicitly and clearly define all of the possible entry points into the flow, and will conclude with all of the possible exit points from the flow.

The alternate flow will also state explicitly the exit point and where the actor continues to next - whether it is returning to a specific step in the basic flow, or ending.

Where the flow of events becomes cluttered due to complex behavior, or where a single flow exceeds a physical printed page in length, sub-flows can be used to improve clarity and manage the complexity. Sub-flows will be written by moving a self-contained, logical group of detailed behavior to a sub-flow, and referencing this behavior in summary form within the flow of events.

3.9 Preconditions and Postconditions

The use case specification will include a set of conditions (also referred to as assumptions) that are expected to be true before the use case begins (preconditions) and after the use case has ended (postconditions). Note that the use case may end in a number of ways, and each "postcondition" should be described accordingly.

3.10 Use of placeholders for missing detail (TBD)

Where information is not yet defined or not yet decided, the use case will include a reference to the issue or element and will include the placeholder: TBD.

3.11 Definition of and Reference to Supplementary Specifications

Where there are additional requirements that cannot be described naturally during the flow of events, these will be defined as supplementary requirements. For those that are specific to a use case, these will be defined in the Special Requirements section of the use case specification.

For those requirements that are applicable system-wide, especially those of a non-functional nature, will be defined in one or more separate supplementary specification documents.

Performance: - The system must provide an online response that does not exceed 5 seconds under the expected normal load conditions.

3.12 Crosscheck with UI Prototype/ Design

The use case contents will be cross-checked against the UI Prototype/ Design to ensure no system requirements are missing from the use case or the UI Prototype/ Design. Where changes are required to the use case, these will be actioned: Changes to the UI Prototype will be noted as a discussion for future action.

3.13 Exception Flows (Optional)

The following guidelines are provided in assisting in the discovery of Exception Flows:

3.13.1 What can go wrong?

For each step in the use case, consider what can go wrong. Each unique exception can be captured as an Exception Flow. In some cases, a single Exceptions Flow will be used commonly across the use case, e.g. "Timeout". The key information to be captured is what the business requirement is when the exception occurs, i.e. what should the actors experience be?