Requirements Interchange Format (ReqIF)

Starting with CodeBeamer 7.6.0, you can exchange data between CodeBeamer and other systems, e.g. IBM Rational DOORS, via Requirements Interchange Format (ReqIF).
Only ReqIF 1.0.1 and higher are supported, older RIF formats are not supported.

More Information about ReqIF can also be found in Wikipedia or the ProSTEP iViP ReqIF implementor forum.

ReqIF is an XML file based data exchange, with the following file extensions:

• .reqif for a single ReqIF XML file (instead of the usual .xml extension)
• .reqifz for ZIP archives containing ReqIF files and additional files, e.g. images (instead of the usual .zip extension)

Other than the name suggests, the Requirements Interchange Format is not restricted to exchanging requirements only.
ReqIF is a generic semantic data model, that allows to define arbitrary types of

• Items,
• Relations and
• Specifications.

Item types are similar to classes in object orientated programming, tables in a relational database model or trackers in CodeBeamer.
There can be any number of item types in a ReqIF file, each having a different set of attributes, e.g. User Story, Use Case, Requirement, Test Case, etc.

Relation types are similar to CodeBeamer association types. They define a specific type of relation between two items, e.g. "Depends On", "Derived From", etc.
Relation types can also define attributes for relations, e.g. the equivalent to "Suspected".

Specifications aggregate items into a tree hierarchy.
Specifications can include items of different types and the same item can be included in multiple specifications or in the same specification multiple times.
Specifications are more like tables of content or document outlines than real documents, because they cannot carry any extra information, except the tree hierarchy.
The best equivalent to a Specification in CodeBeamer is a tracker document view (although trackers can only contain items of the same type).


Example ReqIF schema:





ReqIF does not have a concept of reference fields or foreign keys, but CodeBeamer is able to convert reference fields into Relations upon export and bind Relation types to tracker reference fields upon import.

ReqIF does also not have a concept for exchanging a history of changes or comments about changes. A ReqIF file/archive only contains the current/head revision of the data to exchange.

Exchanging data via ReqIF

There are four use cases in a ReqIF exchange process:

1. Initial import of ReqIF data
2. Export data as ReqIF
3. Re-Export of previously imported (and possibly modified) data back to origin
4. Re-Import (modifications of) previously imported ReqIF data from the same origin

The scenario depicted above is only an example. CodeBeamer can be also at the begin or at the end of a ReqIF exchange chain.
There can be any number of iterations between two exchange partners.


Exchanging work/config items of the following type is not supported:

• Teams
• Work Log (Time recordings)
• Reviews
• Test Runs
• Source code Commits/Pushs
• Pull Requests

Import of ReqIF data

You can import ReqIF data

• into a new project
• or into an existing project (only CB-9.3 and newer).

Create a new project from ReqIF data

Creating a new project for the ReqIF data to import is preferable, if these are customer requirements, that should only be qualified, commented and referred to within CodeBeamer and should otherwise be kept unchanged. Write access to the imported data should be restricted and larger structural changes of the imported data model (tracker configuration) should be avoided, if continuous/iterative exchange of modifications/updates between the origin/customer and CodeBeamer is required. Adding new fields to imported trackers is no problem in that respect. But of cause, these are only recommendations.

To import new requirements via ReqIF:

• Choose New Project from the CodeBeamer Projects menu
• Choose Create a new project from a template and
• Attach the ReqIF file (*.reqif) or archive (*.reqifz) to import

On the Next screen, you can then enter the name of the new project, and you can also map the ReqIF data to import to target trackers in the new project. presented the object model found in the ReqIF file to import.

In CB-9.4 and newer, you can choose a name for the Source of the ReqIF data, or simply accept the default name: Origin:



In CB-9.4 and newer, you can also expand the Source information, to see the header of the ReqIF file(s) to import:




CodeBeamer 8.2 and newer, tries to group the ReqIF meta data by Specification:

• If a Specification Type is used exclusively by one Specification, the Specification Type will be shown as a child named Tracker of the Specification.
• If items of a specific Item Type are used exclusively by one Specification, then the Item Type will be shown as a child of the Specification, and it will be automatically associated with the same target tracker than the Specification.
  • If there is only one type of items in a Specification, then the name Items will be used for the Item Type
    e.g. Example 2: IBM Rational DOORS.
  • If there are multiple types of items in a Specification, each Item Type will be shown with it's own name, and you also have to specify a unique set of qualifiers, that identify items of this type in the target tracker
    e.g. Example 3: IBM Rational Requirements.

The following screenshots are only examples. They may look completely different, depending on the data model of the ReqIF file to import:


