Best Practices while using ReqIF

Authors: SudarshanRao
Build basis: None.

The Requirements Interchange Format™ specification provides standards-based exchange of requirements authored in different Requirements Management (RM) tools. Requirements Interchange Format (ReqIF) defines an open, non-proprietary exchange format. Requirement information is exchanged by transferring XML documents that comply to the ReqIF format. IBM Enterprise Requirements Management DOORS Next is compliant with ReqIF standard, wherein it allows export and import of requirements using ReqIF files.

While the standard aims to provide a seamless mechanism to exchange requirements across different tools, due to varied features and implementation nuances of each tool, there are situations where exchange of requirements may fail or have undesired affects. This article aims to equip the reader with best practices while exchanging requirements information while using IBM Engineering Requirements Management DOORS Next (DOORS Next). Primary focus of this article is on importing ReqIF files into DOORS Next, how it affects information architecture within DOORS Next and so on.

What's in a ReqIF file

In order to facilitate seamless exchange of requirements, a ReqIF file is fully self contained to describe a requirement. Apart from simple text describing requirement, the ReqIF file must also contain information about attributes related to requirement, data types used to describe such attributes, relationship to other requirements, any embedded image/document based representations etc. Thus, a ReqIF file primarily contins 3 sections:

Header - contains metadata related to the tool from which the ReqIF file originated.

Core Content - this is the main section, that describes the structure of requirement (attributes, data types, relationships) and requirements itself. Each of these are defined as elements with a unique ID - called ReqIF ID and a Name. This ReqIF ID is a one to one mapping with the resource, which must remain unique and unchanged across all ReqIF related interactions. Further details of how each of these elements are represented, is defined in the ReqIF Specification found here.

Tool Extensions - this is an option sectional to augment tool specific nuances of requirements described in earlier section of Core Content.

The exchange file generated by any tool could simply be an XML file with .reqif extension, or could be a compressed file with .reqifz extension. A compressed file (.reqifz), may contain more than one .reqif file and also additional files representing images, documents etc embedded and referred to, within the requirement resources in .reqif file(s).

What all happens during a ReqIF import

When a ReqIF file is imported, it can create or modify the type system and also requirement resources. In other words, it may create or modify Artifact types, Attribute definitions, Attribute Data Types, Link Types, Folders, Requirement resources. Imports are non-destructive - it does NOT remove/delete any resource. However, since the import can affect the type system, utmost care should be taken in what is allowed to be modified in the type system. By Type System, we refer to Project / Component properties area where data types, attribute definitions, artifact types are defined and managed. Not managing the type system well affects reportability of data, or at times incorrect updates to data. Hence, it is important to ensure modification to type system are intended and planned. Let's look at few approaches in managing a healthy type system while engaging in ReqIF based transactions.

Best practices while exchanging requirements using ReqIF

Plan before you send or receive

To begin with, when you have a need to collaborate with another organization or team which needs ReqIF based exchange of information, it is essential to discuss and define a framework for this exchange. This should involve clearly defining which party owns the data, what attributes of requirement resources will be editable, what needs to remain read-only, who can modify data types and so on. This would help in avoiding any data inconsistency from creeping in.

Planning to send data

If you are the data owner, remember, DOORS Next allows you to define subset of requirements and also subset of attributes to be included in export. This can be achieved by using module based views. Even for the attributes you choose to send, you may agree with your partner on set of attributes that are allowed to be edited by your partner and set of attributes that are not allowed. For example, you may not want your partner to modify the main text of requirements, but can suggest modifications via separate text attribute. This is to be agreed during the planning phase. While the partner can update any attribute that is imported into their repository, you have the discretion of updating attributes selectively. Thus, you can enforce control on what data sent from your repository is modifiable by your partner via the updates they send back to you.

Planning to receive data

You may receive ReqIF files from your partner as new data, or as updates for the data you sent to them earlier. In either case, when you import a ReqIF file, it not only creates or modifies requirements, but also potentially modifies the type system of your project area.

Use a Changeset to import any ReqIF file

As a best practice, it is always recommended to use a Changeset while importing any ReqIF file. This allows you to review the modifications introduced by the import in a detailed manner, while also allowing for discarding the changes if there are adverse modifications observed.

Managing changes to type system

Importing new data vs importing updates

