Author: Dan Tasker

The objective of my 2016 Requirements in Context series was to help business analysts elicit requirements

through an improved understanding of the difference between high-level requirements (HLRs) and detailed requirements (DTRs).

The Trips-R-You case study is an addendum to that series, offering end-to-end examples of requirements documented using spreadsheet-based templates.

In IIBA® BABOK® V3 terminology, end-to-end means from Business Requirements to Stakeholder Requirements to Solution and Transition Requirements. Both the original series and the case study use the more traditional business terms Goal, HLR, and DTR. Also both only address functional requirements within the context of a project chartered to deliver an IT-based solution.

NOTE: A business may choose to organize their IT solution-delivery resources following Agile principles. But if the delivery of those solutions are managed by a project manager, or the Agile teams do not include a ‘real’ product owner – able and available to prioritize and refine user stories, then requirements still need to be documented and managed.

The Case Study

The case study involves a fictitious organisation — the Trips-R-You Travel Agency. It deals primarily with the requirements phase of an equally fictitious project, established to deliver a web-based customer self-service flight booking capability — commonly referred to as an Airline Reservation System.

The case study is divided into three sections, based on the three levels of requirements. The first section introduces the organization and a problem it faces. A goal is set that is intended to eliminate the problem, and a business case is commissioned to examine potential solutions.

The second section sees a project initiated to deliver the solution recommended by the business case. That project’s scope is shown, and how it leads to high-level requirements for the project.

The third section takes five HLRs to the detail level – one HLR involving each of the primary capability types a business information system is able to support:

• User Interface (UI)
• Report
• Data Import
• Data Export
• Automated Function

To support capturing the details involved in each of the above capability types, type-specific spreadsheet-based templates are utilized.

The third section also discusses and uses a Data Dictionary template. As the detail for a given HLR is discussed, the data-specific business needs involved are captured using this template. Once captured, those data-specific details are available for referencing in the other templates when those needs come up again, as they will, during discussions involving other HLRs.

NOTE: The Data Dictionary template incorporates the concepts presented in my 2018 “Well-defined Data” series.

Detailed Requirements vs Detailed Requirement Statements

It’s natural (and correct) to assume that for every HLR, there will be some number of DTRs. But what, exactly, should a detailed requirement look like? A formal requirement statement is expected to be a single sentence that includes the word ‘shall’ (rather than a term implying a priority such as ‘must’ or ‘should’). More typically, to accommodate detail, a textual requirement statement involves a number of sentences or paragraphs.

Requirement documentation techniques that make use of ‘fully dressed’ UML use cases describe an Actor interacting with ‘the system’ performing a given business activity. That description includes the individual steps within the activity, organized into different flows — one main flow and any number of alternate and/or exception flows. The step description includes names of individual fields and ‘controls’ (e.g. buttons) involved. The requirements documentation technique may treat each flow or each step within the use case as an individual DTR, or treat the entire use case as a single DTR.

The spreadsheet-based templates used by the Trips-R-You case study uniquely identify individual rows, each representing a detailed requirement (but not in ‘statement’ form). Three separate worksheets (tabs) are used to capture different categories of detailed requirement. Those three categories address:

• The capability’s operation – E.g. who needs it, when.
• An Individual element – E.g. a field, control, or step within an automated function.
• An Element Grouping – E.g. an area on a screen or report (see mock-up below), a record being imported or exported.

Tabular format allows for separate columns to represent different types of detail (i.e. characteristics) applicable to a given item. E.g. for an individual field element within a report area, characteristics identifying the font to be used and whether the field is to be justified left, right, or centered. The templates also support visual representations of the detailed requirements, such as screen or report mock-ups (see example below).

Because all of the details for a ‘unit of delivery’ (a specific UI, report, etc.) are captured in an individual spreadsheet file, those DTRs can be represented by a single ‘formal’ DTR statement (similar to a whole use case being treated as a single DTR). The following is an example from the case study of one of the HLR statements for a report, and its corresponding single formal DTR statement representing the template-based DTRs for that report:

REQ008 (HLR) – A customer shall be able to access and print the booking confirmation details.