Example 1: SparxSystems Enterprise Architect




This example ReqIF file contains one Specification with an exclusive Specification Type (Tracker) and 2 Items.

Special about the Items is:

• There is no extra attribute (ReqIF.Name or ReqIF.ChapterName) for the item name/summary, so the LONG-NAME of the SpecObject (item) will be used as the item name/summary.
• There is an extra attribute for the item description, although it's name is not the proposed name (ReqIF.Text).
  • If there is also no attribute for the item description (e.g. Scalability Requirement), the DESC of the SpecObject (item) will be used as the item description.

There are also additional Item Types, that are not related to any Specification, e.g. User Story.
You could map User Story to the default User Stories tracker, but in our example we do not map/import them (--Ignore--), simply because there are no items of this type.

Ignoring empty Specifications, Item Types or Relations, as well as empty attributes, may not be appropriate, if you intend to edit the imported data, e.g.

• Add new tracker items
• Set values for (empty) fields
• Add new item associations

and then re-export the modified data.


Example 2: IBM Rational DOORS




In ReqIF files produced by IBM Rational DOORS, typically each Specification has it's own Type and only contains Items of a single type.

Because the association between Specification and Item Type is only defined indirectly via: Specification → SpecHierarchy → SpecObject → SpecObjectType, the Item Type of an empty Specification is undefined, and will be listed under the non-exclusive/shared Item Types.

DOORS requirements also have (along with lots of other attributes), each a

• ReqIF.ChapterName
• ReqIF.Name
• ReqIF.Text

But whether the attribute actually has a value, depends upon the type of the requirement:

• A DOORS Heading has a value for the ReqIF.ChapterName, but ReqIF.Name and ReqIF.Text are typically empty.
• Non-Heading types, e.g Requirement have a value for ReqIF.Text, but both, ReqIF.ChapterName and ReqIF.Name are typically empty.

If the mapping of ReqIF attribute to target field is ambiguous, e.g. both ReqIF.ChapterName and ReqIF.Name could be mapped to Summary, then you can use the number of items, where the field has a value, and the list of the first 10 field values, to find the best match.
In the example above, only 1 item has a ReqIF.Name, but 9 items have a ReqIF.ChapterName: So use ReqIF.ChapterName for Summary.


Example 3: IBM Rational Requirements




In ReqIF files produced by IBM Rational Requirements, Specifications typically contain items of different types, e.g. Heading, Information, Requirement etc.

Because all these items are mapped to the same target tracker, each item type must have a unique set of qualifiers, to identify items of this type in the tracker.
E.g. Heading items are those items in the target tracker, where Type == Folder

Specifications can also refer to (config) items, that are not part of the Specification itself, e.g. Actor.
These separate Item Types should typically be mapped to appropriate config item trackers, e.g. Actors.

In IBM Rational Requirements, all item types have a ReqIF.Name and a ReqIF.Text, that should be mapped to item Summary and Description.
The item type Heading also has a ReqIF.ChapterName, but the value of this attribute is the same than ReqIF.Name, so it can be safely ignored.

Target Tracker

For each Specification and standalone Item Type to import, you have to map this type of items to a target CodeBeamer Tracker.

You can either

• not import this Specification or items of this Item Type (-- Ignore --)
• choose a pre-defined tracker from the dropdown list
• or create a new custom tracker, via -- New Tracker -- at the bottom of the dropdown list.

Ignoring empty Specifications and Item Types may not be appropriate, if you intend to edit the imported data, e.g.

• Add new tracker items
• Set values for (empty) fields
• Add new item associations

and then re-export the modified data.

Depending on the type of the selected target tracker, additional mappings for the chosen target may be necessary.

Target Table

For trackers with embedded tables like Test Cases or Test Sets, there is an optional embedded Table selector.
This allows to map input items not to main items of the target Tracker, but to rows in the selected embedded Table of a main/parent target tracker item.

From another example ReqIF import:



Please note, that mapping items to an embedded tracker item Table (e.g. Test Cases -> Test Steps) will only work, if you have also a mapping for the main tracker items (e.g Test Cases) and there is a Specification, that establishes the parent/child relation between the main tracker items (e.g. Test Cases) and their respective sub items (e.g. Test Steps) in it's hierarchy tree.

Target Qualifiers

You can map multiple input Item Types to the same CodeBeamer target tracker (table). But in this case you must additionally specify a set of item qualifiers, that uniquely identify this subset of items in the target tracker (table).

In our Example 1, the input Item Types Functional Requirement, Performance Requirement, Scalability Requirement, Security Requirement, Maintainability Requirement, Usability Requirement and Legal Requirement can all be mapped to the pre-defined tracker System Requirement Specifications, and we can use the field Type as unique item qualifier:




