The preceding chapter presented a brief and relatively informal picture of use-case modeling and its goals. As with many techniques, there is a bit more to use-case modeling that needs to be understood before it can be successfully applied.
Use-case modeling is based on a formal technique. This is both a strength and a weakness. It is a strength because we can use the underlying formalisms to improve our precision and provide additional depth and rigor to our modeling activities. It is a weakness because it is easy to (mistakenly) assume that use-case modeling is limited to drawing diagrams and because the formality and terminology can be confusing to people who are new to use cases. The reality is that the formalism provides a framework for the creation of our models and the diagrams provide a nice overview of the system, but the real value of a use case is in the textual use-case descriptions. It is in the use-case descriptions that the majority of the model’s content resides, and it is in the authoring of the use-case descriptions where most effort will be expended.
In this chapter we look at the formal definitions of the fundamental elements of the use-case model, consider the contents of the use-case descriptions, and describe the artifacts that are required in addition to a use-case model to form a complete software requirements specification. This chapter is structured as a reference guide to the basic components of a use-case model and provides the foundation for the subsequent chapters in the book. If you are familiar with the basic building blocks of use-case modeling and want to start writing your own use cases, you can skip to Chapter 3, Establishing the Vision, and come back to this chapter later.
The use-case model is the set of all the use cases, actors, and use-case–actor associations used to describe a particular system. See Figure 2-1. The UML (Unified Modeling Language) defines a model as
a semantically closed abstraction of a subject system
In other words, a model is a complete description of a system from a particular perspective. (Here, complete means self-contained; you don’t need any additional information to understand the model.) In software development, as in many other fields, the models are simplifications of reality, created to enhance understanding of the system being built.
*Ivar Jacobson, et al. Object Oriented Software Engineering: A Use-Case Driven Approach, 1992, ACM Press, introduced all the fundamental concepts of use-case modeling: actors, use cases, use-case models, use-case instances and descriptions, and related concepts. We have based our work on these original concepts, and have focused on applying these concepts rather than introducing new concepts.
Figure 2-1. Use-case model
So, does the use-case model provide a complete description from a requirements perspective? No, it doesn’t. To provide a complete requirements definition, the use-case model must be complemented by other requirements models and artifacts. [1] Use cases place requirements in context and often contain all of the functional requirements of a system. This is the relationship that drives the UML definition of a use-case model:
A model that describes the functional requirements of a system or other classifier in terms of use cases [2]
The use-case model presents a system in terms of its usage. When treated formally, the use-case model describes all the possible ways of using the system. Use-case models can also be used less formally where the set of use cases illustrates the most significant ways of using a system rather than all possible ways of using the system.
The basic building blocks of the use-case model are the actors, the use cases, the relationships between them, and the diagrams in which they appear. In this section we explore these concepts in more depth.
If we refer to our simple telephone system, the subtle distinction between the roles the users can play and the users themselves will become clear. See Figures 2-2 and 2-3.
In the system in Figure 2-2, we have three actors that define roles that will be adopted by the users of the system. Now obviously, several users can play the same role; in fact, the list of people that can take on the role “Caller” or “Callee” is almost unlimited. It is equally obvious that the same person can take on more than one role: In most cases the Customers (the people who actually pay the bills) would be very upset if they could not also be Callers or Callees.
A list of all the actors would be a list of all the different roles that people or other systems could play while interacting with the system. This is subtly different from a list of users, which would be a list of all the different people and other systems that are allowed to interact with the system. Like the term user, the term actor, is often taken to imply a person, especially given its stick-person representation, but few systems operate without interacting with other systems, and many systems interact only with other systems. In the example of the simple telephone system, actors also define roles to be taken by other systems. See Figure 2-4.
Just like the human users of a system, these other systems are beyond the control of the system being built and they impose certain requirements on what the system being built must do.
Now you may be thinking, “If the actors are either humans or systems why are they all represented by stick people?” The answer is that the role defined by the actor is not restricted to being only a human or a system. In Figure 2-3, an answering machine, a fax machine, or a computer could take the role of Callee. The telephone system will treat these in exactly the same way as it would a human Callee, and the Caller may not even be able to tell the difference. When defining actors, it is important to capture their characteristics and any constraints that these place on their interaction with the system rather than making assumptions about the form that the users playing the roles will take.
The more formal UML definition of actor is
A coherent set of roles that users of use cases play when interacting with these use cases
We prefer our more expansive, but compatible definition, as it is less self-referential, and, we hope, more approachable.
Several concepts in this definition in Figure 2-5 are central to a thorough understanding of use cases:
A use case has a description. Use-case modeling provides much more than a simple visual representation of a system and its actors. Like an iceberg, the true extent of the use case is not immediately apparent; the ellipse is just an iconic placeholder for a description of how the system and its actors interact. A use case is mostly text that describes what the system does for a particular actor; the use-case diagram can be thought of as a visual aid to comprehension but does not tell the whole story.
The actor uses the system. When defining and describing use cases, remember that the system provides the use case and the actor starts the use case.
The use cases describe how the system provides value to one or more of the actors. Each use case delivers something of value to at least one of the actors. The concepts of actor goals and the delivery of value to the actors are fundamental to the successful discovery, definition, and application of use cases. The use cases should reflect the goals of the actors and enable, at least in part, their achievement.
For example:
The actors use the system only if it enables them to do something that they want to do.
The actors perform a use case only if doing so helps them achieve one of their goals. The physical manifestation of the goal is the value that the use case delivers to the actor.
A concrete value can be put on the successful performance of a use case. Every use case should have an easily understandable and clearly identifiable value.
From a well-formed set of use cases you can immediately, and intuitively, identify the benefits that the system offers its actors, why the actors would want to use the system, and why you would want to buy or develop it.
The formal UML definition of a use case is
A description of a set of sequences of actions, including variants, that a system performs that yields an observable result of value to a particular actor [3]
We prefer our less formal, and more expansive, expression—it’s easier for people to understand, and therefore easier to apply. The UML definition focuses more on the form that the story described by the use case should take than the underlying purpose of use cases.
Too often, when presented with this kind of formal definition, people get hung up on the meaning of the specific phrases it contains, phrases like sequences of actions. The original meaning with respect to a use case was more informal and simply referred to some sequence of steps that occurred together or not at all. The story metaphor works better for most people; it is simpler and gets to the real essence of the use case—providing a coherent picture of how the system is used and what it does.
The use-case description tells a story of how a system and its actors collaborate to achieve a specific goal. It is a step-by-step description of a particular way of using a system. The structure of a use case is essentially narrative in nature. The story it tells is of how the system and its actors work together to achieve something of significance to the actors involved. This collaboration takes the form of a dialog between the system and its actors, with all the parties contributing to the completion of the use case.
Just like a story, every use case should have a clear beginning (how the actor starts the use case), middle (how the system and actors work together), and end (how the use case is concluded). The use case starts when an actor does something, causing the system to do something in response. This dialog continues (at least) until the system has done something useful for at least one of the actors. The use case is not a complete description of all possible ways that some task is performed, nor does it in any way say anything about how the system is designed or implemented. It’s just a story, although sometimes a very detailed one. As the term suggests, use cases describe typical ways (or cases) of using the system.
Each use case expresses a goal of the actors involved and describes a task that the system, with the assistance of the appropriate actors, will perform. You can get an idea of a use case’s goal simply by observing its name and associations. In the example of our simple telephone system, the use cases clearly represent the goals of a Caller. See Figure 2-6. When treated formally, the collected set of a system’s use cases constitute all the possible ways of using the system.
The system and its actors interact by sending signals or messages to one another. To indicate such interactions, we use a communicate association between the use case where the interaction occurs and the actors involved in the interaction. See Figure 2-7. A use case has at most one communicate association to a specific actor, and an actor has at most one communicate association to a specific use case, no matter how many interactions there are. The complete network of such associations provides a static picture of the communication between the system and its environment.
*There are other associations between actors, and between use cases, that we will discuss later in Chapter 10, Here There Be Dragons. While getting started with use cases, the communicate association is all that we will need to be concerned about.
Figure 2-7. The graphical representations of a communicate association
This view is essential to the understanding of the use-case model. To fully understand the role defined by an actor, you must know in which use cases the actor is involved. To fully understand the scope of a use case, you must know the actors with which it communicates. This is shown by communicate associations between the actors and the use cases.
Actors communicate with the system for many reasons, including:
To start a use case. Use cases are always started by actors.
To ask for some data stored in the system, which the use case then presents to the actor.
To change the data stored in the system by means of a dialog with the system.
To report that something special has happened in the system’s surroundings that the system should be aware of.
One actor initiates a use case. However, after the use case has started, the use case can communicate with several actors. Communicate associations are added between the use case and the supporting actors to show the actors with which the use case communicates.
The communicate association is sometimes mistakenly regarded as representing data flow. It does not. The communicate association represents a dialog between the actor and the system, a kind of communication channel over which data flows in both directions during the dialogue.
Use cases communicate with actors for many reasons, including:
If something special has taken place in the system, an actor might need to be informed.
A use case may need to ask an actor for help in making a decision needed to achieve a goal.
A use case may delegate responsibility to an actor.
It is common, but not always true, that the use case waits for an answer when it has sent a signal to an actor. This time period may be a microsecond, a minute, a day, a year, or any length of time. The details of the communication between the actors and the use case is explicitly described in the use case.
In the simple phone system example, we can see quite clearly how the communication association works. When placing a local call, the Caller communicates with the system to set up the call (by lifting the handset and dialing the number), and the system communicates with the Callee (ringing the Callee’s telephone). The communication is bidirectional, with the telephone system relaying information back to the Caller, thereby enabling the Caller and Callee to communicate directly as soon as the call is established. See Figure 2-8.
In Figure 2-8 which actors start which use cases? From the diagram, it’s not possible to say. By adding arrowheads (optional in the UML), we add clarity to the diagram. See Figure 2-9.
The use of the arrowheads allows us to clearly see who starts the interaction. As shown by Figures 2-8 and 2-9, the diagrams are far more communica-tive when the arrowheads are included, especially when you consider that no meaning is attached to the positioning of the actors on the diagram.
To sum up:
The communicate association shows which actors are involved in which use cases.
Arrowheads indicate which party initiates the interaction; this provides a visual indication of which actor starts the use case.
The use cases, actors, and their associations can be shown on use-case diagrams, such as Figure 2-10. On this diagram, we see an actor called “Customer” and a use case called “Get Call History.” The direction of the arrow shows that the Customer initiates the communication.
A use-case diagram provides a view of a use-case model. Many use-case diagrams can be used to view and provide different perspectives on a single use-case model. A use-case diagram may contain only actors, only use cases, or any combination of the two. Commonly used use-case diagrams include the following:
An overview diagram showing all the use cases and actors
Actor summary diagrams showing a set of conceptually related actors
Actor perspective diagrams showing all the use cases involving an actor
Use-case summary diagrams showing a set of conceptually related use cases
Use-case perspective diagrams illustrating how a use case relates to its actors and other user cases
The diagrams are used to convey who the actors are, what the use cases are, and how they are related. The diagrams are just views into the underlying use-case model; they should not be confused with the use-case model itself.
Each actor and each use case must have a brief description, no more than a few sentences long, that states what it is and why it exists. For example, our simple phone system model generates the following descriptions:
Note
A Caller is any person or external device that uses the system to make a phone call.
A Customer is the person, or authorized representative of the organization, that pays the bills. The Customer is the owner of the account with the telecom’s provider. The Customer is identified by an account number.
The use case Get Call History provides the Customer with the ability to access the details of all of the calls that have been charged to the account. This call history is made available in both text and audio formats.
The purpose of these brief descriptions is to make sure we know what we are talking about, or more important, to make sure that we all agree on the purpose of and the value provided by the use cases. Without a brief description of the actors, we may think we agree on who or what the actors represent when in fact we may have slightly different conceptions. Without a brief description of the use cases, we may not agree on the purpose of the use case, or worse yet, we may think we agree when we do not. In many senses, the diagrams alone are incomplete. Without more explanation, they are ambiguous at best. This is never truer than when a team spends several hours filling white boards and flip charts with use-case diagrams of actors and use cases, forgetting to record the brief descriptions that flow naturally during the brainstorming process. Days later, the diagrams can become a source of confusion if no one remembers whether the use case “Manage Orders” includes order fulfillment or not. Recording brief descriptions prevents this.
The brief descriptions should be at least a sentence or two long, but no more than a short paragraph; anything longer is probably overkill. Keep the descriptions simple and direct. If you cannot come up with a simple and direct description of the actor or use case, then you should reconsider whether you need it—if you can’t define it you may not have a clear idea of what you are trying to achieve. This is always a good first sanity check of the actors and use cases chosen by the modelers. There’s a different vehicle for the more complete description—the use-case description itself.
Use cases are much more than just a named ellipse and a brief description. For each use case there will also be a use-case description where the full story of the use case is told.
The use-case descriptions provide the substance of the use-case model, and they are the basis for most of the use-case modeling work. The graphical representations we have seen so far are useful in positioning and scoping the system to be built, but they only provide a very general overview of what it will do—they represent merely the tip of the use-case modeling iceberg. More than 90% of the use-case model lies beneath the surface, in the textual use-case descriptions themselves.
Ever since Ivar Jacobson first popularized use cases, [4] the industry has seen many different approaches to the writing of use case descriptions. Each approach recommends a different writing style and level of detail and content. Alistair Cockburn has described 18 different styles of use-case description that he has seen in use on projects. [5] One of these styles is the one proposed by Jacobson in his book and subsequently adopted by the Rational Unified Process. We have found it to be the most effective, and so it is the one we present here.
The use-case description is where the details of the use case, sometimes referred to as the use-case properties, are defined. The UML defines many properties for a use case. Here we concentrate on the key properties of the use case: the flow of events, preconditions, and postconditions. It is important that you have an understanding of the principles behind these key use-case properties before you start attempting to identify your system’s use cases. This will help you to find an appropriate set of use cases for your system. We explore the full set of use-case properties in Chapter 7, The Structure and Contents of a Use Case.
The most important part of the use-case description is the Flow of Events. This is the section where the story is told. Although the flow of events is only considered a single use-case property by the UML, it has a well-defined and significant structure.
The flow of events provides the description of how the system and actors collaborate to deliver the value promised by the use case, including all the things that can prevent the value from being achieved. It acts as a map of the territory for people interested in what the system will do. Unlike a pictorial map, or flowchart, it does not merge all of the paths together into a single picture. The storylike nature of the use case leads to a much more narrative format where the normal route is described first, followed by a description of alternative routes. The use-case descriptions focus on describing each path individually as a unique flow of events.
The approach taken is the one that people use when providing directions to others:
Instructions to Get to Kurt’s Party
Turn right out of the car park. Carry straight on down the main road for five miles until you reach the crossroads. Take the first right and then the second left. The house is the third on the left. Don’t forget to bring something to drink.
If the main road is busy, you can turn off by the pub and follow the winding country lane, but normally this will take a lot longer.
If you need to get some alcohol on the way, there is a wine shop in the shopping center opposite the pub. If the wine shop is shut then the pub will do carry outs. If you can’t get any alcohol at all then just come anyway.
First the expected, successful route is described, followed by the alternative routes and variations on the normal route. This is exactly the way that use-case descriptions are structured. There is a bit more formality in the way that the text is formatted and the actor and system interactions are described, but the basic principle is the same. First the expected flow of events is described, and then the alternatives and exceptions are detailed. The normal, expected route is called the basic flow. All the other routes, regardless of whether they end in success or failure, are called alternative flows.
We will now start to look at how an actual use-case description is constructed. The focus here is on how the flow of events is structured and how the different kinds of flow are related to each other. To this end, the descriptions are kept at the outline level—we will look at how to complete the use-case descriptions in Chapter 8, Writing Use-Case Descriptions: An Overview, and Chapter 9, Writing Use-Case Descriptions: Revisited. The example we will use is the Place Local Call use case from the Simple Telephone System example.
The basic flow is the description of the normal, expected path through the use case (sometimes referred to as the happy day scenario). This is the path taken by most of the users most of the time. The basic flow for the Place Local Call use case could look like this:
Use Case—Place Local Call
Basic Flow
The use case starts when the Caller lifts the receiver.
The Caller enters the number to be called.
The system connects the Caller’s phone to the requested device.
The call is made.
The connection is terminated.
The details of the call are recorded.
The use case ends.
Remember that this is just an outline, not the full use-case description. The assumption behind the basic flow is that it will successfully enable the actor to achieve the goal.
Because of the circumstances that may prevail at the time the use case is being performed, other, less common elements of behavior may be required to extend the flow of events.
If the basic flow represents the normal route to success, the alternative flows can be considered as detours. Some of these occur at the actor’s discretion, perhaps providing an easier or more scenic route. Others occur at the system’s discretion, perhaps enforcing a higher degree of security, exploiting the system’s knowledge of the user’s preferences, or handling special cases. For example, the variant and optional behavior in the Place Local Call use case could include the following alternative flows:
Line Busy
If the Callee’s line is in use, the system rings the busy tone. The Caller then replaces the handset and the use case ends.
Note: the descriptive text is included for explanatory purposes only and is not supposed to represent how the alternative flows of events themselves would be written.
When you consider all of the possible optional and variant behavior that could be defined for a system, it is easy to become overwhelmed with the available possibilities and forget to focus on the system’s core, essential behavior. One of the benefits of the flow of events’ structure is that all of this information is kept independent of the use case’s basic flow. The basic flow defines the core behavior; the alternative flows complement this. Some of these are essential to the success of the system, but many are extraneous “bells and whistles” and wish-list materials. The structure of the flow of events allows us to address each flow on its own merits and maintain our focus on the system’s essential behavior.
The most common kinds of alternative flows are those that describe the errors that can occur and how they should be handled.
In our experience 60 to 80 percent of all software is written to handle exception and error conditions. Use cases are no exception to this rule; it is very common for 60 to 80 percent of the text in the use-case descriptions to describe what errors can occur, when they can occur, and how they are handled. For example, in the Place Local Call use case, the exceptional and error handling behavior could include the following alternative flows:
When you start to consider all the things that could go wrong at each step in the basic flow, you quickly generate a long list of error-related alternative flows. This is one of the reasons that the use-case descriptions adopt the additive structure described here. This allows the basic flow to be kept simple and avoids swamping it with descriptions of all the exceptions that can occur. This structure also helps you write the use cases; plan the project; and scope, test, analyze, design, and implement the system.
As a use case becomes more detailed, the text of the individual flow of events can become unwieldy and overlong. This is true for even the simplest systems. Generally, as a flow of events grows in size, it naturally falls into a series of smaller, self-contained subsections, each with its own clearly identifiable purpose. For example, the Place Local Call use case includes the sentence:
This requires elaboration into a set of individual actions and responses:
Note
The system analyzes the digits of the entered number and determines the network address of Callee.
The system determines whether a connection can be established between Caller and Callee.
The system establishes the connection.
The system rings Callee’s phone.
This expansion can lead to the thread of the flow becoming lost in the details. In cases like this, the individual sections of the flow can be broken out into self-contained sections of text called subflows. These are given their own title and are presented as a miniflow of events.
Subflow—Connect Caller and Callee
The system analyzes the digits of the entered number and determines the network address of Callee.
The system determines whether a connection can be established between Caller and Callee.
The system establishes the connection.
The system rings Callee’s phone.
They are then included in the original flow of events by their title:
Note
The Caller enters the number to be called.
Perform connect Caller and Callee.
The system maintains the connection until either the Caller or the Callee terminates the call.
This name of the subflow could be entered into the electronic format as a hyperlink or in a different text style. What is important is that you can see that this is a placeholder and not the actual text from the flow of events.
Remember that the key to writing effective use cases is to focus on communication. It is only worth splitting up the flow of events into subflows if they make the use case itself easier to read.
Another side effect of developing the use-case descriptions is that the identified alternatives and subflows will start to have alternatives, exceptions, and subflows of their own. This can even be seen in the simple example, “Instructions to Get to Kurt’s Party”: “. . . If the wine shop is shut then the pub will do carry outs” or “. . . If you can’t get any alcohol at all then just come anyway.” One of the powerful things about the way that use cases are structured is that we are always dealing with the same, simple constructs. As we saw in the preceding example, defining subflows is very easy. A section of the flow of events is extracted and given a separate section and a heading. It can then be included in any other flow of events in the use case by simply placing its title in the text and providing a pointer to it. Defining alternative flows is also very simple. We just have to define when and where these flows may occur, what the alternative flow of events is, and where the original flow of events is resumed if the use case is not explicitly ended by the alternative flow. When writing basic and alternative flows, it is important that the basic flow of events is written independently of the alternative and that it has no knowledge of the alternative flows; it must make complete sense without reference to the alternatives. The alternative flow knows the details of when and where it is applicable as opposed to the original flow. It inserts itself into the basic flow when a particular condition is true. See Figure 2-11.
Figure 2-11. The typical structure of the flow of events. The straight arrow represents the basic flow of events, and the curves represent alternative paths in relation to the basic flow. Some alternative paths return to the basic flow of events, whereas others end the use case.
If the subflow or alternative flow is being applied to another subflow or alternative flow, then the rules are the same except that the original flow of events is no longer the basic flow. Figure 2-11 illustrates the typical structure of a flow of events.
We shall look at these relationships in more detail in Chapter 7, The Structure and Contents of a Use Case.
Or “how long is a piece of string?” [6]
Typically, use-case descriptions are 5 to 15 pages long. We have seen some as short as half a page and others as long as 30 pages. The key thing to remember is that each use-case description has to be long enough to clearly tell its story. It has to explain the basic and alternative flows in a form that satisfies all of the stakeholders. For a very simple, data-capture use case with few or no alternatives, this can be a few sentences long, and in other cases—say for a complex interaction involving many actors with many alternatives—this will require a lot of text. Even in a use case as simple as one describing how to withdraw cash from an automatic teller machine, we have seen as many as 22 alternative flows identified. If the alternatives and exceptions themselves have lots of alternatives and exceptions, this will again lead to longer use-case descriptions.
Use-case descriptions should be as long as it takes to tell the full story. As we shall see in Chapter 10, Here There Be Dragons, there are various techniques we can use to help to manage the textual descriptions of the use cases. However, these techniques do not really change the underlying size and complexity of the use-case model, they just move text from one use case to another and should be used sparingly, if at all.
We have met some who might say that detailed use cases are unnecessary. To this complaint we would respond “is the behavior required?” If the system must do the things described, then you’ll have to capture the requirements at some point, and a use case offers a number of advantages over other means of description.
To elaborate on our map analogy a little more, we can see that the description provided by the flow of events is of no use unless you are at the correct starting point. The Instructions to Kurt’s Party are of little or no use to you unless you are either in the car park or know how to get there.
In the use-case model, this starting point is represented by the states of the actor(s) and the system at the time the use case is to be started. This statement is known as a precondition. For example, the Place Local Call use case could be given the following precondition:
Preconditions are not a description of the event, or trigger, that starts the use case, but rather a statement of the conditions under which the use case is applicable. The precondition is necessary for the use case to be started but is not sufficient to start the use case. The use case must still be started by an actor but can only be started when the precondition is true. In the example, the precondition clearly states that no local calls can be made when there is no carrier signal available.
In addition to using preconditions to clarify when the use case is available, it is often very useful to also specify the state of the system when the use case ends. This is done by the use of postconditions.
A postcondition for a use case should be true regardless of which alternative flows were executed; it should not be true only for the basic flow. If something could fail, you would cover that in the postcondition by describing the states in which the system can be when the use case is completed. For example, the Place Local Call use case could be given the following postcondition:
Note
The connection between the Caller and Callee has been terminated and all call details have been recorded.
This may seem trivial, but we know that as alternative flows are added to the use case, they can often lead to the system being left in unacceptable states. For example, one of our colleagues was once phoned by a friend who was using a prototype next-generation mobile phone. Unfortunately, the new system didn’t allow the termination of the connection from the Callee’s phone. When the initial call was over and the prototype phone was returned to its owner’s pocket, the call button was accidentally pressed and the phone redialed our colleague’s number. He answered the call and hung up when nobody replied to his greeting. This should have ended the call, and, by implication, the use case, but unfortunately it did not terminate the connection between the two phones. He was able to repeatedly pick up the phone receiver and listen to events at his friend’s house, such as the playing of music, and so on. The end result was that our colleague’s phone was left in an unusable state for the next few days as a consequence of receiving a call from a badly behaved system.
The clear definition of the use case’s postcondition can go a long way toward alleviating this kind of problem, because it provides a clear statement of the responsibilities of each use case and defines the state the system must be left in when the flow of events completes.
Preconditions and postconditions can be powerful tools when initially defining and scoping the use cases. You first define when the use case is applicable, using a precondition, and what the use case is supposed to achieve, using a postcondition. You can then describe how to reach the postcondition from the precondition by writing the flow of events. See Figure 2-12.
Figure 2-12. A precondition is the state of the system and its surroundings that is required before the use case can be started. A postcondition is the state the system can be in after the use case has ended.
Care should be taken when using pre- and postconditions: Only use them if the use-case audience perceives this as adding value. We introduce them here to illustrate that use cases don’t have to start from square one all the time. We revisit preconditions and postconditions in more detail in Chapter 7, The Structure and Contents of a Use Case.
To sum up:
Ninety percent of the use-case model is beneath the surface shown by the use-case diagrams; the diagrams themselves are merely overviews of system behavior.
The most important part of a use case is the detailed description.
The most important part of the use-case description is the flow of events.
The flow of events has a well-defined structure based around the concepts of the basic and alternative flows.
The basic flow describes the normal way of achieving the goals of the use case.
Alternative flows extend the basic flow to cater to variants and exceptions.
Subflows can be used to make a complex flow of events easier to read.
Use cases do not have to start from square one but can make assumptions about the state of the system at the time that they start.
Preconditions and postconditions can be used to clarify the scope of a use case and document any assumptions the use-case author has made about the state of the system.
We have alluded repeatedly to the insufficiency of use cases alone to fully specify a system’s requirements. As we observed in Chapter 1, additional requirements-related documentation is needed to provide a full software requirements specification. In this section, we take a brief look at these supporting artifacts, their format, and the role they play.
A model that describes the essential concepts of the problem domain and environment to be addressed is required to support all use-case modeling endeavors. If we do not have a good set of shared definitions related to the problem to be solved, then we do not have a firm foundation for the construction of our use cases. This model usually takes one of three forms:
A simple, textual glossary. The problem domain is described by a simple set of textual definitions and is presented as a traditional glossary of terms. The glossary in Appendix C illustrates the format and level of detail that are usually used.
A formal domain model. An in-depth model is required and so a UML domain model is produced. [7] This visual model of the objects in the problem domain is more formal than the glossary. A domain model is particularly important if there are complex relationships among the problem domain objects. These become much clearer if they are shown visually.
A class diagram or similar technique is used to represent the domain model. In this case, the domain model replaces the textual glossary entirely and contains all of the definitions required to understand the use cases and their supporting documentation.
A textual glossary with illustrative domain model(s). You may build a domain model to complement and further visualize the terms in the glossary. In this case, the domain model is only a partial representation of the glossary, containing only the visualization of a subset of the more complicated concepts.
The important thing to remember is that the purpose and role of these different representations is the same: to define the important terms used in the project. Whatever its format, the focus of the model is on capturing the common vocabulary to be used in all textual descriptions of the system, especially those terms and concepts used in the use-case and actor descriptions.
In general, we use the term glossary to refer to this model. [8] The term domain model refers to the optional, more formal, UML representation of the glossary. Whatever its format, this model is the project’s conceptual model of the world and represents the project team’s understanding of the problem domain. Project members use the glossary primarily to understand terms that are specific to the project. However, it is important to many other activities:
Understanding the Context of the Project. Stakeholders use the glossary to understand the problem domain as well as the terminology used in the project and its documentation.
Creating Use Cases and Other Requirements Documentation. Analysts use the glossary to capture the terms that are specific to the problem being solved, to clearly define business rules, and to ensure that requirement specifications make correct and consistent use of the terms. As we shall see in Chapter 8, Writing Use-Case Descriptions: An Overview, the glossary is one of the most effective tools we have to help us manage detail and complexity when writing use-case descriptions.
Designing the Resulting System. Developers use the glossary to understand each other’s work and make use of the terminology when designing and implementing the system.
Producing the User Documentation. Course developers and technical writers use the glossary to construct training material and documentation using recognized terminology.
To find common terms in the problem domain, consider the terms used by the stakeholders and the development team’s general knowledge of the system to be built. Focus on terms that describe the following:
The concepts and objects used in the organization’s daily work or in the system’s expected operating environment. In many cases, a list of concepts of this kind already exists in the form of an organizational or industry glossary.
Real-world objects of which the system needs to be aware. These objects occur naturally and include such things as a person, car, dog, bottle, aircraft, passenger, reservation, or letter.
Events of which the system needs to be aware. An event is a point in time or an incident that the system must be aware of, such as a meeting or an error.
Each term is typically described as a noun, with a definition. Terms should be in the singular (“bill” and “account,” not “bills” and “accounts”). All interested parties should agree on definitions for the terms. Each term should be given a clear and concise definition and be used consistently throughout the use-case model. It is important to remember that, from a use-case modeling perspective, the only terms that require definition are those used in the use-case and actor descriptions. This relationship helps us to constrain any domain modeling that we undertake to the definitions required to define the solution to the problem at hand.
Remember, each glossary term should be used somewhere in the actor or use-case descriptions. If it isn’t, it may imply that an actor or use case is missing or that the existing use cases are not complete. It is more likely, though, that the term is not included because it is not needed. In that case, you should remove it from the glossary.
The glossary may also be used to capture the terminology of the process and techniques used when discussing how the software is to be developed (for example, the definitions of actor and use case). Although useful to the project, these terms are not essential to the well-being of the use-case model.
In projects that do not include business modeling or formal domain modeling, the glossary is the only artifact used to capture the business domain of the project. If you are building your use-case model in an environment where comprehensive business modeling has already been undertaken, then all of the terms required should already have been captured. If the level of detail required to support the use-case model is not there, then you must either update the business models to include it or develop a complementary glossary to complete the documentation of the problem domain.
Conceptually, there should be only one glossary for the system. This artifact is important to all stakeholders, especially when they need to understand or use terms that are specific to the project or the problem domain. It defines the common vocabulary to be used in all the textual descriptions of the system, especially in the use-case descriptions, and its use simplifies description production and comprehension. It also helps to avoid misunderstandings among the stakeholders about the use and meaning of terms. Regardless of its format, it must be easily accessible to all the project’s stakeholders.
The production and maintenance of a comprehensive glossary is essential to any successful large-scale use-case modeling exercise. Only the most trivial of systems can be described without the production of an effective and widely used glossary. For most projects, we recommend capturing the glossary as a set of textual definitions, with additional, partial UML domain models to add rigor where required. The glossary should also be augmented with examples and illustrations where these help to clarify and illuminate the terms adopted. The situation to avoid is the one where the same concept is defined both in the glossary and in a domain model. When this occurs, problems ensue because it is inevitable that the two different definitions will diverge.
The role of the glossary in the production of good use-case descriptions is one of the major concepts addressed in Chapter 9, Writing Use-Case Descriptions: Revisited.
Not all of a system’s requirements fit nicely in the use-case descriptions of the system. Many requirements apply to many use cases and do not benefit from being forced into the narrative structure of the use-case descriptions. In the Rational Unified Process there is a special artifact for capturing these requirements: the Supplementary Specification. The requirements captured in these artifacts are referred to as supplementary requirements.
The supplementary requirements capture the system requirements that are not readily captured in the use cases of the use-case model. Such requirements include
Legal and regulatory requirements
Application development standards
The quality attributes of the system to be built, including usability, reliability, performance, and supportability requirements
The constraints placed on the design and implementation of the system, such as operating systems, environments, compatibility requirements, programming languages, and other design constraints
Other requirements that don’t fit naturally into the use cases
The term supplementary often makes people think that these requirements are not as important as those captured in the use cases and in many cases, people assume that they don’t need to have them at all. This is a major mistake; many projects have failed because project members have forgotten to focus on some of the major supplementary specifications. In many cases, the supplementary specifications form the major part of a system’s critical success criteria.
For example, one of us was once called in to try to turn around a project that was having difficulties passing the most basic user-acceptance tests. The target market for this particular system was a large customer with 300 to 500 simultaneous users. On entry into the user-acceptance test, the system would only support eight simultaneous users. One of the major supplementary specifications, and success criteria, for the project had been completely ignored by the developers, who instead had focused all of their efforts on the system’s user interface. As the testing progressed and other problem areas came to light, it became apparent that the developers had failed to investigate any of the requirements beyond the scope of the most basic flow of events. Not surprisingly, the system was never deployed.
As this example illustrates, the supplementary specifications are particularly good at focusing on and capturing the nonfunctional requirements of the system. This makes them a perfect complement to the use cases, which are generally more functional in nature. The difference is not purely between the functional and nonfunctional requirements. Use cases are often the best place to capture many of the nonfunctional requirements, especially those that apply only within the context of a single use case. The supplementary specification is often the best place to capture many of the functional requirements, especially those that are global in nature or do not vary from one use case to the next.
The correct way to think of the relationship between the use cases and the supplementary specifications is one of balance. See Figure 2-13. The balance will vary depending on how dynamic the system to be built needs to be. Where there is a lot of interaction between the system and its actors (for example, an automatic teller machine), the majority of the requirements will be captured in the use cases, with just a few global, nonfunctional requirements captured in the supplementary specifications. In other cases where the amount of interaction is small (for example, a compiler), the majority of the requirements will be captured in the supplementary specification, with a just a few use cases illustrating the goals of, and the interaction with, the user.
If the focus is purely on the use cases, then the overall quality objectives of the system are often ignored. If the focus is purely on the supplementary specifications then the real objectives of the system, in terms of the facilities it offers the users, are often overlooked. In our experience, all systems benefit from being considered from both perspectives and producing both a use-case model and a set of supplementary specifications. The trick is to keep the two in balance and not be lured into focusing all the project’s time and effort into one form of specification to the detriment of the other (and usually the project as a whole).
The concept of supplementary requirements maintained outside the use-case model and special requirements, which can be maintained inside the use-case descriptions themselves, are often confused. [9] Special requirements are additional requirements that complement, and only make sense in the context of, individual use cases. They are sometimes captured in their own section within the use-case description, but we prefer to capture them alongside the other supplementary specifications and trace them to the use cases.
The most common form for capturing the supplementary and special requirements is in the form of traditional, declarative requirement statements. These generally take the form of statements indicating what the system shall or must do. For example, the simple telephone system could be given the following supplementary specifications:
Note
There shall be no more than 10 percent signal loss on all communications.
It shall take no longer than 0.1 seconds to make a connection.
Just as a balance must be struck between the requirements that are captured in the use cases and those that are captured in the supplementary specification, balance also must be achieved between those that are captured in the narrative, conversational format of the flow of events and those that are captured in the more traditional declarative format. Care must be taken to choose the right tools for the job. For those adopting use-case techniques, a good grounding in other requirements specification techniques is always an advantage. These techniques will help when deciding where and how extensively to use use cases. Remember all these techniques are purely a means to an end and not an end in themselves.
There are many techniques available for the elicitation and documentation of these requirements. In subsequent chapters we discuss how these requirements are related to use cases and provide some further hints and tips on how to document them. Here, our focus is on how to create and write good use cases rather than the broader, more general topic of requirements management. [10]
In this chapter we have looked at the definition and role of the basic building blocks of a use-case model. You should now have a better understanding of actors, use cases, the communicate associations, and the use-case diagrams on which they appear and realize that most of the value of the use cases, and consequently the effort required to produce a use-case model, is in the use-case descriptions themselves.
There is more to the components of a use-case model than the elements visible on the use-case diagrams. As well as the visible elements of the use-case model—the actors, use cases, and their associations—a good understanding of the key properties of the use case is also required.
The most important property of a use case is the flow of events. This is where the story is told. Within the flow of events there are three kinds of flows:
The basic flow, the most important part of the flow of events, which describes the normal way of achieving the use-case’s goal.
Alternative flows, which extend the basic flow to allow for variants and exceptions.
Subflows (subsections of the other flows), which are extracted to make the original flows easier to read. These are self-contained, titled mini-flows that are included in the original flows by reference to their title.
This structure is important because it allows us to elaborate on all of the variant, optional, and error-handling behavior without losing focus on the essential behavior required of the system.
To be effective, the use-case model must be supported by other requirements-related artifacts:
The glossary or problem domain model, which is a model of the concepts inherent in the problem domain to be addressed. This is essential to any successful, large-scale use-case modeling exercise.
Supplementary specifications, an artifact capturing those requirements that do not readily fit into the use-case model. A balance must be maintained between the mainly functional, narrative-driven requirements captured by the use case’s flow of events and the declarative, mainly nonfunctional requirements captured in the supplementary specification and the special requirements.
Use-case modeling is based on a formal technique. Like any modeling technique, it is important to understand what the technique is telling you, but it is also important not to overinterpret its application and let the process degenerate into pointless discussions about whether the perfect set of use cases has been attained. Just as a class diagram of a software system can tell you something about the major elements and their relationships but next to nothing about the behavior of the system, a use-case diagram tells you about the relationships between the actors and use cases but very little about what the system does. For that we have to dig into the details.
[1] These are described in the Supporting Artifacts section later.
[2] Although this book focuses on using use cases to describe systems, they can be used anywhere that there is a clear boundary.
[3] Booch, The Unified Modeling Language User Guide, 1999, Addison-Wesley, p. 468.
[4] See Jacobson, et al., Object-Oriented Software Engineering: A Use-Case Driven Approach, 1992, ACM Press.
[5] See A. Cockburn, “Goals and Use Cases,” Journal of Object-Oriented Programming, 10(5), Sept., 1997.
[6] Answer: It should be as long as necessary to accomplish the task at hand.
[7] The domain model is a subset of the “Business Object Model,” as described in Jacobson et al., The Object Advantage. If a Business Object Model does not exist, some business modeling may need to be undertaken to understand the business and its processes. The alternative is to “guess” at the business objects, which may be acceptable for very simple business processes but which will be inadequate for more complex business processes.
[8] Various other terms are used for what is essentially a model of the world where the system will be deployed. The name adopted is often driven by the source and method used to produce the model. We have seen it referred to as the essential model, the business object model, the conceptual model, the business information model, and the high-level logical data model. When considered in relationship to the use-case model, all of these models play the role of the glossary in that they define the terminology to be used when describing the system’s interaction with the world.
[9] The UML defines a use-case property “special requirements” as “a textual description that collects all requirements, such as nonfunctional requirements, on the use case, that are not considered in the use-case model, but that need to be taken care of during design or implementation.”
[10] For more detail on how to capture and document the supplementary and special requirements, we recommend Leffingwell and Widrig, Managing Software Requirements, 2000, Addison-Wesley.