Section 2.1. Capturing a System Requirement


2.1. Capturing a System Requirement

Enough theory for now; let's take a look at a simple example. Suppose we're defining requirements for a weblog content management system (CMS).

Requirement A.1

The content management system shall allow an administrator to create a new blog account, provided the personal details of the new blogger are verified using the author credentials database.

There's actually no specific "best way" to start analyzing Requirement A.1, but one useful first step is to look at the things that interact with your system. In use cases, these external things are called actors .


The terms shall and should have a special and exact meaning when it comes to requirements. A shall requirement must be fulfilled; if the feature that implements a shall requirement is not in the final system, then the system does not meet this requirement. A should requirement implies that the requirement is not critical to the system working but is still desirable. If a system's development is running into problems that will cause delivery delays, then it's often the should requirements that are sacrificed first.


Blog Features

Weblogs, commonly referred to as blogs, originally started out as privately maintained web pages for authors to write about anything. These days, blogs are usually packaged into an overall CMS. Bloggers submit new entries to the system, administrators allocate blogging accounts, and the systems typically incorporate advanced features, such as RSS feeds. A well-publicized blog can attract thousands of readers (see O'Reilly's blogging site at http://weblogs.oreillynet.com).


2.1.1. Outside Your System: Actors

An 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 account


that 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.

What's in a Name?

It's actually worth being very careful when naming your actors. The best approach is to use a name that can be understood by both your customer and your system designers. Wherever possible, use the original term for the actor as identified within your customer's requirements; that way, at least your use cases will be familiar to your customers. This approach also lets system designers get comfortable with the system's unique context.


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 actors

Not 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 actor


It 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 actors

When 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 user


2.1.2. Use Cases

Once 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.

Remember, if use cases are truly requirements, then they must have very clear pass/fail criteria. The developer, the tester, the technical writer, and the user must explicitly know whether the system fulfils the use case or not.


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 represents


After 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.

What Makes a Good Use Case?

Experience will help you determine when you have a good use case, but there is a rule of thumb that can be used to specify a use case:

A use case is something that provides some measurable result to the user or an external system.

Any piece of system behavior that meets this simple test is likely to be a good candidate for a use case.


2.1.3. Communication Lines

At 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 represents


This 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 execution


Sometimes 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 Boundaries

Although 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 boundary


2.1.5. Use Case Descriptions

A 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-1. Some types of information that you can include in your use case descriptions

Use case description detail

What the detail means and why it is useful

Related Requirements

Some indication as to which requirements this use case partially or completely fulfills.

Goal In Context

The use case's place within the system and why this use case is important.

Preconditions

What needs to happen before the use case can be executed.

Successful End Condition

What the system's condition should be if the use case executes successfully.

Failed End Condition

What the system's condition should be if the use case fails to execute successfully.

Primary Actors

The main actors that participate in the use case. Often includes the actors that trigger or directly receive information from a use case's execution.

Secondary Actors

Actors that participate but are not the main players in a use case's execution.

Trigger

The event triggered by an actor that causes the use case to execute.

Main Flow

The place to describe each of the important steps in a use case's normal execution.

Extensions

A description of any alternative steps from the ones described in the Main Flow.


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.

Table 2-2. A complete use case description for the "Create a new Blog Account" use case

Use case name

Create a new Blog Account

Related Requirements

Requirement A.1.

Goal In Context

A new or existing author requests a new blog account from the Administrator.

Preconditions

The system is limited to recognized authors and so the author needs to have appropriate proof of identity.

Successful End Condition

A new blog account is created for the author.

Failed End Condition

The application for a new blog account is rejected.

Primary Actors

Administrator.

 

Secondary Actors

Author Credentials Database.

 

Trigger

The Administrator asks the CMS to create a new blog account.

Main Flow

Step

Action

 

1

The Administrator asks the system to create a new blog account.

 

2

The Administrator selects an account type.

 

3

The Administrator enters the author's details.

 

4

The author's details are verified using the Author Credentials Database.

 

5

The new blog account is created.

 

6

A summary of the new blog account's details are emailed to the author.

Extensions

Step

Branching Action

 

4.1

The Author Credentials Database does not verify the author's details.

 

4.2

The author's new blog account application is rejected.


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 critical


The 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.

If you can, it's worth reviewing your use case model with your users as much as possible to ensure that you have captured all of the key uses of your system and that nothing has been missed.


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


How Many Use Cases Should Your Model Have?

There is no set rule for the number of use cases that your use case model should contain for a given system. The number of use cases depends on the of the jobs that your system has to do according to the requirements. This means that for a particular system, you might only need two use cases or you might need hundreds.

It is more important that you have the right use cases, rather than worrying about the amount you have. As with most things in system modeling, the best way to get your use cases right is to get used to applying them; experience will teach you what is right for your own systems.





Learning UML 2.0
Learning UML 2.0
ISBN: 0596009828
EAN: 2147483647
Year: 2007
Pages: 175

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net