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.
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
- 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:
- The customer selects products to purchase.
- The system adds the products to the order.
- The customer submits the order.
- The system requests payment for the order from the customer.
- The customer provides payment information.
- The system requests payment for the order from the billing-provider.
- The billing-provider acknowledges payment processing.
- The system notifies the customer of successful payment.
- The system submits the order to the fulfillment system (another system at the company).
- The fulfillment system ships the order [note: this would likely be a subordinate use case].
- The fulfillment system notifies the system that the order has shipped.
- 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:
- A customer order is created in the “Saved” state when the user saves it.
- When the customer submits the order (use case step 3), it changes state to “Submitted.”
- When the customer is charged for the order (use case steps 4 – 8), the order changes state to “Charged.”
- When the order has been shipped (use case step 10+11, or just 11), the order changes state to “Shipped.”
- 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:
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.
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.