For each input Item Type mapped to System Requirement Specifications and using Type as item qualifier, you must choose a different type value from the drop down list.




If there is no pre-defined value matching the Item Type, you can create a new value via New Value... at the bottom of the drop down list

If a single qualifier field/value pair is not sufficient, to uniquely identify item sub-sets, then you can add More qualifiers....
To remove chosen qualifiers, click on Remove behind the qualifier.
If you have chosen multiple qualifiers, you can re-order them by dragging.

Target Fields

For each mapped Specification, Item Type and Relation Type, the type attributes must be either mapped to target (tracker) fields or ignored.




Ignoring empty attributes, may not be appropriate, if you intend to edit the imported data, set the values of these fields and re-export the modified data.
In order to be able to map empty attributes, you must check including empty in the header.

You can only map input attributes to compatible target fields (according to the attribute type).
If there is no pre-defined field matching the input attribute, you can create a new field via -- New Field -- at the bottom of the drop down list.

If the mapping of ReqIF attribute to target field is ambiguous, e.g. both ReqIF.ChapterName and ReqIF.Name could be mapped to Summary, then you can use

• the number of items, where the field has a value (in the Count column),
• and the list of the first 10 field values (Click on the number in the Count column),

to find the best match.

• In the Example 2 above: only 1 item has a ReqIF.Name, but 9 items have a ReqIF.ChapterName:
  • So use ReqIF.ChapterName for Summary.
  • Ignore ReqIF.Name
• In the Example 3 above: The item type Heading has a ReqIF.ChapterName and a ReqIF.Name
  • but because the values of ReqIF.ChapterName and ReqIF.Name are the same
    • Use ReqIF.Name for Summary.
    • Ignore ReqIF.ChapterName

Only for Item Type:

• If there is no attribute (e.g. ReqIF.Name or ReqIF.ChapterName) associated with the item Summary, then the LONG-NAME of the SpecObject (item) will be used as the item name/summary.
  
• If there is no extra attribute (e.g. ReqIF.Text) associated with the item Description, then the DESC of the SpecObject (item) will be used as the item description.
  

In CB-7.9.1 and newer, you can also choose to Ignore all or Assign all attributes, whose name starts with a common prefix, e.g. "ReqIF.*" .

For choice attributes with discrete values, you must assign a target choice field, and each input attribute option must be assigned to a target choice field option.
If there is no pre-defined choice field option matching the input option, you can create a new option via -- New Option -- at the bottom of the value drop down list.

Import Status

In CB-9.5 and newer, codeBeamer automatically adds the pseudo attribute ReqIF.ImportStatus to all Items to import.

Via this pseudo attribute, you can map the ReqIF import status of an item to a target item field, e.g. Import Status:



You may also map the ReqIF.ImportStatus to the actual item Status:



so that the status of all items, that become updated via ReqIF, will be set to Draft.

Using ReqIF.ImportStatus is optional, by default this pseudo attribute will be ignored.

If you map the ReqIF.ImportStatus Deleted to a field value, then items deleted via ReqIF will only have their field value set to Deleted, but the items will not be moved into trash!

Remove/Restore items

In order for CodeBeamer, to recognize deleted objects or object deletions upon import:

• the object (type) must have the special ReqIF.ForeignDeleted attribute,
• and ReqIF.ForeignDeleted must be mapped to the Deleted flag/field of the target tracker.

Upon (re-)import:

• Objects will be removed (moved to trash), if their ReqIF.ForeignDeleted is true.
• Removed objects will be restored, if their ReqIF.ForeignDeleted is false.

Please note:
The simple absence of previously imported objects in a subsequent re-import does by default not remove the absent objects in CodeBeamer, to avoid unintended removals as in the following scenario:

1. ReqIF Data is imported from peer A
2. The imported data is forwarded to peer B
3. Updated ReqIF data from peer A is imported, that contains new objects
4. A response from peer B is imported
   • Since peer B does not know about any new objects, that were imported after the (last) forward to B, those objects are absent in the response

But when importing ReqIF data into an existing project (see below), CB-9.4 and newer, allows to optionally choose, whether items in mapped target trackers, that were imported via ReqIF before, but are absent in the current ReqIF file/archive to import, should be removed (moved to trash), or not:




Please consider the scenario depicted above, before you activate this option!

Relation type mapping

Input Relation Types must be mapped to CodeBeamer Association types and/or Reference fields.




You can only choose from the pre-defined Association types. Creating new Association types is not supported.

You can also bind an input Relation type to target Tracker Reference fields:



