In this article, we build on our ability to represent straight forward business relationships in UML class diagrams. These relationships describe how two objects are related to each other. Representing relationships in class diagrams helps us to better understand the domain and helps us to uncover hidden requirements. Occasionally, we have to deal with more complex relationships that involve more than two objects to properly describe. This does not happen as frequently, but when it does, our modeling efforts are more likely to uncover overlooked requirements. In this article we learn how to describe relationships that involve more than two objects.

Catching Up On UML Class Diagrams

If you navigated to this page first, it is the fifth in a series introducing UML Class Diagrams for requirements elicitation.

1. Uncovering Requirements With UML Class Diagrams Part 1: Discusses how to represent objects and entities from a business perspective.
2. Uncovering Requirements With UML Class Diagrams Part 2: Discusses simple relationships between objects or entities.
3. Uncovering Requirements With UML Class Diagrams Part 3: Discusses combining objects into collections and concepts.
4. Uncovering Requirements With UML Class Diagrams Part 4: Defines generalization (inheritance) and how to use it.
5. Uncovering Requirements With UML Class Diagrams Part 5: This article

Jump back to the other articles and get up to speed if you need. We’ll wait for you here. As a reminder, in this series, we’re specifically focusing on using UML class diagrams for uncovering requirements – as part of analysis, not design. We’re talking about what the business needs, not how the solution will work.

Understanding Details About The Relationship

One reason you may want to deal with more than two objects is obvious only after you change your way of thinking. So far, you’ve been thinking about objects (classes) and relationships (associations). Sometimes, when you need to understand the details of the relationship, you should think about the relationship as an object. It is both a relationship AND an object. And you draw this with an association class. We’ll walk through an example that illustrates the idea clearly, then we’ll look at the steps needed to create a relationship that is also an object.

Consider that you are gathering requirements to support software for tracking court cases – perhaps a mashup site that combines the latest public record lawsuits with entries from LinkedIn (my profile) and Crunchbase.

As part of your requirements gathering, you need to understand how these court cases work – so you start with a class diagram.

First – identify the main players in the lawsuits:

Both a plaintiff and a defendant are litigants, as they are involved in lawsuits.

That represents a simple relationship. A plaintiff sues one or more defendants. When you show this diagram to one of your stakeholders, she likes that you captured that one plaintiff can sue more than one defendants. She also likes that you can determine “who is the plaintiff suing” as well as “who is suing a given defendant.”

You point out one small problem – it is not clear if the plaintiff can only sue multiple defendants one-at-a-time, or if the plaintiff can sue multiple defendants in the same lawsuit. You get the answer (multiple defendants can be sued at the same time), and as you start to scratch your head about how to represent it, your stakeholder interrupts (they do that):

“We need to be able to show lawsuits with a “most recent” view, and a “largest” (in dollar amount) view on the main page of the site!” You realize that your diagram doesn’t work, and you make a note to yourself about the multiple-defendants issue.
You need a way to capture information about the suit. Suddenly, instead of a verb (sues), you need a noun (suit). You need to reason about the relationship. So you update your class diagram.

Your updated diagram now shows that a single plaintiff, in the context of a single suit, can sue multiple defendants. You also capture that you need to know the trial date and the dollar amount of the suit. You erase that note to yourself, because your diagram now clearly indicates that one lawsuit involves multiple defendants. You make another note to yourself that it is not clear if a plaintiff can be involved in more than one suit with the same defendants (he can). You’ll deal with that later.

What you’ve drawn is something (the suit) that is both a relationship and an object. In UML class diagrams, this is called an association class.

Creating An Association Class in a Visio UML Class Diagram

To create an association class, you use the Association Class shape in the Visio UML Static Structure stencil.

Drag the association class onto the page.

By now, you realize that you need to suppress the end names in the display. Right click on the shape and select “Shape Display Options…”:

And disable the display of the end names:

Now your shape will look like this:

You can manipulate the shape and its placement in two different ways. You can select and drag either line end (to connect to another shape in the diagram)

Or you can drag the “class” portion (the box) of the shape to wherever you want to place it. [Note: When you drag the class, it looks like you are disconnecting the line from the shapes and messing everything up. It is not happening. When you release the mouse button, the class will be where you put it, and the line will still be where it was before.] There is a dashed-line that connects the class (the box) to the association (the line). Visio automatically updates that for you – you never have to worry about it. In fact, if you don’t like it where it is, you can’t do anything about it either.

You could use the rotate-handle (the green circle on top) to rotate the box, but please don’t. Class diagrams, by convention, are drawn with everything aligned with the page. To get the line on top, just drag the line ends above the shape (or drag the shape below the line ends).

You use the same rules for showing directions with an association class that you do with a regular association. If the business needs to think in one direction – “Who has the plaintiff sued?” then show that arrow. If the business wants to think in the other direction – “Who has sued a particular defendant?” then show the opposite arrow too.

Even More Complex Relationships

The cool shape above lets you draw a three-way relationship. It is most handy when you need to understand something about the relationship itself – treating the relationship as a noun instead of a verb. You can create relationships in UML class diagrams that involve more than three objects. These are called N-Ary Associations. The “N-Ary” part is geek-speak for “binary, trinary, quaternary, etc” – any number is valid.

Earlier, we glossed over one question – “Can a single plaintiff, related to multiple defendants in the context of a single suit, also be related to those defendants by another suit?” You can use an n-ary association to depict this.

In the Visio UML Static Structure stencil, select the N-Ary Link shape.

Drag it onto the page

It looks a bit like a decision diamond from a flow chart, but with handles. Drag it to where you want it to be in your diagram and then start connecting the line ends to the related classes.

After you’ve connected the ends (or before, but after is easier), double click on the shape to bring up the properties dialog.

You’ll see three “Link Ends” – just rename them to show the multiplicity of the connections. You will end up with a final diagram that shows:

One plaintiff can sue one or more defendants in one or more suits. You could (and I will) argue that this is even more ambiguous than the previous diagram.

• Who does the suing? Is it the plaintiff, the defendant, or the suit itself?
• Are they even suing? Perhaps the relationship is just “they are all in the same room at the same time.”
• When a plaintiff sues multiple defendants, is it one defendant per suit, with multiple suits? Can it be? Must it be?

Personally, I never use an n-ary association when modeling complex relationships. I much prefer the association class.

A Simpler But Busier Alternative UML Class Diagram

You never have to use an association class. You can always represent the situation with three classes and two associations as the following diagram shows:

Instead of an association class, you create a single class (suit) that represents the noun, and you break up the single association (suing) into two association (attacks with, defends against). In some ways, this is more precise than using an association class. You can tell from the diagram above that

• A single plaintiff attacks with one or more lawsuits.
• One or more defendants defend against a single lawsuit. Therefore, there could be two suits between the same plaintiff and the same defendants at the same time.

What you lose is a notion that the suit establishes the context of the relationship between the plaintiff and the defendant(s). Ultimately it is a judgment call about which form to use (the association class or the normal class with two associations). If understanding the specific multiplicity data is important, you should use the two-association diagram. If it is not, I personally feel that the association class provides clarifying context.

Next Up

In the first five parts of this series we’ve covered

• Using classes to represent business objects and entities.
• Using simple associations (relationships) to demonstrate how objects are dependent or how they relate to one another.
• Using composition and aggregation to show how objects are treated when grouped together.
• Using generalization and inheritance hierarchies to show how similar, related objects can behave differently.
• Using association classes and n-ary associations to express more complex relationships.

If you understand all of these concepts, you are ready to create UML class diagrams of the business domain and concepts. You are ready to use these tools to uncover otherwise hidden requirements. If you want to study some of the more arcane details around UML class diagrams, you should be ready to read Scott Ambler’s articles.

• UML 2 Class Diagrams – an explanation, in detail, of how and what and why to draw things a particular way
• UML 2 Class Diagram Guidelines – advice on how to make your diagrams consumable and appealing

Just keep in mind that Scott jumps right into complex topics (which you are now ready for), and also includes tips and advice that are only relevant when creating class diagrams of implementation designs. Just filter that stuff out. Or come up with a way to leverage those details to the modeling of business ideas, and share them here.

