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 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:
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 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 Questionaire” 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 a given 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’).
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.
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 export 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 insuring 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 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 Questionaire” 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.
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.
Next Time
The next article addresses detail requirements for automated functions (AFs). An automated function (AF), within the context of these articles, is a system capability that is important enough to the organization to warrant its own high-level requirement (HLR). An AF is intended to fully automate a business activity. This means that the system is able to perform the activity from start to finish without human intervention. An additional MS Excel-based template will be introduced for capturing details specific to this capability type.
Previous articles in the Requirements in Context series:
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].