REQ015 (DTR) – The system shall be able to produce a Booking Confirmation report for a specific Booking – as specified in DR015 – Self-service Booking Confirmation Report v1.0.

The template-based DTRs for this report consisted of the following:

The spreadsheet file also included the following mock-up, visually representing the six Report Areas and the Elements contained in each:

Individual Statements, Templates, or a Requirements Management Tool?

Requirements have a reputation for taking too long to document. They have probably earned that reputation from projects where: Requirements were ‘hand-crafted’ requirement statements; HLR statements were allowed to include too much detail; And DLR textual statements were written that included varying combinations of details about fields and/or field characteristics.

Keeping HLRs to the capability type-specific level (i.e. specific UI, report, etc.) is intended to avoid time wasted at this stage of requirements elicitation. Using capability type-specific templates is intended to save time by representing and providing space for capturing values for the specific types of details that need to be addressed for each capability type and category.

NOTE: The templates used in the Trips-R-You case study represent an amalgamation of detailed requirement types and characteristics based on my years of experience as a business analyst working in project teams delivering IT-based solutions. That experience included working for software package vendors, for organizations acquiring software packages, and for organizations outsourcing parts of a solution.

Better than spreadsheet-based templates, where affordable, would be a commercially-available requirements management (RM) or application lifecycle management (ALM) tool that supports the requirements-related concepts presented in the Trips-R-You case study.

The Trips-R-You Case Study as a Tool Benchmark

In addition to being an aid to understanding concepts related to HLRs and DTRs, it was hoped that the Trips-R-You case study would serve as a benchmark utilized by RM and ALM tool vendors. While their tools would not be expected to support all of the concepts out of the box, most tools currently on the market offer some degree of configuration. Any organization looking to acquire a commercially-available tool to support the requirements phase of IT-based projects might ask their candidate tool vendors to demonstrate their tool’s ability to support this case study.

NOTE: Any tool vendor that believes their tool to be capable of supporting the “Requirements in Context” concepts represented in the Trips-R-You case study is welcome to contact me for assistance with the benchmarking exercise.

In this article we discuss point-in-time attributes — more commonly referred to as dates and times.

Dates are points on time scales we know as calendars, and times are points on scales we view as clocks. From a well-defined data perspective they are actually quantities, similar to those described in Part 7. Like other quantity attributes, points in time have units of measure, precision, and their values can participate in calculations.

A date, time, or combined date/time attribute represents when something occurred (or will occur). There are business entities, such as purchase, flight, and journal entry, which represent events of interest to an organization. These entities act as the context for one or more point-in-time attributes. Flights, for example, will have a number of point-in-time attributes, including ‘scheduled departure date/time’ and ‘scheduled arrival date/time’.

There are business entities such as customer, product, and location, which are not events themselves but can act as the context for events related to them. A customer that is an individual can have a ‘date of birth’. A product can have a ‘launch date’. A location can have daily opening and closing times. Each of these points-in-time attributes represent the ‘when’ aspect of an event of interest to the organizationn.

Point-in-time Units of Measure

The most common calendar system in civil use is the Gregorian calendar, with its year zero some 2000 years ago and its units of years, subdivided into 12 months which in turn are divided into 28 to 31 days. Google advises that there are some 40 other calendar systems used around the world, most associated with a religion. Each has its designated year of origin, sub-units of months, and days within months.

The commonly-recognized time scale divides a day into 24 hours with sub-units of minutes and seconds. The zero-point of a day is most often assumed to be midnight local time. Organizations that involve events that can take place in different time zones require an additional unit of measure attribute whose role is to identify the time point’s specific time zone. Again, see Part 7 for its discussion regarding associating units of measure with quantity attributes.

Point-in-time Precision

Different organizations or industries can have different precision requirements for the same event. For example, a person’s birth event. ‘Day’ is the most common precision. However, organizations that deal with official birth records record the event date/time to the nearest ‘minute’. Conversely, only the year of birth for an author is needed by book publishers, book retailers, and libraries — used to distinguish between authors with the same (or similar) names.

If the point-in-time attribute involves precision finer than ‘day’, the options progress from hours, to minutes, to seconds, and finally some number of decimals of seconds. The nearest ‘minute’ is usually sufficient for human-related activities. When greater precision is needed, microchip-based timekeeping devices are utilized to source a value (e.g. a POS terminal recording the time-of-purchase transaction to the second).

