Refining the Use-Case Model—Interfaces, Data Flows, GUIs, Traceability, and Interaction

• By Kumar Vadaparty
• July 13, 2001

This column shows how to develop a fully refined use-case model. I hope some of the ideas about traceability and packaging are picked up by tool vendors (e.g., Rational, CA).

The main concepts of this column:

1. Identify UML artifacts required for showing a refined use-case model, customize them where appropriate to accommodate some important aspects of traceability and interaction, and illustrate this with a detailed example. Classify the artifacts into structural package and interaction package.
2. Show how different artifacts relate to one another and how to trace one from the other. This is critical. It is not uncommon for people to get lost in all the volumes of artifacts that can be generated using CASE tools. I show how to tame this diagram-plethora.

BACKGROUND
Our WebShop, nozama.com, decides to add books to its product line, which already has greeting cards, gifts, and software (exactly opposite in strategy to Amazon.com, which added the latter to books).

A user goes to the shop's URL, browses a bit for a desired book, and puts in an order for it. The system receives the request and sends back an immediate confirmation (comparable to amazon.com) through e-mail (this is the first step). In addition, the user can query the status of prior orders and see the details of a specific prior order.

The use-case diagram in Figure 1 captures the problem statement at a certain high level of abstraction. This example is made successively more sophisticated going forward to illustrate some of the UML customizations.

Essentially, the entire system is broken into three main use cases (ProcessOrder, FillOrder, and CheckStatus) and two actors (Web-Client and ShippingClerk). My previous column¹ discussed the general process of decomposition of a system into use cases and actors. I now address the next question: how to refine use-case diagrams with interfaces and data flows (mapping to data sources) and how to hyperlink the UML artifacts to provide traceability.

FIRST REFINEMENT: ADD INTERFACES AND INTERFACE DESCRIPTIONS
Use cases capture cohesive business functionality. Therefore, it is appropriate to define precise contractual interfaces to interact with them. The idea of adding interfaces to use cases is not new: Schneider² uses explicit interface icons for the actors and use cases to represent their contractual interaction. D'Souza and Wills³ add explicit interface descriptions to use-case diagrams.

According to the UML specification, "Actors" and "Use Cases" are special subtypes of the more general category called Classifier. A classifier has an interface, implementation, and relationships with other classifiers. Therefore, it is absolutely in accordance with the UML to speak of the interfaces of the use cases and actors. From the UML specification guide:

UML V1.3 alpha R5 March 1999: The interaction between actors and use cases can be defined with interfaces. An interface of a use case defines a subset of the entire interaction defined in the use case. Different interfaces offered by the same use case need not be disjoint.

We use UML notation for interfaces, namely, adding lollipops to classifiers. Figure 2 adds named interfaces to the use cases in Figure 1. The names of the interfaces are used to provide more detailed information about them, i.e., signatures and pre- and postconditions (see Fig. 3). Unfortunately, tools such as Rational have not yet caught up with this. There are ways to "tweak" Rational Rose to show this representation, however.

Each interface of a use case is a collection of operations representing a certain subset of functionality of the use case. Therefore, it is important that we show the pre- and postconditions and, finally, the side effects associated with each operation. A side effect is a state change brought about by an operation on an object that is neither the calling or called object nor a parameter passed. In contrast, pre- and postconditions are usually describable using the parameter names of the signatures or the attributes of the objects on which these operations are defined. Side effects can sometimes capture very important information but cannot be captured through parameter names. Examples abound: putting elements in queues (as specified in system configuration files), updates to databases (whose names are neither the parameter names nor the object data members, but again, picked from configurations), removing or adding work items/work elements to work-flows, and sending information through sockets. Besides just the name of the message queue or the database, etc., the semantics associated with such a side effect can be quite crucial and is worth mentioning in the description of the interface. The pre- and postconditions and side effects of the interfaces defined in Figure 2 are shown in Figure 3. Again, keeping up with the spirit of deliverable traceability, these details of the interfaces should be hyperlinked to the interfaces themselves in Figure 2. Also, Figure 5 shows the pre- and postconditions, and the side effects associated with a particular stored procedure. Note that the statement about row locking in the side effect has a significant impact on the performance. Hopefully, the tool vendors will pick up on the traceability aspects discussed here, and incorporate them in their tools.

SECOND REFINEMENT: DEVELOP THE TYPE-MODEL, RELATE TO EXISTING DATA SOURCES, AND HYPERLINK TO GUIs
The previous section showed how interfaces of use cases describe the operations and their signatures. Those signatures capture the types of input and output data types (like any IDL specification of interfaces). It is these types and their interrelationships that determine the type-model of the use-case model created earlier.

In the ProcessOrder use case, for example, the actor sends in the full information of the order (say, of type OrderInfo, with specific fields for ISBN Number, Title, Author, Shipping Address). The use case will send in return, if the order is complete, a confirmation message (of type ConfirmInfo) consisting of specific fields such as Confirmation Number and Anticipated Date. It is this confirmation number that the actor could later use to inquire about the status of the order.

The data exchange between different actors and use cases is shown in Figure 2. The next step with respect to data is to depict the details (i.e., logical field/attribute names and possibly types) of the data types as shown in Figure 4.

It is expected that information in Figure 4 is hyperlinked to the data-flow-type names of Figure 2. It is this process of interlinking different related deliverables that is referred to as unified deliverable traceability.