You can even bind a Relation type to more than one Reference field (in different types of trackers).
The actual target reference field will then be determined for each input Relation according to the actual type of the relation source/origin item.

A Relation Type can also have attributes, which must be either ignored or mapped to appropriate target Association fields.

There are 3 pre-defined Association fields:

• Comment (Text): Optional association comment
• Propagate Suspects (boolean): Whether this association supports suspected link propagation
• Suspected (boolean): Whether this association represents a suspected link

But you can create new custom Association fields by right-clicking on the target field dropdown list and choosing New Field... from the popup menu.
Please note, that you will not be able to see custom Association fields at the CodeBeamer GUI.

In order for CodeBeamer, to recognize deleted relations or relation deletions upon import:

• the relation (type) must have the special ReqIF.ForeignDeleted attribute,
• and ReqIF.ForeignDeleted must be mapped to the Deleted flag/field of the target association.

Upon (re-)import:

• Associations will be removed (moved to trash), if ReqIF.ForeignDeleted is true.
• Removed associations will be restored, if their ReqIF.ForeignDeleted is false.

Please note:
The simple absence of previously imported relations in a subsequent re-import does not remove the absent associations in CodeBeamer!

Import ReqIF data into an existing project

To import ReqIF data into an existing project:

• Go to the General tab of the Project Admin page
• and choose Import ReqIF ... from the Import menu.

In the upcoming File Upload dialog, choose the ReqIF file/archive to import:





In CB-9.2 and older, you can only import ReqIF data into an existing project,

• if the project was created from a ReqIF file/archive and the specified ReqIF file/archive is a Re-Export from the same source,
• or the project was exported as a ReqIF file/archive and the specified ReqIF file/archive is a return/response based on the original export.

In CB-9.3 and newer, you can always import ReqIF data into an existing project,

• even if the project was not created from ReqIF,
• even if the ReqIF file/archive contains data from a yet unknown data source.

The data schema of the selected ReqIF file/archive will be shown next, and you have to map input data to target trackers:





If this is an import from a yet unknown ReqIF data source (according to the Conversation- and RepositoryId in the ReqIF Header of the ReqIF file/archive), then you will have to provide a unique name for the new ReqIF data source:





If this is an import of new or updated ReqIF data from an already known data source (according to the Conversation- and RepositoryId in the ReqIF Header of the ReqIF file/archive), then you can also see information about the Last Import from that source and the import History. Also the configuration used for that last import will be automatically loaded and shown:






If there are multiple data sources for the same Conversation- and RepositoryId, then the one used for the Last Import will be shown and pre-loaded, but you can easily switch to another one.
You can also choose to store this import under a -- New Source -- name.

It is not necessary, to explicitly Load the ReqIF import configuration from a file, because codeBeamer will automatically load the last import configuration used for the selected Source.

It is not necessary, to explicitly Save the ReqIF import configuration to a file, because codeBeamer will automatically save it to a file called Source.jsonin the specific ReqIF Import folder in the Project's Documents, where Source is the name you assigned to the ReqIF data source.






If you are trying to import a ReqIF file/archive

• that was already imported before (according to the unique Identifier in the ReqIF Header), or
• that is older (according to the Creation Time in the ReqIF Header) than the last imported ReqIF file/archive from the selected Source

then, in CB-9.5 and newer, an appropriate warning dialog will be shown:





In general, you should not continue here, because you are most likely going to overwrite current project contents with obsolete data!

But if you have good reason (e.g. repeat the last import because you forgot to map some new specifications or attributes) and know what you are doing, then you may choose to ignore the warnings and continue.

But you have been warned!

And that will be visualized on the import configuration screen




and also later in the import history:

After the import has finished successfully, statistics about the imported, updated or deleted items per target tracker are shown.

For target trackers, that were created by the import, only the number of Imported items will be shown, because there can be hundreds or thousands of items, and these are all items currently in the tracker. You can see them by clicking on the tracker link.




For re-imports into trackers, that already existed before the import, you can see the items imported, updated or deleted, by clicking on the appropriate number:




E.g. Show the items, that were updated, including the changed field values:





Please note: CB-9.2 and older used an automatically created baseline, to show the differences between the project before and after the import.

CB-9.3 and newer will not longer create baselines upon ReqIF imports into an existing project!

ReqIF Import History

In CB-9.4 and newer, there is a history of all ReqIF imports into a project, grouped by source:

Project → Admin → Settings → General → Import → ReqIF sources …





Clicking on a specific source, shows the import history from that source:




To view the settings used for a specific import:

• Expand the import
• Click on Settings …

