Chapter 13. Develop Instance Scenarios

We have seen that use cases provide an abstract view of the activities that occur between an actor and the system. When use cases model these activities, however, they do not describe how specific instances of the interactions will occur. Use case instances can be thought of as paper prototypes of how a use case will execute in a given situation. In this sense they can assist in drawing out and validating requirements from the stakeholders. Use case instances are another way of exploring the details, alternatives, and exceptions in the use cases. They are also a nice transition into acceptance and system test cases.

A use case describes the abstract behaviors that happen when, for example, an applicant submits a loan request. In this use case, a generalized description of the behaviors is provided in the flow of events. What the use case does not describe, for example, is what happens when a specific individual applies for a specific loan of a specific amount. The use case does not specify what exactly occurs when Joe Smith submits a loan request for $100,000 on November 10, 2002. This would be considered one instance of how the use case would execute under a given set of conditions.

Use Case Instances Model Specific Executions of a Use Case

A use case provides a generalized representation or template of behaviors that occur when a specific event happens. During requirements analysis, documenting system requirements without having to document what would happen in every possible execution of the use cases (an infinite number) can be an advantage. Just as with other modeling techniques applied during analysis, such as conceptual object models, process models, and data models, the specific values or execution normally are not as important to capture as the abstractions of how things occur or what things are.

During analysis, it can sometimes be useful to look at how specific instances of use cases execute, especially in situations when defining the specific instance provides a valuable addition to the use case model. To capture a specific execution of a use case, UML provides a concept called a use case instance.

Booch describes an abstraction as a representation of the “ideal essence of a thing,” whereas an instance represents a “concrete manifestation” [Booch 1999]. The use case instance is a description of what occurs in a specific situation. UML 1.3 defines a use case instance as a “performance of a use case, initiated by a message instance from an instance of an actor. As a response the use-case instance performs a sequence of actions as specified by the use case, like communicating with actor instances, not necessarily only the initiating one.” In other literature and in practice, use case instances are sometimes also referred to as instance scenarios, analysis scenarios, or just scenarios.

Use case instances can be used during the use case modeling effort to draw out and add more detail to the behaviors in a use case flow of events. Use case instances are also commonly used to capture and understand behavioral variations in a use case. Use case instances can be created in an informal manner or captured very formally with specific input and output parameters.

Use Cases Are to Object Classes as Use Case Instances Are to Object Instances

The relationship between use cases and use case instances is similar to the relationship between an object class and its object instances. An object class is a description of a set of objects (instances) that share the same attributes, operations, relationships, and semantics. So each object instance of a class has specific values for its attributes and relationships. The same can be said for the use case and its instances; the use case is a description of the behaviors, and the instances provide specific executions of the behaviors.

Graphically, UML can be used to represent the relationship between a use case and use case instance as a dependency relationship with the <<instanceOf>> (Figure 13-1). Whereas use cases provide a set of generalized preconditions and postconditions and a flow of events, a use case instance describes what happens if a certain set of input values and environmental conditions occur and a specific set of decisions are made during the execution of the use case. Just as with object classes and object instances, use case instances do not stand alone; they always depend on a use case. Since a specific set of input values will result in the execution of specific path through the use case flow of events, a specific set of output values will also occur. The use case instance can also document these output parameters.

Figure 13-1. Use case instances depend on a use case

Why Create Use Case Instances?

Use case instances complement and supplement the use cases in a number of ways.

• They provide a paper prototype of how a use case will execute in a given situation.

• They draw out and validate requirements from the stakeholders.

• They provide another way of exploring the details, alternatives, and exceptions in the use cases.

• They act as a transition into acceptance and system test cases.

Within a use case modeling effort, we have seen use case instances utilized

• in a very informal manner to draw out and validate requirements with the end user and customer,

• in a more formal manner to discuss and document additional details as well as alternates and exceptions,

• as a starting point to develop acceptance and system test cases, and

• as a means to drive incremental development.

In this chapter we discuss applying use case instances both informally and formally. Testing is discussed in detail in Chapter 14. Using them in an incremental development effort is discussed in Chapter 19.

An excellent discussion of both use case instances (referred to as analysis scenarios) and their place in a development effort can be found in Developing Object-Oriented Software: An Experience-Based Approach [IBM 1997]. The book states:

Consider the use case model and analysis scenarios (use case instances) as a complementary pair of work products. The use case model identifies system boundaries, external agents, and top-level system requirements; the analysis scenarios elaborate the requirements and tease out the behavioral variations of the system.

We should state now that there is very little agreement on a “standard” approach to applying use case instances. They are typically applied in a very different manner on different projects. Our intent is not to survey every approach or to specify a standard approach but to present several ways of proceeding with use case instances. Additional information on use case instances and scenarios can be found in a number of references, including Weidenhaupt [1998], Hsia [1994], and Potts [1994].

Use Case Instances Can Be Applied Informally

End users sometimes have a hard time describing or validating behaviors that are too abstract. Users may find it easier to think about and describe what they want in concrete terms rather than in the abstract terms. There is a software development saying that when it comes to defining a system’s requirements, stakeholders “know it when they see it.” So, developers build prototypes to provide concrete examples to the stakeholders, with the intention of drawing out difficult new requirements early in development. Users and customers often like to express requirements in terms of examples or, conversely, to review and validate the requirements presented as examples. In an informal approach, use case instances can be presented as examples of how a use case will execute.

Figure 13-2 shows an informal use case instance for submitting a loan request. This instance represents one possible execution of the use case. In this example, an instance of the applicant actor named Joe Smith submits a loan request for $20,000 with a “normal” set of circumstances surrounding the loan submission: The applicant’s credit is good, all needed information about the applicant is available, and the loan amount is well within bank policy for approval. Another use case instance, presented in Figure 13-3, represents a situation where there are specific credit problems. Finally, in Figure 13-4, a use case instance represents the situation of an applicant submitting incomplete information on the loan application.

Figure 13-2. Use case instance for a normal execution of the “Submit loan request” use case

Figure 13-3. Use case instance for an insufficient credit situation of the “Submit loan request” use case

Figure 13-4. Use case instance for incomplete information on the application of the “Submit loan request” use case

The informal approach to representing use case instances is useful in both gathering requirements from users and presenting examples to them of how a use case would execute under certain conditions. When taking the informal approach, create a use case instance that represents a normal execution and, if needed, several other use cases instances that represent major variations. Just as in prototyping, focus on areas of the requirements that are unknown or at high risk.

When presenting use cases in this manner, keep the template and descriptions simple and very basic. Remember your audience: If more formal use case instances are needed, they can be documented in another format. Don’t overwhelm the user with a large number of informal use cases; the purpose is to present information in a manner that is quickly grasped. Also, be careful in selecting the use cases to be represented in this manner. This technique supplements the use cases; it does not replace them.

When developing informal use case instances, we find it useful to explicitly describe the flow (at a high level) to help capture the user’s focus. Consider using high-level graphics to represent selected use case instances with the users.

Normally, the actual use cases are developed first during the analysis; then, based on this analysis result, selected use cases are chosen to be presented with instances. However, on one project, we developed several informal use case instances first, before developing the actual use cases, since the users felt much more comfortable with this approach and were able to more easily express their needs. We then generalized the use case instances into use cases.

We have also used this technique very, very informally during a use case brain-storming session. We verbally walked through a use case model with different execution paths or instances that could possibly occur. Also, modelers can create instances if they get “stuck” in a use case to help move it along. In these situations, you may not need to write the instances down. This technique proved useful in quickly validating the use cases in a workshop group.

Use Cases Can Be Applied More Formally

While informal use case instances are a useful technique for presenting basic behaviors and attributes to users, a more rigorous approach can be taken for capturing in detail the behaviors, inputs, environmental factors, and alternatives associated with one specific execution of the use case. Use case instances are extremely useful in highlighting and documenting specific details of both the basic use case flow of events and the alternative flows. In this manner they can complement extend relationships, alternative flows, and conditional logic.

We have stressed the pros and cons of capturing a large amount of detailed information in use cases versus leaving them at a higher level (see Chapter 19 for more discussion on this topic). Since use cases are abstract, documenting the details and all the possible alternatives within a use case flow of events or through extend a relationship can be unwieldy. One approach that addresses this problem and provides robustness to the use case model is documenting basic behaviors in the use cases and utilizing the use case instances to flesh out additional details, alternatives, and exceptions. This approach helps keep the use case flow of events “clean” and understandable.