Map data flow types to existing data sources
The next step is to identify stored procedures and the data sources from which the data types of Figure 4 are populated. This step is particularly critical if we are providing Web interfaces to existing systems whose data has already been sourced in databases. In our example, the WebShop nozama.com has all the customer data fully modeled because it already sells other products on the Web. However, some data such as status information and delivery information may be particular to the current product (book) and therefore need to be modeled and sourced.

Map associations between actors and use cases to GUIs
The interaction between use cases and actors is typically captured through either GUIs or programmatic interfaces (such as messages or structured e-mails). In any of these situations, it is appropriate to define these interfaces (graphical or programmatic) and hyperlink them to the associations connecting the appropriate use case and actor. The interfaces should show:

1. look and feel, including the standards in the case of GUIs,
2. information about how the GUI session is expected to behave,
3. service level agreements for each of the sessions (response time, throughput, etc.), and
4. in case of messages, show the header, body, and format of the message, and the general agreements on how to represent the message (e.g., XML schemas).

THIRD REFINEMENT: DEVELOP THE INTERACTION MODEL
Our use-case diagrams so far show "structural" relationships only. We still do not have the information about how the actors and use cases interact with one another to fulfill a request. Many authors have suggested writing them as a series of steps under the name "Flow of events." In a typical example, from Applying Use Cases: A Practical Guide²:

The use case starts when the customer selects Place Order.

The customer enters his or her name and address.

The customer will enter product codes for the desired products...

My belief, which is re-enforced by an excellent account by Hruby,⁴ is that at each level of description, we need a structural model and an explicit interaction model. In the present example, we need to show the interaction/collaboration of the use cases and actors to achieve the desired effect. Figure 6 gives such interactions for the ProcessOrder and CheckStatus use cases in our running example using a sequence diagram. The interaction in our example is quite simple, so the sequence diagram is also very simple. These interactions, however, can be quite complex. Also, one could use UML collaboration diagrams to describe these interactions. (UML allows us to use either sequence or collaboration diagrams to describe interactions.)

Figure 6 shows how individual use cases and actors interact with one another to achieve a request. Note that interaction is not about how a particular use case is realized. Instead, it shows how requests at the parent level (in our example, the entire system) are achieved by the individual participating actors and use cases (shown as subsystems). Figure 6 becomes a lot more interesting if we add more interactions, and possibly collaborations between use cases to satisfy a request.

CONCLUSION
I showed how to customize use-case diagrams with interfaces, data flows, and pre- and postconditions, and how to map the data flow types to data descriptions, data sources, and stored procedures that load and store the data flow types. I also discussed how to hyperlink the different deliverables to provide a unified deliverable traceability. The following steps summarize the customizations:

1. Static structural package of use-case model.
• Draw the use-case diagrams: Draw the usual use-case diagrams as illustrated in Figure 1.
• Add named-interface representations: Add named-interface representations to the use cases as illustrated in Figure 2. In our example, there is only one interface per use case. In general, there could be several interfaces to a given use case.
• Add data flow type names: Add data flow types to the lines connecting the actors and the interfaces attached to the use cases (see Fig. 2). The data flow types indicate the input and output to the interfaces of the use case (i.e., the data consumed and produced by the operations within the specific interface of the use case).
• Hyperlink interface representations to actual interface descriptions: Hyperlink the named interface representations to the actual interface descriptions containing the operation names, pre- and postconditions for each operation, and the side effects of each operation (as shown in Figure 3).
• Hyperlink interfaces to their details and data flow types to their definitions. See Figure 4 for an example.
• Hyperlink data flow types to their sources in case existing systems need to be integrated. See Figure 5.

2. Behavioral aspects of the use-case model.
• Draw interaction diagrams: For each use case, draw one or more interaction diagrams (see Fig. 6) indicating the main flow of events for each major scenario. These interaction diagrams are critical to the completion of use-case model.
• Annotate the interaction diagrams: Annotate the interaction diagrams with the right interfaces and their operations (as shown in Fig. 6 on the horizontal lines).

QUESTIONS TO BE ANSWERED
There are a number of questions that need to be addressed. First, Load/Save Stored procedures capture some of the most important behavioral parts of the system, yet these are not shown in use-case diagrams such as Figure 2. Is this level of detail necessary? If so, where and how should they be shown? The second is about GUIs. A user may give, by mistake, the wrong ISBN number of the book in the OrderInfo (or wrong author name, etc.), or may want to decide on a book after a number of interactive queries. Ideally, we should let the user browse whatever information he wants to browse, then collect all the information about the book he wants to purchase in possibly more than one screen exchange, validate it, and then (and only then) SendOrder(OrderInfo) on the use case. How do we depict this GUI logic? Where does it belong?

Future installments will address these crucial questions.

References

1. Vadaparty, K. "Use Cases—Basics," JOOP, 12(9): 4–8, Feb. 2000.
2. Schneider, G. and J. Winters. Applying Use Cases: A Practical Guide, Chapter 4, Exhibit 4–7, Addison–Wesley, Reading, MA, 1998.
3. D'Souza, D. and W. Alan. Objects, Components and Frameworks with UML: The Catalysis Approach, p. 158, Addison–Wesley, 1998.
4. Hruby, P. "Structuring Software Development Artifacts with UML," JOOP, 12(9): 22–33, Feb. 2000.