View source for Understanding Use Cases

Before choosing or programming an information system or any other type of software, it is important to identify the functions that the system will perform and document them. Think of these functions as '''goals'''. What goals do you want to achieve with your system? 

When you install and download Open Source software, you may find that some goals cannot be accomplished in the system as it is installed. In that case, a programmer will need to customize the system to achieve those goals. For example, you may need to build a new report or add a new field to capture additional data. These customizations are the '''functional requirements''' of the system.

A simple way to document functional requirements is to write use cases. A '''use case''' describes how to achieve a specific goal, or function, using the system. As an example, the iHRIS documentation (available with [http://www.capacityproject.org/hris/suite/ the iHRIS software on our website]) includes a full set of use cases for the three systems to help you understand the functions that each HRIS natively supports. If you install the iHRIS software, you may want to modify these use cases to document the customizations needed to achieve your goals, or you may use the template that follows this introduction to write use cases.


== Benefits of Use Cases ==

One of the most difficult aspects of system development is figuring out exactly what to build. There is often a gap between the people who understand the problem and the people who understand how to build the solution. Use cases are one of the most effective means of bridging that gap. Written in plain language, with no technical jargon, use cases describe functional requirements in a way that can be understood by the stakeholders and users of the system and by the developers of the system.

Use cases are usually co-written by stakeholders, users and developers. This ensures that the system includes the functions that are truly important to the people who will be using it. Use cases should focus on the goals that users want to achieve. Focusing on action-oriented goals defines the scope of the system and eliminates unnecessary requirements, reducing costs and development time.

Several related use cases may be organized into modules, called ''packages''. Development of each module can then be prioritized and scheduled. This helps plan an iterative path for development where core functions can be developed first and enhanced later by lower priority features. The core system can be used even while new functions are being developed.

Use cases should be living documents. Stakeholders, users and developers should constantly review, revise and expand the use cases during the development or customization of a system. At different stages, use cases can be used to: 
* describe a work process
* focus discussion about system actions
* be the functional requirements for a system
* document the design of a system
* generate procedures for testing a system
* write instructions, help and training materials for end users.

Not all requirements have to be known before starting development. Use cases may be edited during development to capture additional functions, and new use cases may be written as needs for the system arise.


== The Parts of a Use Case ==

The use case enumerates all of the steps describing the interaction of one user—called the ''primary actor''—with the system to achieve a goal. The use case begins at a triggering event and continues until the goal is either successfully achieved or abandoned. It collects all the possible scenarios for how the goal can be achieved and how it may fail.

At minimum, each use case should contain the following information:
* a goal to achieve
* the primary actor who is attempting to achieve the goal; the actor should be identified by a role in interacting with the system, not by a name or the name of a group
* a condition under which the scenario runs; this may include any preconditions that must be true before the scenario can start and a triggering event that starts the scenario 
* an end condition that must be true after the use case is finished if the goal is successfully achieved, called the ''success guarantee''
* a set of action steps, forming the body of the scenario; these are called the ''main success scenario''
* a possible set of ''extensions'', or alternate scenarios, leading toward either the success or failure of the goal


== Writing Use Cases ==
 
Use these guidelines to write your own use cases. You should write a use case for each function or goal that has been identified for your system. A completed example is given following the guidelines.

'''1A. Use Case Number:''' Assign a number to the use case for reference. It is helpful to number use cases in order of implementation or priority. 

'''1B. Use Case Title:''' Assign a title to the use case, generally a shortened form of the goal in action-verb-noun format.

'''2. Level:''' Select ''summary'' for a use case that summarizes a number of activities or is outside the scope of the system; ''user-level'' for a use case that describes one complete activity in the system; or ''subfunction'' for a use case that depends on a user-level use case but is too long to include in the user-level use case.

'''3. Primary Actor:''' Write the role of the user performing the use case. It is often helpful to brainstorm and list all the possible actors on a system before beginning to write use cases.

'''4. Brief Description/Goal:''' Write a goal statement that is longer and more detailed than the use case title. This statement describes the function that the primary actor wants to accomplish.

'''5. Preconditions:''' List any preconditions for the use case. Preconditions specify what the system will ensure is true before letting the use case start. Generally, a precondition indicates that some other use case has been run to set it up.

'''6. Success Guarantee:''' State the successful result that the primary actor wants. It should satisfy the stated goal and ensure that the stakeholders’ interests are met.

'''7. Main Success Scenario (MSS):''' Write the action steps of a typical scenario in which the goal is delivered. The first step is the trigger that initiates the use case. Each following step describes an action that the user or the system takes in reaction to the previous step to accomplish the use case goal. Ideally, there should be 3-12 steps; number each step. 

'''8. Extensions:''' Brainstorm and list the conditions that may cause the system behavior to branch from the steps that occur in the Main Success Scenario. An extension must be detectable by the system, and the system must take some action to handle it. Number each extension to link to the MSS step in this format: 1a, 1b… If the extension can happen at any time, precede it with an asterisk (*) and list it first: *a, *b… Indent extensions to extensions and restart numbering: 1a1, 1b1… Under each extension, indent and write how the system responds, the extension-handling steps. Each extension-handling step should end back in the main success scenario, at an alternative successful exit or in failure (a system error) that stops the use case before the goal is accomplished. 

'''9. Notes/Issues/Reviewer Comments:''' Add any comments on the use case or explanatory notes needed. This is also a good place to note any issues that have arisen regarding the use case or its implementation in the system. 
 

== Example Use Case ==

'''1A. Use Case Number:''' 9

'''1B. Use Case Title:''' Log in

'''2. Level:''' User-level

'''3. Primary Actor:'''  Any user

'''4. Context of Use:''' The user logs in to authenticate his or her role in the system and to perform a task in the system.

'''5. Preconditions:''' A user account has been created for the user. 

'''6. Success Guarantee:''' The user can successfully access the system and perform actions appropriate for his or her role.

'''7. Main Success Scenario (MSS):''' 
	
# The user connects to the system.
# The user enters his/her username and password.
# The system validates the username and password.
# The system determines the user’s role.
# The system displays a list of actions the user can perform based on the user’s role.

'''8. Extensions:'''

<pre>3a. The system determines that the password is incorrect for the username entered.
    1. The system prompts the user to re-enter the password.
       3a1. The system determines that the re-entered password is incorrect.
            2. The system provides the option for the user to retrieve a forgotten password.

3b. The system determines that the username does not match a username for any account.
    1. The system displays an error message.

4a. The system determines that the user has no role assigned in the system.
    1. The system does not allow the user to access the system.
</pre>

'''9. Notes/ Issues/ Reviewer Comments:''' This use case is the same for iHRIS Manage, Qualify and Plan.

'''Completed by:''' Use case writer
'''Date:''' October 25, 2008

'''Reviewed by:''' Use case reviewer
'''Date:''' November 4, 2008


== Guidelines for Finding Actors and Goals ==

# List every possible human and non-human primary actor, over the life of the system. 
# Brainstorm and exhaustively list all possible user goals for each actor.
# Write a short description of use case behavior for each goal--the ''use case brief''--mentioning only the most significant activity and failures. This summarizes what is going on in the use case.
# Re-evaluate the goals for each primary actor. Add, subtract and merge goals as necessary.
# Identify all business use cases--those that have the organization as the scope, rather than the system--and separate. These may be written to clarify business processes, assumptions and preconditions, but probably will not be included in the specifications. 
# Write user-level use cases for each goal using the use case template above.
# Prioritize and assign goals to development teams and software releases. 

You may find it helpful to use the [http://spreadsheets.google.com/pub?key=rq3k2zguXd68aJYwfpEv7gA&output=xls Actors and Goals Template] to organize all actors and goals before writing full use cases.


== Writing Summary-Level Use Cases ==

Summary-level goals involve multiple user goals. The purpose of summary-level use cases is to:
* Show the context in which the user goals operate
* Show life-cycle sequencing of related goals
* Provide a table of contents for the lower-level use cases.

Summary use cases tie together, and thus refer to, a number of user-level use cases. There are typically only four or five summary-level use cases for a system. Summary use cases typically execute over hours, days, weeks, months or years. They do not provide functional requirements.
To find a summary-level use case, ask "what does the primary actor really want?" or "why is the actor doing this?" The answer will be a goal one level higher than the goal stated in the user-level use case. To write a summary-level use case, remove the user interface details; show the actor's intent, not their movement. 

I prefer to write summary-level use cases in narrative rather than numbered step format. I also find it helpful to write an example scenario for each summary-level use case telling a story about how the users will interact with the system.

Written this way, summary-level use cases provide a helpful tool for quickly communicating with executives, stakeholders and customers the broad scope of what the system will do.