REQUIREMENTS IN CONTEXT PART 1 - JUST KNOW IT!

I have long been a believer in the saying “Context is everything.” As a business analyst
dealing with business users, understanding the context of the topic of discussion is essential.
In thinking about what constitutes quality requirements it occurred to me that there are a
number of additional contexts that play a role. Examples include the organizational maturity
level (from Informal through to Optimized) and delivery context (green fields through to
package acquisition).
This is the first in a series of articles about business requirements. My primary objective is to
help business analysts improve their elicitation and documentation of requirements. With
an increased awareness of multiple contexts, I believe that the quality of the requirements
documented can be improved, and subsequently lead to the better design, development
and implementation of business systems.
Mark Twain is credited with saying, “Everyone talks about the weather, but nobody does
anything about it.” The equivalent saying in the IT context would be, “Everyone agrees that
good requirements are essential, but nobody does anything about them. “A perfect
illustration of this is the classic IT cartoon “The Swings”:

1
What is not funny about this cartoon is that the situation it depicts is as true about business
systems delivered today as it was when the above version was published. Over 40 years of
struggling, and most often failing to meet user expectations, despite unimaginable
improvements in technology.
I have no illusions that what I intend to present will magically make it all better. But these
articles are at least my attempt to do something about it. If you are reading this, it means
you are interested in improving your BA skills. Hopefully learning about the impact of
different contexts on requirements will lead to that.

2
The Business Information System Context
I find it virtually impossible to take off my business analyst hat. Any time a family member or
friend mentions that they want something – a new car, an electrical appliance, I
immediately go into ‘requirements mode.’ I start asking questions intended to help them
focus on their thinking in order to lead to making the best choice. It occurred to me that it
as I begin to present the various contexts related to requirements that I should set the
context for this series of articles. The context of requirements that I intend to focus on is
business information systems. And while a complete information system includes a
hardware and a network aspect, the requirement contexts that will be discussed will not
include these technical aspects. The requirements contexts will focus on business analysts
interacting with business users to deliver the functional and information components of a
system.
Please note that when I use the term ‘system’, from a requirements perspective that
doesn’t mean that every requirement will result in a computer-based solution. Having
gathered requirements a subsequent exercise is to determine which of them will be given
automated support and which will be left as manual processes.
Functional and Information Components
The earliest “computers” were primarily electronic calculators. They allowed complex
formulas to be broken down into individual computational steps. Having expressed these
steps in a language the computer could understand the resulting instruction set was ready
to receive the data to be manipulated. The end product was a set of calculated results.
When businesses began using computers their objective was to maintain data about their
business. Computational requirements were minimal. Simple things like adding or
subtracting deposits and withdrawal amounts from a customer’s account balance. The
original computerized business systems all performed their functions by reading in batches
of data, operating on each record as it went through the system, and producing individual
results before the next record was processed.
With the advent of database management systems and access in ‘real time’ to computer
applications, more and more business processes could be supported by computers. Today
virtually every office worker has a computer on their desk. And thanks to wireless networks
and portable devices workers (and customers) outside of the office have access to the
information they need when they need it.
With the focus of business information systems being the support of functions that capture
and utilise data I offer a variation on the Nike slogan “Just Do It”. The objective of the
business information systems we gather and document requirements for should be “Just
Know It.”

3
Functional Context / High-level Requirements
Having established the context for these articles to be business information systems, the
journey itself will begin in the next article. In it I will present a technique I have used for
many years to help establish the functional context for a requirement gathering effort. The
more common term for this functional context is “Project Scope.”
I will also discuss the possibility of combining the scoping exercise with the producing of
high-level requirements. The result of doing this reduces that requirements task down to
hours rather than days (or weeks). This will be the first of several demonstrations of the
strength of applying the thinking that “Context is everything.”

4
REQUIREMENTS IN CONTEXT PART 2: THE FUNCTIONAL VIEW FROM
10,000 FEET
In Part 1 of this series it was stated that the overall objective of these articles is to improve
the quality of requirements produced by business analysts. Following the adage
that “Context is Everything” it established that a number of different contexts will be
explored. And in keeping with this principle, it set business information systems as the
context of the requirements to be addressed.
Classic Business Functions
My very first position as a business analyst 30 years ago was with a company that had just
completed an enterprise-wide planning effort. (1) They had gone so far as to remodel one of
their conference rooms for the specific purpose of displaying the results on multi-layered
whiteboards. The most prominent board displayed a functional model of the business. It
was said to be a view of the company from 10,000 feet up. The functions were
organised into three categories: Management, Support and Line of Business. The following
diagram is a slightly simplified version of that model:

In my first article I presented the classic “Swings” cartoon. It is a classic because it has
remained relevant all these years. I consider the high-level functional model presented
above to be a classic. It too has stood the test of time. Throughout my years as a business
analyst, working in a wide variety of industry segments and government agencies in three
countries, this model has proved to be both relevant and useful.

5
Not all organisations utilise every one of the functions shown. And some organisations
have multiple lines of business. For example, Walt Disney - Film production would be
one, theme parks another. In this style of model, each would have its own ‘Line of Business’
functions to provide contexts for dealing with very different products. Regardless of the
numbers of lines of business, the Management and Support
functions are applicable across the organisation.

Enterprise Resource Planning

Thirty years ago, using a model like this to plan an organisation’s business information
systems was leading edge. Database management systems had been around just a few
years. Their use typically involved one-for-one replacement of application-specific files. A
batch processing inventory management system would be upgraded to an online inventory
management system supported by an inventory database. A batch
processing sales management system would be upgraded to an online sales management
system supported by a sales database. And on and on.
High-level functional models like this were used to demonstrate to the organization that a
shared set of data could and should be used to support multiple functions across
the business. The idea was to stop developing application-specific information systems and
start developing an enterprise-wide one. Fast forward to today and this vision has
become business as usual for many organisations.
It is common today for an organisation to have a relational database that holds data utilised
by multiple business functions. Some of these systems have been developed in-house.
Others utilise one of the commercially available Enterprise Resource Planning (ERP) systems.
Probably the original and best known of these is SAP. The following is a list of integrated SAP
modules that an organisation to pick and choose from:
Human Resource Management
Production Planning
Material Management
Financial Supply Chain Management
Sales and Distribution
Project System
Financial Accounting and Controlling
Plant Maintenance
Quality Management

6
Quite a striking correlation between these modules and the high-level functions from
that 30-year-old model.

High-level Requirements from High-level Functions?

This series of articles is about requirements in context. The Functional context is where we
are starting. The functions from the 10,000-foot level are the most general functional
context I can imagine. Could these be used to draft requirements? I can think of one
scenario where they could - an organization interested in acquiring an ERP system. Here is
an example of one such high-level requirement:
The system shall support accounting processes integrated between themselves and with
processes of other functions.
Each ERP function the organisation is interested in should have its own requirement naming
a high-level function it wants within its integrated system. Each would be assigned its own
priority. Some would likely be must haves while others might only be nice to haves. (Who
am I kidding? – we all know that to business users every requirement is a ‘must have.’)
Processes within Functions
The view from 10,000 feet is an interesting functional context, but outside of acquiring an
ERP system we need business functions closer to earth. Fortunately, the majority
of functional modelling techniques include the concept of functional decomposition.
That technique used to produce the model above offered a simple three-level
decomposition scheme. The things at the top level were called Functions. A level
below functions were things called Processes. The third and lowest level things
were called Activities.
Functions were considered to be ‘ongoing’ activities. A person working in Accounting or HR
does their job year-round, year in and year out. Processes in the context of this model were
defined to be things that have a start and an end point. A given Function typically would
decompose into 10-ish Processes. Again, using SAP as an example, we
see its HR module breaks down into 12 processes:

Organizational Management
Personnel Administration
Recruitment
Payroll
Travel Management
Personnel Management
Time Management

7
Compensation Management
Training and Event management
Wages
Personnel Development
Workforce Administration
It’s easy to envision most, if not all of the above processes having start and end points. For
example, while it could be argued that Recruitment goes on continuously, in reality filling a
specific position starts with some form of notification of the opening and ends ideally with a
successful candidate coming on board. Here is an example of a high-level requirement
utilising a Process context:

The system shall support the recruitment process including keeping records of published
notifications, candidates, interviews and proof of fairness during the selection process.

Activities within Processes

The term Activity can be defined as the individual steps in a process. Visualise a
workflow diagram. The boxes in the diagram that don’t themselves require further
decomposition would be considered activities. The basic idea is that an Activity is that
it should be simple enough that an individual is able to complete it in a single
‘sitting.’ No need to hand the work off to anyone else mid-activity or to have to wait for
some other activity to complete. An example of an activity within the Recruitment
process would be one called “Make Offer to Candidate.” An example of a high-level
requirement utilising an Activity as a context would be:

The system shall support keeping a record of offers made to selected candidates.

I have used a variety of functional modelling techniques from dataflow diagrams to business
process modelling notation (BPMN). Regardless of the terminology used in any method, I
have found the definitions of the three functional levels presented above to be excellent
guideposts for both functional modelling and drafting requirements.

Next Time – Project Scope as a Context for High-Level Requirements

Gathering of requirements is typically managed within a project, and part of managing a

project is establishing its scope. Requirements are expected to address the things within this

8
scope. Next time we will look at scope and how high-level requirements can be derived
directly from it, and actually as part of the scoping effort.

9
Requirements In Context Part 3: Scope = High-Level Requirements
Part 1 (Just Know It) of this series established the context of requirements being
addressed are those that relate to business information systems and that various contexts
have an impact on those requirements. Part 2 (The Functional View From 10,000
Feet) addressed the first of these contexts - Functional. That context was further divided
into three conceptual levels labelled Functions, Processes and Activities. An example high-
level requirement was presented at each of these levels.

This article moves on to a different context - Project Scope. We will see how
scope statements, when making reference to business functionality, lead directly to High-
Level requirements.
Gathering requirements for a business information system is most often done within the
context of a project. Approval of a project includes its sponsors signing off on its
scope. The scope for a business information system project is typically defined
in functional terms. Items in scope make reference to (or should make reference
to) business functions, processes and/or activities that are to be delivered.