It is important to recognise if the ReqIF file to be imported contains primarily new data set, or updates to already imported data. If it is new set of data, the potential to impact type system is higher. DOORS Next allows you to identify if the ReqIF file being imported contains new data, within the Import Wizard. Any new module or attributes that exists in the ReqIF file are shown with suffix as (NEW). This information is presented in Step 4 and 5 while using Advanced option to import. If the file being imported is completely new set of data, consider importing into a separate new component. If you work with multiple partners, you may want to consider managing data from each partner in separate component or project areas. Instead, if you need to import into an existing component for any reason, review the changes to type system the import affects thoroughly. Use a changeset to evaluate the changes. If the file being imported is updates for existing data in your repository, ensure you evaluate all new types coming in. As suggested earlier you can do so by looking for "(NEW)" suffix to the attribute names in Step 5 of import (while using Advanced option to import). In particular, look for any existing attributes being treated as 'New', or if there are any duplication. This can occur if the ReqIF ID assigned to attribute is changed (should not happen).
Note: Attributes are always viewed in relation to what artifact type it belongs to. During an import, an attribute can be marked as 'New', if it is newly added to an Artifact Type.

How are attributes and data types mapped?

The primary reference to match the data in ReqIF file and your project area is, is ReqIF ID.
There are occasions where two distinct ReqIF files may have a type represented by same name, but have different ReqIF IDs. Semantically they mean the same type, but since they come from a different scope, a different ReqIF ID may be used. This is true within DOORS Next as well, when they come from two different components/projects, since type system in DOORS Next is scoped at project/component level. In such a case, during import, DOORS Next treats it as a new type and creates it with a suffix added to the name - [DNG-Renamed-n], where n is a number. If the ReqIF exchange is between two DOORS Next instances, then you can make use of RDF URI to indicate a given type is the same even if it is coming from different project/component/repository. For more info, refer to Creating attributes for requirement artifacts in IBM Knowledge Center. When a resource has RDF URI assigned, this information is included in TOOL-EXTENSIONS section of ReqIF File *generated by DOORS Next.*
For any attributes that has same RDF URI assigned, DOORS Next treats them as the same even when the names are different, provided the underlying data type is the same. For any artifact types that has same RDF URI assigned, DOORS Next treats them as the same even when the names are different, provided the underlying artifact format is the same. If there is a difference in the attributes included, those are merged. Note, no attribute is removed; it is only appended where applicable. For any data types that has same RDF URI assigned, DOORS Next treats them as the same even when the names are different, provided Base Data Type is the same. In case of enumerations, similar match happens against the Values. If no match found, the value is inserted into the list.

The concept of using RDF URI is native to IBM. What about the ReqIF Files coming from a different tool that does not use RDF URI - how do we manage types that mean the same, but have different ReqIF IDs?

Using Mapping Contexts

Mapping contexts is another mechanism provided to better manage type system. This mechanism does not rely on RDF URI as explained earlier, but simply relies on the name of the type. If the name matches (name of the type in your existing component, and name of type in the incoming ReqIF file), the import considers them to be the same. Other rules for match to occur (see earlier section, like underlying base type should be the same etc), will remain the same here as well.

An additional advantage of using Mapping context is, the same context can be used during export as well. This will ensure same pairing of name/id is used consistently for import and export.

Managing Enumerated attributes or data types

Enumerated attributes/data types contains a list of values/labels, making it more sophisticated compared to other data types. Thus, it is important to manage any changes to such lists in a controlled fashion. If you have such enumerated attributes, ensure there is an agreement with your partner about who controls the definition of this attribute. Casual modification to the data type, like removing and re-inserting a label to the data type definition can have undesired outcomes like data loss. For example, consider the following scenario:
You create an Enumerated attribute with 3 values - A, B and C.
You send a few artifacts that use this enumerated attribute to your partner as ReqIF file.
Your partner imports this file, starts updating the artifacts.
The partner inadvertently deletes value C from the data type definition. They then re-create it with same value 'C'.
They send back updated ReqIF file to you. When you import, it will re-create a new value for C. This can have undesired affect on the data.

When such situation occurs (deletion of value from data type definition), ensure both parties are aware. Determine next steps in consensus, and evaluate the approach you take to revert the change thoroughly. See below for couple of potential approaches in such a sitation:

As a partner, if a modification occurs to an attribute definition provided by your provider, it is best to create a stream from the previous baseline created just after import. Or, you may also consider re-importing the ReqIF file provided by your provider, choosing to update just this specific attribute (in Step 5 of import wizard). If you as provider is the owner of the attribute, then while importing updates it is best to use unselect option "Allow modification to existing to attribute definitions" (Step 3 of import wizard). This will ensure your data is protected against any such unknown situation. If your partner makes you aware of such a situation, you may choose to allow or disallow, as appropriate. The situation can also be set right by sending a new copy of your data, and asking your partner to import by choosing to update just the specific attribute (Step 5 of import wizard).

Note: These can be avoided even by using RDF URI for the data type definition (including labels of enumerated data type), or by using Mapping Context. But, right thing to do as data owner is, not let such problems to creep in to your repository by not allowing such modifications during an import.

Related topics: Deployment web home, Deployment web home

External links:

• IBM

Additional contributors: TWikiUser, TWikiUser