Use Case Specification Guideline – Best Tips & Guidance For 2024
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.
Post Comment