NOTE: This series uses the more traditional terms High-Level Requirements and Detail
Requirements. In IIBA(R) BABOK(R) Terminology the first of these terms equates
to Stakeholder Requirements and the second to Solution Requirements.

A CONTEXT DIAGRAM IS WORTH A THOUSAND WORDS

In addition to the bullet-item list of scope items it is very common for the project initiation
document to include a Context Diagram. The objective of a context diagram is to illustrate
what is inside the system and what is outside. Things outside the system represent sources
and/or consumers of data. The original form of context diagram comes from Dataflow
Diagramming (DFD). The top-most level of functional decomposition using DFDs was
considered a context diagram. The Unified Modelling Language (UML) Use Case
modelling also supports a form of context diagram. Both of these diagramming techniques
represent ‘the system’ and both portray things outside the system boundary. The DFD term
for these outside things is External Entity. The UML term is Actor. The definition of these
two terms is virtually identical.

10
A DFD context diagram says nothing about the functions inside the system. That is left to
subsequent levels of functional decomposition. Clues are provided by labels given to
the dataflows. The Use Case context diagram provides more of a clue to the functions within
scope by including named use cases. Dataflows in a DFD context diagram connect only to
the system. Actor connectors in a Use Case context diagram connect to one or more specific
use cases within the system.
HIGH-LEVEL REQUIREMENTS FROM PROJECT SCOPE
Examples of high-level requirements were presented in the previous article based on a high-
level business function, a medium-level business process and a low-level business activity.
We are about to present an example of a project and its scope. As mentioned above, the
scope of business information system projects is very often expressed in functional terms. It
should therefore be possible to derive high-level requirements from scope items.
Consider the following situation involving a large hypothetical on-line retailer we will call
Nile.com:
Nile.com has a well-established purchase process for its on-line customers. The check-
out portion of this process includes activities for identifying the intended shipping address
and for providing some form of payment. What the process does not currently include is
anything to do with tax on items being purchased. As the result of pressure from various tax
authorities this needs to change.
In establishing a project to deal with this change in the business environment the
following scope items were agreed by the business sponsor and signed off:
Maintaining tax-related details for designated tax authorities
Determining applicable tax on items being purchased
Including applicable tax with purchases
Accounting for tax charged
The Use Case form of context diagram for this example would look like this:

11
Scope items will seldom be stated so conveniently that they can be converted one-for-one
into the names of use cases. For the sake of brevity, please accept that the scope items in
this example are “ones that I prepared earlier.”
The objective of this article is to show that it is possible to derive high-level
requirements based on a project’s scope. The following are examples of such requirements
from the scope in this scenario:
Scope Item 1 - Maintaining tax-related details for designated tax authorities
The system shall support an administrator maintaining tax-related details
required to perform tax determination. This includes establishing tax authorities that are
the source of tax rates and to whom collected taxes need to be paid. It also includes
mapping of products to tax rates for each authority where there are product-specific rates
or specific product types that are tax exempt.
Because charging tax is new to this organisation there may not be an in-house subject
matter expert available when it comes time to sorting out the details for this requirement.
Until more is known this high-level requirement acts as an appropriate placeholder for what

12
is likely to be a number of business processes. One would likely be needed for setting up
new tax authorities, one for setting up the tax rates and where applicable, one for specifying
different rates for different product types. The requirement from a business perspective is
fairly straight forward – maintain whatever details are necessary to be able to charge tax.
The devil is in the detail.
Scope Item 2 - Determining applicable tax on items being purchased
The system shall be able to identify the appropriate tax that applies to the purchase of a
given product based on the product type and the tax authority(s) that have jurisdiction
where the shipment is to be delivered.
Where the previous requirement calls for whole new business processes to be supported
within the business information system, the functional context of this requirement would be
somewhere within the “Identify the shipping address” activity within the “Purchase”
process. At this point the product(s) are known and the shipping address details can be used
to determine any applicable tax authority(s). Subsequent detail requirements would get into
how an appropriate tax rate is determined and specifics of where that rate is used in
calculating the total charge to the customer.
Scope Item 3 - Including applicable tax with purchases
The system shall present to the customer all applicable tax amounts as part of
the purchase process.
This statement should be sufficient as a high-level requirement from a business
perspective. Part of the detailed requirements analysis would include identifying all of the
places where the customer ‘sees’ purchase price details. Each of those places will require
modification to include whatever tax applies, if any.
Scope Item 4 - Accounting for tax charged
The system shall report charged tax amounts as a distinct component of each purchase to
the general ledger system identifying appropriate GL Codes and the designated
tax authority.
Wherever money is involved the organisation’s general ledger needs to be kept informed. In
this case it is unlikely that there will be any new processes or even activities required.
Reporting to the GL will be in place for the current un-taxed purchases. This reporting will
just require an enhancement to include the tax amount and its corresponding GL
Coding. There should also be an existing Accounts Payable process that handles making
payments to suppliers for the organisation. The different tax authorities that are to receive
payment of collected taxes should be covered under that process.

13
REQUIREMENTS IN CONTEXT PART 4 – KEEPING HIGH-LEVEL
REQUIREMENTS HIGH-LEVEL
The four requirements derived from the project scope items would not be the only ones for
the whole project. But it must be said that they cover the agreed scope of the project, and
that they are high level (not slipping into detail). Next time we will look into how to prep
high-level requirements high-level when dealing with stakeholders that are asked to
participate in the context of “Gathering high-level requirements.”

Keeping High-Level Requirements High-Level

The objective of this article is to provide business analysts with guidelines for distinguishing
between high-level requirements (HLRs) and detail requirements (in IIBA® BABOK® V3 terms
– Stakeholder requirements and Solution requirements respectively).
The following example, taken from a signed-off HLR document, illustrates the problem:
Each Customer record must be assigned a unique identifier.
This statement certainly represents a valid business need. It’s just not a high-level one.
During HLR elicitation, if a detail needs like the one above is expressed by a stakeholder, it
should be noted - but not formally as a requirement statement. These notes can then be
revisited when detail requirements are elicited.
NOTE: You can find the previous articles in this series here:
Requirements In Context Part 1 - Just Know it!
Requirements In Context Part 2 - The Functional View from 10,000 feet
Requirements In Context Part 3 - Scope = High-Level Requirements
REQUIREMENT ‘SHALL’ STATEMENT VS USER STORY
The formal way to document a business need as a requirement is with a single sentence
‘Shall’ statement. The Agile form of representing business needs is a user story. Like a ‘shall’
statement, a user story is also a single sentence. A user story is considered to be ‘… the start
of a conversation’.
Example ‘Shall’ Statement:
A Customer shall be able to transfer funds between their accounts.
Example User Story:
As a Customer, I want to be able to transfer funds between my accounts, so that I’m not
restricted to banking hours or need to wait for an available teller.
The real difference between requirement statements and user stories is how they are
managed within a waterfall or Agile environment. With waterfall, requirements are

14
managed within the context of a project. A complete set of high-level requirements are
expected to be elicited from, and signed off by, designated stakeholders. Assuming the
project continues, those HLRs act as the context for detail requirements. The details behind
each HLR are elicited from subject matter experts (SMEs). The complete set of detail
requirements is then signed off by stakeholders. They are used as the ‘bible’ throughout the
life of the project, to support design, development, and testing.
User stories, in an Agile development environment, are managed within a story backlog by a
product owner. Ideally, this person is available to participate as a member of a development
team. New stories can be written at any time. A story is given a place in the story backlog
based on its relative value, with the highest-value stories closest to the top. Before a story
can be taken from the backlog for development, it must be ‘refined’. Refinement involves
the product owner ‘continuing the conversation’ with the rest of the team. The product
owner contributes whatever details are necessary to allow development and testing to
proceed.
BUSINESS INFORMATION SYSTEM CAPABILITY TYPES
NOTE: The requirements addressed in this series are limited to ones involving the software
aspect of a business information system. Network, hardware, non-functional, and business
readiness requirements are not addressed.
A business information system is capable of supporting business processes or activities in
the following ways:
User interfaces (UIs) – allows users to interact with the system (e.g. one or more screens)
Data Importing or Exporting – the system recording or producing ‘machine-readable’ data
Automated Functions – the system using existing data to generate new data, updating
existing records, or adding new records
Reporting –the system producing a view of data that can be read off-line
A properly high-level HLR should represent a stakeholder need involving one of these
capability types. Each HLR should represent a ‘… topic of conversation’ about a UI, import,
export, automated function, or report intended to satisfy the need.
The objective of high-level requirements elicitation is to come up with the full set of in-
scope topics of conversation (i.e. a signed-off set of HLRs). The conversations themselves, on
each topic, take place as part of the detail requirements phase of the project. Each
conversation should involve SMEs that have operational knowledge of the business process
or activity the capability supports.
NOTE: The terms ‘conversation’ and ‘discussion’ are used in this article as a metaphor for
any requirements elicitation technique.

15
REPORTING HLRS
Reporting involves taking a ‘snapshot’ of data within a business information system at a
point in time. The HLR discussion, to establish a report topic, should start by identifying the
purpose of a given report, and who its intended audience is. Ideally the organization knows
the report by some name. If it’s a new report, someone can provide a reasonable name
based on its purpose. At this point in the discussion there should be sufficient information to
draft the report’s HLR statement.
Example:
The system shall be able to generate a statement of account for a customer.
The following types of details should be excluded from report HLR discussions. They should
be left for the conversation on that topic with SMEs during detail requirements:
Data selection criteria, grouping, and sorting
Report scheduling or triggering
Layout and pagination
Delivery
NOTE: If there is a question as to the future-state need for a current-state report, that issue
should be resolved as soon as possible.
DATA IMPORTING OR EXPORTING HLRS
Data importing or exporting supports a business process that gets data, in ‘machine-
readable’ format, into or out of the system. The HLR discussion, to establish an import or
export topic, should address the following business-oriented questions:
How is this process referred to by the organization (i.e. its ‘name’)?
Is its objective to get data in or out of the system?
Is the data expected as an immediate response to a request? I.e. in real-time, otherwise the
need can be satisfied by a ‘background’ process
What type of person or system is providing (or needing) the data?
What is the main type of data is involved (i.e. the primary Entity)?
With answers to the above questions, it should be possible to draft an import or export HLR
statement.
Examples:
Real-time import: The system shall be able to obtain the current availability of an item from
the inventory management system.
Real-time export: The system shall be able to provide the sales system with the current
availability of an item.

