Activity:  Detail a Use Case

Detail the Flow of Events of the Use Case

You should already have a short, step-by-step description of the use-case flow of events. This is created in the Activity: Find Actors and Use Cases. Use this step-by-step description as a starting point, and gradually make it more detailed.

Decide on the following points before describing the use cases so that you are consistent across use cases:

• How does the use case start? The start of the use case must clearly describe the signal that activates the use case. Write, for example, "The use case can start when … happens."



• How does the use case terminate? You should clearly state whatever happens in the course of the flow to terminate the use case. Write, for example, "When … happens, the use case terminates."



• How does the use case interact with actors? To minimize any risk of misunderstanding say exactly what will reside inside the system, and what will reside outside the system. Structure the description as a series of paragraphs, in which each paragraph expresses an action in the format: "When the actor does …, the system does …." You can also emphasize interaction by writing that the use case sends and receives signals from actors, for example: "The use case starts when it receives the signal 'start' from the Operator."



• How does the use case exchange data with an actor? If you like, you can refer to the arguments of the signals, but it might be better to write, for example, "The use case starts when the User logs into the system by giving his name and password."



• How does the use case repeat some behavior? You should try to express this in natural language. However, in exceptional cases, it might be worthwhile to use code-like constructs, such as "WHILE-END WHILE," "IF-THEN-ELSE," and "LOOP-END LOOP," if the corresponding natural language terms are difficult to express. In general, however, you should avoid using such code-like constructs in use-case descriptions because they are hard to read and maintain.



• Are there any optional situations in a use case's flow of events? Sometimes an actor is presented with several options. Team members should write this in the same way. For example:

"The actor chooses one of the following, one or more times:

a) . . .

b) . . .

c) . . ."

• How should the use case be described so that the customer and the users can understand it? The use of methodology-specific terminology, such as use case, actor, and signal, might make the text unnecessarily hard to grasp. To make the text easier to read, you might enumerate the actions, or adopt some other strategy. Whatever strategy you use should be specified in the general use-case-modeling guidelines so that you keep it in mind during the entire activity of describing use cases.

Concentrate on describing what is done in the use case, not how specific problems internal to the system should be solved. When working with object models, you may have to complement the description with details about how things work, so do not make the description overly detailed at this point. Describe only what you believe will be stable later on.

If a use case's flow of events has become too encompassing or complex, or if it appears to have parts that are independent of one another, split it into two or more use cases.

When you write the descriptive text, refer to the glossary. As fresh terms evolve from new concepts, include them in the glossary. Do not change the definition of a term without informing the appropriate project members.

The Content of a Flow of Events Description

A flow of events description explores:

• How and when the use case starts.

Example:

"The use case can start when the function 'Administer Order' is activated by a user."

• When the use case interacts with the actors, and what data they exchange.

Example:

"To create a new order, the user activates the function 'New' and then specifies the following mandatory data concerning the order: name, network elements (at least one), and type of measurement function. Optional data can also be specified concerning the order: a comment (a small textual description). The user then activates the function 'Ok,' and a new order is created in the system."

Note: You must be explicit regarding the data exchanged between the actors and the use case; otherwise, the customer and the users will probably not understand the use-case description.

• How and when the use case uses data stored in the system, or stores data in the system.

Example:

"The user activates the function 'Modify' to modify an existing order, and specifies an order number (small integer). The system then initializes an order form with the name of the order, its network elements, and its type of measurement function. This data is retrieved from a secondary storage device."

• How and when the use case ends.

Example:

"The use case ends when the function 'Exit' is activated by the Orderer."

You should also describe odd or exceptional flows of events. An exceptional flow is a subflow of the use case that does not adhere to the use case's normal or basic behavior. This flow may nevertheless be necessary in any complete description of the use case's behavior. A typical example of an exceptional flow is the one given in the first example. If the use case receives some unexpected data (that the actor is not the one expected in that particular context) it terminates. Having the wrong actor and terminating prematurely are not in the typical flow of events.

Other "do's and don'ts" to consider when you describe a use case include:

• Describe the flow of events, not just the use case's functionality or purpose.
• Describe only flows that belong to the use case, not what is going on in other use cases that work in parallel with it.
• Do not mention actors who do not communicate with the use case in question.
• Do not provide too much detail when you describe the use case's interaction with any actor.
• If the order of the subflows described for the use case does not have to be fixed, do not describe it as if it does have to be fixed.
• Use the terms in the common glossary and consider the following in writing the text:
• Use straightforward vocabulary. Don't use a complex term when a simple one will do.
• Write short, concise sentences.
• Avoid adverbs, such as very, more, rather, and the like.
• Use correct punctuation.
• Avoid compound sentences.

For more information, see Guidelines: Use Case, the discussions on contents and style of the flow of events.

Structure the Flow of Events of the Use Case

A use case's flow of events can be divided into several subflows. When the use case is activated the subflows can combine in various ways if the following holds true:

• The use case can proceed from one of several possible paths, depending on the input from a given actor, or the values of some attribute or object. For example, an actor can decide, from several options, what to do next, or, the flow of events may differ if a value is less or greater than a certain value.

Example:

Part of the description of the use case Withdraw Money in an automated teller machine system could be "The amount of money the client wants to withdraw from the account is compared to the balance of the account. If the amount of money exceeds the balance, the client is informed and the use case terminates. Otherwise, the money is withdrawn from the account."

• The use case can perform some subflows in optional sequences.
• The use case can perform several subflows at the same time.

You must describe all these optional or alternative flows. It is recommended that you describe each subflow in a separate supplement to the Flow of Events section, and should be mandatory for the following cases:

• Subflows that occupy a large segment of a given flow of events.
• Exceptional flows of events. This helps the use case's basic flow of events to stand out more clearly.
• Any subflow that can be executed at several intervals in the same flow of events.

If a subflow involves only a minor part of the complete flow of events, it is better to describe it in the body of the text.

Example:

"This use case is activated when the function 'administer order' is called for by either of the actors Orderer or Performance Manager Administrator. If the signal does not come from one of these actors, the use case will terminate the operation and display an appropriate message to the user. However, if the actor is recognized, the use case proceeds by....."

You can illustrate the structure of the flow of events with an activity diagram.

For more information, see Guidelines: Use Case, structure of the flow of events.

Illustrate Relationships with Actors and Other Use Cases

Create use-case diagrams showing the use case and its relationships to actors and other use cases. A diagram of this type functions as a local diagram of the use case, and should be related to it. Note that this kind of local use-case diagram is typically of little value, unless the use case has use-case relationships that need to be explained, or if there is an unusual complexity among the actors involved.

For more information, see Guidelines: Use-Case Diagram.

Describe the Special Requirements of the Use Case

Any requirements that can be related to the use case, but that are not taken into consideration in the Flow of Events of the use case, should be described in the Special Requirements of the use case. Such requirements are likely to be nonfunctional.

For more information, see Guidelines: Use Case, special requirements.

Describe Communication Protocols

Develop a communication protocol if the actor is another system or external hardware. The description of the use case should state if some existing protocol (maybe even a standardized one) is to be used. If the protocol is new, you must fully describe it during object-model development.

Describe Preconditions of the Use Case

A precondition on a use case explains the state the system must be in order for the use case to be possible to start.

Example:

In order for an ATM system to be able to dispense cash, the following preconditions must be satisfied:

• The ATM network must be accessible.
• The ATM must be in a state ready to accept transactions.
• The ATM must have at least some cash on hand that it can dispense.
• The ATM must have enough paper to print a receipt for at least one transaction.

These would all be valid preconditions for the use case Dispense Cash.

Take care to describe the system state; avoid describing the detail of other incidental activities that may have taken place prior to this use case.

Preconditions are not used to create a sequence of use cases. There will never be a case where you have to first perform one use case, then another, in order to have a meaningful flow of events. If you feel there is a need to do this, it is likely that you have decomposed the use-case model too much. Correct this problem by combining the sequentially dependent use cases into a single use case. If this makes the resulting  use case too complex, consider techniques for structuring use cases, as presented in Structure the Flow of Events of the Use Case above, or in the Activity: Structure the Use-Case Model.

For more information, see Guidelines: Use Case, Preconditions and Postconditions.

Describe Postconditions of the Use Case

A postcondition on a use case lists possible states the system can be in at the end of the use case. The system must be in one of those states at the end of the execution of the use case. It is also used to state actions that the system performs at the end of the use case, regardless of what occurred in the use case.

Example:

If the ATM always displays the ‘Welcome’ message at the end of a use case, this could be documented in the postcondition of the use case.

Similarly, if the ATM always closes the customer’s transaction at the end of a use case like Withdraw Cash, regardless of the course of events taken, that fact should be recorded as a postcondition for the use case.

Postconditions are used to reduce the complexity and improve the readability of the flow-of-events of the use case.

Under no circumstances should postconditions be used to create a sequence of use cases. There should never be a case where you have to first perform one use case, then another, in order to have a meaningful flow of events. If you feel a need to do this, the sequentially dependent use cases should be combined into a single use case. If this makes the combined use case too complex, consider techniques for structuring use cases, as presented in Structure the Flow of Events of the Use Case above, or in the Activity: Structure the Use-Case Model.

For more information, see Guidelines: Use Case, Preconditions and Postconditions.

Describe Extension Points

If the use case is to be extended by another use case, you need to describe what the extension points are (see Guidelines: Use Case, extension points).

Evaluate your Results

Review and discuss the use case with the stakeholders, so that they have a clear understanding of the use case and agree on its description.

The use-case description is complete only when it describes everything the use case performs, implements, or otherwise allows from beginning to end. Before you finish, check that the use case exhibits the properties that characterize it as a "good" use case. See checkpoints for use cases and use-case reports in Activity: Review Requirements.