(Requirements In Context Part 4)
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 need 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:
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 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.
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
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.
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:
- 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?
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.
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.
Author: Dan Tasker
Dan is the author of over 30 requirements-related articles and other resources. His 45+ year career in Information Technology has involved organizations in a variety of industry sectors in the United States, Canada, Australia, and New Zealand. His business analysis experience includes projects involving in-house software development, software vendor solution development, and COTS software acquisition and implementation. He continues to be passionate about quality requirements and helping business analysts produce them. He can be contacted at [email protected].