16
Background import: The system shall be able to receive a cargo manifest from the shipping
company, identifying containers due to arrive in port on a given ship.
Background export: The system shall be able create a file of customer-specific direct debits,
to be actioned by the bank on a given date.
The following types of details should be excluded from data importing or exporting HLR
discussions. They should be left for the conversation on that topic with SMEs during detail
requirements:
Data selection criteria
Sorting
Summarization
Real-time request parameters, response format
File format, naming conventions, record layouts
Import data field-level validation, value transformation, error reporting
Background job triggering or scheduling
UI for user-initiated importing or exporting
Most often there will need to be two separate detail requirements conversations about the
importing or exporting of machine-readable data. One with business stakeholders and
another with a SME familiar with the ‘technical specification’ aspects.
NOTE: Any reports or UIs needed in relation to an import or export process should be dealt
with as part of the detail requirements conversation. A separate report or UI HLR should not
be needed.
USER INTERFACE HLRS
A user accessing a business information system, in real time, is doing so via a user interface.
The access should support the person’s performing a business process or activity. Access to
the UI may be restricted to specific roles, or be available to anyone authorized to access the
system. The UI may focus on a specific instance (e.g., a customer), or a selected set of
instances (e.g. all customers that have overdue accounts).
The HLR discussion, to establish a UI topic, should address the following business-oriented
questions:
What is the business process or activity?
What types of users do this?
What is the primary type of data involved (i.e., Entity)?
Does it involve a specific instance or a number of selected instances?

17
User types should be recognized roles within the organization, or external parties such as
‘customer’ or ‘supplier’. If the process or activity were seen in a business process diagram,
the user role would be the label of the process’s swim lane. If it were seen as a ‘bubble’ in a
use case diagram, the user type would be the ‘actor’ connected to the bubble.
With answers to the above questions, it should be possible to draft a UI HLR statement.
Example:
An accounts receivable clerk shall be able to apply a selected payment from a list of
unallocated payments to a designated customer account.
The following types of details should be excluded from UI HLR discussions. They should be
left for the conversation on that topic with SMEs during detail requirements for a given HLR:
Data fields displayed for one record, or in columns for a list of records
Layout of fields on a screen, or the order of columns in a list
Actions that can be invoked (e.g., Save, Cancel, Undo)
Navigation Options to other screens from the single record, or to a selected record from
within a list
The ultimate design of a given UI can involve one or more screens, tabs and/or sub-
windows, to display all of the data. Or a given UI can be designed to serve multiple activities
(e.g., by varying visibility or update capability of fields and/or action controls based on user
role). Design and usability issues are outside the scope of this series of articles.
NOTE: Use of terms such as ‘maintain’ or ‘manage’ in a requirement statement is normally
considered unclear, and to be avoided. However, there can be valid uses of these terms in
HLRs. For example, it is perfectly reasonable to express a need for a customer to ‘maintain’
their account details. Or an Admin person to ‘manage’ the set of valid values presented in a
select list.
AUTOMATED FUNCTION HLRS
A business information system can be ‘programmed’ to automate some business activities
that involve deriving data. Such automation can be included in the scope of a project if the
following conditions can be satisfied:
The data needed by the automated function will be available in the system
The business rules and/or logic involved in manually performing the function can be
described by a [willing] SME
That description can be ‘translated’ into a computerized function
A given automated function would either be scheduled to perform as a batch job, or be
triggered in real-time based on conditions. The result of the system performing the function
is either existing data within the system updated, or new records added.

18
The HLR statement should name the function as if were performed manually and give an
indication as to when it should be scheduled to perform, or what conditions should trigger
it.
Example 1 - Scheduled function creating new records:
The system shall automatically post a credit transaction for each savings account that has
interest due.
Example 2 - Triggered function updating an existing record:
A customer account shall be blocked automatically if its credit limit is exceeded.
The following types of details should be excluded from automated function HLR discussions.
They should be left for the conversation on that topic with SMEs during detail requirements
for a given HLR:
Business rules or logic involved in the function
The fields within records added, or within existing records being updated
Scheduling or triggering condition details
NOTE: The feasibility and/or cost effectiveness of fully automating a business activity may
not be known at HLR time. If so, this is a potential risk to the project. Managing this risk is
outside the scope of these articles.
HIGH-LEVEL REQUIREMENTS ELICITATION OR REQUIREMENTS PLANNING?
Stakeholders, as a rule, do not distinguish between high-level and detail requirements. Nor
do they appreciate being invited to discuss their [high-level] needs and hearing that some of
those needs are ‘too detailed’ - that they will have to participate in yet another [detail
requirements] conversation at a later date.
What managers and SMEs can appreciate is being invited to contribute to
project planning sessions related to an IT-based solution that they have a stake in. The
stated objective of these planning sessions should be to come up with a list of reports, data
imports, exports, user interfaces, and automated functions that the solution should include.
It should be understood that the resulting list will be used as topics for subsequent
conversations with appropriate stakeholders and SMEs.
NEXT TIME – MANAGING DATA-SPECIFIC BUSINESS NEEDS
Something common to all of the capability types is that they involve data. The next article
discusses options for managing data-specific business needs, as they arise during detail
requirements conversations on an HLR topic. The use of a data dictionary is recommended
as a place to record data-specific details, and potentially reduce the number of individual
detail requirements that need to be managed.

19
Managing Data-Specific Business Needs Using a Data Dictionary
Requirements In Context Part 5 – Managing Data-specific Business Needs Using a Data
Dictionary

The previous article in this series discussed ensuring that High-Level Requirements (HLRs),
within the context of an IT-based project, were properly high level. The remainder of articles
in the series will look at detail requirements and the need for them to be sufficiently
detailed. The objective of this article is to demonstrate how a data dictionary (DD) can be
used as a tool for capturing the appropriate level of detail representing data-specific
business needs.
NOTE: This series uses the terms ‘High-level Requirement’ (HLR) and ‘Detail Requirement’ -
intended to correspond to the IIBA® BABOK® V3 terms ‘Stakeholder Requirement’ and
‘Solution Requirement’.
The following questions are addressed in this article:
What are data-specific business needs?
How might these needs be represented in a DD?
How does a DD differ from a data or class model?
What details should be captured?
What is the role of a DD in relation to detail requirements?
The remainder of the articles in this series draw examples from the Trips-R-You Flight
Booking Case Study. The objective of the case study is to present an example of an
integrated set of high-level and detail requirements. Accompanying the case study is the MS
Excel-based Trips-R-You Data Dictionary. It contains the data-specific business needs related
to those requirements.

20
WHAT ARE DATA-SPECIFIC BUSINESS NEEDS?
The primary objective of business information systems is to support business processes.
These systems do this by utilizing five basic functional capability types – user interfaces, data
importing and exporting, reports, and automated functions. These capability types were
discussed in Part 4 of this series, in relation to HLRs.
Function-specific business needs are addressed by one or more of these capability types.
Data-specific business needs are addressed by the system being able to manage data
involved in those functional capabilities. In this context, ‘manage’ means:
Provide persistent storage - available for the different types of data needed by users of the
system, irrespective of functional capabilities that source, update, or reference that data
Validate sourced data - irrespective of functional capabilities that support its sourcing or
updating
Derive new data from data available within the system
Most business information system users think of their data as records and fields.
Representing data-specific business needs in a DD involves adding or updating entries that
represent either a type of record or field. Fields are intended either to hold data or
reference another record. A reference allows the record to access fields of the related
record type.
NOTE: The Data Dictionary used with the Trips-R-You case study, to be business-friendly,
uses the terms ‘Record’ and ‘Field’. Within the context of this series of articles, those terms
should be considered equivalent to the logical data terms ‘Entity’, ‘Attribute’, and
‘Relationship’.
REPRESENTING DATA-SPECIFIC BUSINESS NEEDS IN A DATA DICTIONARY
The best way to demonstrate capturing data-specific business needs in a DD is with an
example. In the previous article the following ‘requirement’ was discussed:
Each Customer record must be assigned a unique identifier.
Reasons were given as to why this requirement (found in an actual signed-off HLR
document) was considered to be too detailed to be an HLR. The recommendation was to
‘note’ such details for revisiting during detail requirements elicitation.
For this example, the appropriate time to revisit the note would be when discussing the
functional capability (e.g., a user interface) intended to support the business process of
adding a customer. The data-specific business needs that statement was trying to represent
turned out to be the following:
There needs to be Customer records.
That type of record needs a field (agreed to be called “ID”), that will be a numeric business
identifier for Customers.

21
“Assigned” (within the context of the note) was confirmed by the stakeholders to mean
‘automatically generated by the system’.
The need for identifier values to accommodate 2,000 new customers per year over the next
10 years, in addition to the existing 10,000 customers currently identified.
These needs can be captured using the Data Dictionary with one entry representing the
Customer record and a second entry representing its ID field. The specific DD columns used
to capture those needs are:

Current Volume and Estimated Growth Rate, sourced from business subject matter experts
(SMEs), are necessary to support capacity planning - a non-functional requirement. In this
case these values also provide an indication to database designers of how big the ID field
needs to be.
The Source(s) property for the ID field indicates that values are expected to be derived by
the system rather than manually entered. This implies that a derivation function will be
needed.
The Participates in Unique Business Identifier property relates to the uniqueness need -
again useful to the database designer in making decisions about primary keys.
DATA DICTIONARY VS DATA / CLASS MODEL
There is no question that a data or class model is a picture worth a thousand words (to
people who understand the meaning of the boxes, lines, and symbols used). The
documented representation of a graphical model, in tabular form, can be considered a basic
form of DD. For comparison purposes, we will look at an example of data-specific business
needs represented both as a data / class model and using the Trips-R-You Data Dictionary.
The example involves a field representing the Status of a Customer. The field is involved in
several different business processes that reference or update its value. The result of
discussions with stakeholders, within the context of functional capabilities supporting those
processes, was that most of those processes only needed the customer’s current status.
However, one needed access to previous values. And another needed to be able to set a