The easiest way to think of ‘date’ or ‘time’ precision is digitally. Think of a digital clock that displays both the date and time, with a 4-digit year and 2-digit months and days. A digital clock (and point-in-time attributes) have no concept of precision-based ‘rounding’ (e.g. to the nearest year, month, or day). The same applies to point-in-time precision for ‘hour’, ‘minute’, or ‘second’ values.

Period-defining Time Point Attributes

Business time periods can be specified in one of three ways:

• Two different point-in-time attributes — one marking the start and the other marking the end.
• One point-in-time attribute and a quantity attribute representing the duration.
• A sequence of time-point attributes indicating a start point, and the subsequent start point implying the end point of the previous period.

Two different Points — Two different point-in-time attributes are defined, both with the same units of measure and precision. Naming and/or definition should make the role of each clear (start or end marker) and that the two attributes are associated. Business rules need to be confirmed indicating if two or more periods are allowed to overlap and if gaps in time are allowed between periods. E.g. the event-entity ‘staff assignment’ can have overlapping periods indicating job sharing and gaps indicating vacancy periods.

Time Point and Duration — Given either a start or end point in time, plus a duration, the other time point can be derived. For example, given a ‘contract’ start date and a contract duration of four weeks, the end date can be calculated.

Sequential Points in Time — In cases where time periods are contiguous (i.e. no overlapping and no gaps), only one time point attribute is needed. For example, foreign exchange rates. At the point in time a new rate value becomes effective, the previous value ceases to be in effect. Whether to define the start point and assume the end point or the reverse depends on which best represents the business event. In the exchange rate example, there being a new rate taking effect clearly is the event.

Well-defined Point-in-time Attributes

From a data dictionary template perspective, a well-defined point-in-time attribute should have the following properties addressed:

• Name — Follow any organizational standards for naming date, time, and date/time attributes. Where one of a pair of attributes specifies a time period, try to be consistent with pair names (e.g. begin/end, start/stop, from/to, or effective/expiry)
• Definition — Describe the business event that time point is marking. Include examples that illustrate precision and any rules that may apply.
• Unit(s) of measure — Specify calendar system if other than Gregorian (or explain in Definition). For Time, specify ‘local time’, or indicate the attribute that identifies the associated time zone.
• Precision — The precision that is required for business purposes. Normal dates can assume ‘day’ as the precision. Time (or Date/Time) captured would not be more precise than minutes.
• Associated-Period Boundary Attribute — Where the time point is one of a from/to pair, identify the other member of the pair.
• Future values allowed (Y/N)?
• Historic values allowed (Y/N)?
• Derivation — For a date or time being derived, a business definition or rule describing the derivation (e.g. ‘Best Before’ date derived from Product Batch ‘Processed Date’ plus Product Type’s ‘Shelf Life Days’). Include examples using business values.
• Validation — Reference business rules or describe. E.g. Value should not be more than 50 years beyond current date.

Coming next – 5 Questions for Business Stakeholders About Their Data Requirements

The remaining topics applicable to well-defined data are wrapped up in next (and final) article in this series. The topics are addressed in the form of questions, such as ‘optional or mandatory’, that require responses from business stakeholders. The questions, and their answers, are applicable to either attributes or relationships.

Click here for Part 1 – Series Introduction

A classification attribute allows the recording of a meaningful fact about an entity instance, with that fact drawn from a pre-established set of values.

Common forms for presenting a set of such values to users include drop-down lists, checkboxes and radio buttons.

This article will discuss three levels of complexity of attribute-based classification:

• Self-defining — where the attribute represents something that is either true or not.
• Value-only — where any one of the predefined values may be applicable to a given entity instance.
• Complex — where one value that is applicable to an entity instance impacts other values that can be applicable to that instance.

Naming and maintaining value sets will also be discussed.

Self-defining Classification Attributes

