Five Step UML, Step 1: Define

In this step, you will define of the requirements of your system as viewed by actors: people and computer systems outside of your system itself. To do this we are going to create symbols to represent all the features that are required, symbols we call use cases. A use case is a sample of how the system is used by an actor to accomplish some goal. Behind the diagram, a use case consists of a description of what the actor wants to accomplish, the steps involved in accomplishing it, the conditions that will be necessary for the steps to be performed, the expected outcome, and other actors that are involved in making these features happen. All of this information is represented on a use case diagram as one use case. The use case diagram then will show an actor and the use cases that actor needs to perform. This is the diagram we will draw in this stop of the Five Step UML tutorial.

To create a use case diagram in Tablet UML, click the Use Case Diagram button: .

To begin, select one actor who would use your system. If you’re not sure where to start, it’s always easy is to start with “customer”. Now as soon as you do, your customer (the person who wants you to build the system) will tell you, “No, no, we’re a hotel, so we call them guests.” Or perhaps your customer calls them clients, patrons, users, visitors, or some other term. That’s fine. That’s part of what you want to accomplish by drawing these diagrams: you want to learn all about how your customer views their system and their business. A large part of that is learning to draw the diagrams and getting their feedback in response. When you draw a diagram and they tell you that it’s wrong, you learn more about what’s right. So in this case, put down “customer”, and see what your user thinks about the term.

To add an actor to a use case diagram, draw a circle. Tablet UML will use that circle as the head of the stick figure that represents the actor.

To name the actor, tap on the name, and a naming window will appear, including a pen input panel. This will allow you write or type the actor name. (You may also select another content editing mode to edit the name directly within the diagram.)

Now when you put the customer down as an actor, you do so by drawing a stick figure to represent that customer. Underneath that you write the name, “customer”. This represents the person or persons who will act as a customer for the system. Next, identify some things that the customer wants your system to do for them within this problem domain. List these features on the use case diagram as use cases: ellipses that each contain within them the name of a feature. Keep the name brief, and save details for a description that lies behind the use case inside the model. (This is an example of the Model Rule: you’re never just drawing pretty pictures; you’re creating a model, using the pretty pictures as your user interface to create the model. In other words, each diagram in the UML model reflects just one view – perhaps one very limited view – of everything that you consider the UML model itself. And so you may have things which are known in the model but are not necessarily represented in any particular diagram. In this particular case, we know that a use case really consists of much more than just the name of a feature; and we will store that “much more” inside the model in a piece of the model that describes the use case, and that’s attached to the use case on this diagram.)

And now draw an association from the customer actor to each use case. An association can be navigable, meaning that it starts with one of the participants in the association and ends with the other. In this example, it would be navigable from the customer actor to the customers requested use case. You show that the communication or the association is navigable by drawing an arrow from the participant that sees and requests to the participant that is seen or performs the request. In this case, you would draw an arrow from the customer to the use case.