Thanks for following along this far, and if you have any questions or would like to see us cover anything else about using UML class diagrams for uncovering requirements, add a comment below.

The hardest part of gathering requirements effectively is uncovering the requirements that people don’t immediately tell you. You have to ask the right questions. And one of the best ways to find the right questions to build a class diagram of the business domain. This article continues our introduction to class diagrams.

Catching Up on UML Class Diagrams

If you’ve found this article first, there are three that came before it.

1. Uncovering Requirements With UML Class Diagrams Part 1: Discusses how to represent objects and entities from a business perspective.
2. Uncovering Requirements With UML Class Diagrams Part 2: Discusses simple relationships between objects or entities.
3. Uncovering Requirements With UML Class Diagrams Part 3: Discusses combining objects into collections and concepts.
4. Uncovering Requirements With UML Class Diagrams Part 4: This article.

So jump back to the other articles and get up to speed. We’ll wait for you here. As a reminder, in this series, we’re specifically focusing on using UML class diagrams for uncovering requirements – as part of analysis, not design. We’re talking about what the business needs, not how the solution will work.

Generalization: A Dog Is A Mammal

We’ve looked at objects and relationships between them. We’ve looked at the special association relationships that give us aggregation and composition. Generalization is another form of relationship, but not one that tells us how different objects interact – one that helps us better describe objects. We could talk about a dog, and create an object that represents a dog. But what if we also wanted to talk about a horse? They have some things in common, because they are both mammals. Generalization allows us to talk about mammals too. That’s fine, but let’s use a business example instead of a classroom example.

The key to this generalization relationship is to think about the phrase “is a.” A dog is a mammal. Don’t confuse this with combining objects into an aggregation. A pack has a bunch of dogs in it. A zoo has a bunch of mammals (and other animals) in it. But a dog is not a specialized pack. It is a specialized mammal.

Remember “…is a…”

This relationship carries special meaning – all things (characteristics, behaviors, etc) that are true about the general object are true about the specialized object. But all things about the specialized object are not necessarily true about the general object.

• All mammals have hair, therefore all dogs have hair.
• All mammals have live babies (they do not eggs), therefore all dogs have live babies (puppies).
• All dogs are pack animals, but all mammals are not (elephants are, but shrews are not).

Technical folks usually call this inheritance – the specialized object inherits all of the properties and behavior of the generalized object. Inherit is almost as good of a word to use as generalizes. Where inheritance really helps as a term is it allows us to think in terms of parents and children objects. The mammal is a parent and the dog is a child of mammal. The terms parent and child make it much less cumbersome to talk about generalization relationships.

Understanding Insurance Policies With Generalization

Consider that you’re working on a project for a life insurance company. In your first conversation with a subject matter expert, you hear five different terms for describing insurance policies. At a convenient pause, you stop the interview, walk over to a white board, and draw class diagram objects for each of the five items.

You ask your expert how all these objects are related to each other. She explains that all life insurance policies are either term policies (they last for a fixed term of time) or permanent policies (they last for as long as the premiums are paid).

You recognize this as a generalization relationship.

• Every Term Policy is a Life Insurance Policy
• Every Permanent Policy is a Life Insurance Policy

Your SME also informs you that permanent policies, as a form of investment, are always one of two special types – whole life policies and variable insurance policies. Whole life policies have a fixed return for a fixed premium. Variable policies invest your premium in market securities, and the amount of money available at the time of payment depends upon the performance of the policy. More generalization relationships.

• Every Whole Life Policy is a Permanent Policy
• Every Variable Insurance Policy is a Permanent Policy*

[*As far as I know. If there is such a thing as a variable term life insurance policy, my apologies - just assume that your company does not sell one.]

You draw the generalization relationships on the white board, and you move forward in eliciting requirements. This drawing is known as a hierarchy.

Drawing Generalization Relationships in Visio

You use the generalization shape in visio to create generalization (inheritance) relationships between classes in your class diagram.

As you drag it onto the page, it looks like the following:

The shape is an arrow with a closed (but not filled) arrowhead on one end. You connect that arrowhead to the parent class – the more-general of the two. The tail is connected to the child class – the more-specific of the two.

Once you draw all the relationships, your Visio class diagram will look like the following:

Now you’re prepared to understand the other information your subject matter experts are sharing, in the context by which the business is describing their requirements.

This hierarchy makes sense, but it seems to be completely different from all the other class diagram stuff we’ve done. How can you combine these different views? It is the combination of them that really brings out the value.

Relationships, Classes, and Inheritance

The first thing to realize is that association relationships, composition relationships, and inheritance relationships can all happily co-exist within the same UML class diagram. In fact, much of the insight you gain into uncovering requirements only comes when you combine these different analyses within a diagram.

The structure we looked at above provides a good description of how a company manages the policies that they write. What you are likely to want to document are requirements around selling those policies. Each time a policy is sold, an agreement is created. That agreement is a copy of the policy sold (at the time of selling it), with the insured person’s name filled in. You can imagine the policy to be a form with blanks that need to be filled in. Each time a policy is sold, someone makes a copy of the “official” policy, fills in the blanks – name of insured, policy dates, etc – and then it becomes an agreement.

Introducing the term agreement allows the business to treat the two ideas separately. A policy defines the agreements that can be sold at any given time. An agreement is one policy, as sold to an insured person (customer).

