A look back at the best from this week in the past.
A look back at the best from this week in the past.
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.
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.
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 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:
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.
What is a data dictionary and how is it used when communicating and managing requirements?
A data dictionary is a collection of the definitions of the structure of information that is relevant to a set of requirements. That’s a lot of words for a simple concept. We need to know (and constrain) a set of information about some business element when managing our requirements. We use a data dictionary to define what that information is, and any constraints on how it must be used.
Viewing The System
When using object oriented analysis (OOA) as part of defining requirements, we represent business concepts as objects and processes. For example, an order management system might define orders as having line items and customers. We can represent that information graphically with a UML diagram like the following:
In prose, we could also capture the same information as follows:
- The system shall include a representation of customer orders.
- 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.
- Each order will have at least one, and possibly multiple line items. Each line item is uniquely associated with a single order.
- 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).
While this diagram tells us about the structure at a high level, it doesn’t tell us enough information to go implement the solution. What exactly is a line item? What information does it contain? And what format must that information be in?
A Dictionary Entry
We could create a data dictionary entry for the line item object as follows:
A line item represents a portion of a customer order that describes a product being ordered, as well as the quantity of that product being ordered. Each line item must include the following information:
Note that we have not specified that a line item includes a price. It is very likely that a line item would have a price, but we would be specifying implementation details if we did. Pricing may be done per product, or may be unique for each product for any given customer. Discounts may be applied based upon quantity of products in a line item, or dollar amount for an order. Discounts may be applied based upon all products ordered by a customer over a period of time. These different possibilities are a function of the requirements of the system.
When those business requirements are defined, they will dictate the ownership of properties by business objects. With that information, we can include the data as appropriate. For example, a list price property may be defined for the product object, or a customer-price may be defined for a line-item as a function of (product, quantity, customer). We would add that data as part of the business modeling. Note that this is a description of the problem domain, not a description of the implementation.
Another Data Dictionary Example
Here’s an example of a “Customer”
A customer represents the business or person for whom an order has been placed. Note that all character fields are to be represented in unicode 4.1.0 or later per corporate policy ABC. A customer has the following information:
This list is intended to show all of the elements of information that must be present in the “customer object” to support the requirements of the system.
Joe, at Seilevel wrote a post back in March with a good explanation of data dictionary entries. As Joe points out, requirements can drive the need for specific information.
For example, my business users have told me that the number of decimal places of each weight value tracked by the system is very important for monitoring and reporting. It stands to reason that other objects and attributes might require the same level of specification. If you figure it out once, you can use it in many places.
Barbara, at B2T Training points out the importance of understanding the details of the data for a system. She also touches on the value of having that information in a separate document.
Many BAs document data as part of the business process or part of the Use Case. Our recommendation is that you document data in a separate part of the requirements package because it is often used in multiple places.
A data dictionary should be defined as a repository of all data definitions like the examples above. Those examples should be referenced in all requirements documents that rely on the defined objects. Requirements documents should not specify the content of the objects, they should defer to the referenced dictionary entries.
Some projects, especially migration projects, have many constraints tied to data formats and structure. These projects will have extensive data dictionaries, and multiple references to entries throughout the requirements document. Other projects will have far fewer constraints on data formats, but will still have explicit structural definitions for business objects (like our line item example).
– – –
Check out the index of the Foundation Series posts which will be updated whenever new posts are added.
The UML way to organize and manage use cases.
Instead of duplicating the explanation and summary work already done by Chris at grillcheese.blogspot.com, I’ll point you to his post, Introduction to UML-2 use case diagrams. Agile modeling has a detailed post on UML-2 use case diagrams.
There are ultimately four pieces of information you want to know about use cases. UML diagrams will show you two of them.
Knowing that we can’t answer all 4 questions with a single communication tool, here’s what we should do:
(1&3) Create a matrix view of use cases versus actors to show which actors perform each use case, and when they will be available.
(2) Create a UML 2.0 use case diagram if you find that the benefits for your communication outweigh the costs of maintaining the diagrams. In projects I’ve worked on in the past, a simple flow chart with use case names have been used. These simple charts can be made in a fraction of the time, are more easily scannable, and present information more densely. If you are managing requirements with a tool that automatically generates the diagrams, then do it – but don’t spend a lot of time on them. A flowchart takes almost no time to draw, and communicates the information just as effectively (and more succinctly). Suggestion – use the flow chart.
(4) Ultimately, UML diagrams (often referred to as “use case cartoons”) focus your attention on what you are building, at the expense of losing focus on why you are building it. Create a mapping or maintain links (traceability) from use cases to goals.
The why of the use case is the most important information. Don’t let use case cartoons distract you from it.
Poll: Which use case format do you use?
If you answered ‘Other’ please comment and let us know what you use!
Quick links to posts in this series