2.1. Capturing a System RequirementEnough theory for now; let's take a look at a simple example. Suppose we're defining requirements for a weblog content management system (CMS).
2.1.1. Outside Your System: ActorsAn actor is drawn in UML notation using either a "stick man" or a stereotyped box (see "Stereotypes" in Chapter 1) and is labeled with an appropriate name, as shown in Figure 2-2. Figure 2-2 captures the Administrator role as it is described in Requirement A.1. The system that is being modeled is the CMS; the requirement's description indicates Figure 2-2. Requirement A.1 contains an Administrator actor that interacts with the system to create a blog accountthat the Administrator interacts with the system to create a new blogger's account. The Administrator interacts with the system and is not part of the system; therefore, the Administrator is defined as an actor.
Deciding what is and what is not an actor is tricky and is something best learned by experience. Until you've gained some of that experience, Figure 2-3 shows a simple technique for analyzing a "thing" that you've found in your requirements and how to decide whether it is an actor or not. Actors don't have to be actual people. While an actor might be a person, it could also be a third party's system, such as in a business-to-business (B2B) application. Think of an actor as a black box: you cannot change an actor and you are not interested in how it works, but it must interact with your system. 2.1.1.1. Tricky actorsNot all actors are obvious external systems or people that interact with your system. An example of a common tricky actor is the system clock. The name alone implies that the clock is part of the system, but is it really? The system clock comes into play when it invokes some behavior within your system. It is hard to determine whether the system clock is an actor because the clock is not clearly outside of your system. As it turns out, the system clock is often best described as an actor because it is not something that you can influence. Additionally, describing the clock as an actor will help when demonstrating that your system needs to perform a task based on the current time. Figure 2-3. Here are a couple of questions to ask yourself when trying to identify an actorIt is also tempting to focus on just the users of your systems as the actors in your model, but don't forget about other people, such as auditors, installers, maintainers, upgraders, and so on. If you focus on only the obvious users of your system, then you might forget about some of these other stakeholders, and that can be very dangerous! Those actors may have a veto ("We can't certify this system without proof that the data has not been tampered with") or they may have to enforce important nonfunctional requirements, such as an upgrade in a 10-minute system downtime window and an upgrade without shutting the system down, etc. If these actors are ignored, these important functions of your system won't be documented, and you risk ending up with a worthless system. 2.1.1.2. Refining actorsWhen going through the process of capturing all of the actors that interact with your system, you will find that some actors are related to each other, as shown in Figure 2-4. The Administrator actor is really a special kind of system user. To show that an administrator can do whatever a regular user can do (with some extra additions), a generalization arrow is used. For more on generalization and the generalization arrow, see Chapter 5. Figure 2-4. Showing that an administrator is a special kind of user2.1.2. Use CasesOnce you have captured an initial set of actors that interact with your system, you can assemble the exact model of those interactions. The next step is to find cases where the system is being used to complete a specific job for an actoruse cases, in fact. Use cases can be identified from your user's requirements. This is where those wordy, blurry definitions in the user requirements document should be distilled into a clear set of jobs for your system.
A use case, or job, might be as simple as allowing the user to log in or as complex as executing a distributed transaction across multiple global databases. The important thing to remember is that a use casefrom the user's perspectiveis a complete use of the system; there is some interaction with the system, as well as some output from that interaction. For example, Requirement A.1 describes one main use of the CMS: to create a new blog account. Figure 2-5 shows how this interaction is captured as a use case. Figure 2-5. A use case in UML is drawn as an oval with a name that describes the interaction that it representsAfter all that build-up, you might have expected a use case to be a complex piece of notation. Instead, all you get is an oval! The notation for a use case is very simple and often hides its importance in capturing system concerns. Don't be deceived; the use case is probably the single most powerful construct in UML to make sure your system does what it is supposed to.
2.1.3. Communication LinesAt this point, we've identified a use case and an actor, but how do we show that the Administrator actor participates in the Create a new Blog Account use case? The answer is by using communication lines . A communication line connects an actor and a use case to show the actor participating in the use case. In this example, the Administrator actor is involved in the Create a new Blog Account use case; this is shown in Figure 2-6 by adding a communication line. Figure 2-6. A communication line joins the Administrator actor to the "Create a new Blog Account" use case; the Administrator is involved in the interaction that the use case representsThis simple example shows a communication line between only one actor and only one use case. There is potential to have any number of actors involved in a use case. There is no theoretical limit to the number of actors that can participate in a use case. To show a collection of actors participating in a use case, all you have to do is draw a communication line from each of the participating actors to the use case oval, as shown in Figure 2-7. Figure 2-7. The login use case interacts with three actors during its executionSometimes UML diagrams will have communication lines with navigability; for example, a diagram with an arrow at one end will show the flow of information between the actor and the use case, or show who starts the use case. Although this notation is not really a crime in UML terms, it's not a very good use of communication lines. The purpose of a communication line is to show that an actor is simply involved in a use case, not to imply an information exchange in any particular direction or that the actor starts the use case. That type of information is contained within a use case's detailed description, therefore it doesn't make sense to apply navigation to communication lines. For more on use cases and descriptions, see "Use Case Descriptions," later in this chapter. 2.1.4. System BoundariesAlthough there is an implicit separation between actors (external to your system) and use cases (internal to your system) that marks your system's boundary, UML does provide another small piece of notation if you want to make things crystal clear. To show your system's boundary on a use case diagram, draw a box around all of the use cases but keep the actors outside of the box. It's also good practice to name your box after the system you are developing, as shown for the CMS in Figure 2-8. Figure 2-8. The Administrator actor is located outside of the CMS, explicitly showning that the system boundary box use cases must fall within the system boundary box, since it doesn't make sense to have a use case outside of your system's boundary2.1.5. Use Case DescriptionsA diagram showing your use cases and actors may be a nice starting point, but it does not provide enough detail for your system designers to actually understand exactly how the system's concerns will be met. How can a system designer understand who the most important actor is from the use case notation alone? What steps are involved in the use case? The best way to express this important information is in the form of a text-based descriptionevery use case should be accompanied by one. There are no hard and fast rules as to what exactly goes into a use case description according to UML, but some example types of information are shown in Table 2-1.
Table 2-2 shows an example use case description for the Create a new Blog Account use case and provides a handy template for your own descriptions.
The format and content in Table 2-2 is only an example, but it's worth remembering that use case descriptions and the information that they contain are more than just extra information to accompany the use case diagrams. In fact, a use case's description completes the use case; without a description a use case is, well, not very useful. The description in Table 2-2 was reasonably straightforward, but something's not quite right when you compare the description to the original use case diagram (shown in Figure 2-9; although the use case description mentions two actors, this use case diagram shows only one). Figure 2-9. Ensuring that your use case diagrams match the more detailed use case descriptions is criticalThe use case description has identified a new actor, the Author Credentials Database. By creating a complete description of the Create a new Blog Account use case, it becomes clear that this actor is missing.
You will often find that items are missing from your diagrams as more detail goes into your use case descriptions. The same goes for any aspect of your model: the more detail you put in, the more you might have to go back and correct what you did before. This is what iterative system development is all about. Don't be too worried though, this refinement of your model is a good thing. With each iteration of development you will (hopefully!) get a better and more accurate model of your system. Figure 2-10 shows the corrected use case diagram incorporating the new Author Credentials Database actor. Figure 2-10. Bring the use case diagram in sync with the use case's description by adding the Author Credentials Database actor
|