22
future value. The combined data-specific business needs related to a Status field within
Customer therefore are:
A Customer needs to have a single value for Status effective at any given point in time.
Previous values need to be kept.
One future value can be recorded.
The set of valid Customer Status values is owned by Customer Care and is to be maintained
in the system on their behalf by users with System Admin authority (following a change
management procedure).
Based on these needs, Status, along with an Effective Date, is a repeating group. Because
data and class models typically do not support an entity or class containing a multi-valued
field or group, a separate entity/class is added to the model, with a one-to-many
relationship to it (see below). Also, where a value set needs to be ‘maintained’ in the
system, via user interface or data import, the value set is also represented by its own
entity/class.
These combined needs, viewed in a data or class model, might look like this:

Let’s now look at those same needs captured using two entries in the Trips-R-You Data
Dictionary:

The Status DD entry above is an example of a relationship rather than an attribute. It

indicates that the Status value is sourced from the CUSTOMER STATUS value set. This
corresponds to how system users ‘see’ value set-based fields (e.g. as a ‘dropdown’ list).

23
The reason that Status can be captured as a field within Customer is that the DD includes
individual columns to represent multi-value needs, including historical and/or future values.
With these needs captured, a database designer is left to add any additional database tables
needed and fields related to effective dates.
DETAILS CAPTURED IN A DATA DICTIONARY
The two examples presented above have demonstrated how different aspects of data-
specific business needs, such as uniqueness or the need to support history, can be
represented as specific columns within the DD’s tabular format. The general rule of a DD is,
“If there isn’t a dedicated column for something, then that something is described using the
‘Comments’ column.” Too many columns make the DD difficult to use and review - too few
and important aspects get buried in text.
The dedicated columns included in the Trips-R-You Data Dictionary are intended to hold
details of data-specific business needs that are useful to designers, developers, testers,
technical writers, and trainers. For cases where there is no specific column representing a
type of need, there is still a ‘Comments / Other Business Rules’ column.
Ideally a DD tool helps deal with offering lots of property-specific columns (25-ish for the
Trips-R-You template) by presenting only those applicable to a given entry type. The Trips-R-
You Data Dictionary accomplishes this by greying out unneeded cells for a given row, based
on further classifying record and field entry types into the following sub-types:
Entities – Primary Record, Record Sub-group, Value Set, Field Set
Attributes – Label, Quantity, Date Time, True/False Value, Description, File
Relationships – Related Data, Value Set Reference, Field Set Usage
NOTE: See the Trips-R-You Data Dictionary regarding the purpose of each column and
examples of entries involving each of the entity, attribute, and relationship subtypes.
DATA DICTIONARY INFORMATION VS DETAIL REQUIREMENTS
Utilizing a data dictionary to capture data-specific business needs is intended to replace
individual detail requirements representing those needs (as demonstrated in the examples
in this article). The contents of the DD still need to be reviewed and signed off. But its
tabular format, reducing the need for textual descriptions, is intended to make those tasks
easier.
Individual DD entries do not need prioritizing (e.g., the MoSCoW scheme), as is the case with
individual requirements. Nor would they be individually moved in or out of a project’s
scope. This is because the priority and delivery of data-specific business needs are based on
the functional capabilities that reference them. The priority of a DD entry is tied to the
highest priority of the [in scope] functional capabilities that involve the entry. Similarly, an
entry is in scope if utilized by at least one in-scope functional capability.
A DD would ideally be used by multiple projects. If so, entries must be change-managed. For
a given project, entries that represent new or updated data-specific business needs for

24
persistent data can be represented by a single transitional requirement (the IIBA® BABOK®
V3 term), such as the following:
The system shall be able to store, update, and retrieve records, and the fields they contain,
as identified in the Data Dictionary - Version N.N dated dd mmm yyyy.
The reason just one requirement is needed is that a new or updated database schema is a
single deliverable. It needs to be implemented in time for the development of the functional
capabilities to begin.
END OF OVERVIEW
Hopefully this article has achieved its objective of demonstrating how a data dictionary can
be used as a tool for representing the appropriate level of detail associated with data-
specific business needs. This article has touched on some, but not all, DD concepts. If what
has been demonstrated makes sense, the reader is encouraged to spend additional time
with the Trips-R-You Flight Booking Case Study and examples the Trips-R-You Data
Dictionary contains.
The next article in the series looks at the need for detail requirements for user interfaces
and reports to be sufficiently detailed. Additional Trips-R-You templates specific to each of
these capability types will be discussed.

25
Detailed Requirements for User Interfaces and Reports
If you are reading this, you are not working in a ‘pure’ Agile environment. Those people
have no need for requirements and therefore have no interest in articles about them. This is
because they work with a product owner - ideally a subject matter expert (SME) - as a
dedicated member of their Agile team. The owner’s business needs are recorded as user
stories. The detail needed to develop and test a solution to a given story is provided to the
team through ‘story refinement’ by the owner - just in time for its development to begin.
For business analysts working in an environment where there is a gap between SMEs and
the delivery of an IT-based solution for business needs, requirements are documented to
bridge that gap. You are reading this because you are a business analyst responsible for
documenting detailed requirements and, in the case of this article, business needs involving
one or more user interfaces (UIs) or reports.
The objective of this article is to answer the question, “How much detail is necessary?”
Spoiler alert – quite a bit. This is to avoid, as much as possible, a BA having to go back to a
SME when designers or developers have business-level questions about a UI or report. Or
worse – designers or developers not asking questions. Instead, making assumptions about
what the business needs and proceeding to deliver the solution based on those
assumptions.
The good news is that every detailed business ‘need’ does not need to equate to a detailed
requirement ‘statement’. More on this below.
NOTEs:
Use of the terms ‘High-level Requirement’ (HLR) and ‘Detailed Requirement’ are intended to
correspond to the IIBA® BABOK® V3 terms ‘Stakeholder Requirement’ and ‘Solution
Requirement’
Use of the term ‘discussion’ in relation to stakeholders or SMEs is intended to imply any
requirement elicitation technique
Use of the terms ‘Record’ and ‘Field’ is intended to be equivalent to the logical data terms
‘Entity’, ‘Attribute’, and ‘Relationship’.
This article references examples based on the Trips-R-You Flight Booking Case Study.
CONTEXT FOR DETAILED REQUIREMENTS
The context for detailed requirements should be high-level requirements (HLRs). Part 3
(Scope = High-Level Requirements) and Part 4 (Keeping High-Level Requirements High
Level) of this series dealt with HLRs. When kept appropriately high-level, each HLR
represents a ‘unit of delivery’. Units of delivery, within a business information system, were
seen to be one of five types: a user interface, a report, a data import or export, an
automated function. Each HLR, similar to an unrefined user story, leaves the discussion of
details for later. In our case, ‘later’ is during the detailed requirements phase of a project.

26
The Trips-R-You Case Study includes an example of documenting detailed business needs for
a UI based on the following two HLRs:
An internet user or customer shall be able to search for flights for a trip.
A customer shall be able to book flights based on selected journey options.
It also includes an example of documenting detailed business needs for a report based on
the following HLR:
A customer shall be able to access and print their booking confirmation details.
The case study describes discussions with SMEs about the UI and report with these HLRs as
a context. The detailed business needs identified during those discussions were captured
using MS Excel-based templates. See Trips-R-You User Interface Example and Trips-R-You
Report Example.
UI AND REPORT OPERATIONAL, AREA, AND ELEMENT DETAILS
When it comes to detailed requirements for a screen-based UI or a report, a picture is
definitely worth a thousand words. Unfortunately (or fortunately for business analysts), a
mock-up of a screen or report doesn’t begin to tell the whole story. For example,
operational business needs such as who gets access or when it needs to be available. Nor
does it cover relationships between it and other aspects of the business, such as day end
processing. And while the headings and labels included in a mock-up provide valuable clues
to record and field types of displayed data, they don’t cover data derivation, input
validation, or relevant business rules. All such details need to be captured in addition to a
mock-up.
The full range of detailed business needs related to a UI or report can be divided into three
categories:
Operational Details – Things that apply to the UI or report as a whole. E.g., who needs it,
when and where is it needed, what volumes are expected.
Area-level Details – Things that apply to a portion of the thing based on a meaningful
grouping of fields or list of records. E.g., area-specific selection criteria, sort criteria,
pagination rules.
Individual Element Details – Things that apply to a data item being presented – either its
source or its derivation. Each textual label of a field, column, or area. For UIs involving input
fields – validation criteria and any business rules. For each UI action item (e.g., a button), a
description of the action to be carried out.
Each of these categories is discussed below and a complete set of detailed examples for a UI
and report can be seen captured in the Trips-R-You spreadsheet templates.
OPERATIONAL DETAILS
Each UI and report represent a capability expected to be part of the solution available from
a business information system. Project members, and eventually users, need a basic

27
understanding of the purpose of each and how it fits in with the overall operation of the
system. These basics, plus additional details necessary to support design and
implementation phases, should be captured. Each of the UI and report templates used for
the Trips-R-You case study includes an ‘SME Questionnaire’. Ideally SMEs that are able to
provide or obtain answers for each UI or report in scope can be identified.
Example questions for a UI:
What days/hours does the user interface need to be available for use?
Are there expected to be peak usage conditions? If so, describe the conditions, when they
can occur, and volumes of users expected during those times.
Example questions for a report:
Is this report to be run on a regular schedule? If so, describe its frequency and time of day.
Should it be produced even when there is no data to report?
The UI template questionnaire involves 11 questions. The report template involves 29, but
that number includes some very simple ones, such as page size and orientation.
AREA-LEVEL DETAILS
Between operational details, which apply to a whole UI or report, and the details of
individual elements they contain, there is an in-between area level. An area within the
context of a UI or report contains a meaningful group of elements and/or sub-areas.
The Trips-R-You UI template uses the following area classifications:
Screen
Tab
Field Area
Table Area
Repeating Area (Fields and/or Tables)
Show/Hide Area
Pop-up / Overlay
Widget (embedded application)
The Trips-R-You Flight Search / Booking UI example utilizes six screens, each mocked-up
individually. An example of the first screen, including labelled areas and sub-areas, looks like
this:

28
NOTE: The UI mock-up uses generic drop-down symbols to indicate any way of presenting a
set of values, and square brackets as a generic representation of action items.
The Trips-R-You report template uses the following area classifications:
Header
Footer
Fields
Table
Repeating Area (fields and/or tables)
Graph / Dashboard
The Trips-R-You Flight Booking Confirmation report example utilizes four areas and two sub-
areas. The area labels and their boundaries overlaid on a sample report look like this:

29
Details about an area include a unique area identifier, a meaningful label, and its area type.
If it’s a sub-area, one or more areas that contain it are identified. If it involves multiple
records there should sorting criteria, and possibly selection criteria. For areas that have
elements or groupings that should not be split across pages there should be pagination
rules.
An important detail for each area is the elements it contains. The pictorial mock-up
represents this containment. The Trips-R-You templates deal explicitly with containment
from the element perspective (i.e., for each element, what area it is contained in).
Ideally a requirements management tool would support the concept of areas, both when
creating mock-ups, and capturing details for areas and their contained elements.

30
When the business sees the need for an activity supported by a UI to be broken down into a
number of ‘workflow’ screens, a screen-flow diagram can be a useful communication tool.
The UI template includes a separate ‘Screen Flow’ tab for capturing details about possible
flows. The possible transitions between the six screens involved in the Flight Search /
Booking UI example shown in the following diagram have been captured in the template:
l

UI AND REPORT ELEMENT DETAIL

Because UIs and reports are used by people, there is both a form and a content aspect to
the elements involved. A mock-up may or may not go into full detail about form – e.g.,
covering needs for using specific fonts, text sizes, etc. Typically, UIs and reports intended for
use by customers or other external users receive the most form-related attention from
business stakeholders. Regardless, a mock-up should represent the content in full – both in
terms of the data involved, as well as any textual labels for fields, columns, and areas.
NOTE: ‘Usability’ is outside the scope of this series. Ultimately the business is responsible for
signing off the representation of their needs related to a given UI or report. That
representation includes both the mock-up and the supporting element-specific detail.
Usability can also be constrained by an existing application architecture or framework
controlling such things as menu configuration/navigation and error handling. These are also
out of scope of this series.

31
For a given element, the details that need to be captured about it depend on the type of
element it is. Labels are the most basic. A displayed data element needs details about its
source or derivation, plus other details depending on its data type. Data being input or
updated needs validation details. And an action element needs details about the action(s) it
initiates. The Trips-R-You templates used to document the UI and report examples discussed
above include details recorded for each of their elements (utilizing the data dictionary
template where appropriate for capturing data-specific needs for a given element).
WHERE ARE “THE REQUIREMENTS”?
The three HLRs presented at the beginning of this article were ‘formal’ requirement
statements – each a single sentence in ‘shall’ format. These statements can be seen
recorded in the Trips-R-You Case Study Requirements template [URL NEEDED]. That
template includes a unique identifier for each requirement (as should every requirement
that is managed by a project).
This article has discussed taking those HLRs as contexts for discussing detailed business
needs for an example UI and report. Those detailed needs have been captured as properties
of uniquely identified elements in templates. But none of those entries are formal
requirements. Those individual details could each be represented by their own formal
statement – which would make for a large number of individual requirements for the
project to manage.
At the other end of the spectrum is managing all of the details for a given ‘unit of delivery’
as a single formal detailed requirement. A ‘fully dressed’ use case is a good example of
packaging the detailed business needs into a single uniquely identified unit of delivery for a
project. Had the Trips-R-You UI example been captured in use case form and assigned a
unique identifier, the single, formal detailed requirement could be documented as the
following:
An internet user or customer shall be able to search for and book flights for a trip, as
described in UC013 – Self-service Flight Booking v1.0.
Use cases are an excellent ‘discussion’ technique. When fully dressed, the textual narrative
can contain considerable detail, spread among main flow, alternate flows, and exception
flows. They do not, typically, go into as much detail, shown captured in tabular form, in the
Trips-R-You templates. One way to think of the level of detail represented in the templates
is as a business specification of a UI or report. Given a tool that supports specifying this level
of detail for a UI or report, and assigning that unit of delivery a unique identifier, a single
detailed requirement such as the following can represent it:
An internet user or customer shall be able to search for, and book, flights for a trip – as
specified in DR013 - Self-service Flight Booking User Interface v1.0.
Spreadsheet templates, as a form of managing detailed business needs, are a step up from
trying to manage those needs in text-based documents. Ideally a requirements
management tool would support both the maintenance of formal requirements statements
and the details behind them.

32
Detailed Requirements for Data Importing and Exporting
Requirements In Context Part 7 – Detailed Requirements for Data Importing
and Exporting
It’s important for business analysts to recognize that there is a significant amount of non-
technical (i.e., business) detail associated with a system interface capability. The interface is
either importing data that’s needed and available in electronic format from another system
or exporting data in electronic format when it’s needed by some other system or
organization. The data is either needed in real time or can be processed as a batch job.

Part 6 of this series discussed detailed requirements for user interfaces (UIs) and reports.
This article will show that system interfaces involve many of the same types of details. As
with UIs and reports, some of those details are about the interface capability as a whole,
such as its operational characteristics. There are detailed requirements at the record level –
a concept similar to area-level within UIs and reports. Both records and areas act as
meaningful containers for fields. And ultimately, every field that is expected to be included
(from a business perspective) in records (or areas) has to be identified, and details about
each captured.
What should not be included in detailed requirements for a system interface are any
technical aspects. Such things as file naming conventions, header and trailer records, and
field-level mapping between the system’s database tables and the interface’s physical

33
records. These are not business issues. A BA dealing with any of these things is
performing systems analysis, not business analysis.
NOTEs:
Use of the terms ‘Record’ and ‘Field’ in this series of articles is intended to be logical, not
physical.
Use of the terms ‘High-level Requirement’ (HLR) and ‘Detailed Requirement’ are intended to
correspond to the IIBA® BABOK® V3 terms ‘Stakeholder Requirement’ and ‘Solution
Requirement’.
Use of the term ‘discussion’ in relation to stakeholders or subject matter experts (SMEs) is
intended to imply any requirement elicitation technique.
Examples presented in this series are based on the Trips-R-You Flight Booking Case Study.
CONTEXT FOR IMPORT OR EXPORT DETAILED REQUIREMENTS
The context for detailed requirements for a given import or export capability should be a
high-level requirement (see Part 4 of this series). When data needs to pass between two
systems the decision to do so by system interface or by means of a report or user interface
should be part of defining the project’s scope. Detailed requirements discussions should not
take place until this matter is settled and represented by an appropriate HLR.
NOTE: Making the decision between using a system interface and a manual interface (UI or
report) is out of scope of this series of articles. Also, out of scope is managing any impact to
a project if the choice changes subsequent to HLR sign-off.
The following context diagram was developed as part of the scoping effort for the Trips-R-
You Web-based Flight Booking project:

34
Two systems are seen to be outside the context boundary – the Global Distribution System
(GDS) and the organization’s Financial System. Connections in the diagram indicate that
those systems are involved in a number of business activities. The following HLRs represent
decisions for four system interface capabilities – a real-time and a batch import, and a real-
time and a batch export:
Real-time Import: “The system shall be able to request scheduled options for a trip from the
GDS.”
Batch Import: “The system shall be able to request current values for reference data
maintained by the GDS.” E.g., Airlines and Airports.
Real-time Export: “A customer shall be able to cancel a booking within the allowed
cancellation period for a full refund.”
Batch Export: “The system shall be able to report self-service booking flight seat sales and
sale cancellations to the financial system.”
The Trips-R-You case study describes detailed discussions with stakeholders addressing the
operational, record, and field-level details for the real-time Import and the batch export
HLRs above. The detailed requirements identified during those discussions can be seen
documented using spreadsheet-based templates. See Trips-R-You Import Requirements
Example and Trips-R-You Export Requirements Example. In addition to the details

35
documented in tabular format in spreadsheets, a single ‘formal’ detail requirement
statement was written for each of the two capabilities. See these statements in the Formal
Detailed Requirements section below.
INTERFACE-LEVEL DETAILS
Interface-level details are about a system interface’s purpose, how it’s expected to operate,
and its relationship to other system capabilities. Many of the details depend on whether the
interface is importing or exporting data and doing so in real-time or as a batch job. Examples
of the interface-level details that need to be discussed with business SMEs are:
For a batch import interface:
Is the import file expected to be received regularly? If so, at what frequencies and/or times
of day?
Do other business processes need to wait for the data to be processed before they proceed?
If so, which processes?
For a real-time export interface:
When might peak demands for this data export occur? If peaks are expected, what is an
estimated number of requests during those peak times?
If the requesting system is part of this organization, would unavailability of the data:
Be a minor business inconvenience
Be a major business inconvenience
Halt all business involving that system
(I.e., would resolving the problem be considered a priority 3, 2, or 1?)
A full set of questions applicable to an import or export capability type can be seen in the
“SME Questionnaire” tab of the case study example spreadsheet files.
RECORD-LEVEL DETAILS
A system interface record represents a meaningful grouping of fields involved in passing
data between two systems. The fields in each record are intended to contain either data
being imported or exported, or parameter values relevant to the interface. A data or
parameter record can act as the parent of one or more child records making up a hierarchy
of data or parameter records.
Record-level details include the record’s business name, its role (i.e., data or parameters),
and a description of its purpose. For data records, there may be selection and/or sorting
criteria details. Where a record is a child in a hierarchy, its parent record should be
identified along with the minimum and maximum number of instances of the child within
that relationship (e.g., minimum zero or one, maximum a specific number or ‘many’).