A self-defining classification attribute is one where the fact it represents either applies or doesn’t apply to a given instance. Examples include a person holding a valid passport (or not) or eggs being from free-range chickens (or not). Because the valid set of values is a simple yes/no (or true/false) pair, it’s up to the attribute name and definition to provide the business meaning of a positive or negative value. The name of the attribute need only be descriptive enough to allow people to understand the general nature of the classification — e.g. ‘Has Valid Passport’, ‘Is Free-Range’. The attribute’s definition should provide further business details related to an appropriate choice in a given instance.

NOTE: It’s recommended that self-defining classification attributes represent the active (or positive) condition. This avoids responses that involve a double negative — e.g. ‘No Valid Passport’ requires a response of ‘No’ to indicate that the person actually has a valid passport.

Also worth noting is that there is a difference between a self-defining classification attribute and a classification attribute that has only two possible business values. For example, in accounting systems, a journal entry is classified as being either a ‘debit’ or a ‘credit’. It would be possible to define a classification attribute named ‘Is a Debit’, where a value ‘false’ implies that the entry is a credit. However, from a well-defined data perspective, the value set should be composed of the valid business values.

Value-only Classification Attributes

A value-only classification attribute is one where the only thing the organization cares about is the business-meaningful values in the classification scheme. These values may be made available for selection or be derived based on defined business rules. For example, a car dealership will classify each car by color, from a fixed value set relevant to their business, including ‘black’, ‘white’, ‘red’, etc. This set of values is sufficient for sales staff and car buyers to find all of the cars they are looking for in a specific color.

Conversely, to an organization that manufactures cars, paint color is a critical component in the manufacturing process. In this context, ‘paint color’ would be a full-fledged business entity with its own business entity identifier, plus naming, quantifying, and classification attributes of its own.

Complex Classification Attributes

A complex classification attribute is one that not only has a set of valid values, but those values involve relationships to other classification values. Continuing with the car business example, the dealership will deal with cars from different manufacturers, which will call for one value set for a car manufacturer and a second value set for the car model. There is a parent/child-type relationship between these two attributes, with a manufacturer being the parent of multiple car models. Implementation of a parent/child relationship in a user interface might involve the user initially selecting a parent value from one combo box and then selecting a child value from a second combo box, which would list only those child values relevant to the selected parent.

Another type of relationship between classification attribute values involves allowable transitions within the same value set. For example, consider the case of a business entity that has a defined set of status values, but the business wants to ensure that an instance is only allowed to transition to a selected subset of other values based on its current ‘status’ value. In addition to the value set, each value needs to identify the other values that it can transition to. State transition diagrams are good for graphically representing valid value transitions.

Classification Attribute Naming

The terms type, class, and category are often used when naming a classification attribute (e.g. ‘Customer Type’, ‘Product Category’, ‘Class of Service’). An organization’s users — familiar with existing business processes that involve one of these generically-named attributes — will also be familiar with their value sets. A classification attribute having a name that provides no clue regarding the classification scheme is only ‘well defined’ when examples of its values are available. For example, the name ‘Customer Type’ is, by itself, meaningless. Add example values ‘new’ and ‘existing’ and all becomes clear.

Value Set Change Process

The maintenance of value sets within an IT-based system typically takes place under the ‘Administration’ functionality. The process should ensure that all change requests originate from an authorized source. Users of the classification scheme ideally are given advance notice of any changes.

A value that becomes no longer applicable for the organization, and should therefore no longer be available for selection, should be end-dated rather than deleted. Similarly, a newly added value should have an effective date associated with it, unless all new values for a given classification scheme take effect immediately.

Additional complexity in changing a value set arises when the classification values are involved in business rules, process flows, or interfaces to other systems. Any added value needs to be accounted for in the rule specification, in existing or added process flow decision points, and/or interfaces. Both the value change and the associated system changes will need to be tested before they are put into production.

Well-defined Classification Attributes

The attribute should have the best name that the organization can provide. Similarly, the values, when textual, should also be as meaningful as possible. As with attributes that name (discussed in Part 6 of this series) the organization may want, in addition to the full ‘name’ of each value, an abbreviated and/or code value. When this is the case, these should be included as part of the definition.

At attribute definition time, the full value set may or may not be known or available. If not, or if it’s a large value set, enough examples should be included to make the classification scheme understandable. The definition should indicate whether the values are examples or they represent the complete value set.

