The RSI Approach to Use Case Analysis
A ProtoPattern for Structured Use Case Development
Mark Collins-Cope

PDF version

---

1. Summary

This paper describes the RSI (requirement/service/interface) pattern for use case analysis. The RSI pattern for use case analysis separates use cases into three major categories, which are represented as stereotypes using the UML notation

• «requirement» use cases - which provide the starting point for the use case analysis process, and are based on Alistair Cockburn's work on goal oriented use cases;
• «service» use cases - which define (in detail) the underlying services that a system will offer to its users; and
• «interface» use cases - which define aspects of functionality that are concerned with the interfacing of the services provided to system actors (both users and external systems).

2. Background

Use case analysis is a requirements capture technique that is most often used in the early stages of OO and component development projects. It was first introduced by Ivar Jacobson in his book "Object Oriented Software Engineering" [1], although the description of use case analysis presented in this book has, in practise, been interpreted in many different ways (one of the consequences of which is that, seemingly at least, no two use case analysis projects ever deliver the same information). Broadly speaking, use cases assist in defining the functional requirements of computer systems. Following is a typical use case diagram:

Figure 1 - An example use case diagram

The use case diagram in figure 1 is made up of the following elements:

• a bounding box - showing the scope of the system under specification (the inner box of figure 1).
• a number of actors (stick men) representing the categories of users or systems which interact with the system under specification, in this case:
• the manager of the bank
• the clerks at the bank
• the BACS network for inter-bank transfers, and
• automated timing facilities
• a number of use cases (ovals) representing the 'business functions' provided by the system, in this case:
  • functions to set overdraft limits
  • functions to undertake BACS (automated inter-bank) transfers
  • functions to create new customers and accounts, and
  • functions to produce a monthly overdraft report
• interaction flows (double ended arrows), showing which actors interact with which use cases.

Use case diagrams are typically supplemented with additional documentation, describing the detail of each use case.

Jacobson's use case are structured around business processes for which automated support is required. Page 350, section 13.3.1 of [1] describes the use case 'Transfer goods between warehouses'. The description of this use case contains both individual 'commands' ("Foreman issues command to transfer goods between warehouses", "Truck driver notifies system that he has arrived at the warehouse", etc.), and detailed user interface designs (diagrams of dialogs are shown). Much of the description is concerned with describing user interface dynamics (e.g. "the foreman may move between fields by using the tab key.")

Cockburn's work ("Structuring Use Cases with Goals" [2]) describes use cases in terms of a goal oriented sequence of steps. The following use case extract is taken from Cockburn's paper [2]:

Use Case: Get paid for car accident (insurance system):
Actor - Claimant
Actor goal - to get paid for a car accident

1.      Claimant submits claim with substantiating data;
2.      Insurance company verifies claimant owns a valid policy
3.      Insurance company assigns agent to examine case
4.      Agent verifies all details are within policy guidelines
5.      Insurance company pays claimant

Extensions
1a.    Submitted data is incomplete
1a1.  Insurance company requests missing information
… etc.

(Note that some steps of this description (e.g. step 1) are unlikely to be automated).

Cockburn goes on to describe how each step within the description can be viewed as a mini 'use case' in its own right - thus use cases are decomposed into sub-use cases. Cockburn describes the classification of use cases into 'summary goals', 'user goals', 'subfunctions' and 'dialog interactions' (at which level Cockburn describes goals such as 'move to next field using the tab key').

The work presented in this paper builds on Cockburn's approach. It differs in its classification of use case types; and in targeting the decomposition of use cases into «interface» and «service» sub-use cases.

3. Motivation for the RSI Approach

The RSI (requirement/service/interface) approach to use case analysis provides a structural model for use cases that:

• provides a framework for analysing and understanding the potential deliverables of use case analysis and their inter-relationships, with a view to answering questions such as:
  • what is the appropriate level of granularity for use cases? If large grained use cases are used, should they decomposed into 'lower level' use cases, and if so, at what point should this decomposition stop, and how should these sub-use cases be used?
  • should user or external system interface functionality be described in use case text? How do dialog descriptions fit in? Where do report layouts go? Should user interface dynamics be included? Should interchange file formats, or interface protocols form of the documentation? Where and how should these items be documented?
  • should non-automated functionality be documented in use cases?
• assists in maximising software re-use by partitioning functionality into those aspects which are concerned with 'managing the interface' to an actor, and those areas which make up the re-usable core of the system.

4. Applicability

The RSI approach to use case analysis should be used:

• as a framework for decision making regarding the granularity, structure and content of use case analysis and its deliverables.
• on medium to large projects where it is desirable to split the business analysis/system design/user-interface roles.
• on projects requiring a component oriented view of the system being developed.
• projects requiring a high degree of rigour and traceability in the development process.

5. Structure

Use cases are divided into three categories, shown by the UML stereotypes «requirement», «service» and «interface»:

Figure 2 - Relationship between «requirement», «service» and «interface» use cases

«requirement» use cases document business processes for which automated support may be required. They detail the requirements driving the development of a system, but do not define the detail of a system's functionality. «interface» use cases provide a detailed description of the interfaces presented to the system's actors and association functionality. «service» use cases provide a detailed description of the underlying functionality a system offers in a manner independent of the needs of any particular interface. An alternative view of the relationships between the RSI use case types can be seen in figure 3:

NOTE: Enlarge the diagram below by clicking on the picture.

Figure 3 - Relationship between RSI use cases

The separation of «interface» and «service» use cases can be viewed as a layering of the functionality of a system, with «interface» use cases providing a 'translation' role between the nuances of a particular interface and the essential core of a system (see figure 4).

NOTE: Enlarge the diagram below by clicking on the picture.

Figure 4 - Separation of the functional concerns of the interface and the core of the system

6. Participants

6.1. «Requirement» Use Cases

A «requirement» use case defines a business process for which some automated system support may be required (e.g. "sale of goods", "resource a course", "open a new account", etc.). «requirement» use cases may be documented in the manner described by Cockburn [2], detailing:

• the actor,
• the objective of the use case,
• a process oriented decomposition of the use case into a sequence of steps,
• a list of any extensions dealing with deviations and exceptions in the normal sequence of events (Cockburn's exception numbering convention is particularly useful in these descriptions),
• a list of variations (in actor types) to avoid use case scenario explosion.

6.2. «Interface» Use Cases

«interface» use case describe functionality that is concerned with managing the interface between the actors of a system and the underlying services it offers. «interface» use cases undertake the role of 'translating' the information provided by an actor into a form acceptable to a set of underlying «service» use cases. To do this, they factor the elements of functionality that are more related to the interface than to the underlying system.

«interface» use cases may be documented as follows:

• the objectives of the interface
• a detailed description of any interface formats used. This might include user interface designs (dialogs, etc.), report layouts, file formats, interface protocol descriptions, etc.
• a step by step description of the functional aspects of the interface such as user interface dynamics (e.g. "when the 'select customer' button is clicked, the 'accounts' list-box is refreshed"), file processing, how report contents are made up, etc.

6.3. «Service» Use Cases

«service» use cases define the underlying functions offered by a system in a manner independent of any particular interface concerns.

«service» use cases may be specified as follows:

• the objectives of the service
• a list of input parameters detailing the information (if any) that is passed to the use case from its calling environment (e.g. customer, account, date, etc).
• a list of output parameters, detailing the information (if any) that is passed from the use case to its calling environment upon termination (e.g. set of overdrawn customers, all new accounts, etc.). Both input and output parameters may be described in terms of objects in an associated specification object model.
• the pre-conditions of the use case, describing what conditions must be true of the system before the use case can be initiated. Note that pre-condition descriptions may cross-reference an associated specification object model, and could be specified in OCL.
• the post-conditions of the use case, describing any changes that will be made to the internal state of the system once the use case has been completed. Note that post-condition descriptions may cross-reference an association specification object model, and could be specified in OCL.

Two flavours of «service» use cases emerge:

• «update service» use cases - those that change system state, and
• «query service» use cases - those that retrieve information without changing system state.

The input parameters to «query service» use cases are typically used to provide a selection criteria by which sets of objects within the system will be identified. These are then returned in the output parameters. The input parameters to «update service» use cases are typically objects returned by a previous invocation of a «query service». «update service» use cases do not usually deal with selection criteria.

7. Inter-Relationships (Collaborations)

See figures 2, 3 and 4.

«requirement» use cases are decomposed into the «service» and «interface» use cases necessary to implement those parts of the requirement it is decided to automate. The inter-relationships between «requirement» and «interface»/«service» use cases may be shown using a «uses» trace on the use case diagram.

«interface» use cases invoke «service» use cases to gain access the core elements of the system. The two subdivisions of «service» use cases are typically used in the following manner:

• «query service» use cases are used by «interface» use cases to provide information necessary for the construction of (user) interface dynamics. For example, in a banking system double-clicking on a particular customer in a ‘customers' list-box may cause an associated ‘accounts’ list-box to be refreshed with the chosen customer's accounts. To retrieve this information, a «query service» would be used ('select accounts by customer' in this case).
• «update service» use cases are used by «interface» use cases to change the internal system state (to actually “do” something). The parameters of the «update service» will have typically been returned by a previous invocation of a «query service». The inter-relationships between «interface» and «service» use cases may be shown using a «uses» trace on use case diagrams.

8. Worked Example

8.1. Retail Banking Example

This example looks at the need for automation in the cheque clearing and inter-bank transfer aspects of a retail bank.

8.2. «Requirement» Use Case Model

Two «requirement» use cases are identified: 'processing cheques and credits' and 'inter-bank transfers'. These are documented in the following fashion:

Figure 5 - «requirement» use case model for retail banking example

Use case «requirement»: "process cheques and credits" Objective: To enable clerks to process the paperwork associated with cheques and credits, entering the relevant information into the bank's systems. Steps 1. Cheques and credits are delivered in (paper) batches to the clerk's desks (not automated). 2. The clerk picks the next cheque or credit, and calls up the relevant bank account information on the system (automated) 3. The clerk enters the cheque/credit details (automated) Extensions: 2a. the cheque or credit is not related to an account on the bank's system. 2a1. the cheque or credit is put into a 'rejects' pile (not automated). etc. Use case «requirement»: "inter-bank transfer" Objective: To enable the reading and writing of files sent via the banking network. Steps 1. Inter-bank transfer files are sent (nightly) over the banking network to a well defined place in the bank's computer system. Files conform to a defined format. (automated - but not part of this system's functionality) 2. At a configurable time, the bank's system reads and processes the credits and debits in the file (automated). 3. These are entered into the bank's system (automated). Extensions: 1a. The transfer fails. 1a1. This is logged on the external system (not automated in this system) 2a. The file is not there. 2a1. A note is made in the system log. Use case is terminated (automated). 2b. There is a formatting error in the transfer file. 2b1. A log of the offending part of the file is written to the 'outgoing error log' file. If possible, the remainder of the incoming transfer file is processed as normal (automated). 3a. The account for which the transaction is specified is not a valid account in the system. 3a1. As per 2b1, detailing the transaction (credit or debit) which failed (automated).

Figure 6 - example description of «requirement» use cases

8.3. «Interface» Use Case Model

The following «interface» model meets the automation requirements detailed in figures 5 and 6:

Figure 7 - «requirement»/«interface» use case model for retail banking example

Steps 2 and 3 of «requirement» use case “process cheques and credits” are refined into the following «interface» use case description:

Use case «interface»: "enter transaction details" Objective: To provide an interface enabling clerks to enter transaction related details into the system. Formats Functionality 1. Adding a character into the “Customer Surname” field causes a list of those customers on the system matching the (possibly incomplete) name shown in the field to be displayed in the “Customer” list-box (using «query service» “select customer by name“) 2. Selecting a customer in the “Customer” list-box causes that customer’s accounts to be displayed in the “Accounts” list-box (using «query service» “select accounts by customer”) 3. Clicking on the “Cheque” radio button causes the “Cheque No.” field to be enabled. 4. Clicking on the “Credit” radio button causes the “Cheque No.” field to be disabled. 5. Clicking OK causes the following dialog validation to take place: Account selected, Value entered, Cheque number entered (if “Cheque” radio button selected). On completion of validation, the details provided are entered into the system (using the «update service» add transaction)

Figure 8 - Example description of «interface» use cases

Steps 2 and 3 of the «requirement» use case “inter-bank transfers” are refined to the following «interface» use case:

Use case «interface»: "process inter-bank transfer file" Formats The inter-bank transfer file is formatted as follows: <Account Number>, <Transaction Type>, <Value> [,<Cheque no.>] e.g. 122312 credit 234.55 123345 cheque 1244.43 019876 etc. The 'outgoing error log' file is formatted as follows: <error-code>, <related text (from input file)> e.g. 217: input error line 234: '122341 cheque 3345.3' etc. Functionality: For each line in the inter-bank transfer file, the corresponding transaction is added to the system (using the «query service» select account by number to validate the account, and the «update service» add transaction enter the transaction).

Figure 9 - example description of «interface» use cases

8.4. «Service» Use Case Model

The full use case model for the retailing banking requirements is as follows:

Figure 10 - full use case model for retail banking example

The «service» use cases are documented in the following manner:

Use case «query service»: "select customer by name" (in:theNameString, out:theCustomers) In: theNameString - a (possibly partial) name string which forms the criteria by which customers will be selected Out: theCustomers - set of customers meeting matching the stated criteria Objective: to return a collection of customers whose surnames match the (potentially partial) string theNameString. Pre-: True Post-: theCustomers.customers contains all customers in IBankingService.customers where theNameString[i] matches IBankingService.customers.surname[i] (where 0 <= i < length(theNameString)). Variants: None. Use case «update service»: "add transaction" (in: theTxType, theTxValue, theAccount, theChequeNo) In: theTxtype - the type of the transaction to be added theTxValue - the value of the transaction to be added theAccount - the account to which the transaction is to be added theChequeNo - the cheque number, if applicable. Objective: to add the specified transaction to the specified account Pre-: theAccount must be a valid account in the system ... etc. Post-: A transaction t (of the appropriate type) is added to theAccount.transactions, where t.value = theTxValue, t.chequeNo (if applicable) = theChequeNo. Variants: Other transaction types are envisaged in the future.

Figure 11 - example «service» use case descriptions (both query and update)

Note that the «service» use cases are specified against the following specification model:

Figure 12 - Specification model for retail banking system

9. Benefits

• A framework for decision making on the appropriate "granularity" and "content" of use cases
  It is not the intention of the RSI approach to mandate that all three types of use case be specified at all times. Such decisions must be driven by project needs such as size, skills availability, criticality, etc. The RSI approach provides a framework within which conscious decisions can be made as to what level of detail of use case is appropriate for a particular project, and provides clearly defined placeholders for all major specification deliverables.
• A component-oriented view of the system encouraging re-use
  The RSI approach assists in presenting a component oriented view of a system. The «service»/«interface» split facilitates inter-system integration by easing the addition of new interfaces on the system.
• Team structuring
  The RSI approach assists in the separation of roles between: business oriented non-technical analysis staff (who would undertake «requirement» use case definition); design oriented staff (who would undertake «service» use case definition) and user-interface specialists (who would undertake user «interface» use case development).
• Traceability
  The RSI approach provides traceability between the «requirements» driving system definition and the «service»/«interface» implementing them. This can be particularly beneficial in evaluating the cost of requirement changes.

10. Consequences

10.1. Separating «Interface» and «Service»

The separation of «interface» and «service» use cases is functional (although in some circumstances it may also be mirrored by an architectural split between the client and server elements of multi-tier systems), and so within the scope of the use case analysis. The separation of «service» and «interface» use cases partitions functionality into the elements that are primarily concerned with manipulating the peculiarities of an interface, and the elements that are fundamental to the system in question. The motivations for this separation are twofold: to encourage the re-use of «service» use cases (from a variety of «interface» use cases), and to enable a clear factoring out of interface concerns in the specification process.

In some cases the «service»/«interface» separation is clear-cut, most often when the actor is a human user. In other cases things are not quite so straightforward. Consider the retail banking example in section 8. A requirement exists for a file of transactions to be read and entered into the system. Is the file parsing activity a «service» or an «interface» use case? To answer this type of question consider what aspects of functionality would change if the nature or the if the interface changed. The aspects that remain constant constitute part of the «service» use case set; the aspects that vary constitute part of the «interface» use case set. Accordingly, the file parsing activity in the "inter-bank transfer" use case (see figure 9) is part of an «interface» use case.

10.2. Two Phased Approach to Use Case Analysis

Figure 13 - the RSI use case analysis process

From a process perspective, two phases of use case analysis emerge: high level «requirement» use case gathering and detailed «service» and «interface» use case specification. «service» and «interface» use case definition are undertaken in parallel, as «interface» use cases drive the definition of the set of «query service» necessary in the system.

The process of moving from «requirement» use cases to «interface»/«service» use cases involves both scoping and refinement. A decision is made as to what steps in the «requirement» use case are to be automated. These are then refined into «service» and «interface» use cases.

It is interesting to note that this process has a related parallel in the transformation of a conceptual object model into a specification model. «requirement» use cases are at the level of abstraction of conceptual object models; «service» use cases at the level of specification models.

Figure 14 - scoping and refinement of models

10.3. «Interface» Drives «Query Service» Definition

«interface» use cases use «query service» use cases to locate objects that need changing, and «update service» use cases to perform the changes. «query service» use cases provide functionality useful in ensuring the pre-conditions of «update service» use cases are met.

The set of «query service» use cases required in a system will vary depending on the exact nature of the interface. Consider two interfaces to an «update service» "delete customer". A dumb terminal interface requires the user type in the customer number, which will then be validated before deletion operation is carried out. To do this it might use a «query service» "check customer exists using customer number." Alternatively, a GUI style interface will be more sophisticated (perhaps similar to the interface in figure 8), building up lists of customers on the screen. To do this, it might use a «query service» use case such as "get all customer by name."

11. Known Uses

The RSI approach has been used successfully by Ratio Group on several projects of varying sizes. The approach was developed at Ratio Group, hence its classification as a proto-pattern. Fowler [3] discusses the difference between what he calls 'user goals' and 'system interactions' (in RSI terms - these are akin to the «requirement»/«service» split.) Cockburn [2] talks about the difference between 'dialog interface' and 'semantic interface' - perhaps akin to the «interface»/«service» split of RSI.

12. References

[1]	Ivar Jacobson et al. - Object Oriented Software Engineering - A Use Case Driven Approach, Addison-Wesley.
[2]	Alistair Cockburn - Structuring Use Cases With Goals - http://alistair.cockburn.us/crystal/articles/sucwg/structuringucswithgoals.htm.
[3]	Martin Fowler - UML Distilled - Addison-Wesley.
[4]	Component Based Development and Object Modeling - Keith Short - Texas Instruments.
[5]	Personal discussions with Benedict Heal on the Catalysis and its approach to use cases.

13. Credits

I would like to thank: Thomas Mowbray, Pete McBreen, Steven Kefford, Alan Williams, Hubert Matthews and Greg Gibson for their work in reviewing the first draft of this paper. Their comments were invaluable, and led to a substantial reworking of this paper.

Particular thanks are due to Benedict Heal, whose work had a major impact on the ideas presented in this paper.