36
Record-level detail requirements for the real-time import HLR example above involves one
parameter record and four data records. The parameter record is needed to provide the
data about the specific journeys that make up a given trip being planned. Provided with this
data, the GDS gathers details of different options from airlines. The resulting records are
returned to be imported by the system, structured in the following way:

A Scheduled Option record is needed to contain data that identifies which Journey it is an
option for. A trip, and therefore an import request, can involve multiple journeys (e.g. a
round-trip involving two). Ideally there will be one or more Scheduled Option instances
found for each journey by the GDS to return for importing. The Flight record is needed to
contain fields about a specific flight involved to get passengers from the journey departure
point to its destination point. Data needed about a flight includes its specific departure and
arrival time and the airline operating it. There must always be at least one Flight per
Scheduled Option, but there may be options that involve ‘connecting’ flights to accomplish
getting to the journey destination point. The other two records are needed to hold other
groups of fields related to a given Flight, and therefore need to be included as part of the
data imported.

37
NOTE: Hierarchy diagrams representing record types involved in a system interface are a
form of data model, which may or may not be understood by business stakeholders. As an
aid to detail discussions about system interfaces, an alternative is to present examples of
instances of the hierarchy. E.g., for the Scheduled Options import interface, one scheduled
option instance involving a single non-stop flight and a second scheduled option instance
involving a pair of connecting flights.
An import or export capability can be single-purpose or multi-purpose. Where an HLR
represents a system interface intended to be capable of multiple types of actions there may
need to be action-specific records defined as part of record-level details.
Both the real-time import and batch export examples discussed in this article are single
purpose in that the data records all represent adding information. The batch import HLR
example dealing with reference data about airlines and airports would involve two purposes
– adding new instances and updating existing instances. Whether one record or two is
needed to represent the different action types depends on the extent of differences that are
identified during detailed requirements discussions for the interface.
NOTE: A record supporting a delete action will almost certainly involve fewer fields than are
needed for adding or updating instances. I.e., only those fields needed to uniquely identify
instances.
FIELD-LEVEL DETAILS
Field-level details for an export capability are similar to field-level details for a report.
Detailed requirement discussions should include identifying every field that needs to be in
one of the data exports records – just like every field that is needed in a report should be
identified as belonging within the appropriate report mock-up area. And for each field
exported, the system needs a corresponding field defined within a system record (i.e., the
system’s database). The system field serves as the source of the values being exported (or
reported).
Field-level details for an import capability are similar to field-level details for a screen-based
UI (that supports manual sourcing of data needed in by system). Detailed requirement
discussions should include identifying every field that needs to be in one of the import data
records – similar to each field intended to receive manually entered data should be
identified as belonging within the appropriate UI mock-up area. And for each field imported,
the system needs a corresponding field defined within a system record. The system field
serves as the target of the values being imported (or manually entered). Data entering the
system, by import or UI, involves additional detailed requirements related to ensuring that a
given value is valid prior to it being allowed to be stored in the system.
NOTE: For either importing or exporting, the relationship between the interface field and the
system field may or may not be direct. I.e. there may be some derivation, transformation,
and/or data navigation required to achieve a target field value from a source value. Where
the need for this additional effort is known by the business SMEs, it should be captured as

38
field-level detail. If not, that effort will have to be addressed as part of mapping between
physical tables and interface file specifications during the design or development phase.
Each field in an import or export-related record will also have field-level properties (e.g.,
data type, size, decimal precision). These are actually physical properties based on the
physical record design for the interface. Physical record and field details should be
documented in an interface’s technical specification document. These details are not
expected to be included as part of detailed requirements.
What does need to be part of field-level detail for an interface are the ‘business’
characteristics of each system record field identified as corresponding to an interface record
field. Where a field has been discussed as part of some other capability (e.g., a UI or report),
those details should have been addressed and captured. If those details have not been
captured for a given field prior the interface is being discussed, those details should be
included in the discussion and recorded.
NOTE: Characteristics for a given system field are intended to represent business needs
(including data validation) irrespective of the field’s participation in one or more capabilities.
Ideally these details can be recorded using some form of a Data Dictionary and easily
available for reference during detailed requirements discussions. The specifics of what field-
level details are needed are the subject of Part 5 of this series - Managing Data-specific
Business Needs.
Field-level details for the real-time import and batch export example HLRs described above
can be seen in Trips-R-You Import Requirements Example, Trips-R-You Export Requirements
Example and the Trips-R-You Data Dictionary.
SYSTEM INTERFACE-RELATED CAPABILITIES
The types of detailed requirements discussed above focus on the interface capability itself.
A real-time import or export either succeeds or it doesn’t, with immediate feedback to the
source that initiated it through its real-time connection. But a batch import or export has no
such connection through which to provide feedback to the business. Where batch
execution-specific feedback is required, it can involve an additional report and/or data file
(e.g., unsuccessfully processed records intended to be manually corrected and re-imported).
The business need for such a report or file should be identified during interface-level
detailed requirements discussions. The “SME Questionnaire” discussed above includes a
number of questions intended to identify the need for any additional system interface-
related capabilities. Having identified such needs, detailed requirements for each specific
capability should captured using a tool appropriate for the capability type.
Detailed requirements discussions for each interface-related capability should be part of the
discussions of the interface itself. A workflow diagram can be helpful to these discussions,
with swim lanes representing the types of users (or organizations) receiving reports or files,
and where needed, performing activities related to dealing with results of the import or
export.

39
NOTE: Spreadsheets are a common tool for supporting the ‘bulk’ entry or update of data by
users of a system. Typically, this capability is in addition to a screen-based UI that supports
the entry or update of individual records of a given type. Detailed needs for a spreadsheet-
based user interface should be discussed within the context of a user interface HLR, not a
system interface HLR.
FORMAL DETAILED REQUIREMENTS
The objective of the templates used in the Trips-R-You case study is to demonstrate how
large numbers of detailed business requirements can be recorded as uniquely identified
items, and the characteristics or properties of those items represented in tabular format.
Having used a template or other requirements management tool to capture the detail for a
‘unit of delivery’, a single formal detailed requirement statement can be used to manage
that unit. This eliminates the need for numerous detailed requirement statements to
represent bits or pieces of that detail.
The single formal detailed requirement statements for the real-time import and batch
export capability examples presented in this article look like this in the Trips-R-You case
study:
The system shall be able to obtain Scheduled Options for a Trip from the GDS - as specified in
DR016 - Trip Scheduled Options from GDS v1.1.
The system shall be able to provide summarized booking sales in the form of general ledger
posting transactions - as specified in DR017 - Self-service GL I/F v1.0.
By linking a formal detail requirement statement to where its details have been captured, as
well as back to the HLR representing the business capability original identified, there is full
traceability of requirements. In cases where an import or export capability needs one or
more supporting UI, report, or additional interface, as discussed above, details for each of
those should be captured separately (using the appropriate template type or tool). Each of
those capabilities should have its own formal detailed requirement statement linking to its
detail, but backwards to the HLR for the import or export capability it supports.

40
Detailed Requirements for Fully Automating a Business Activity
Requirements In Context Part 8
This final article in the Requirements in Context series discusses detailed requirements for
a fully automated business activity. ‘Fully automated’ means that the business information
system (BIS) is expected to perform the activity from start to finish without user
involvement. A simple example is the system automatically posting a monthly fee against
customer accounts. A more complex example is the system utilizing customer-specific
pricing details to determine the amount charged for a purchase made by a customer.

Within this series this type of system capability is called an automated function (AF). Like the
other four capability types discussed in the previous two articles – user interfaces (UIs),
reports, data imports, and data exports – an AF is a ‘unit of delivery’. Each should be
represented by its own high-level requirement (HLR). That HLR becomes the context for
detailed requirements discussions.
NOTES:
Use of the terms ‘High-level Requirement’ and ‘Detailed Requirement’ are intended to
correspond to the IIBA® BABOK® V3 terms ‘Stakeholder Requirement’ and ‘Solution
Requirement’.
Use of the term ‘discussion’ in relation to requirements is intended to imply any requirement
elicitation technique.
Use of the terms ‘Record’ and ‘Field’ is intended to be logical, not physical. The records and
fields involved in an automated function may or may not equate to physical database tables
and columns.
Examples presented in this series are based on the Trips-R-You Flight Booking Case Study.

41
BUSINESS ACTIVITY LEVEL OF COMPLEXITY
The business logic involved in AFs can range from very simple to very complex. A simple
activity is a candidate for full automation based on the need for it to be performed against a
large number of instances. A complex activity is a candidate based on the cost and/or
availability of staff with the necessary knowledge or skill level to perform the activity
manually (or with partial support from the system via user interface).
NOTE: The justification for including the full automation of an activity within the scope of a
project, including any organizational change management needed because of it, is outside
the scope of this series.
ACTIVITY-SPECIFIC DETAILED REQUIREMENTS
Types of detailed requirements for an AF address operational, record, and field details
similar to those for data importing and exporting discussed in Part 7. Types of operational
details relate to whether the AF is expected to run as a batch job or respond to real-time
requests. Detailed requirements for records and fields depend on their involvement in one
or more of the following roles:
Input parameters
Reference data available either within the system or through a real-time import request
System records added, updated, and/or deleted by the activity
Output parameters
Specific error-related details
NOTE: How a BIS handles errors is a system issue. The business issue is what information
business users need when a given type of error occurs.
In addition to operational and data-related details, an activity involving complex logic (i.e. a
number of steps and/or decisions) should have that logic addressed as part of detailed
requirements discussions. The objective is to understand and document how a trained or
knowledgeable user would produce the intended results using input parameters and
reference data that would be available to the AF.
Subject matter experts should confirm (i.e., sign off) the manual process description.
Designers and developers should use the description as an aid to produce their deliverables
(but not be ‘required’ to follow the process exactly as described). Testers can use the
process description to develop test scenarios and test cases. They will need to follow the
manual process to produce expected results for each test case involving a given set of
inputs.
Flow charting is a well-understood form of representing a complex business activity
graphically. As with any graphical representation, the labelled ‘shapes’ in the diagram
should be accompanied by supplementary textual descriptions.