Where classification values are derivable, that derivation should be identified, either as part of the definition or by referencing the derivation business rules (maintained separately).

The example values provided should be sufficient for designers to know what is needed from a database-definition perspective. The examples should be indicative of field size, data type, and precision if required for numeric value sets, and so these properties should not be required.

NOTE: As mentioned at the beginning of this article, there are a number of ways value sets can be presented in user interfaces (e.g. combo-boxes, checkboxes, radio buttons). Usability is a design issue and, as such, is outside the scope of this series.

Coming in Part 9 — Point in Time Attributes

Click here for Part 1 – Series Introduction

Having discussed attributes intended to name entity instances in Part 6 of this series, we move on to attributes intended to satisfy the need to say something quantitatively about an instance.

Well-defined quantity attributes require particular attention be paid to their unit of measure (UoM) and precision.

Numbers verses Quantities

There are attributes whose values only contain numeric digits, such Credit Card Number. There are others, such as Part Number, whose name implies that values are numbers, but in some organizations, values of these attributes are allowed to include alphabetic characters. The objective of these sorts of attributes is actually to name or identify an entity instance, not to quantify it.

Genuine quantities have magnitude. A value can be bigger, smaller, or the same size as another value. If you double a quantity value (i.e. multiply it by 2), the resulting value is twice as big (unless of course the original value was zero). It would not make business sense to double a credit card number, or subtract one from another.

Unit(s) of Measure (UoM)

The following table contains types and examples of units of measure commonly used in relation to quantity attributes.

NOTE: In the table above, ‘None’ represents types of quantities that are intended to be used in calculations but themselves have no unit of measure. E.g. An additional 10% discount, intended to be applied to the value contained in a ‘price’ attribute.

The unit of measure that applies to a given quantity attribute may be defined globally for the organization, apply to a number of attributes within a given entity, apply to a single attribute, or be different for each attribute instance.

Precision

For most quantity attributes, their precision can be specified as a number of decimal places required by the organization. E.g. integer indicating no decimal places, or cents for currency quantities, implying two decimal places. The following are examples of precision that require special attention when defining the quantity attribute.

Sources of Quantity Values

As with other types of data, quantity values can be provided from sources external to the organization or from internal sources. A third source, in the case of quantity attributes, is derivations.

Well-defined Quantity Attributes

From a data dictionary template perspective, a well-defined quantity attribute should have the following quantity-specific properties addressed:

• Unit(s) of measure — Even if the attribute name says something about its units, the unit(s) should be identified explicitly. Where the unit(s) vary per instance and are captured in a separate attribute, that attribute should be referenced.
• Precision — Most often a simple statement of the number of decimal places. Exceptions, as discussed above, should be described in text.
• Maximum — The business question that should be answered by a subject matter expert is, “What’s the largest value of this quantity ever encountered or that needs to be catered for?” NOTE: Using nines (e.g. 999,999) to describe a large value is not business oriented. If, for example, the answer to the question is ‘850,000’ then designers will understand what’s required.
• Can be negative? — yes/no
• Zero ok? — yes/no
• Derivation — For the attribute being derived, a business definition or rule describing it. This can be in the form of an algebraic formula, a step-by-step process, a flow chart, or formal business rule definition language. Ideally one or more worked examples containing realistic values would be included.

Coming in Part 8 —Attributes That Classify

In this article we focus on people-oriented identifier attributes — ones intended to record the name by which the person or thing is known, addressed, or referred to.

Unlike the business entity identifier attributes discussed in Part 5, name values may change over time, and values may not be expected to be unique, e.g. names of persons.

There are instances of things that an organization establishes internally, and therefore has the right to name. These things include positions within its organizational structure, its general ledger accounts, the products it produces, the services it offers, and the locations it manages for operations and sales purposes.

Things that an organization does not have the right to name include its staff members, customers, and suppliers.

Full, Abbreviated and Coded Name Attributes

When a business entity is the type of thing that has named instances, there is a good chance that there will be requirements for more than one name attribute. Wherever names consist of a number of full words, the organization will most likely have a shorter version of the name that it uses in its business processes.

And where a name is used frequently, and keystrokes are to be minimized, there is likely to be an extra-short code version of the name.

Non-word Names