For these purposes, use case instances can be categorized as primary or secondary. Primary use case instances, also referred to as “sunny day” use case instances, reflect what normally happens when things go as planned. Secondary use case instances, also referred to as “rainy day” use case instances, document what happens when something goes wrong or occurs unexpectedly. For example, what happens if the loan amount exceeds the bank’s loan policy guidelines or the credit bureau does not have a record of the customer? Secondary use case instances are used to document alternatives and exceptions.

Layout of a Use Case Instance Description

There is no standard way of representing a use case instance, but several common pieces of information can be captured. These can include the fields described in the use case instance template in Figure 13-5.

Figure 13-5. Use case instance template

A warning on creating detailed instance flows: While they can be very useful for capturing detailed business logic, they can also be very difficult to maintain and keep up to date throughout the development effort. As a tool for drawing out requirements, instances are very effective, but be aware that updating and maintaining a large number of use case instances during a large project development effort can be a nightmare.

Finding and Creating Use Case Instances

The best place to start creating formal use case instances is obviously with a use case. We like to first select use cases that are central to the system and/or that will be implemented first during the development effort. As previously mentioned, the goal is to develop prototypical representations of how the system will execute. As with dynamic or executable prototypes, the entire system is not normally prototyped.

There is no set number of use case instances to create, but keep in mind that there is an infinite number of possible execution paths. It is neither desirable nor useful to document a very large number. We like to target no more than five to seven use case instances per major use case selected for insurance modeling. If significant questions continue to rise after creating several use case instances, you can create additional use case instances to address them. This is not design, so don’t try to test every possibility. Look for specific situations that change requirements or are architecturally significant. During requirements analysis, focus on only prototype concrete instances of things that you are unsure of or that carry a risk if they are not defined in detail. Also, if you are performing incremental/iterative development, focus on behavioral sequences that are of the highest development priority.

When developing use case instances in this manner, look at the use case’s preconditions and postconditions to determine meaningful examples of inputs, starting with input parameters and environmental factors that are “sunny day.” For example, in the “ATM withdraw funds” use case, a sunny day assumption would be that the customer wishes to withdraw $300 from a checking account, that the account currently contains $1,000, and that the customer has not exceeded the daily withdrawal limit.

Do several sunny day instances, focusing on the boundaries—for example, the customer attempting to withdraw all the cash or just the minimum amount. Look for environmental conditions that might impact the execution of the instance.

Then, select several major alternatives/exceptions to model. For example, what happens if the customer tries to withdraw $1,200 from a bank account with only $1,000 in it? What happens if the customer tries the same thing but has overdraft protection? As you can see, the use case instances (see Figures 13-6 through 13-9) can model instances of the submit loan request use case’s flow of events and its alternatives. A single use case instance can also model a combination of a use case and its include and extend relationships.

Figure 13-6. Use case instance: Positive evaluation of loan request

Figure 13-7. Use case instance: Negative evaluation of loan request

Figure 13-8. Use case instance: Additional information needed

Figure 13-9. Use case instance: Marginal request of loan request

Some developers like to document the major alternative flows with high-level extend relationships or alternative flows and flesh out the details with use case instances. We’ve also seen developers replace extend relationship and alternative flows entirely with a set of use case instances that model the key alternatives.

What we really like about use case instances is their ability to draw out and model requirements without driving the use case into too much detail. By the way, the UML activity diagrams presented in Chapter 9 can also be used to represent the use case instance.

Conclusion

If use cases tell a broad story, then use cases instances fill in the details based on a specific set of conditions. And, whereas a use case models the abstract, a use case instance describes how specific parameters such as input information, a specific instance of an actor role, environmental factors, and decision points affect the execution of a use case flow of events.

Applying use case instances can be informal, to help elicit and express requirements to high-level stakeholders, or formal, to help model detailed requirements to complement the use cases and/or replace extend relationships when modeling alternatives.

Instance scenarios are a useful tool for understanding the implications of a use case. Instance scenarios can be developed at any time in the use case modeling process to help understand or clarify ambiguous requirements. In addition, use case instances are also a very good starting point for outlining acceptance and system test cases because they document expected input and expected outputs.