[click for larger diagram

As you can see from the diagram, we have the same hierarchy for describing insurance policies. We've added some other objects and relationships.

Objects

• Agreement. A policy written by an agent for an insured person. The agreement is written in a specific state.
• Agent. An agent is someone who sells insurance policies (agreements). The agent lives in a specific state.
• Insured Person. Someone who purchases an insurance policy (agreement). The person lives in a specific state.
• Insurance License. An official document that allows someone to sell policies in a specific state for a period of time.
• NASD License. A special license from the National Association of Securities Dealers that allows someone to sell variable insurance policies.

Relationships

• A life insurance policy is used as a template for an agreement.
• An agreement is written by an agent.
• An agreement is held by an insured person
• An agent holds one or more insurance licenses.

From the diagram, we can understand that an agent sells an agreement to an insured person. That agreement is based on a life insurance policy. The agent holds at least one license to sell insurance.

Notice the relationship between the agreement class and the life insurance policy class. The life insurance policy is at the top of an inheritance hierarchy. Each other type of insurance policy (term, whole life, etc) is just a specialization of life insurance policy. The diagram depicts that the agreement can be one of any of the different types of insurance policy. And therefore, an agent can sell any of the types, and an insured person can hold an agreement of any of the types of insurance policy.

When reviewing these relationships, you discover that this is an overly simplified representation. You capture the additional information and update your diagram.

More Complex Class Diagram

As part of reviewing the diagram, you discover that variable insurance policies are treated very differently than other insurance policies.

• An agent must have a different type of license (an NASD) license to sell variable insurance. Because of this, the business treats these agents as being special - they are called "Broker / Agents" and are subject to many different internal policies and procedures. Some of those policies represent enforcement of legal regulations, and others are internal policies.
• A broker / agent can sell both variable and fixed (non-variable) insurance policies.
• A variable policy is a combination of a fixed policy and an investment. As such, the business thinks about those customers as investors, and not just insured people. This distinction is really only relevant to sales people and marketing - who will use different approaches to sell to people who want investments.

You update your class diagram to look like the following:

[click for larger diagram]

This diagram is much more complicated.

• We enhanced the hierarchy for insurance licenses to reflect that broker/agents need a different type of license (NASD license) to sell insurance.
• An insured person holds a fixed agreement, where an investor holds a variable agreement.
• An agent can only write a fixed agreement, where a broker/agent can write any type of agreement (fixed or variable).

The diagram is almost too complex to absorb within a UML tutorial. If you were writing these requirements, and did not create a similar diagram, you would be in trouble. In the best case, you would end up with an implementation that met all the requirements, but did not use a good implementation design (due to lack of context). It is more likely that either you would miss some requirements, or your implementation or test team would miss some.

The diagrams that have had the most impact, in our experience, are diagrams that have a similar level of complexity.

Next Up

In the first four parts of this series we’ve covered

• Using classes to represent business objects and entities.
• Using simple associations (relationships) to demonstrate how objects are dependent or how they relate to one another.
• Using composition and aggregation to show how objects are treated when grouped together.
• Using generalization and inheritance hierarchies to show how similar, related objects can behave differently.

All of the tools you’ve learned so far deal with binary associations – an agent sells a policy, a book club reviews books. In the next article, we will look at relationships that involve more than two classes.

Uncovering Requirements With UML Class Diagrams Part 5: Complex Relationships

UML Class Diagrams are very effective at uncovering requirements. They give us insight into how the business thinks about objects and their relationships. And from that understanding, we think to ask questions we might otherwise overlook. In this part of our series, we look at how to represent when one object is made up of other objects. The two types of relationships we explore are composition and aggregation.

Catching Up on UML Class Diagrams

If you’ve found this article first, there are two that came before it.

1. Uncovering Requirements With UML Class Diagrams Part 1: Discusses how to represent objects and entities from a business perspective.
2. Uncovering Requirements With UML Class Diagrams Part 2: Discusses simple relationships between objects or entities.
3. Uncovering Requirements With UML Class Diagrams Part 3: This article.

So jump back to the other articles and get up to speed. We’ll wait for you here. As a reminder, in this series, we’re specifically focusing on using UML class diagrams for uncovering requirements – as part of analysis, not design. We’re talking about what the business needs, not how the solution will work. UML class diagrams can be used for both, and most tutorials are written for programmers doing design work. This one is written for people who work with requirements.

Relationships of Combination

When a collection of bananas are combined, we call them a bunch. Crows exist in a murder, and lions in a pride. Teams are made up of players. It is a deck of cards. An order is a collection of line items. We have always had the notions of both individual items (or people) and combinations existing as an interesting entity. Sometimes we treat them the same – you can eat a banana or a bunch. You can feed a lion or a pride. Sometimes, we deal with the combined entity. You shuffle a deck, you fulfill an order.

Understanding this type of relationship can be very important to understanding what your customer (aka “the business”) needs. You are describing the mental model of the business. Business people think about fulfilling an order, not “fulfilling all of the items on the order.” A user may want to archive the history (all the previous versions) of a file, or she may just want to keep the most recent version. Thinking about these concepts helps you uncover the requirements.

There are two jargon terms – aggregation and composition – that apply when we talk about multiple things as one combined thing. They have precise meanings.

• Composition – when one item is part of another item, the relationship is composition.
• Aggregation – when one item can be included in another item, the relationship is aggregation.

If that doesn’t make sense, this “formal” distinction will really mess you up:

Composition is a stronger form of aggregation where the whole and parts have coincident lifetimes, and it is very common for the whole to manage the lifecycle of its parts.

Scott Ambler

Here are some examples that may simplify things:

Composition

• A building is composed of one or more rooms (a room is part of a building)
• A plane is composed of a fuselage, one or more engines, and one or more wings (a wing is part of a plane)
• An order is composed of one or more line items (a line item is part of an order)

Aggregation

• A team includes more than one players
• A library includes more than one books
• A market includes one or more customers

Ambler’s definition makes sense, when you think about these examples. You could shut down a library without destroying the books – likewise, you could kick one of the players off a team and the team would still exist. That’s what he means by coincident lifetimes.

Drawing a Composition Relationship With Visio

To draw a composition relationship in Visio, you use the composition shape from the UML Static Structure stencil.

When you first drop this shape on the page to connect two classes, it looks like the following:

There is a solid black diamond on one end (the first end) and nothing on the other end. In UML, this is stating that an order is composed of line items. By default, Visio shows the “end names” as it did with the association shape. You can fix it the same way we did before. Right click on the line and select shape display options.

Then make the same modification we did before, to show the shape name and suppress the display of the “end names.”

Now you have the kind of display you want. Note the check marks at the bottom of the dialog – you only have to make this change once per class diagram. Unfortunately, Visio does not remember this change, so you have to do it once for every diagram (every new file, and every new tab within the same file). Annoying.

Double click on the line to update the information about this composition relationship.

You will end up with the following (we re-arranged it to make it easier to read):

Drawing an Aggregation Relationship With Visio

Drawing an aggregation relationship is almost the same as a composition relationship with Visio – it just requires an additional step.

In this example, a book club reviews books. You want to show that the book club includes members. Note – members can come and go without causing the book club to be disbanded. You can think of aggregation as membership in a combined entity.

First, use the composition shape again (the same as above), and update the properties as we just did. You will see

The Visio stencil does not include a special aggregation shape, so we will cheat by changing the formatting of the composition shape. Select (in the menu at the top of the window) format > line…

And in the dialog, you will change the display of the “Begin” end-point.

Aggregation is represented in UML Class Diagrams with the same diamond-shape as composition. The difference is that the shape is “empty” instead of being a solid black diamond. Click “Apply” and “OK” and you end up with what you want:

Note: If you change the format of the composition line first, and then change the properties (“Joins” etc), Visio will reset the line end to be a solid diamond again. It resets. Annoying. If you copy an aggregation line, the copy reverts to the solid diamond again too. Very annoying.

Next Up

Up to this point, you’ve learned how to define classes (and attributes), simple relationships (A book club reviews books, and a member reads books), and combinations of items as compositions and aggregations (an order is composed of line items, and a book club aggregates members).

Next, we will cover hierarchies, usually thought of as “Is a” relationships. A Sales Rep is an employee, and an employee is a person.

Uncovering Requirements With UML Class Diagrams Part 4: Generalization (inheritance) and how to use it.

We continue our exploration of UML Class Diagrams with this article that explores how to represent basic business relationships in a class diagram. Drawing these relationships can dramatically clarify requirements documents. Using a class diagram to supplement other requirements documents provides for a centralized reference that enables a shared understanding of the problem domain. That understanding prevents mistakes in interpreting requirements.

Getting Up To Speed

We started this discussion of class diagrams last week. In it, we presented the notion of a class. When a stakeholder cares about a concept, idea, or thing, we represent it as a class.

The business cares about customers. And customers have addresses and credit ratings.

Classes and Attributes

How do you know when something should be an attribute, and not another class? In our example above, think about Customer and Address and Credit Rating. One way to make a distinction is to say that if an attribute has other attributes, it should be a class. A credit rating is just a number. But an address is a compound object made up of multiple attributes.

An address can have multiple lines of street address information, as well as city, state, zip code and country information. That is a good indicator that it is likely to be a class of its own. If we were to represent an address as attributes of a customer, we would have to include each of the “sub attributes” as a separate attribute of customer. That feels bad, from a design standpoint.

The distinction is one of design, but generally speaking, if the concept stands on its own, it should be its own class. An address is related to the customer. A credit rating is a property of a customer.

Simple Relationships

How do we show a relationship between a customer and an address?

The customer receives bills at an address. That is the relationship between the customer and the address. The business wants to know where to send bills for the customer. We’ll talk more about relationships in a bit. First, we’ll cover the steps in visio for creating the relationship shown above.

Showing Relationships With Visio’s UML Stencil

The relationship shown above is called a binary association, because it shows the association between two classes. There is an object (Visio calls it a “master shape”) in the Static Structure template for creating these, aptly named binary association.

Drag that onto the page, and connect the two classes for which you wish to show a relationship.

The default display properties for the binary association shape cause the shape to display some weird information – called the “end names” of the relationship. The shape also does not give us the arrowhead, or the name of the relationship, Receives Bills At. Right click on the line and select “Shape Display Options…”

Remember this, you will use the dialog that pops up a lot.

We want to do three things for now:

1. Check “Name” so that the name of the relationship (Receives Bills At) will show up.
2. Un-check “First end name” so that it is hidden.
3. Un-check “Second end name” so that it is hidden too.

Click OK, and the shape will have updated to look like the following:

The name is defaulted (to “Association1″), and no arrowheads are showing up. We also have two asterisks, an no “1.” We need to update the shape’s properties (not display properties) to include that information. Double click on the line and you will see the following dialog (Fill it out to match):

[click for full size view]

• Name: Enter “Receives Bills At.” for the name. Note – some people prefer mixed case or lower-case. Any approach is fine, just be consistent. The name is the name of the relationship and it indicates the meaning of the relationship.
• Name Reading Direction: forward and backward will confuse you. It confused me for years. This is what determines where the small solid triangle shows up to indicate the direction of reading. Customer Receives Bills At Address, instead of Address Receives Bills At Customer. One day, I realized that this field only controls if the triangle shows up before or after the text. With up-down relationships, I still get confused. Use the standard of top-to-down is the same as left-to-right, and you’ll eventually get used to it.
• Association Ends: This section shows the two ends as rows in a table – with five columns describing each end. For now, we will only focus on the last two columns. This is another area for confusion – the first row represents the top-left end of the line (when you drag it onto the page) and the second row represents the bottom-right end of the line. You can move the ends of the line around after you place it on the page, and the rows in this table will maintain their original associations. Try not to get frustrated when you get these backwards. I still make that mistake all the time, after creating a few hundred diagrams over the course of a decade. Think of the top-left end of the line as the “first” end, and the bottom-right as the “second.” Then when you move it around, you might remember which is which. If you get in the habit of attaching the line first to the “from” class, and then to the “to” class, you will start to get the hang of it.
• Multiplicity: Multiplicity allows you to specify how many objects can be on either end of the relationship. In our example, a customer can receive bills at only one address, but multiple customers could share the same address. My stepdaughter and I each have iTunes accounts. We are two separate customers, but we have the same address. Since I attached the “first” end to the Customer class, there is an asterisk in the first row, and a “1″ in the second row. [*See below for explanations]
• IsNavigable: Either the UI designers for Visio expected all of their users to be Java programmers, or they ran out of space. “IsNavigable” can be translated into “Should the arrow be shown on this end of the line?” Since, as a business, we care about the address at which a customer receives bills, we show the arrow for the “second” end. But we don’t anticipate (commonly) needing to determine all of the customers that receive bills at a particular address – so we don’t show the arrow in the opposite direction.

Types of Multiplicity

There are a few different concepts that can be displayed for multiplicity. Your developer co-workers and math geeks will call this cardinality. That’s probably even the better term to use. But since Visio chose multiplicity, so will we, at least for this article.

• 1: Exactly one object of this type is involved in the relationship. A customer has one billing address.
• *: Any number of objects (or none at all) are involved in the relationship. Any number of customers can receive bills at a given address.
• 0..1: Zero or one objects are involved in the relationship. A driver may or may not have a drivers license.
• 0..*: Same as “*”
• 1..1: Same as “1″
• 1..*: Any number of objects (as long as there is at least one) may be involved in the relationship. A shipment can include any number of items, and it must include at least one item.

This brings us back to our original relationship example.

The small class diagram above represents the following:

• A customer has a credit rating.
• An address includes three fields for “street information”, city, state/province/county, zip or postal code, and country fields.
• A customer receives bills at exactly one address.
• Any number of customers (or none at all) can receive bills at any one address.

Simple Relationships Revisited

With the mechanics of using Visio out of the way, we can show some examples of some other simple relationships.

• A sales rep sells products to any number of customers.
• Any number of customers purchase products from a sales rep.

Both examples above depict the same relationship, and either is acceptable. What would be bad would be to use the passive voice and say “any number of customers are sold products by a sales rep.” This is the same advice that applies when writing use case names – don’t use passive voice.

There are opportunities to misread requirements when relying solely on UML. Imagine we had a requirement that any customer always make purchases from a single sales rep. The goal is to provide a sense of relationship for that customer. Both of the diagrams above technically express that requirement. If a customer could have more than one sales rep, we would show “1..*” instead of “1″ for the multiplicity on the sales rep side of the relationship.

Someone reading the examples above could reasonably be unsure about the intended requirement. Is there a single sales rep for a given transaction? Is there a single sales rep for a given customer, regardless of the number of transactions? Only the latter interpretation is technically accurate – but either is a reasonable interpretation. Professor Daniel Berry, author of The Ambiguity Handbook [The actual title is From Contract Drafting to Software Specification: Linguistic Sources of Ambiguity, A Handbook], explained in a lecture last year at the 2007 IBRF that UML stands for Undefined Modeling Language. This is a good example of that.

By including the diagram within, or as a reference from, a requirements document, you provide both the context and the graphical clarity needed to understand the intent. Don’t rely solely on the diagram!

A product has a price. One product has one price. This relationship is almost too simple, making it difficult to come up with a good name for the relationship. “A product has a price of price” is awkward.

“A product will be sold for a price” is better. If we were limited to “has a”, we could make an argument that the price should be an attribute. But the price may have properties (like currency used), or may be calculated dynamically based on coupons or contracts.

Using action verbs will help with both understanding and elicitation. If you are reviewing the diagram above with a stakeholder, you are not likely to get any discussion from “product has a price” – of course it does. But if you show “product will be sold for a price” you will immediately trigger responses. Especially if you ask “how do you know what price to sell the product for?” Use active verbs with explicit meanings instead of “weasel words” like “has a.”

This is a very clear way to indicate that from a business perspective, the customer has a billing address and a shipping address, and no reason to expect them to be the same. If you have to worry about export compliance, you may add an “end use” address – the location where the product will ultimately be used. Imagine how messy that would be if we had used attributes instead of classes!

As messy as that would be, this highlights why we use classes. Think about some other business relationships we have not drawn. Credit card authorization uses the billing address. Taxes may be* calculated based upon the billing address or the shipping address. Shipping charges would be based upon the shipping address. [*I believe that for physical goods, the shipping address is used, and for electronic downloads, the billing address is used.]
There is no limit to the number of entities and relationships that can be represented in a class diagram. As a guideline, think about usability. Are you producing class diagrams as part of exploring specific areas of the business? Are you making sure that a complex set of relationships do not get oversimplified? Are you “boiling the ocean” with a giant encyclopedia of the business domain? If you are – why?

Summary So Far

So far, we have discussed classes as a means to represent entities from a business perspective. We’ve also introduced some simple relationships. Those relationships show how pairs of entities interact or inter-relate. We’ve shown how to make the relationships directional and bidirectional – depending on which way(s) the business needs to look at things. And we’ve covered multiplicity – how many of each type of object are involved in the relationship.

There is still a fair amount of ground to cover between here and Scott Ambler’s comprehensive reference. If any of the concepts so far are unclear, or if there’s something you want to make sure we cover – add a comment!

Next Up

In our next article on using UML Class Diagrams for unearthing requirements, we will look at more complex relationships.

Uncovering Requirements With UML Class Diagrams Part 3: Combining objects into collections and concepts.

UML Class Diagrams can be used not only for documenting software design, but for documenting software requirements. One of the challenges in writing clear, unambiguous requirements is being precise about what a particular word means. This is especially true with symbolic terms like “quote” or “customer” – where everyone knows what they mean – but they mean different things to different people.

Why Create UML Class Diagrams for Requirements?

One of the first articles we wrote in 2005 provides a very simple class diagram example, and an explanation of why you should use class diagrams to clarify your documents.

In prose, we could also capture the same information as follows:

1. The system shall include a representation of customer orders.
2. Each order will have a single associated customer, and each customer can have multiple orders. Note that a customer is not required to have any orders.
3. Each order will have at least one, and possibly multiple line items. Each line item is uniquely associated with a single order.
4. Each line item represents a single product. Note that a product is not required to be represented in a line item. A product can be represented in multiple line items (even within the same quote).

OOA is compellingly powerful as a descriptive tool – it took less time to draw the diagram, and it can be easier to read than the prose.

A Picture is Worth A Thousand Requirements

UML class diagrams, in addition to being potent for communication, can also help with requirements discovery. They provide a clarity and explicitness of understanding that helps you gain insight into the topics being explored.

Getting Started or Getting Refreshed

If you already know UML, or generally know how to draw UML 2 Class Diagrams, you can “test out” of this article, and go to the best, most thorough explanations we know of, courtesy of Scott Ambler.

• UML 2 Class Diagrams – an explanation, in detail, of how and what and why to draw things a particular way
• UML 2 Class Diagram Guidelines – advice on how to make your diagrams consumable and appealing

If your eyes glazed over, that’s ok. There is a lot to absorb. There are a lot of advanced concepts that can be represented in class diagrams, and Scott provides explanations and examples of how to do most of them. If you are new to modeling with UML, or are only interested in what you need to know to document requirements, those articles may be too advanced for now. We’ll try and close the gap. Keep those links handy, both for reference, and for deeper explanations than we cover here. If Ambler’s articles are written to help you be a master craftsman, we want to help you become a journeyman first.

Class diagrams are incredibly powerful tools for anyone doing requirements work. I never wrote about them before, because Ambler already did. And he didn’t leave me wanting more, so I never knew what to write. After a recent conversation with someone new to modeling, I discovered that he did leave a gap. There’s a fair amount of learning you need to do before you can really get the value from his articles. Ambler also addresses both the analysis and design uses of class diagrams.

We will focus exclusively on using UML class diagrams for analysis. So if you are a business analyst or requirements analyst, this will help. If you are a developer, this will help you read the diagrams that analysts create. If you are a product manager, this will help too, but I think you’ll need to do this less frequently than a business analyst would.

We do assume that you are already comfortable using Microsoft Visio, but have not used it for creating class diagrams. You don’t have to use Visio, but the tools in Visio are good ones for creating class diagrams.

Visio Template for UML Class Diagrams

The easiest way to get started is with the default drawing type already available in Visio.

Create a new file, and select the Software category, then scroll down and select “UML Model Diagram” in either US or Metric units. When you do, a number of stencils will automatically load for you. You want to use the UML Static Structure stencil.

These are the shapes that you use to represent objects in a class diagram. You can safely ignore all of the other stuff that Visio provides in the other templates.

The Class

When you drag the “Class” shape onto the page, you get the empty looking box on the left. Visio automatically names it for you as “Class1.” The class represents a concept, entity, item, or object. It is important for analysts to remember that what you are drawing is “how the business thinks about these objects” – not “how developers will implement a representation of the objects.”

There are three areas in each “class” shape. The shape on the right shows that the top area is where the name of the class appears (in bold), the middle section represents attributes, and the lower section captures operations that can be performed by the shape. This feels like describing an implementation or design. The terms attribute and operation certainly sound like programming. UML Class Diagrams may have initially been created to help developers design solutions, that would certainly explain the names. There is still a lot of power to be unleashed – so take it on faith for now – we’ll present some examples that demonstrate the value of class diagrams for analysis.

Imagine that you are thinking about a lamp. Perhaps you are designing an emergency battery backup system, and one of the things you need to think about is how much wattage a lamp requires to operate. The wattage of the lamp, in English, is a characteristic of the lamp. Programmers call it an attribute. For our purposes, the terms are interchangeable.

A lamp can be turned on. That is pretty intuitive. We imagine ourselves turning on a lamp. Actually, all we do is turn a dial (or flip a switch). When we turn the dial, the lamp turns itself on. If we were really playing with language, we might say “When the user requests illumination, the lamp turns on.” We would never use that phrasing for a concept as simple as a lamp, but you get the idea. The operation is something that the object can do. Dogs bark, cats meow, lamps turn on.

When we are creating class diagrams for requirements discovery, we will always use class names, almost always use attributes, and almost never use operations.

A customer, in the diagram element above has an address. The customer also has a credit rating.

The two elements above represent the same information. A product has both price and weight. We also find, during our requirements exploration, that we need to know if a product is available. Perhaps our users need to know if a product is available right now before suggesting it as an up-sell item to a customer. If that is our requirement, we realize that we need to know the availability of the product. You can either include the question “Is it available?” or a single name for the attibute – “Availability.”

It is better to use the word “Availability” for two reasons. First, it is consistent to say “price, weight and availability.” You could achieve consistency with all questions – “What is the price?” “How much does it weigh?” and “Is it available?” But that becomes overly wordy. The second reason for using a single word is to avoid embedding rules in your requirements.

Consider the “Credit Rating” attribute for the Customer object. What we really want to know is if the customer’s credit is good. The definition of “good” will change over time, or may become complex. “Good enough for small purchases”, “Good when putting 20% down” are examples of the definition of “good” becoming complex. Or maybe you’re loaning money, and you can improve your profits with notions of “pretty good” and “really good.” You will create business rules to define what you mean by good. You happen to know that those rules will reason about the customer’s credit rating, so you should capture that value.

You could but should not represent the notion of “Is Credit Good?” with an operation:

You end up specifying design here – however unintentionally. Depending on how you interpret this, you are either saying “Customers are responsible for determining if their credit is good” or “The credit worthiness of a customer is determined without considering anything other than the customer.” While precise for programmers doing design, this is a pretty ambiguous thing to document in an analysis. By adding this operation, you are not providing unambiguous insight into how the business thinks about customers. So don’t do it.

Next Up

In our next article on UML Class Diagrams for analysis, we’ll look at relationships between classes.

If there’s something in particular you’d like to see explained, add a comment below and we’ll either fold it into the series or answer in the comments. And remember – you can subscribe to the comments for any article, just click the link.

Uncovering Requirements With UML Class Diagrams Part 2: Simple relationships between objects or entities.

Documenting processes is something most business analysts have to do. The goal of documenting the process is to communicate requirements. By establishing a shared understanding of the process, you can establish the context for the requirements. Easy processes are easy to draw and understand. When documenting a more complex process, you need to provide the same clarity and consistency. In this article we show how to document asynchronous process steps to maximize the clarity of the documentation.

Speak in Your Reader’s Language

The diagrams you choose to use represent a graphical language for communication. It is really no different than choosing a language in which to write your textual requirements. You need to choose a graphical language that the consumers of your document understand.

You can use BPMN (business process modeling notation) to document your processes, and be quite precise in your description of the process. However, if the team you are communicating with does not know BPMN, it may not be the most effective way to communicate. You are faced with a trade-off. You have to either use a language (process flow charts) that is easily understood but hard to extend, or use a language that is precise in interpretation – but only to people who know the language.

Here’s a solution that uses diagrams that are better known than BPMN, leveraging process flow charts and UML sequence diagrams.

Asynchronous Process Definition

An synchronous process is one where two objects or systems talk to each other. The first system sends a message to the second system and waits for a response. An asynchronous process is one where two objects or systems talk to each other – but the first system does not wait for a response from the second.

Imagine making a bank deposit. If you go to the bank, hand your money to the cashier, and wait for a deposit slip, you have just participated in a synchronous process. You did something, and waited for the cashier before doing something else.

Now imagine driving through a toll booth. You drive up to the toll booth, roll down your window, and throw your money into the collection basket. You wait for the machine to count the money, the light turns green, and you drive on. This is also a synchronous process.

Now imagine that you are in a hurry. You roll down your window as you approach the toll booth. You slow down, and as you drive by, you throw the money into the collection basket, and accelerate. You don’t wait for the light to turn green – you trust that you had put enough money in the basket and you move on. The machine still counts the money, and the light still turns green – but you didn’t wait for it. You continued to do what you were doing – driving in a hurry. You just participated in an asynchronous process.

Drawing an Asynchronous Process

Consider a simple asynchronous process – ordering a hamburger at Wendy’s.

Wendy’s has an interesting process for serving “made to order” burgers quickly. They cook a small number of hamburgers in advance, and keep them warm for a short period of time. If someone orders a burger, they take one of the already cooked burgers, and assemble it with the custom toppings. They also put another raw burger on the grill to replace the one they just sold. The challenge for the grill cook at Wendy’s is to have enough burgers ready that no one has to wait – while not having so many burgers precooked that any of them dry out before you order.

The labels in the boxes above are generic, but it could be used to describe ordering a burger at Wendy’s. The box “calling process” represents you ordering a burger. The cashier processes the request, and then the flow splits into two parallel paths. The grill cook immediately prepares your hamburger, and simultaneously starts cooking a new hamburger to replace the one he just used.

After your burger is prepared, the process returns to you – you get your burger and go eat. You don’t wait for the new hamburger to finish cooking.

A process diagram doesn’t normally do a very good job of communicating that a process is asynchronous. We’ve had good success in using a modified box – with a small clock in the lower right corner – to indicate that a process is asynchronous. You could infer that the “delayed activity” is asynchronous because the flow moves directly from the “immediate response” to the “return” symbol. But in a good diagram, you don’t have to infer.

Sometimes, it helps to create an alternate view of the same process. This additional view can make it easier for the consumers of your diagram to understand the process.

An Asynchronous Sequence Diagram

Another way to diagram processes is with UML sequence diagrams. Scott Ambler has an excellent article explaining how to read a sequence diagram. The same burger ordering process could be drawn with the following sequence diagram.

The diagram above uses the same generic labels again, but still applies to our example of ordering a hamburger at Wendy’s. Inside the “par” bounding box, you get the immediate response (preparing your burger), and in parallel, the delayed activity (cooking a replacement hamburger). Note that, in the diagram, you don’t have to wait for the response from the delayed process. You get to eat your burger before the new one has completed cooking.

Summary

Asynchronous processes don’t come up often when learning about diagramming techniques. But you find them all the time in the real world. One of the easiest ways to speed up a process is to find steps that take a long time, and figure out how to do them asynchronously. You don’t wait for paperwork to be processed when signing up for an insurance policy – the coverage is effective immediately. You don’t wait for a loan application to be processed before driving off in your new car. Once the loan is approved, you get the keys. Many different software and manufacturing processes take advantage of queueing (like the Wendy’s example) to allow for faster “real time responses” to requests.

Being able to draw and discuss asynchronous processes is a good skill to have in your repertoire when documenting requirements in the real world.

More iteration in our agile project. In this article, we make several updates to the domain model (UML class diagram) based upon discussions on all of the articles in the series. More than a couple dozen in the last day. Thanks to everyone who has helped with feedback and encouragement – just awesome!

Updated domain Model

Here’s the updated UML class diagram representing our domain model.

[larger]

Overview of Changes

Rather than enumerate all of the changes to the diagram (you can compare the diagrams), I think it would be more effective to identify the concepts that have been incorporated into this iteration of the UML class diagram.

• Added placeholder for the mashup concept.
• Added notion of broadcasting “events” from users, to distribution lists, about articles.
• Updated user roles to reflect minimal classification scheme.
• Added meta data for users, including openID support; articles.
• Added notion of reading “events” from users, of articles, at times. Could support “what did I read” or “been read X times”.
• Added category/synonym idea for articles.
• Expanded notion of “Rating” to include rating of articles, reviews, and other users.
• Refactored ratings to be a 5 point scale like the one on this article.
• Added notion of beginner/expert/not-sure for articles.

Questions

Thoughts and questions after making this update.

• Do we need explicit rating of other users? Should this supplant the admired/admirer model? Should “people rating” be implicit based upon ratings of their reviews? Should people know how they are rated? Presumably not knowing who rated them.
• Not Sure could be “conflicting or insufficient opinion”. When filtering for “beginner” would you want “beginner only” or “beginner + not sure”?

Along with design sketches and requirements, as part of the concurrent design and requirements development for our agile project, we have created a UML class diagram representing the domain. This iterative process allows us to incorporate the benefits of each perspective rapidly with the others in our race to prototype a working site.

This article reviews the domain model.

UML Class Diagram Background

Scott Ambler has an excellent article explaining how to use and read UML 2.0 Class Diagrams – also called static diagrams or static models. This article does not have the typical “explain how to read it” introduction, please bear with me, or refer to Scott Ambler’s excellent tutorial as background for this. [Note: Ambler will have a lot of articles submitted to the ratings site - he does lots of great stuff!]

Ratings Project UML Class Diagram

The goal of this diagram is to capture / describe our understanding of the space – an object oriented analysis step. This diagram represents a business-perspective on the space, not an implementation-perspective. The implementation will look very similar, and does crop up a little in the naming of attributes. In “true agile fashion” we are trying to use the same document to represent the OOA as well as OOD artifacts.

[larger]

This is the 20070424 version of the model. It will evolve. If you see any glaring holes or errors, please mention them in the discussion below this article.

[Update 20070427. Here's the next version of the domain model]

Ratings Project Domain Entities

Article

• articleScore. Each article will have a score that represents the collective perception of the quality of the article.
• articleReviews. A list of all reviews / commentary on the article.
• articleSubmitter. The user who submitted the article.
• articleTimestamp. When the article was submitted.
• articleRatings. [Private]. The individual ratings of the article, used to calculate the score.
• articleStatus. [Private]. An article can be public, possibly private, or removed (no longer visible to users, but still in the database to prevent its re-appearance).

User

• userRatings. All of the ratings submitted by the user.
• userArticles. All of the articles submitted by the user.
• userAdmiredUsers. Possibly have a list of users who you admire. Keeping this as a placeholder.
• userFans. Possibly have a list of all users who admire you. Placeholder.
• userRole. [Private?] A user can be an admin, can submit articles, and can review articles. Most likely, anyone who can review can submit. An admin can do both, but also has the ability to “clean house” in the system.
• userContactRule. [Private?] A user may allow other users to contact her. The site may provide an abstraction/email interface that allows contact without revealing email addresses. And people may want to restrict who can contact them based on the fan-admired network, or allow any user to contact them. Another placeholder for future possibilities.

Rating

• ratingArticle. The article being rated.
• ratingUser. The user doing the rating.
• ratingValue. The actual rating value assigned to the article by the user.
• ratingTimestamp. When the rating was created.

Review

• reviewArticle. The article being reviewed.
• reviewUser. The user doing the reviewing.
• reviewTimestamp. When the review was created.
• reviewTitle. Title of the review (e.g. “Best. Article. Ever.”)
• reviewBody. The content of the review. Possibly “safe” html, analogous to comment field limitations on blogs.

Thoughts And Questions

• User metadata (name, loginID, pwd, email, timestamp, etc) is missing from the domain model. Pwd will need to be encrypted in the database [design note: probably SHA1 vs. MD5 - review details and options to determine].
• Should user roles be private?
• Is there a reason to have a distinction between reviewers and submitters? What would be the reason that someone would be able to do one, but not the other?
• Any contact rules other than “Only people I admire”, “People I admire or who admire me”, “All registered users”, and “No One?”
• ratingValue – last night, I believe I convinced myself not to do it this way. Will cover in more detail in the next article.
• Should people be able to “Rate” a review? Think of Amazon’s “Was this review helpfull?” feature. Over time, the feedback that people give to reviewers could be used to create a notion of credibility, or be used to determine similarity of opinion between users.
• What about threaded commenting? Essentially reviews of reviews – not just reviews of articles.

Share your thoughts and feedback below. And thanks in advance.

Prototyping.

Depending on which discipline is dominant in the project approach, the next step could be to define the functional requirements (or specification) that support the use cases. Or it could be to take user-centric approach to prototyping interface elements. Or it could be developing an understanding of the domain model that will drive the behavior of the site.

Functional Prototyping

Ruby on Rails (Rails, for short) makes rapid prototyping of the “under the hood” stuff appear to be very quick to develop. And Rails separates the presentation from the logic with a model-view-controller approach to code structure. From the reading I’ve done about Rails, the next step needed to get an interactive prototype is to define the representational model.

In the better object oriented programs I’ve worked on in the past, the underlying representation matches the user’s conceptual model as well as possible. This will be challenging to not confuse the two and expose the implementation to the users. I’m not sure what differences will exist between them, we’ll see when we explore this. Creating a UML static diagram of both will help.

UI Prototyping

Creating some mockups of the user interface and documenting some design elements and interaction ideas will help here. I started that process last night and have the first initial thoughts drawn on paper. I will scan those in and post them as paper prototypes.

Documenting Requirements

If we were using a purely structured requirements approach, we would create an SRS at this stage. In conjunction with this prototyping approach, we will capture those same requirements. The requirements will be defined in the context of the individual use cases that we are focusing on for the first release. Don’t forget to vote on the use cases if you haven’t already.

Iteration

This process will be iterative or concurrent. The goal is to get enough of an understanding of the design to create an initial prototype.

UML Statecharts can be very effective modeling tools for describing systems and software requirements. They provide a clear framework for identifying business rules. The same business rules often apply to multiple states – defining a commonality for those states. There is an element called a substate in UML statecharts that can be used to make it more obvious that a particular business rule applies to multiple states.

A Simple UML Statechart

We documented business rules with a UML statechart in a previous article, that describes the possible states of a customer order. Those states are saved, placed, charged, shipped, delivered, and cancelled.

We defined a series of transitions and talked about the rules associated with those transitions. Imagine that the business rules changed, and customers were allowed to cancel orders even after they had been shipped (as long as they hadn’t been delivered).

Commonality In UML Statechart States

This could serve as an indication that there is a relevant commonality between the states: placed, charged, and shipped. All of these states represent an order that is “in process.” The customer has officially asked us for something, we have not delivered it yet (from the customer’s perspective), and the order has not been cancelled.

You can think of our states as having a hierarchy. You can create a state called “In Process” that generalizes the three states placed, charged, and shipped. By introducing this notion of generalization, we create “substates.”

UML Statecharts allow you to draw these substates inside of a larger superstate. The superstate is drawn with a rounded-corner rectangle, like the other states – but it includes a horizontal bar at the top that allows you to easily show the name of the superstate, separated from the information describing the substates.

Notice that the transitions between the substates are the same ones that were defined when the “In Process” superstate did not exist. You can have transitions between substates, and to and from substates to other states that are outside of the superstate. You can also have transitions that go directly to or come directly from the superstate.

Notice the single “cancel order” transition that comes from the superstate, In Process. This represents that the transition can be from any of the substates of In Process. The “deliver order” transition can only come from the Delivered substate. The transition “submit order” goes directly from the Saved state to the Placed substate.

Summary

The technique of using substates within UML statecharts allows for cleaner documentation when there are notions that present commonality (like business rules) that justify generalizing multiple states into a single state. This technique allows you to reduce the number of business rules that you must maintain, and makes the diagram easier to read.

In yesterday’s article we compared use cases and UML statecharts as tools for discovering business rules. James Taylor asked a question about how we would document those rules, and then followed up my comment response with an article about business rules and RUP. In this article we move the conversation slightly forward – recognizing that we’re slowly entering the ocean of business process management.

UML Statechart and State Transition Table Artifacts

There are two primary artifacts that come from using a UML statechart to discover business rules. The first is the statechart itself.

This is a primary artifact from the perspective of object oriented analysis (OOA). It provides a large amount of information in a dense, yet incredibly easy to absorb format. It is the ease of understanding that makes this a great tool for validating your understanding of the business process with stakeholders.

There are three elements of information that are documented in a UML statechart. The first is the list of possible states. In the example above, the rounded rectangles represent the possible states for a customer-order (Shipped, Delivered, etc). The second is the exhaustive list of all allowed state transitions (“Deliver Order” is the event that causes a transition from Shipped to Delivered). The third element is the events that describe (or cause) the state transition. “Deliver Order” is one of them.

Note that there can be multiple events that cause transition between the two states. If you modify the example above as follows…

You can document that either the customer, or the supplier (of the products for the order) can cancel the order.

There are two failings of the UML statechart. The first is the lack of support for rule discovery, and the second is that it is a poor framework for trying to document the business rules for later consumption.

State Transition Tables

You will have already created a state transition table as part of validating the completeness of your UML statechart. This is how the lack of support for rule discovery was addressed.

[larger image]

In the comparison of UML statecharts with use cases, we made a small reference to documentation of business rules.

Each possible transition has a number – which provides a reference for defining the business rules associated with each transition. You could put the rules inside the boxes, but the numbers make the table much easier to read.

In this example, #3 represents the allowed transition of the customer-order object from the state of Placed to the state of Charged.

What You Need To Document

To document the business rules associated with a UML statechart, there are five elements that must be documented.

1. Defining The Object. The definition and relevance of the object being described.
2. Listing The States. The list of possible states that the object can be in.
3. Defining The Rules of State. The rules that in force when an object is in a single state.
4. Listing The Transitions. The list of allowed state transitions that the object can make.
5. Defining The Transition Rules. The rules that govern the transitions from one state to another.

Defining The Object

A definition of the object is important to establish the context in which the business rules are being applied. Remember that this is a business object (a customer-order), not an implementation detail (class CustomerOrder :: Object). The description of the object and rules that define it will be in the language of the business, not implementation details.

Listing The States

You already have the list of states explicitly in the state transition table, and you could create it from the UML statechart. If you only had to list the different states, there would not be any value to creating an additional list – just reference the table.

Defining The Rules of State

Each state that the object can be in has a set of business rules associated with it. These are rules in addition to the rules that define the allowable transitions (more details below). Here are some example business rules of state.

• Suppliers can view orders that are in the Charged or later states.
• Suppliers can only view orders that include products that they supply.
• Customers can edit orders that are in the saved state.

Listing The Transitions

The allowable transitions are implicitly defined in the state transition table. Each allowable transition has a reference number (or ID) in the table. Every transition is also displayed in the UML statechart. If there were no rules associated with the allowable transitions, the table could have been done with yes/no boxes instead of references.

Defining The Transition Rules

Each allowable transition will have some rules associated with it. What initiates the transition? What constrains the transition? Here are some example business rules that govern the transitions from one state to another.

• An order will only be shipped when it can be completely fulfilled.
• An order will not be charged unless the customer has provided a valid shipping address.
• Orders will only be charged when the shipping address is in the United States of America.
• A charged order will be cancelled if it has not been shipped within ten business days.
• A saved order will be deleted if it has not been submitted within 90 days.

These business rules are important to the company. It is important to document them.

Scott Ambler shows a way to include this information within the UML statechart. His Figure 1 example demonstrates how to do it for object oriented design (the implementation design) and includes references to java functions that may be called. The concept could be applied to OOA diagrams as well.

We would encourage you to not include the rules within the diagram, as practicioners of Scott’s own advice – “I prefer to follow the AM practices Depict Models Simply and Model in Small Increments.” The extra information in the diagram makes it unwieldy. In our experience, a concise diagram with accompanying text is a better communication vehicle than a standalone diagram with higher information density.

Practical Application of This Approach

There are many systems for documenting and managing requirements and business rules. Forrester and The Gartner Group have even changed the name of the space from “Requirements Management (RM)” to “Requirements Documentation and Management (RDM)” in their communications. Generally, the solutions in the RDM space either use a repository to store information in a structured format, or they manage individual documents as artifacts.

Individual Document Approach

When your team is using individual documents to manage requirements, we suggest that you create a single text document that includes the text descriptions of states, transitions, and rules. This document should also include the UML statechart and the state transition table. These objects can be embedded or referenced to prevent the dual-maintenance problem of updating the text “wrapper” document whenever the underlying object changes. When using Microsoft Office, a Word document can include both the Visio and Excel objects by reference. HTML documentation will include the objects by reference. There is no really “clean” way to manage individual documents, and certainly no standard way to do it. Whatever works for you should continue to work. The goal is to present a single document (the “wrapper”) that contains or references all of the relevant information – prose + UML statechart + state transition table.

Requirements Repository Approach

If you have a repository that has been customized to specifically deal with UML statecharts, transition tables, and supporting rules, you’re ahead of the game. Please tell us about it too. As far as we know – it doesn’t exist.

Most structured RDM tools allow users to attach files to “requirements” objects. They also allow for the notion of supported and supporting “requirements” – either through traceability or composition. In the rest of this explanation, the term “requirement” is a reference to whatever artifact, object, or container the particular RDM tool uses to encapsulate a discrete business requirement or rule.

You can create a requirement that represents the business object and includes the contextual information describing the object (customer-order in this example). The list of states that the object can be in should be included in this requirement.

In support of that requirement, you should create other requirements that represent the defined business rules (#3 and #5 in the list) as separate objects. You separate the objects so that each requirement is atomic. The UML statechart and state transition table should be attached to the “wrapper” requirement as references. The diagrams, in this approach, are providing clarifying but redundant information. They need to be identified as such, so that in the event of misinterpretation (or requirements becoming out of sync), there is a clear “winner.”

Summary

There are many business rules associated with a business object that can change state. Those rules define the interpretation and ramifaction of being in a state. They also constrain and enable the transitions between states. The list of states and possible transitions are also business rules of a sort – although they may be better described as decision services than business rules.

Documenting these rules is important. You shouldn’t try and cram the documentation inside the diagram or the table. You should use accompanying prose.

What is the better requirements management model for capturing business rules? The use case, or the UML statechart? In this article, we explore how customer orders are submitted and processed, and contrast how use cases and statecharts expose and document business requirements and business rules.

The Scenario

To set up the comparison between use cases and statecharts, consider a website for a company that sells products online. Customers can create orders and submit them. The company will process the order and ship it to the customer. You need to define the requirements.

When gathering requirements, you learn the following:

• The company wants customers to be able to save an order and come back later (like Amazon’s shopping cart) to complete it.
• When a customer submits an order, the company will charge the customer (credit card, paypal, etc) through an outsourced billing service provider.
• The company doesn’t ship the order until after the charge has been made successfully.
• The company wants customers to eventually be able to track their orders by providing them with a tracking number from the third-party shipper that they use.
• The company also wants to be able to track their “work in progress” inventory and analyze their pipeline. To them, that means they want to know how many orders have been saved (but not submitted), how many orders have been submitted (but not shipped), how many orders are being processed, and how many have been delivered.

The Use Case Example Analysis

If you take a user-centric approach to documenting the requirements, you should start with the most important use case – Customer Orders Products.

Customer Orders Products

Actors:

• The customer – user who purchases products from the company.
• The system – the software with which the customer interacts.
• The billing-provider – an external system that is responsible for billing transaction processing.
• The fulfillment system – an internal system that is responsible for shipping purchased products to the customer.

Use Case Steps:

1. The customer selects products to purchase.
2. The system adds the products to the order.
3. The customer submits the order.
4. The system requests payment for the order from the customer.
5. The customer provides payment information.
6. The system requests payment for the order from the billing-provider.
7. The billing-provider acknowledges payment processing.
8. The system notifies the customer of successful payment.
9. The system submits the order to the fulfillment system (another system at the company).
10. The fulfillment system ships the order [note: this would likely be a subordinate use case].
11. The fulfillment system notifies the system that the order has shipped.
12. The system notifies the customer that the order has shipped.

There would also be an alternate case (use case extensions) allowing the user to save an order in-process and return to complete it later.

During the review of this use case with stakeholders, you would uncover the need for customers to be able to cancel an order at any point prior to shipping the order (step 10).

This use case analysis gives you the framework for designing the user interface of the system, and for defining functional requirements. Starting with a use case does not prevent you from gathering all of the business rules associated with customer ordering, but it also doesn’t help very much with some requirements.

Using a UML statechart provides a different view on the requirements.

Into To UML Statecharts

UML 2.0 statecharts, also known as state-machine diagrams and state transition diagrams, are designed to show how an object can change its state of being over time. When documenting requirements, you would create a state chart for a business object, in this example, a customer-order. The UML statechart would show all of the possible states that an object can be in, and all of the possible transitions, or paths, that would allow the object to change from one state to another.

The following legend shows the four primary elements of a UML 2.0 state chart.

The UML statechart starts with a solid black circle, and has a transition to the first of the possible states. The transition is the action or event that causes an object to be created or change state. In the legend above, the act of saving an order causes the creation of a customer-order object in the saved state. Near the end of the diagram (the middle is removed), a “Deliver Order” transition causes the customer-order object to change to the state “Delivered.” The end of the process is designated with a solid black circle wrapped in a thin line.

A much more thorough introduction to UML statecharts can be found at Scott Ambler’s awesome site. Ambler’s introduction includes other statechart elements, nesting of statecharts, and more complex examples. Good stuff.

The UML Statechart Example Analysis

If you had approached the requirements from a system-centric or rule-centric point of view, you might have started with the creation of a UML statechart for the customer-order object. You could also start with a process flow diagram of the customer ordering process – but that has more in common with the use case analysis.
The customer-order object is a conceptual object that represents the order that the customer is trying to place. While it is very likely that the implementation will be designed with a customer-order object too, you are not describing the implementation – you are describing the requirements.

Your first drawing of the UML statechart might look like the following:

The obvious path is clearly defined in the statechart:

1. A customer order is created in the “Saved” state when the user saves it.
2. When the customer submits the order (use case step 3), it changes state to “Submitted.”
3. When the customer is charged for the order (use case steps 4 – 8), the order changes state to “Charged.”
4. When the order has been shipped (use case step 10+11, or just 11), the order changes state to “Shipped.”
5. When the order has been delivered, the order changes state to “Delivered.”

During the review of this UML statechart with stakeholders, you would uncover the need for customers to be able to cancel an order at any point prior to shipping the order. Three additional transitions are defined, leading into a new state, “Cancelled.” If the user deletes a saved order, or cancels an order that has been placed but not yet shipped, the order’s state is changed to “Cancelled.”

Viewing the UML statechart for the customer-order object still doesn’t help uncover more requirements. Joe Shideler presented a great requirements model – a state transition table on Seilevel’s blog in late 2005. The table presents a view of possible state transitions that gets your brain out of the linear mode that it is in in either of the above situations.

A State Transition Table Example

Creating and populating a state transition table for the customer-order object would look like the following:

[larger image]

Each row in the table represents a starting state (the tail end of a transition in the diagram). Each column represents an ending state (the arrowhead end of a transition in the diagram). To read the diagram – you can see that transitions from the “Saved” state are possible to both the “Placed” state and the “Cancelled” state. Transitions to the other states are not possible – indicated by the “X” and light grey shading in each cell.

Each possible transition has a number – which provides a reference for defining the business rules associated with each transition. You could put the rules inside the boxes, but the numbers make the table much easier to read.

In some situations, it is possible for an event to cause a transition into “the same state.” An example would be if a customer desired to split one order into two orders based on shipping lead times. The “transition” is actually from one object to two other objects. Ambler shows an example like this, but it doesn’t apply in this example. The dark grey shading and bold “X” represent that an object can not “change” into the same state.

Why State Transition Tables Help Uncover Business Rules

The table above is already populated with the final answer – and you’ll notice that it shows some valid transitions that are not indicated in the UML statechart above. Populating the table forces you to consider each possible transition. As part of that consideration you are more likely to uncover “hidden” requirements than if you were only reviewing a linear model like a use case (or the previous statechart).

It is possible that an order is shipped to the wrong address, or not shipped at all. Mistakes happen. The company wants to be responsive to customers, and has defined specific business rules and policies for handling this situation.

You can update the UML statechart to show the additional transitions that must be supported:

Is The Statechart Better Than The Use Case?

Yes and no. For defining interface requirements (both the user interface and system interfaces) the use case is much more effective – it describes, by definition, the series of events that happen. However, it is biased towards documentation of the normal flow of events. Exceptions, errors and alternatives can all be documented with use cases, but it becomes harder to consume – because the use case triggers a linear analysis through the process.

When striving to achieve requirement completeness, an additional perspective is required. A statechart can provide a two-dimensional perspective of the process. It is object focused (with actions as transitions), versus action-focused. As this example has shown, the statechart can be presented in an equivalent form to the use case – very linear.

The state transition table forces you to think outside of the linear flow of the obvious course of events. You don’t have to brainstorm about “what might go wrong” – you systematically explore all of the potential state-transitions. Each transition is either explicitly excluded (with an “X” in the table cell) or explicitly included. The risk of missing a transition and its associated requirements is dramatically reduced.

The identification of all valid transitions is the first step in defining the business rules that control each possible transition.

The state transition table, while very effective for analysis, falls short of the UML statechart in presenting the results. A good practice is to update the statechart with all transitions identified in the table.

Conclusion

The use case and the UML statechart provide different views on the same requirements. Using one without the other risks missing requirements. The use case helps define interfaces with users and external systems. The statechart helps define hidden paths (alternate flows).

The state transition table is the most rigorous tool I know of for explicitly defining the valid transitions. But it is not a good communication tool. The results from use of the state transition table should be presented in the UML statechart. This solid set of transitions is the foundation for defining business rules and business requirements.