Not all names consist of words or abbreviations. Street names are a good example. The majority of street names do involve words like ‘Main’ or ‘Maple’, or are named after people or places. But there are also street names based simply on numbers or letters, e.g. ‘1st Avenue’, ‘2nd Avenue’, ‘A Street’, ‘B Street’.

Another example of non-word names are floors within a multi-story building. The floors will have full names, such as ‘Ground Floor’, ‘Fifth Floor’, ‘Parking Level One’, or ‘Penthouse’. But the organization may only require the coded versions of floor names (e.g. ‘G’, ‘5’, ‘P1’ ‘PH’).

Person Names

Person names are different again. One difference is that there is seldom an expectation that a person name will be unique. Another difference is that a normal part of life involves individuals changing their name, either legally or simply to the latest way they prefer to be addressed.

For entities that represent persons, such as Staff Member or Customer, there are four basic name-related attributes that may be necessary to support an organization’s business processes:

• Legal Name — (1) Required to support business processes that involve regulatory organizations, where those organizations require identifying individuals (and companies) by their full legal name, e.g. tax authorities. (2) Required during business processes initially verifying a person’s identity, when that name is used to match with other organizations that also maintain a person’s legal name for such purposes, e.g. ‘Thomas Albert Jones’.
• Contact Name — The name a person wants to be recognized by at their points of contact, such as when receiving snail mail or when contacted by phone. It’s expected (but not required) to include one or more ‘given’ names plus a family name, e.g. ‘Tom Jones’.
• Preferred Name — The name a person prefers to be addressed by within the organization and/or by customers, e.g. ‘Tommy’ — displayed on the employee’s ID badge. For customers, it’s the name that the person prefers to see as part of their online user experience, e.g. ‘Welcome back, Tommy’.
• User ID — The name chosen by or assigned to an online user of an IT-based system. Typically it’s some version of the person’s name. These names are required to be unique within the context of the system (but can change over time if required), e.g. ‘TJones’, ‘[email protected]’.

When the legal and/or contact names are expected to be sorted by family name, the family portion of the name would need to be its own separate attribute.

NOTE: Some organizations choose to prefix a person name with a title such as ‘Mr’ or ‘Mrs’. Similarly, an organization may want to present a person’s name followed by one or more recognized qualifications, such as ‘MD’, ‘Ph.D.’, or ‘QC’. Such before and after values should be maintained as separate attributes, as they are classifications rather than an actual part of a person’s name.

Well-defined Name Attributes

From a well-defined data perspective, there must be an existing business entity that the name is an attribute of, e.g. Position, GL Account, Staff Member, Customer. For entities whose instances have just one name, the attribute can simply be called Name. Ideally, the attribute definition would include one or more examples that make it clear what is expected in the way of values for instances.

Name values that originate from within the organization can be made to fit within whatever length limit the organization specifies. Ideally, externally-sourced name attributes would allow for enough characters to accommodate the longest possible value. If not, then the process of capturing a name needs to allow for the value to be abbreviated or truncated to fit the available space.

Each name attribute should have a maximum length specified (testers will test this). A subject matter expert should be able to give an indication of how many characters will be sufficient. In the cases of codes, the organization may also want to specify a minimum number of characters.

In terms of restricting allowable characters within a name, internally-created names can be restricted if there is a business reason to do so (e.g. only alpha characters and spaces). Externally-sourced names are best left unrestricted unless there is a business reason to restrict allowed characters. The question becomes, “What should the IT system do if a valid external name is received that contains one or more restricted characters?” Leaving them unrestricted eliminates this question.

Name Values — The Bottom line

The majority of internally-sourced names come from the organization’s decision makers. If there is a technical reason that one or more special characters should not be allowed within a name, then validating to avoid them is a reasonable thing to do. Externally-sourced names, if they are from valid sources, simply are what they are. The organization that needs to support them within an IT system should not be told by that system (in an error message) that they can’t. It’s just as possible for the value of a name to be entered incorrectly using allowed characters, e.g. ‘Tom Bones’ entered rather than the actual name ‘Tom Jones’.

There should be a system-supported business process that allows an incorrect name to be corrected.

Coming in Part 7 — Attributes that Quantify