UML Statecharts and Documenting Business Rules

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.