(Note: some modelers prefer not to show the association as navigable with an arrow. They prefer to draw it simply as a line from actor to use case. Their reasons for preferring this are simple: they believe that showing an arrow for navigability for a use case indicates that you have already decided how the use case is to be implemented: who is requesting it and who is responding. They believe that, especially during early analysis, it may be premature to decide that. Maybe, rather then the actor requesting that we perform some function, we decide that it needs to be performed, and we ask the actor to provide us with information. While I understand this concern, I think it is far more common that we know that a particular actor is requesting a particular feature or function to be performed. In those cases where we’d do know that the actor will be doing work that we’ve requested because we decided it is time for this action, I believe it will be the case that we will be doing so because some other actor requested something and we need the help of this actor. Or perhaps it would be because a particular event has happened or particular timer has expired; but I consider the event or the timer to be actors for the purposes of our use case diagrams. So in other words, it is my practice to always show each use case being initialized or requested by some actor, and therefore navigable arrow flows from that actor to that use case. And if we do find that other actors are participating use case, then we draw an outgoing arrow from the use case to that actor to indicate that that actor is participating in the U.S. case. There are occasions when I find that we do not quite know whether an actor is initiating a use case or responding to it; and in those cases I agree: we should use a simple association line, not an navigable association arrow. But I believe those are rare, and that it is better to decide how your customer expects the system to behave, and draw arrow from those actors to those use cases that reflect what your customer expects.

To add a use case to a use case diagram, draw an ellipse. (If your ellipse is not noticeably wider than it is tall, Tablet UML may see it as a circle, and may draw an actor instead of a use case. See Erasing for details on how to erase things that you draw by mistake.)

To name the use case, tap on the name, and a naming window will appear, including a pen input panel. This will allow you write or type the use case name. (You may also select another content editing mode to edit the name directly within the diagram.)

To add a navigable association from an actor to a use case, draw an arrow.

To add a simple association from an actor to a use case, draw a line.

If Tablet UML has difficulty recognizing your associations, it may be because the Tablet PC API doesn't recognize diagonal lines, only horizontal or vertical. You should try to draw connectors in Tablet UML as close to horizontal or vertical as possible. But if an association - or anything in a diagram - isn't recognized, you can manually recognize it. Switch to selection mode; select the item; and select the right element type from the manual recognition dropdown list.

You can also perform a manual recognition without switching modes. You can do this via the context menu. Right-click the stroke that you want to recognize, and a menu of possible element types will appear. If your Tablet PC pen does not have a barrel button, you can "right-click" via the press-and-hold gesture. If your Tablet PC pen does have a barrel button, you can "right-click" by holding down the barrel button as you tap the screen. (See your Tablet PC help for details on how to "right-click" with a pen.)

If your Tablet PC pen has a barrel button, there's an even easier way to ensure that Tablet UML recognizes what you draw: hold down the barrel button as you draw. When you lift the Tablet PC pen, the recognition menu will appear, and will let you decide how to recognize what you drew.

And so you’ll draw a number of use cases that represent what this first actor, customer, wants to accomplish. The number should be relatively small: one or two would not be surprising, ten to twelve could be a sign of trouble and perhaps you need a new actor to represent the actual customer that needs those use cases. An actor should be defined by a handful of functions that actor wants to perform. If this does not seem to match your expectations, you need to consider what an actor represents in terms the UML model: the actor is not one particular individual, or even one particular job title. The actor is a role, a part that the person plays in relation to the system. And therefore two things are true that would not seem to be true if you thought of the actor is an individual: one person may play multiple roles and therefore be represented by multiple actors within the model; and one actor, one role, may be fulfilled by a more than one person at various times throughout the existence of the system. When you think of an actor as a role, it becomes easier to see that an actor should have a handful of use cases, not many hands full.

Now that you have created a diagram for one actor with a number of use cases and communications from the actor to that use cases, discuss each use case. Consider for each use case whether another actor might have to participate to provide some sort of information or service as part of the use case. Consider whether some actor may be required to authorize the use case, to provide missing information, to acknowledge an assignment, to record a transaction, to inform the main actor about the results of the operation, or to participate in any number of other ways. It needn’t be the case that the actor participates every single time that use case is performed: if the actor is involved under any circumstances, that’s good enough for a use case diagram. (We’ll show when and how the actor participates in more detail in Step 2.) When you identify new actors that participate in a particular use case, add those actors to the diagram (if they’re not already there), and draw a communication (i.e., a navigable association, or an arrow) from the use case to each participating actor. You may find it convenient to label these outgoing arrow indicate what the system is asking each actor to do as part of the use case. You may not find participating actors for every use case, but it’s a good exercise to ask about them for every use case as part of your analysis. Besides learning more about each use case in so doing, you will also learn about new actors involved in the system.

And what you do with new actors? Why, you draw a use case diagram for each one, of course. Each actor should have one use case diagram that focuses strictly on what that particular actor requires the system to do. Now sometimes, you’ll find that there are actors that really only do work for the system, but never request work from the system. That’s to be expected. You can keep those empty diagrams and document that they have no individual use cases of their own, or you can discard those diagrams as not telling you any new information.

For the purposes of this tutorial, you’ll want to draw at least two use case diagrams for two actors: one to get comfortable with the concept, and one to get practice at the concept. Of course, if you’re analyzing a real system for production purposes, you would want to draw a diagram for every single actor involved in the system. And you would want to pursue the use cases for each one in much more depth. But for now, for a tutorial, you can get by by just concentrating on the use cases of two actors.

But now let’s think about the system in a slightly different way. Let’s think about the information each actor uses or requires as part of each use case, and also about the things within the physical world which must be described and maintained by performing each use case. Let’s even think about units of information that will be maintained by the system as part of each use case. All of these objects – physical objects and data objects– fall into categories, or classes as they’re called in most objec oriented languages. So another part of our use case view of the system can be what classes are involved in each particular use case. So sometimes it’s useful to draw another set of use case diagrams: diagrams which show an actor, the use cases expect by the actor, and the classes involved in those use cases. To some people, this is premature analysis: they believe that identifying classes is largely part of the design of the system, not part of the analysis of the requirements. But the fact is that classes of things exist within the problem domain itself, not just in the code; and that’s what I’m encouraging you to capture: not classes at the programmatic level of detail, but classes at the conceptual level expected by the end users of the system. But just because they’re not “code classes” doesn’t mean we can’t use UML to capture them! Even though they are not programmatic classes, they are still classes which can be described by attributes (that is, things that describe them and make one object of the class different from another object of the same class) and operations (that is, things that an object of the class can do). And so, as another part of the tutorial, you may want to take each actor and draw a second use case diagram for that actor, one which is focused on the domain objects involved in its use cases. To do this, create the new use case diagram for an actor, add the actor to the diagram, add the use cases that that actor requires, and add the communications from the actor to the use cases. And then add the classes that represent the domain objects. A class icon in UML is a rectangle broken into three compartments: a top compartment with the class’s name; a middle compartment listing of all of the attributes of the class; and a bottom compartment listing all of the operations of the class. When you create a class from scratch, the top compartment with the name will be the largest. As you add attributes and operations, of course, those compartments will get larger. And remember again the model rule: we won’t show all of the information we know within the model inside of every single diagram. You might choose – no, more often will choose – to hide the attributes and operations of classes whenever you’re more interested in how classes relate to other parts the model than in the details of how each class is built. So although we’re going to show classes on the use case diagram to represent the domain objects, we may not show attributes and operations at all. Or perhaps we’ll show attributes and operations that are only relevant to the particular use cases were showing on the same diagram.

To add an existing actor to the new use case diagram in Tablet UML, find the actor in the model tree, click down on the actor, drag the actor onto the diagram, and release. The actor should appear, drawn in a default size.

There's a fast way to add an actor's use cases to the new use case diagram: right-click the actor to show its context menu, select the actor name in the menu, and then select Add Related Elements. Everything in the model that's directly related to the actor will be added to the diagram.

When you add the elements in this fashion, you'll need to rearrange them. To do this: switch to selection mode; select an icon to move; and drag it to a new position.

After you have moved the icons, you may also want to rearrange the associations. To move an association end: switch to selection mode; click down on the association end; and drag it to a new position. To add a bend to an association: switch to selection mode; click down at the point you want to bend; and drag it to a new position. To remove a bend from an association: switch to selection mode; click down on the bend; and drag it back to straight.

So after you’ve added the actors, the communications, and the use cases, look at each use case and ask yourself:

• Is there any object in the physical world that is represented within this use case?
• Is there any data are maintained by the system that is modified or otherwise updated within this use case? Such data might include employee records, schedules, orders, logs, or any other sort of thing which is data within the computer only, but which is data that the user cares to see and edit. Don’t worry about programmatic mechanisms: the user doesn’t want to see those, only the classes which represent concepts in the problem domain. For instance, if you had a collection object which consisted of a way to maintain and gather customer orders, then the customer very likely would not care about that collection object itself: that is a programmatic concept, not part of their understanding of the problem. But the orders themselves? Those the customer care is about. Those are domain objects.

After deciding what classes might be involved in a use case, add those classes on to the new use case diagram as rectangles broken into three compartments with the class name in the top compartment. Then draw communications from the use case to each such class icon, and label these communications with the description of what the use case is doing with or changing or requesting from the class.

To add a class to a use case diagram in Tablet UML, draw a rectangle. Tablet UML will use this as the basis for a class icon.

To name the class, tap on the name, and a naming window will appear, including a pen input panel. This will allow you write or type the class name.

To add or edit attributes of a class, tap the attribute compartment. This will open a new window where you can define attributes, including names, types, visibilities, and more.

To add or edit operations of a class, tap the operation compartment. This will open a new window where you can define operations, including names, types, visibilities, parameters, and more.

 (You may also select another content editing mode to edit the name and the attributes and operations directly within the diagram.)

To show or hide attributes and operations of a class, right-click the class to show its context menu, select the class name in the menu, and then select:

• Show All Attributes
• Hide All Attributes
• Show Selected Attributes...: Provides a check list of attributes. Check to show, uncheck to hide.
• Show All Operations
• Hide All Operations
• Show Selected Operations...: Provides a check list of operation. Check to show, uncheck to hide.

Repeat this for each use case for each actor, and you will have a very good perception of what information is being used by the system to satisfy the requirements of each particular actor. A final step in the problem definition here would be to organize the domain classes that you have identified. To do so you, would want to draw class diagrams: diagrams which show how one class is related to or involved with other classes. So create a class diagram, and add the icon for each class to it. (If you find you have many such classes, you may want to create smaller, separate, more focused diagrams for particular groupings of related classes. How many classes is too many classes for one diagram? There is no absolute answer; but a standard answer for too much for any given diagram is 7±2. In other words, if you have fewer than five things on a diagram, many of your users will wonder why you bothered to draw it. It’s just too simple, and they don’t see much benefit from the picture. On the other hand, if you have many more than nine things on the diagram, many of your users will no longer be able to pick out individual things within the diagram, because they are spending too much time trying to understand how the whole thing fits together. So although I wouldn’t say nine is absolutely too many, nine is where you should start questioning the diagram. Nineteen means you’ve probably already gone too far. And twenty-nine and is far, far too far. Keep the number smaller than, say, fifteen, and you should be all right most the time. And then, if you find people are having trouble understanding it, you know you’ve gone too far, and you need to break up the diagram.) Once you have a class diagram with a number of related classes on it, you need to show how the classes are associated with or related to each other. We’ll talk about this a lot more in Step Five, Repeat; but for now, think of classes being associated with each other when one class may need information from another class. To keep matters simple, we’ll only worry about two relationships between classes for now: association and navigable association. As we saw with actors and use cases, a simple association is a line between two classes which indicates, “These two classes work together in some way.” A navigable association is an arrow from class A to class B which says, “Class A has an object of class B, and knows how to tell it to do things.” So look at your diagram full of related classes, and the associations and navigable associations, and ensure that they make sense with what you know so far. You may also find "implied" classes that make sense from your understanding of the problem, but which haven't appeared in any use case diagram yet. Add these as well, as in our sample diagrams.

You can take these diagrams, show them to your end users, and ask for their feedback to see if you have correctly identified the relationships between categories of things within their domain. And in so doing, you’ll learn what’s right, you’ll learn what’s wrong, and you’ll learn why some things are wrong and be a step closer to right.

To create a class diagram in Tablet UML, click the Class Diagram button: .

To add a new class to a class diagram, draw a rectangle. Tablet UML will use this as the basis for a class icon.

To add an existing class to the class diagram, find the class in the model tree, click down on the class, drag the class onto the diagram, and release. The class should appear, drawn in a default size.

But you’re not quite done with your analysis of features: so far, all you’ve done is draw pictures. That may not be enough. Again, as we discussed under use cases, a use case is more than an ellipse on a page. A use case is a lot of information to answer questions about what a feature means when a user requests it and how we’re going to do the work. Now some of that more detailed information is going to be captured in Step Two: Refine. We’ll do so with diagrams, primarily activity diagrams. But some of that information can best be captured as simple text (and perhaps symbols and drawings and so on). So anything you can already tell about a use case or about an actor or about a domain class should be entered into a model, not in any particular diagram, but in the notes and information that lie behind the diagrams. If you’re maintaining your model by hand with paper and pencil, this can be best accomplished by creating a sheet of paper or a word processing document or a note card or some other place to hold the information, one for each actor, each use case, or each domain class.