To view tracker items imported, updated or deleted by a specific import:

• Expand the import
• Click on the appropriate number of created, updated or deleted items in a specific tracker (row)

Export data as ReqIF

To export tracker items (Requirements, Use Cases, User Stories, Test Cases, etc.) from a project as a ReqIF archive:

• Go to the General tab of the Project Admin page
• and choose Export ⯈ As ReqIF archive … .

In CB-9.4 and older, Export As ReqIF archive opened a submenu, where you had to choose between

• Forward … and
• Back To ⯈ Source.

In CB-9.5 and newer, this submenu does not longer exist.

Instead you choose the export Destination in the upcoming dialog:

• If you had already exported the project as ReqIF before,
  then the destination of the last export will be automatically pre-selected.
  
• If the project has never been exported as ReqIF before, but there was already an import from a ReqIF source,
  then the source of the last import will be automatically selected as the destination for an export back to that source.
  
• If there has never been a ReqIF import/export for that project before,
  then you have to define a New Destination:
  
  
  
  
  
  
  • the Name of the destination must be unique within all ReqIF sources and destinations in the project.
  • the Type of the destination system is used to apply some destination specific logic upon export.
    • Only those destination types are listed, where CodeBeamer is able/required to apply some specific logic upon export.
      
    • If you do not know the type of the destination system, or the specific system is not listed, then Other is just fine.
      

Even is an existing Destination is preselected, you can always choose another existing destination or define a new one:

Choosing an existing destination will load the configuration used for the Last Export to that destination and also show date and time of that Last Export as well as the History … of all exports to this destination:



If there has not been an export yet, the reverse configuration for an export back to the ReqIF source will be shown, because

• A ReqIF source is also a destination for re-exports back to that source.
• A ReqIF destination is also a source for replies from that destination.

When creating a new destination, the default configuration according to the selected destination type will be shown.

If you have already previously exported data as ReqIF (from this or another project) and saved the export configuration to a file, you can also Load and re-use this configuration again, but it is not necessary to Save the configuration to a file manually, because CB-9.5 and newer, will automatically remember the export configurations for all ReqIF destinations.

Select project contents to export

Please consider, that you should only export data, that the intended Destination system should see and can handle.

First you have to select, from which trackers you want to export items:




For each selected tracker, you can restrict the export to items in a specific meta status or to items in a specific tracker view:




If none of the pre-defined meta status filters or tracker views is applicable, you can create a new filter view via -- New View -- from the dropdown list.


If you are exporting all tracker items (Any status), then the full tracker item hierarchy will be exported.

But if you are only exporting a sub-set of items, e.g. only Accepted requirements, then parent items (e.g. Folders) might not be exported, which will result in the requirement to be exported as top-level item.

To preserve the (folder) hierarchy upon export, you can check Preserve hierarchy (CB-9.5 and newer):




Preserve hierarchy will also export all ancestors of the tracker items to export, even if they do not match the selected filter!



You also have to select, which attributes/fields of the selected tracker items should be exported:




CodeBeamer proposes a default set of fields, based on the tracker type, but you can add More Fields... or remove selected fields.

There is also the option to Select all or Remove all fields via the appropriate actions in the Fields header.

If you selected an embedded table field for export, you must also select which of the table's columns should be exported.

If CodeBeamer should also export information about tracker items, that have been removed, then the field Deleted must be selected.
This will include removed tracker items in the export, that will have their ReqIF.ForeignDeleted attribute set to true.
By default, CodeBeamer will not export tracker items, that have been removed.

You can select multiple trackers for export.


If you want to export items from one tracker including related/referring items from another tracker, e.g.

• Customer Requirements plus the derived System Requirements
• System Requirements plus the verifying Test Cases

then you should use the References selector:




This way, CodeBeamer makes sure, that also the relations between the related/referring items are properly exported:




Additionally, you can choose to export specific associations of the selected items, e.g. the dependencies of the Test Cases:




Please note, that only associations to other tracker items can be exported, and only, if the target items are also in the same export.

Information about associations, that have been deleted, will only be exported, if Deleted is selected under Fields !
This will include removed associations in the export, that will have their ReqIF.ForeignDeleted attribute set to true.

ReqIF Export History

In CB-9.5 and newer, there is also a history of all ReqIF exports out of a project, grouped by destination:

Project → Admin → Settings → General → Export → ReqIF destinations …






Clicking on a specific destination, shows the export history to that destination:




To view the statistics and the settings used for a specific export:

• Expand the export
• Click on Settings …

The export statistics show the numbers of exported tracker items per tracker.
If also deleted tracker items were exported, their numbers are shown in a separate column.