42
Use cases are another way to describe detailed steps of an activity. With a fully automated
activity there would be no actor involvement in the steps or the activity’s initial triggering.
An AF running as a batch job would be triggered by operational procedures. An AF operating
in real-time would be triggered by some other capability (e.g., a user pressing the
appropriate button that’s part of a particular UI capability).
The pre-conditions for the use case would be the availability (and validity) of values for the
AF’s defined input parameters and reference data. Post-conditions would be the AF’s
outputs – any output parameters or defined system records that the function is intended to
add, update, or delete.
COMPLEX BUSINESS ACTIVITY EXAMPLE
The Trips-R-You case study includes an example of a business activity expected to be fully
automated. The Finding Journey Options activity can be seen highlighted below in the
project’s system context diagram:

The following HLR represents the AF capability unit of delivery:

“The system shall be able to identify the set of selectable journey options applicable to a
given trip.”

43
The business activity to be fully automated is seen in the context diagram as being
connected to the self-service Planning a Trip activity. Detailed requirements for the UI
capability supporting this activity were discussed in Part 6. One of that UI’s screens
supported sourcing details about a given trip. The fields needed as input parameters for the
AF are:
The preferred cabin class (e.g., Economy, Business).
The number of adults taking the trip.
The number of children taking the trip, their ages, and for any under the age of two, if they
will need a seat or be sitting on a lap.
For each journey within the trip, its ‘from’ and ‘to’ city or airport, and departure date.
One of that UI’s screens included a “Search” action element to initiate input field data
validation and subsequent triggering of the automated activity.
The Finding Journey Options activity in the context diagram is also seen connected to an
external Global Distribution System (GDS). This connection ended up as an HLR for a data
import capability – triggered by the AF. Detailed requirements for that capability were
discussed in Part 7. The data provided for importing from the GDS for each journey with a
given trip includes:
One or more flights scheduled on the designated date that allow the journey to be made.
For each flight:
Its current seat inventory and full fare for each cabin class.
Any age-based discounts off the full fare for any cabin class.
Detailed discussions within the context of the HLR for the AF initially identified four manual
steps:
Get data from the GDS about scheduled flights to accomplish each journey.
Identify which of those flights currently had sufficient seats for the trip.
Identify the best available cabin class per flight.
Determine the total fare for each flight based on traveller details for the trip.
At the end of detailed discussions, taking into account alternate scenarios and exceptions,
the complete set of steps and decision points ended up as represented graphically by the
following flow chart:

44
Had use case format been used instead of flow charting, the same steps and decisions could
be represented as a main flow, three alternate flows, and three exception flows. The
following diagram is a visual representation of those flows. The diagram only includes the
individual steps within the main flow:

45
Both diagrams include unique identifiers for each element. Each ID corresponds to a
supplementary textual description captured using the spreadsheet-based template for
documenting detailed requirements for an AF. The spreadsheet includes is a specific
worksheet for defining Activity Groupings (i.e., Use case paths or flowchart sub-processes)
and one for defining Activity Elements (i.e., steps or decisions within a given Activity
Grouping).
The details behind each identified group and element for the above example can be seen
documented in the Trips-R-You Automated Function Example. That same spreadsheet also
includes details of the operational, record, and field detailed requirements for this AF. With
all details captured together as a unit of delivery, a single formal detailed requirement
statement can be used to represent the set of detailed requirements for the AF:
The system shall be able to identify viable journey options based on the search parameters
for a trip – as specified in DR18 – Finding Journey Options AF v1.0.”
SERIES WRAP-UP
The objective of this series, as stated in Part 1 - Just Know it!, was to help business analysts
improve their elicitation and documentation of functional requirements within the context a
BIS.
Elicitation, using whatever technique, depends on knowing what types of information need
to be elicited and to what level of detail. This series has strived to distinguish between high-
level and detailed requirements and, within these levels, between types of information
applicable to each of the five fundamental capability types a BIS is able to provide:
User Interface (UI)
Report
46
Data Import
Data Export
Automated Function
A given BIS will support one or more functional areas within the organization and, within a
given area, business processes involving business activities. These levels were discussed
in Part 2 - The Functional View From 10,000 Feet.
The objective of a chosen solution to a business problem or goal may be to acquire or
develop a new BIS, or to provide additional capabilities within existing ones. Identifying an
initial set of candidate HLRs based on the stated scope of an IT-based solution was discussed
in Part 3 - Scope = High-Level Requirements.
The objective of HLR discussions is to identify as many capabilities as possible that are
expected to be in scope for the project (but not go into details about the needs within a
given capability). This was discussed in Part 4 – Keeping High-Level Requirements High Level.
NOTE: Given an estimate of low, medium, or high for the complexity of each HLR, an initial
(rough) estimate of the effort involved in delivering the capability and, thus the overall
project, can be derived.
Capabilities involve data. Data maintained by a BIS may be sourced or updated manually
through UIs or electronically through data imports. Or it can be derived by simple system
functions or fully automated activities. Data available in the system can be displayed for
users in UIs and reports, output electronically through data exports, and referenced for
deriving data or supporting fully automated activities. Data-specific detailed requirements,
independent of its involvement with any number of capabilities, was discussed in Part 5 –
Managing Data-Specific Business Needs Using a Data Dictionary.
Detailed requirements for a given UI or report capability include addressing its operational
aspects. Requirements also include the fields involved being grouped and arranged in a
reasonably usable way within two-dimensional areas (e.g. a given screen or a page of a
designated size). A UI has additional details involving navigation and action triggering. These
details were discussed in Part 6 – Detailed Requirements for User Interfaces and Reports.
Detailed requirements for a data import or export capability similarly address operational
aspects. But instead of fields being within areas, they are contained within appropriate
records. When records of different types are involved in a given import or export, a set of
record types may relate to each other in a hierarchical structure. Details for these two
capability types were discussed in Part 7 – Detailed Requirements for Data Importing and
Exporting.
Detailed requirements for fully automating a business activity were discussed in this article.
Similar to the other capability types, there will be operational details and details about the
data involved (fields within records, possibly in hierarchies). Depending on the complexity of
producing the intended result, there may be a need to describe steps and decisions involved
to manually produce the result.

47
NOTE: On completion of discussions of detailed requirements for a given capability, the
original estimate of effort based on the capability’s HLR can be revised. Based on the
detailed requirements, the estimates should be significantly more accurate and able to be
given with a much higher level of confidence.
Ideally the detailed requirements for a given capability are captured as a ‘unit of delivery’
using a template or requirements management tool. The Trips-R-You case study examples
have been documented using MS Excel capability type-specific templates. The resulting set
of detailed requirements for each example is therefore contained in its own separate file.
Given the details for a capability contained together as a set, a single detailed requirement
statement (referencing the most recent signed-off file version) was used to represent the
requirements for each capability.
NOTE: The concept of a single detailed requirement statement representing many individual
detail requirements may appear strange at first. But there is a precedent for doing this – A
fully documented use case includes numerous details about actions and fields involved in a
given interaction between an actor and the system. The use case itself, including all of those
details, is typically considered a single (detailed) requirement.
SERIES TAKE-AWAY POINTS
An HLR should represent one of the five basic BIS capability types – UI, report, data import,
data export, or automated function.
The signed-off set of HLRs represents the full scope of an IT-based solution to be delivered
by a project.
A detailed requirements discussion should be within the context of one or more HLRs.
Detailed requirements for a capability should address the business operational and data
needs specific to its capability type.
When detailed requirements for a unit of delivery can be represented as a set, a single
detailed requirement statement can be used to represent those details.
Detailed requirements for records and fields (stored in or derived by a BIS) should be
documented separately (e.g., in a data dictionary). Ideally the requirements management
templates or tool supports referencing the separately defined system records or fields when
involved in detailed requirements for a specific capability.
SERIES CONCLUSION
The term requirement means many things in many contexts. Hopefully this series of articles,
combined with the Trips-R-You case study presenting end-to-end examples, has provided a
clear meaning of the terms high-level requirement, detailed requirement, and
requirement statement within the context of functional capabilities to be delivered in an IT-
based solution.
This series began with a very old version of the 'Swings' cartoon, comically (but still
accurately?) representing the stages of delivery:

48
The concepts presented in this series are intended to improve the primary business analyst
deliverable: requirements. Given a complete and well-organized set of requirements,
hopefully the follow-on steps in the process will result in the most business-appropriate
‘swing’ being delivered.

49
Tool Support for Managing Requirements [in Context]
Requirements In Context Part 9
This article discusses extensions to commercially available requirements management (RM)
and application lifecycle management (ALM) tools. These extensions are intended to
support the concepts presented in the Requirements In Context (RIC) series of articles. End-
to-end requirement examples based on those concepts can be seen in the Trips-R-You Web-
based Flight Reservation System Case Study. That series focused on keeping high-level
requirements high-level and capturing requirement details in a structured manner rather
than in textual detailed requirement statements. Spreadsheet-based templates were used
in the case study to provide the structure for capturing requirements and their associated
details.
The structure represented by the spreadsheet templates has been converted into a data
model (i.e., a requirements meta-model). That model has been used to extend three
currently-available RM/ALM tools — ReqView,(1) Visure Requirements ALM,(2) and Enterprise
Architect.(3) The extensions to each tool were tested by populating them with requirement
examples from the Trips-R-You case study.
Business analysts and/or organizations that see an advantage of applying RIC concepts to
their requirements efforts can, ideally, apply these extensions to a tool they currently use.
Or when looking to acquire a tool, they can factor in its ability to support the RIC extensions.
NOTE: RIC concepts apply only to functional requirements for capabilities provided by
an information system.
REQUIREMENT IN CONTEXT CONCEPTS
All RM/ALM tools, ‘out of the box’, should support the concept of Requirement. The typical
form of support involves a textual requirement Description, accompanied by properties such
as Priority and Status. It’s left to users of the tool to manage the description content (and
quality).
RIC includes the concept of Requirement, but introduces the additional
concepts Operational Detail, Grouping Detail, and Element Detail, intended to give
structure to requirement details. This reduces the content of a requirement statement to
simply identifying a user role and naming a given capability (i.e. a user
interface, report, data import, data export, or automated function). For example:
“A customer shall be able to request a copy of a booking confirmation report.”
Specific details of a required capability each have an appropriate place to be recorded
within the structure provided by the RIC extensions. Detailed data-related needs that are
not capability-specific are recorded within the structure provided by ‘data dictionary’
extensions — based on the RIC concepts Record and Field.
NOTE: The idea of requirement detail not being contained in the requirement statement
itself is not new. A UML Use Case, ‘fully dressed’ with steps, acceptance criteria, and

