This article provides use case specification guidance gained from working on many projects across a number of different organisations and industry. It will help those seeking to understand how to write use case specification and understand what is described in use case specification.
So what is a use case specification? A use case specification captures the requirements, typically of a system, in the form of a use case that contains the descriptive requirements steps in a logical sequence so that document specification can be understood by users to obtain sign-off of their requirements and for testers and developers to understand what is needed by the system to test and build the system functionality detailed in the system use use case.
Use cases and use case specifications were popular in the unified modelling language (UML) 
and is still used in some corporate environments.
Having a good working knowledge of use cases and how they structured provides a very good basis for understanding and transitioning to using user stories in agile ways or working. As a use case can be split into another user stories.
The article answers a number of the questions that business analyst ask who are new to use cases and seeking detailed guidance. The article will also help business analyst on how to write use case specification and understand sections of a use case specification template.
The article also provides use case specification examples section extracts and use case textual description examples so that you can review and a get a good feel of what to specify in an use case specification document.
The article also provides guidance on writing and formatting use case business rules examples in business analysis. Some readers may be interested in a recommended use case training course.
Table of Contents
Use Case Specification Guidelines
Level of Detail
To ensure that the breadth of the functionality is well understood prior to moving into the detailing of the functional requirements, Use cases will be described at 3-levels depending on the stage of the project:
- Name and Brief Description
- Outline
- Fully Detailed
Initially, during the early inception, actors and use cases will be identified, associated, named, given a brief description and an intuitive view of the size/complexity of the use case will be determined. The reasons for doing this are to:
- define and agree the high-level scope at an early stage of the project
- enable an initial estimation of the project size (based on the number of use cases and the size/complexity rating)
During the Inception Phase, the use cases will be further described to an outline level of detail, this is important in order to:
- define a more detailed scope by producing the outline flow for all use cases
- provide more detailed input to the estimating process at the end of inception (the size/complexity rating can be derived from the outline detail)
- enable us to produce a more complete and consistent glossary before going into procedural detail (because the key terms will be mentioned in the outline flows)
By the end of the inception phase, all of the use cases should have been described to an outline level of detail. The “outline” level use-case specification should include the following sections (see later sections in this document for descriptions of the various use-case specification sections):
- A completed use-case diagram
from the ‘use case perspective’, i.e. the use case in context of the actors and other use cases that have a direct relationship with it. - A brief description of the use case
- The pre-conditions of the use case described
- The post-conditions of the use case described
- The main flow of events elaborated to as much detail as possible
- Any alternative flows of events named but not necessarily described by a flow
- Any common flows of events named but not necessarily described by a flow
In addition to the above, if any of the other details (business rules, special requirements, issues) have been captured whilst capturing the “outline” level of detail, these should be included within the “outline” use-case specification.
Note: It is recognised that in a large proportion of use cases, the alternative flows usually contain a great deal of the complexity involved within the use case. Therefore, when an alternative flow is considered to be significant (i.e. it contains some complexity or may involve many steps) it should be described in more detail to ensure that the complexity of the flow is understood as is therefore not under or over estimated.
Ideally, this description should take the form of the outline steps involved, however, a paragraph describing the functionality of the alternative flow will suffice if this is not possible.
Once the “outline” use case has been agreed, the use case will then be elaborated to the full specification, the full specification should include all sections completed. By the end of the elaboration phase, approximately 80% of the use cases should have been described to a fully detailed level.
The following sections describe the contents of the various sections of the standard use case specification.
Use Case Diagram
This use case specification section should be populated with the relevant use-case diagram(s). To avoid inclusion of large use case diagrams, a separate use case diagram should be produced for the use case being described, this diagram should detail the use case and any interacting actors and associated use cases. This is referred to as the “use case perspective” use case diagram.
Brief Description
The brief description of the use case specification section should be populated with the brief description of the use case documented. This description should give an overview of the purpose and scope of the use case and clearly define the end goals of the use case. A single paragraph will usually suffice for this description, however, for more complex use cases, a number of paragraphs may be required.
Note: A single sentence that does not give much more information than the use case name is not acceptable.
Supporting Diagrams
To aid in the understanding of the use case, it may be appropriate to include supporting diagrams into the use case specification, the most common would be:
- Use case specific view(s) of the domain model – showing the relevant business objects and associations that feature within the use case
- State transition diagram(s) – showing the state transitions of the key business objects that features within the use case
- Use case activity diagram(s) – showing a visual representation of the use case flow(s) of events (Note: This should not be a UI navigation diagram)
The inclusion of these diagrams is optional and should only be done when it aids to the understanding of the use case.
Pre-Conditions
This use case specification section should describe the pre-conditions relevant to the use case. A pre-condition of a use case is the state that the system must be in prior to the use case being initiated in order to ensure that the actor will achieve their goal. The pre-conditions may reference other use cases that must have been successfully executed or may be a textual description of an event that is not represented by a particular use case.
Note: Each pre-condition will have a separate sub-section within the use case specification.
Post Conditions
This use case specification section should describe the post-conditions relevant to the use case. A post-condition of a use case defines the state the system must be in immediately after a use case has finished. The post-conditions may be a textual description of an event or description of information being passed to another use case e.g. The business will now have been transferred and the user manually produces a letter of confirmation to the IFA which may include the Unearned Commission Liability report.
Note: Each post-condition will have a separate sub-section within the use case specification.
Flow of Events
Basic Flow
The flow of events in the use case specification section provides the main bulk of the use case specification and describes what the actor does and what the system does in response. It is phrased in the form of a dialog between the actor and the system. The use case describes what happens inside the system, but not how or why.
The glossary should also be used to maintain the definitions of all business terms used in flow descriptions, this ensures that each term has one agreed definition across all use cases and also helps simplify the use case descriptions.
Do not describe specific design items such as user interface screens or controls into the description. Instead, describe these in the Use case storyboard.
Trigger
This use case starts when the actor does something to trigger it – an actor always initiates use cases. The trigger should be documented as the first step within the use case flow of events e.g. 1. This use case starts when the user….
Steps
Each step should be described using standard use case vocabulary (requests, sends, asks, where) and sentence style e.g.
For what the actor does
‘The User requests the to …’
For what the system does in response
‘The System sends message to and …’.
For business rule checks
‘IF then’
Within the flow of events, the name of the actor will not be referenced as this is clearly displayed on the use-case diagram, instead ‘The User’ will be referenced. However, if it is not appropriate for the use case flow of events to reference ‘The User’ (i.e. when the Actor is Time or an external system), ‘The Actor’ should be used.
Each step within the flow of events should be numbered sequentially.
Sub-Headings
To aid understanding and navigation within use cases it can often be useful to include headings within the flow of events describing the action of a group of steps. These headings are not required across all use cases, but are most useful within large, complex use case flows involving many steps.
Example
- The User selects to continue with the transfer of business.
Process Unearned Liability
- The Agent Earnings System returns the unearned commission liabilities for the Agent Organisation Element. The Agent Earnings System will provide the following details of the Unearned Commission Liability for the Agent Organisation Element:
- Number of Schemes
- Total Unearned Commission Liability Amount
- The System checks the total unearned commission liability.
- IF the total unearned commission liability > 0 [BR48], the System displays the details of the outstanding unearned commission liability, giving the User the option to print in a format suitable for onward transmission to the Agent [BR46].
Transfer the Business
- FOR EACH Organisation Element selected for transfer, the System will record that the business for the selected Organisation Element has been transferred and the transfer date [BR43]
Looping
In certain circumstances, the flow of events may require a number of steps to be repeated until a certain condition is true, in this circumstance, the FOR EACH…..REPEAT statement should be used e.g. FOR EACH Attribute REPEAT Steps 8-12.
IF statements
Simple alternatives may be described within the Basic Flow of the use case to describe unusual optional processing or exception processing. If it only takes a few steps to describe the alternative processing, do it directly within the Basic Flow of Events section (using an IF statement), rather than using an Alternative Flow.
The ‘IF’ statement should be a separately numbered, nested step within the Basic Flow (see Nesting sub-section below). The ‘IF’ statement should be nested below a step expressing the base course of action or summarising the nested steps.
Example
The System validates the Customer information entered, any errors must be resolved before progressing with the use case, any warning messages can be accepted and the use case continues:
IF any of the mandatory fields have not been entered [BR1], the system displays an error message indicating that the mandatory fields that have not been entered (MSG0001)
Nesting
In certain circumstances, a step within the flow may actually have a number of nested steps. This prevents the need for breaking the nested steps into an alternative flow. When describing nested system processing, nested numbering should be used (e.g. 4. 4.1. 4.1.1.).
However, if too many levels of nesting are used within the flow, the use case can become very difficult to understand. Therefore, as a rule, no more than 2 levels of nesting should be used (i.e. 4.1.1. is acceptable, 4.1.1.1. is not acceptable).
Referencing Included Use Cases
If the flow needs to reference an included use case, embed the activation of the included use case in the flow, stating the name and reference number of the use case. The standard language for activating an included Use Case to be used is ‘INVOKE’.
E.g. On selection of the Organisation Element, the System will INVOKE UC11 View Party which will display the details of the selected Organisation Element.
Referencing the User Interface
It is useful to provide a cross-reference between the use case and the use case storyboard to aid understanding of which screens/pages are displayed at particular stages of the use cases. This approach has proven particularly useful for the designers and testers.
This is to be achieved by allocating a unique identifier to each user interface with the use case storyboard. The Unique Identifier of the User Interface should take the form UcnnSCxx. This unique identifier can then be referenced alongside the step in the flow of events where that user interface is first displayed.
E.g. The System prompts the User to enter the Search Criteria (UC10SC01).
Data Items
Where information is exchanged between an Actor and the system, be specific about what is passed back and forth. For example, it is not very illuminating to say that the user enters ‘customer information’. Information about Data Items is also contained in the in the use case storyboard artefact. Use the following guidance with respect to the amount of information to capture in the use case with respect to data exchange.
List in detail the data items that are displayed on screen or passed between an Actor and the System, e.g. First Name, Surname, Address Lines 1-4, Post Code, etc.
Alongside each data item in the list, identify whether it is read only/disabled, and any notes applicable to that data item.
Example
- The System prompts the User to enter Customer Details [BR1]:
- Bank Account No (read-only) – automatically assigned by the system [BR2]
- Customer Name
- Address Lines (1-4)
- Postcode
- Date of Registration – populated with the current system date
A business rule should be used to describe which data items are mandatory. A separate business rule should be used for each separate instance of data exchange between an actor and the system to define the mandatory data elements of that interchange.
Any validation that occurs on a data item (e.g. a date between a particular range) or between data items (e.g. the value of one data item may effect the values allowed for another data item) should also be described as a business rule.
Only identify the available/selectable values for a data item in the flow of events, if the value of the data item is referenced within the use case or if business rules exist in relation to selection of a particular value.
To clarify, the data type, (e.g. numeric, date etc), format (e.g. dd/mm/yyyy) and length should be documented within the use case storyboard.
Error Messages
Where an error or warning message is reported to an actor, the use case flow of events must state where in the flow of events that the message needs to be reported and provide an indication of what the message is about. The precise message text, however, should be stored in a separate artefact, which will be referred to as the Message Catalog.
This artefact is in addition to the standard RUP artefacts. Each message in the Message Catalog should have a unique identifier of the form MSGnnnn, and the use case flow of events should reference this unique identifier, e.g. “The system displays an error informing the user that the product cannot be supplied on the date requested due to the associated lead time (MSG0001)”.
The flow of events should make it clear whether the message is an error (where the user must take a different course of action) or warning (where the processing will continue following user acknowledgement of the message) to the Actor, e.g.
“The system warns the user that delivery on this date cannot be guaranteed (MSG0002)”. The specific text of the errors and warnings should be agreed with the stakeholders and then implemented by the development team during build.
Following the display of an error/warning message, the flow of events should be explicit as to what happens next. To avoid use of looping GOTO statements which can make the flow of events difficult to navigate, it is recommended that a statement is made prior to the validation stating what happens in the event of an error and what happens in the event of a warning (see Example).
There are options available to reduce the amount of duplication of messages by making the messages generic and “parameter driven”. A good example of where this approach works well is for messages notifying the user that mandatory information has not been provided.
To make this message generic and “parameter driven”, in the message text, replace the parameter with the percentage sign (%) followed by a sequential number (unique within the message).
Then in the Parameters column, list the sequential number and the parameter that it relates to. For example, to display “Field Name is a mandatory field – please enter”, the following message would be put into the “Message Text” column in the message catalog “%1 is a mandatory field – please enter” and the “Parameters” column would be “1 – Field Name”.
Be aware that this approach to the creation of messages will not work for all types of messages. It is more important that the messages presented to the actor are meaningful than to attempt to make messages generic in an attempt to avoid duplication and increase the re-use of messages.
Alternative Flows
The use case description alternative flows section of a use case specification is used to describe either:
- alternative processing or actions that need to occur as a result of exceptions that occur when carrying out the basic flow or
- an alternative or less common way of achieving the actor goal of the use case.
There may be, and most likely will be, a number of alternative flows in a use case. Alternative flows should contain a number of steps and may be as long as necessary to describe the events associated with the alternative behaviour. Keep each alternative flow separate to improve clarity.
When branching to an alternative flow, the initiating flow should explicitly state the condition why the alternative flow is being invoked (using an ‘IF’ statement). The standard language for activating an alternative flow to be used is ‘refer to’.
Example
- The System prompts the user to identify how they wish to allocate the Agent to a Sales Office:
- By geographical region
- By manual selection
- The User selects to allocate the Agent to a Sales Office based on geographical region.
- IF the User selects to allocate the Agent to a Sales Office by manual selection, refer to Alternative Flow AF1
When an alternative flow ends, the events of the basic flow of events are resumed unless otherwise stated. Attempt to avoid “go to step n” statements, however, this may not always be possible.
Common Flows
Within certain use case specifications, there may be a number of common steps that occur within more than 1 of the flows. An example of this may be when a use case is representing some “maintain” functionality where the main flow is handling the “Create” functionality and one of the Alternative Flows is handling the “Modify” functionality and both of these flows share a number of similar steps. There are a number of options of tackling this:
- A) Repeat the steps within each flow
- B) Link back to a single occurrence of these steps using a PERFORM Flow Steps x-y notation
- C) Factoring the steps out into another Use Case
Each of the above options is not recommended, option A leads to a large maintenance overhead when the common functionality changes, option B makes the case case specification unreadable and also creates an overhead of maintaining the Step No’s, option C will result in a number of very granular use cases.
Therefore, the recommended approach for this scenario is to factor out the common steps into a common flows section. The common flows section is an optional section that should be included within a use case specification when required and will contain a flow for each “collection” of common steps (recommend only using common flows when there are more than 2 contiguous common steps).
The standard language for activating a common flow to be used is ‘perform Common Flow’.
Example
- The User wishes to Add a new Communication Preference to the Communication Agreement, perform Common Flow CF1
- IF the User wishes to Amend the details of an existing Communication Preference within the Communication Agreement, perform Common Flow CF2
- IF the User wishes to Delete the details of an existing Communication Preference within the Communication Agreement, perform Common Flow CF3
- The User confirms that they wish to save and exit from the Communication Agreement.
Special Requirements
A special requirement is typically a non-functional requirement that is specific to a use case, but is not easily or naturally specified in the text of the flow of events. A special requirement may also be a use case specific instance of a system wide requirement that is documented in the supplementary specification.
Capturing special requirements at a use case level is often viewed as a difficult activity, and rightly so. Often the business users that you have worked with to produce the use case specification struggle to answer your questions with respect to non-functional requirements. In reality such questions are best directed to a technical-orientated representative rather than a system end-user. Often this section of the use case specification is overlooked entirely, or conversely people spend all too much effort trying to capture these special requirements for no real gain.
Coming up with a generic set of questions to ask for all use cases is not the answer. And if you did, more than likely you will find that the answers to the questions are the same, i.e. the majority of non-functional requirements will be system-wide with a small number specific to a use case. That is not to say that it is ok to forget about this section of the use case specification, but more that there is a need to understand the non-functional requirements at a system-wide level and determine which use cases are most pertinent to those requirements.
For example, if a system wide requirement exists that states sensitive information must be secured when passed to an external system, make sure you explore this requirement further in any use case where information is passed to an external system i.e. exactly what information needs to be secured?
Therefore, it should be agreed (on the project) that:
- the non-functional requirements/requirement categories to be captured are to be defined by the solution architect by the end of the inception phase
- the solution architect will then explain these non-functional requirements to the business analysts and jointly agree on the pertinence to particular use cases and who is going to capture the specific requirement
- the business analyst will capture their agreed use case specific non-functional requirements during the elaboration of the use cases with the business users
- the solution architect will capture their agreed more “technical” use case specific non-functional requirements from the appropriate technical representatives from the client (those requirements that cannot easily be answered by an end user)
- the use case specific special requirements captured by the Analyst and the Architect will be included within the use case specification
This process will ensure that the relevant non-functional requirements are captured regarding each use case and the business analyst is suitably knowledgable to explain why the non-functional requirement is pertinent to the use case.
In addition to the non-functional requirements, it is useful to capture usage information at a use case level. Again, it is not necessary to capture this information for all use cases in the use case model. Identify which use cases are central to the system and therefore likely to be executed most often, then get an understanding of the Usage profile of the use case, by asking questions like
- How often is this Use Case (or scenario in the Use Case) executed per day, and is there any peak times during the day in which it is performed?
- Are their times during the month or year in which execution of this Use Case peaks?
- Is there any predicted increase in the frequency of execution of this Use Case?
Business Rules
Business rules are chunks of business logic that typically evaluate to a value, most commonly True/False. Key concepts named in the flow of events should have definitions in the glossary and many of these key concepts will also have related business rules. Business rules may also be validation rules and calculations. Here are some examples of Business Rules:
Example
BR1 – Each user is allowed a maximum of 3 logon attempts to the system (configurable) before being locked out.
BR2 – The selected vehicle must be within the maximum and minimum rentals for the Driver’s grade taking into account Driver contribution, (ie. maximum rental + driver contribution).
BR3 – To derive the periodic insurance value:
Periodic Insurance = Total Insurance / Total number of payments.
Entered Monthly Insurance Value * Term (in months) = Total insurance
Term (in months) / (12 / No. of payments per annum) = Total number of payments
IF Rental Type = 1 (Spread rental) AND where the No. in Advance is >1 THEN
Add No. in Advance – 1 to Total Number of Payments
ENDIF
Business rules should be extracted from the flow of events and listed in a separate section of the use case specification. This ensures that the flow of events remains fluid and readable and that a set of testable rules are produced that can be applied from more than one point in the flow of events. Each business rule should have a unique identifier (unique within the use case) of the form BRn.
Business rules need to be referenced from the flow of events at the point at which that business rule should be applied. The standard notation for referencing a business rule is to include the business rule identifier in square brackets and in bold text.
An example of a Business Rule referenced within the flow of events can be seen within Example 3.5.1.c
Business rules are not error conditions themselves although they might result in an error condition.
i.e. the rule, ‘Each user is allowed a maximum of 3 logon attempts to the system’ is valid,
whereas the rule ‘Maximum Number of Logon Attempts Exceeded’ is not valid, as this assumes that the rule has been tested and failed. Similarly, do not include the flow of events to be triggered if the rule fails validation within the business rule. This information should be captured within the flow of events that references the business rule.
A note about the re-use of business rules and holding them in a central repository. It is quite often the case that a business rule will be applicable to many use cases. Being able to recognise that different use cases do in fact use the same business rule and ensuring that this business rule is worded identically in each use case in which it is used, is difficult in practice.
This difficulty increases with the size of the business analyst team. It is important to look out for business rules that are applicable to more than one use case and ensure the wording of the business rule remains identical across each use case. One option for managing this is by having a central repository of business rules.
Issues
Any issues that are encountered whilst elaborating the use case that are significant enough to be discussed outside of the use case workshops, should be documented within the project issues log and a reference to the issue added to this section within the use case. If the issue is not significant and can be addressed within the workshop, the issue should be noted within this section.
When the final version of the use case specification is issued to the customer, there should be either no outstanding issues relating to the use case or any issues that are outstanding have a documented assumption based on how the project team is planning to progress that has been validated by the client. Any issues that are outstanding should also be included within the project issues log.
Use Case Training
If you wish to learn further with use cases and use case specifications – Business Analyst Mentor has recommended a list of use case training for business analysts.
Free Use Case Template
Here is a free Use Case Template from Bridging the Gap that is extremely helpful for business analysts to see an annotated use case specification so you can review them for ideas and compare against any other use case specification template that you may have.
