Business Requirements Analysis Using UML (Part 1)
This article (the first of two parts) describes the Business Requirements Analysis (BRA) process and work products of QED Software Ltd of New Zealand. The process originates from traditional structured techniques but has been heavily influenced and modified by the latest object-oriented techniques -- in particular, the Unified Modeling Language (UML).
Where most OO techniques recommend an iterative life cycle in which a development effort is a series of "design a little, code a little, test a little" cycles, QED's clients require a more traditional up-front signoff of a "Functional Specification" that is the result of performing analysis for the whole application, prior to moving forward into the design phase. This has proved a benefit for both the client and QED, in that it allows for more accurate project resource and cost estimates to be produced.
The BRA phase begins once the client has a 'wish list' of requirements, often in the form of a Request for Quote (RFQ). The first step in this phase is to scope the analysis effort, identifying the specific business processes that are to be enhanced with automated support. This both focuses the analysis and helps manage the user's expectations.
By using use cases to describe functional specifications, the analysis phase is actually heavily steeped in user interface design but without fully committing to actual look and feel prototypes. The primary objectives of the BRA Functional Specification are:
- The client is satisfied that it is an accurate description of the application
they want developed (and will sign a statement to that effect), and
- The design phase can proceed based on this description, with minimum questions.
The result to date of applying the BRA process has been highly-satisfied clients and work products that lend themselves for moving into the application design phase.
BRA Phase Deliverables
Prior to undertaking business requirements analysis, there must be an approved business case for providing automated support in one or more parts of the organization. QED may work with the clients to determine what is 'generally' needed, or the clients may have determined this for themselves, possibly issuing an RFQ or RFI detailing these needs.
But this is not the same as detailed requirements analysis, nor are the work products typically found in such deliverables sufficient to go forward with into a design effort. The BRA phase delivers four documents for client signoff:
- Scope -- identifies the key business processes, primary information types, intended application users, and other applications requiring interfaces that will be the focus of detailed analysis.
- Functional Specification -- describes in detail the business processes in terms of workflows and use cases, based on a fully-attributed data model
- Test Plan -- describes the testing procedures, required resources, and critical business processes that are to be given special attention during system testing.
- Deployment Plan -- describes critical aspects of the environment in which the application will be deployed, including data migration considerations.
This article will focus on the Scope document and the start of the Functional Specification -- the initial task of specifying functions using workflows. A companion article will complete the look at the Functional Specification, presenting example use cases and other work products that make up the Functional Specification. The Test Plan and Deployment Plan will not be described.
BRA Phase Steps
The steps in the BRA phase are as follows:
|1.||The project owner identifies which business processes are targeted for automated support. Based on this, and initial input from key business users, the Analyst drafts the Scope document.|
|2.||The Scope document is reviewed and signed off.|
|3.||Analyst(s) conduct BRA sessions with key user participants.|
|3.1||For each business process identified to be in scope:|
|3.1.1||Critical Workflows and/or Use Cases are modeled as UML Action Diagrams.|
|3.1.2||Analyst documents Action Diagrams.|
|3.1.3||Stakeholders review documented Action Diagrams.|
|3.1.4||Use Cases identified in Action Diagrams are further analyzed.|
|3.2||Analyst documents Use Cases, [Entity] Class model, and Business Rules.|
|3.3||Required interfaces and reports are identified and documented.|
|3.4||Analyst drafts Administration Use Cases.|
|3.5||[Ongoing] Review of documented elements by participants.|
|4.||Functional Specification (FS) is drafted (combined results of Step 3) and reviewed by stakeholders.|
|5.||FS is revised and prepared for signoff.|
|6.||FS is signed off.|
|7.||Scope document is revised to serve as an 'Introduction' to the system.|
BRA Step 1 -- Drafting the Scope Document
Business Requirements Analysis requires many weeks of effort on the part of analyst(s) and user representatives. It therefore is vital to 'scope' the effort of the current project as best as possible (i.e., identify which business processes are to be provided with additional/improved automated support, and what types of information are to be managed in a database). The QED methodology includes a simple technique for defining this scope.
A common input to BRA is a 'wish list' of client requirements. This may have resulted from a needs analysis carried out by QED or as part of the business case that lead to an RFQ. Such a wish list very likely had no restrictions on what any user of the client could ask for. 'Thinking outside the square' should always be encouraged during these efforts. The cost of recording these wishes is minimal (i.e., a few days for small projects, a week or two for larger ones). However, the cost of analyzing the results of wishes in detail (i.e., during BRA) is significantly higher (i.e., a few weeks for small projects, a few months for larger ones). Therefore the first step in performing detailed analysis is to agree with the project owner the scope of the requirements analysis effort.
The Scope document is produced by a QED analyst. Its primary purpose is to focus the project by identifying the specific areas the sponsor/owner is willing to support in terms of analysis time and effort (i.e., cost).
The Scope document identifies and describes:
- Significant business processes
- Primary information types -- to be maintained and/or accessible in a database
- Types of users intended to interface directly with the application
- Other Systems -- that will require interfaces
An initial meeting with the owner/sponsor lasting not more than an hour begins this process. Following this meeting, the drafting of the Scope document by the analyst should take only a few days. During this time the business project manager and one or two key business users may be required to contribute additional details and definitions. Eventually each of these participants needs to review the document for final signoff. At the heart of a QED-developed Scope document is a one-page diagram (see Figure 1).
Figure 1: Generic Scope Diagram
A single box in the center of the diagram represents the eventual application. The significant business processes are seen on the left, named in ellipses. The result of BRA will be some number of tasks within each process, some or all of which will involve a user interacting with the application. Those that do will be further described (in the functional spec) as use cases.
Listed within the application [box] are primary information concepts. These represent the kinds of information that the application is expected to deal with (i.e., 'stored' in a database by this application or accessible from some other system via interface). The stick figures, known as actors in UML, represent [roles of] users and other existing systems requiring interfaces. Not every task will necessarily involve an actor interacting with the application, but this is not determined until detailed analysis is performed.
A typical Scope diagram should contain between five and nine (seven +/- two) business processes, primary information concepts, and actors. Fewer than five of any one type is acceptable. However, if the number of items of any type begins to go above nine, it's either because the analyst is being asked to include too much detail or else the application itself is being expected to cover too large of a business functional area. For business requirements analysis addressing multiple functional areas, there needs to be one Scope diagram for each significant business area. Each of these diagrams can be thought of as representing a 'sub-system' (e.g., a Human Resources system being broken down into sub-systems supporting 'recruiting,' 'benefits,' 'performance review,' etc.).
Example BRA Scope*/ ?>
NOTE: The examples in this article are based on an actual application developed for a client of QED. Specific names and/or facts have been altered in order to maintain confidentiality of information.
The government utilizes part of its income from taxes to provide transportation assistance to primary and secondary school students. Students who qualify for assistance are those living in rural areas, where convenient public transportation is not available. Managing the assistance program is outsourced to Transport Service Agents. Staff of these agents follow guidelines for approving applications from parents for this assistance. The assistance takes the form of an assignment of the student to a school bus and/or paying the parent a conveyance allowance. Depending on the distance they live from the school and/or nearest school bus route, one or both forms of assistance can be granted.
At the same time, the viability of school bus routes must be managed. There is usually a point beyond which it is cheaper to pay one or two parents a 'per Km' rate to bring their children to a more central bus stop than to pay a bus operator (a much higher per Km rate) to drive the full distance to where the most remote students live. The Transport Service Agent is also responsible for dealing with bus operators and managing their performance (and safety) against contracted terms and conditions.
A software system was required by the government to help their Transport Service Agents manage students needing transport assistance, the contracts and monitoring of school bus routes, and also the ongoing payments to bus operators and parents granted a conveyance allowance (all payments direct credited by the government's accounts payable application).
The Student Transport System (STS) to be developed by QED was originally described in an RFQ document that represented the government's requirements (i.e., Phase 1 deliverable). Our first task of the STS project was to Scope the BRA effort. The Scope diagram from the signed-off document is shown in Figure 2. The text that accompanied this diagram in the Scope document is provided in Sidebar 1.
Figure 2: STS Scope Diagram
Each business process was described further in the document. At the initial scoping stage, the details of these processes were not yet well understood either by QED or the users. For scoping purposes, a list of probable tasks within each was included.
For example, within Maintain Students, the initial description read as follows:
The scope of the business process "Maintain Student" is currently understood to include:
NOTE: Sourcing of student details from any student database currently under development is outside of scope for Phase 1.
One or more workflows describing the sourcing and the maintaining of student records will be developed as part of the functional specification. Full details on what information is maintained in STS relating to students and schools will be defined at that time.
Also at this stage, there was only a preliminary understanding of the Primary Information concepts representing the transactions and supporting items listed in the STS Scope diagram. However, an initial definition of each Primary Information concept was included, to give an indication of what details each represented at this initial point in time. The definitions of these concepts were included in a glossary in the Scope document.
An example concept definition from the Scope document was:
A legal agreement between the government and an organisation or person covering some form of Transport Assistance (e.g., bus service, conveyance allowance). A contract includes on or more schedules. Each schedule identifies a specific route and a payment schedule. Contracts are not in effect until the provider and a representative of the government have signed them. Schedules, when requiring modification, are superseded by a new schedule. A new schedule is not in effect until signed by the Provider and Service Agent.
E.g., contract 12345 between the government and ABC Bus Company to provide transport services described in schedules for Route 1234, 1235, and 1236 (each describing the route, student numbers, and payment schedule for the route).
BRA Step 2 -- Signoff of the Scope Document
When the final draft of the Scope document is signed off, the project is ready to proceed with detailed Business Requirements Analysis. Signoff does not imply that the document is 100% accurate or that it absolutely limits the scope of the analysis effort. The expectation is that the it is about 80% accurate, based on the best possible understanding of the situation at the start of a project. As BRA progresses and additional details are learned, cosmetic changes (e.g., terminology) and very likely one or two (agreed) changes to scope can be expected.
BRA Step 3 -- Detailed Requirements Analysis
The Scope document serves as an aid to project planning for the third step of BRA. Appropriate groups of users need to be scheduled for analysis sessions, each session (one or more) focusing on one of the business processes. Participants are given a copy of the Scope document as preparatory reading for these sessions. The Scope diagram is used to 'kick off' each group of sessions involving new participants, providing an overview of the project and setting the context for the session(s) that are about to begin.
Following this introduction, the first order of business at each session is for the participants to confirm that the description is accurate for the business process being addressed. The second order of business is to add detail. This detail (Step 3.1.1) involves either modeling a critical workflow within the business process or describing an individual use case.
NOTE: Thanks to the Scope document, neither analysts nor users are ever faced with the questions:
- "How do we discover use cases?" and/or
- "How do we identify [entity] classes?"
The business processes provide a top-down path to use cases. At the same time most, if not all, of the primary information concepts become entity classes in their own right.
Critical Workflows*/ ?>
Among the information concepts listed in the Scope diagram will typically be one or two 'Event' or 'Transaction' information types. These are things like Orders, Shipments, or some such thing representing interactions between the organization and customers. Typically it is precisely these items that are the impetus for the application itself (i.e., automated support for staff when dealing with customers at the time these events occur).
Most, if not all of the other types of information are there to support these events/transactions. There is typically either a workflow that represents the 'life cycle' of one of these items (e.g., an order, from capture through delivery), or else the item itself involves a complex collection of actions (e.g., configuring a complex product such as a travel reservation).
The business users allocated to the BRA sessions should have the best possible understanding of these processes. The analyst translates the information provided by these experts into Action diagrams. When one or more workers are involved in the process, the Action diagram includes 'swim lanes' (as shown in Figure 3). Boxes in these diagrams represent tasks within the overall workflow. In cases where a task is performed by a worker interacting with the (to be developed) application, that task -- if it results in value to the worker -- becomes a Use Case. Each use case is named in terms of the value it delivers and, at the same time, identified by a unique use case number.
All other tasks are named, and described in the overall workflow description. But any additional detail about these non-use case tasks is outside the scope of the application, and therefore is not part of BRA for the application.
Example Workflow*/ ?>
The diagram in Figure 3 describes the workflow for an application for transport assistance. Note that two of the five swim lanes involve workers that were identified as (human) actors in the Scope diagram. Within this business process, only some of the tasks performed by each have been earmarked for automated support.
Figure 3: Example of a Workflow Activity Diagram
While the diagram does a good job of visually representing the flow, supporting text (see Sidebar 2) provides users with additional information and/or help for those not up to speed with the 'language' of UML (Step 3.1.2).
BRA Step 3.2a -- Document the Use Cases
What is a use case? A use case describes an Actor interacting with the application as part of performing a business task (that delivers some tangible value). If user interface design (i.e., screen painting) were part of analysis, the user (and analyst) would be able to 'see' what is being described (as illustrated in the example below). In a use case description, virtually every field displayed and/or input; every navigation function (e.g., button or hyperlink) is mentioned. However, use cases stop just short of actual screen layouts. They remain generic in that they speak of 'invoking functions' rather than 'pressing buttons.'
During an analysis session it is often useful, if not essential for the analyst to draw a rough sketch of such an interface. However, the formal documentation of User Interfaces is left to the design phase. Because we are asking users to sign off the Functional Specification, we don't want to add an additional set of work products (i.e., explicit screen layouts) to be reviewed and agreed upon (or argued over). Thus, we leave it at textual descriptions within the use cases. This has proved to be much more sign-off friendly than other forms of functional descriptions, while at the same time not opening the 'look and feel' can of worms.
A use case may be a front-office task involving an actor dealing with a customer or a back-office task involving an actor dealing with an item from an 'in tray.' If the application provides for direct customer access, then the actor can be a customer (which is the current trend in Business-to-Business e-commerce applications).
A use case describes a single 'transaction' in the sense that there is a well-defined beginning, one or more steps, and a well-defined ending. Examples include most sale transactions, capturing of an order, an approval step in a workflow, or simply an inquiry (e.g., bank customer checking on account balances). Longer, more complex tasks (e.g., booking a multi-leg travel holiday) are typically broken down into multiple use cases, each addressing one type of interaction (e.g., individual legs of the trip, booking accommodations, car rental).
Detailed analysis of a use case results in the following documentation elements:
- A description of the 'main' flow (i.e., a typical interaction where everything proceeds normally).
- Zero or more alternate flows, each describing a special case that happens occasionally.
- Zero or more other use cases that are 'reused' during the main or alternate flows.
- A use case diagram, depicting the Actor and all of the above items.
- Zero or more Exceptional Conditions describing things that can prevent the task from completing successfully.
- One or more Scenarios for the main use case and alternate use cases, giving 'instance' examples involving actual sample data values.
Example Use Case*/ ?>
Figure 4 is the diagram for the use case associated with the "Enter Transport Assistance Application" task from the workflow (activity diagram) example in Figure 3.
Figure 4: Example Use Case Diagram
The related use case text (see Sidebar 3) describes the main flow of the use case. It begins with a brief description. This description provides an overview of the task being performed. The text contains references to alternate flows and exceptional conditions that are included later in the use case documentation -- (e.g., "A-1", "E-1"). The alternate flows are visible in the use case diagram in Figure 4. Exceptional conditions represent things that can go wrong, and typically translate to error or warning messages presented to the user.
Conclusion -- Part 1
At this point in the BRA process we have accomplished four things:
- Scoped the overall detailed requirements analysis effort
- Identified and described significant workflows within business processes
- Within each workflow, identified specific tasks to be analyzed further and described as use cases
- Diagramed a use case, and described its main flow
In addition, outside of business user working sessions, a fully-attributed and normalized data model is documented in a CASE tool. However, as with screen layouts, asking business users to understand, review, and sign off this particular work product is avoided.
As will be seen in the examples presented in the next part of this article, simplified views of this data model are included and described in the Functional Specification. In addition, definitions of all critical entities are included in the project glossary. However, as long as the use cases and other work products can be satisfied by information stored in the application's database, business users should not have to concern themselves with the details of a data model.
In part 2 of this article, we will continue by looking further at our example use case. In particular, alternate flows, exception conditions, and scenarios will be discussed. Use cases represent about 80% of the content of a functional specification document. The remaining 20% deals with business rules, reports, and system interfaces. Examples of these work products will also be presented. Stay tuned.
# # #
About our Contributor:
February 6-8, 2018
April 17-19, 2018