50
scenarios, has been used to represent the details of a user interacting with ‘the system’ to
carry out a specific activity. RIC concepts provide additional structuring of element-level
detail. This level of detail in a use case is typically included as part of the textual description
of an individual step.
The following concept model represents RIC concepts that are the basis for RM/ALM tool
extensions:

Examples of these concepts from the Trips-R-You case study are presented below, both in
their original spreadsheet template form and as captured in an extended RM/ALM tool.
The following mock-up of the Trips-R-You Booking Confirmation report from the case study
will be the basis for examples presented in this article:

51
INFORMATION SYSTEM-BASED CAPABILITY TYPES
An information system is the combination of a database management system (DBMS) and
some number of domain-specific capabilities provided through software. A business need
that can be satisfied by an information system will be through one of the following five
fundamental capability types:
User Interface – a capability that provides on-line access, allowing users to reference and
maintain information in the system.
Report – a capability that provides a snapshot of information from the system available for
user viewing off-line.

52
Data Import – a capability that allows data available in machine-readable format to be
captured by the system.
Data Export – a capability that provides a snapshot of information from the system
available, in machine-readable format, most typically for importing by another system.
Automated Function – a capability that allows the system, using data available to it, to
generate new data and/or update existing data.
The concept of Capability Type is fundamental to the RIC approach. It is used as a
classification scheme for functional requirements (see next section).
REQUIREMENT CONCEPT EXTENSIONS
RIC extends the concept of Requirement with a number of properties. One of these
identifies its specific Capability Type. RIC uses the Requirement Type property to indicate if a
[functional] requirement is high-level or detailed. A high-level requirement (HLR) represents
a capability in scope within the context of an IT project (i.e. each specific UI, Report, etc.).
The HLR in turn represents the context for one or more capability-specific detailed
requirements (DTR).
Spreadsheet Template Requirements Example

Example of Requirements imported into Visure from an Excel document

53
Each DTR, having identified the capability it represents, acts as the context for the
capability’s Operational Details and Grouping Details.
OPERATIONAL DETAIL CONCEPT EXTENSIONS
An operational detail for a given capability addresses what is needed for the implemented
capability to perform in production. RIC includes a comprehensive set of questions specific
to each of the five capability types (see examples below). These act as a checklist of
operational details that a domain SME is expected to provide.
A capability’s operational details are non-functional. But because they are applicable to a
specific functional capability it’s appropriate, from an RIC perspective, to manage them
within that context, and in a structured way.
NOTE: The operational detail questions within the context of a specific capability are not
intended as a replacement for traditional system-level non-functional requirements.
Spreadsheet Template Operational Details Example

54
Operational Detail Examples Using Enterprise Architect Extensions

NOTE: A complete list of RIC operational detail questions for each capability type is included
with the RIC Tool Extension Meta-Model.
GROUPING DETAIL CONCEPT EXTENSIONS

55
The ultimate level of detail for a capability is the element level. RIC recognizes that
individual elements for a given capability exist within the context of some business-
meaningful grouping. The RIC concept Grouping Detail represents that context.
There are three categories of grouping detail:
Data Grouping Detail – groups a number of element details similar to how an RIC data
dictionary record groups a number of fields. The difference is that the rationale for this
grouping of elements is capability-specific, where the grouping of fields within records has a
different rationale, which is capability-independent. A capability-specific group of data
elements may represent the input or output parameters for a capability, or import- or
export-specific records. A capability can involve a number of different data groupings
related in some way (e.g., a hierarchical structure). In such cases a diagram showing their
relationships is recommended.
Area Grouping Detail – groups a number of element details that make business sense
‘appearing together’ in a user interface or report. E.g., grouped on separate ‘process flow’
screens within a UI, columns of a table within a screen or report. A mock-up of a UI or report
capability is highly recommended. The mock-up should include identifying each area
grouping, allowing its corresponding entry within the tool to be recognized.
Process Grouping Detail – groups a sequence of ‘step’ elements that have a business-
meaningful beginning and end. E.g., a ‘happy path’, an alternate path, or an exception path.
For processes involving a number of groupings a visual representation such as a UML
Activity diagram is recommended.
Spreadsheet Template Grouping Details Example

Grouping Detail Examples Using ReqView Extensions

56
ELEMENT DETAIL CONCEPT EXTENSION
At the bottom of the RIC requirement detail structure is Element Detail. RIC supports
capturing details of the following four element types:
Data Item – a data field needed by the capability, whether it’s managed by the information
system, derived specifically for or by the capability, or participating in a capability-specific
derivation.
Label – text presented on a UI or report to identify a data item, or group of data items being
displayed or to enhance usability. These text elements would typically be included in a
mock-up, but for requirement management purposes they should be individually captured
as part of the RIC structured detail.
Control – an item within a UI that triggers an action (e.g., a button, a navigation link). NOTE:
The actual control-type involved is a design issue. From a requirement detail perspective,
the element is identified as having a ‘trigger’ role. A property of the control element allows
for a description of the result of the action triggered.
Step – one of the instructions within a complex automated function capability. An
automated function capability that is complex enough to involve multiple steps should have
each step managed as an element. While the primary detail for a step is its textual
description, that text will be well positioned within the context of a capability requirement.
Any reference to data within that description should be represented by an element detail in
one of the data item’s Grouping Details within the context of that same requirement.
Within the RIC detail structure, every element detail instance is within the context of a
business-meaningful grouping detail instance. And every group detail instance is within the
context of a specific detailed requirement instance.
Spreadsheet Template Element Details Example

57
Element Detail Examples In Visure Requirements ALM

58
DATA DICTIONARY RECORD AND FIELD CONCEPT EXTENSIONS
Many RM/ALM tools include a Glossary and/or Data Dictionary capability. RIC includes the
concepts Record and Field intended to support defining capability-independent details
about data that is expected to be managed by the information system. Each Field exists
within the context of a Record.
NOTE: RIC uses the business-friendly terms record and field rather than IT-ish terms such
as Class, Entity, and Attribute. It also takes the object-oriented view of Relationships –
treating one direction of a relationship as an attribute of the class it originates from. In RIC
terms - a field within a record. E.g., a “Customer” field within an “Order” record.
RIC tool extensions associate a number of properties as details of a record or a field. The
property Field Type classifies each field as being one of seven types (e.g., Label, Quantity,
Description). Some field properties are type independent (e.g., Mandatory, History
Required). Other properties are type specific (e.g., fields of
type Quantity have Precision and Unit of Measure). The RIC extension meta-model includes
and describes each of these properties.
Spreadsheet Template Data Dictionary Example

Data Dictionary Record and Field Examples Using Enterprise Architect Extensions

59
STAKEHOLDER
The concept of Stakeholder within RIC is analogous to the UML Use Case Actor concept, the
Dataflow Diagram External Entity concept, and the process model Swim Lane concept. RIC
utilizes this concept, adding or extending it to include user, source, and owner relationships
to other RIC concepts (see RIC meta-model for details).
SPREADSHEET TEMPLATES VS RM/ALM TOOLS
The Trips-R-You case study examples utilize spreadsheet-based templates to illustrate RIC
concepts and structured details. There is one template for requirement statements, one for
the data dictionary, and a type-specific template for each of the five capability types.
The capability-specific templates were designed to capture details for only one capability (of
one of the five capability types). That means there would be one spreadsheet file for each
UI, each report (etc.) in scope for a project. An RM/ALM tool captures all requirements and
their details together for a single project. Some tools provide support for documenting
multiple projects within a single file.
Spreadsheets allow for data in one worksheet to reference data in other worksheets. A
referenced worksheet may be in the same spreadsheet file or in a separate file. For
example, it was possible for an element detail in any of the capability-specific worksheets to
reference its corresponding field within the data dictionary spreadsheet. But the opposite
was not achieved (or even attempted). That is — for a given data dictionary field, what
capability-specific element details involved it?

60
The ability to navigate defined relationships between items in either direction within an
RM/ALM tool is a big advantage. The following illustrates using tool extension links to
identify usage of fields within capabilities. This is possible by following links:
From each Record to the Fields, it is the context for
From each Field involved in an Element Detail
From each Element Detail to the Grouping Detail that is the context for an Element Detail
From each Grouping Detail to the Detailed Requirement that is the context for the Grouping
Detail.
Once this traceability has been defined, it can be applied to one Record, a filtered set of
records, or all Records.
Where-Used Example Using ReqView Extension Links

NOTE: The ability of an RM/ALM tool to display or report on data maintained within or
derived from extensions is outside the scope of RIC. Such capabilities should be
discussed/confirmed with the tool vendor.
The RIC spreadsheet templates are available for use on an ‘as is’ basis. Their original
purpose was to demonstrate capturing requirements and their details in
a structured manner. They were never intended for ‘serious’ project work.
My personal recommendation would be to conduct an evaluation of commercially available
RM/ALM tools, including their ability to support RIC extensions.
This article has been about extending a commercially available RM/ALM tool to capture and
manage requirements and associated details in a structured form, rather than in textual
statements. Three such tools have RIC extensions applied and can be tested on a free trial
basis (see notes below). Accompanying this article is the RIC Tool Extension meta-
model that was the basis for creating those extensions. This model is intended to be used as
a guide to extend other RM/ALM tools that offer sufficient extension capabilities.

61
(1)
ReqView Requirements Management Tool – Request an evaluation copy here and see a
blog post specific to the RIC extensions here.
(2)
Visure Requirements ALM – Request an evaluation copy here and the Visure team will
provide the project template upon request at [email protected]
(3)
Enterprise Architect – Request a trial edition here. Download the RIC extension
from here (search this site for “RIC MDG Technology”).

62