Using ReqIF Import/Export

The Wikipedia definition of Requirements Interchange Format ("ReqIF") seems as good as any:

"ReqIF is an XML schema that is used to exchange requirements, along with its associated metadata, between software tools from different vendors. The requirements exchange format also defines a workflow for transmitting the status of requirements between partners. Although developed in the automotive industry, ReqIF is suitable for lossless exchange of requirements in any industry."

In Polarion, you can import ReqIF files into Polarion LiveDoc Documents, and export LiveDocs to a ReqIF file via the ReqIF Round-trip feature. This feature can be used to exchange requirements between different Polarion servers as well as between external tools and systems.

Supported Versions and File Types

Polarion currently supports ReqIF versions 1.0.1 and 1.1, and RIF versions 1.1a and 1.2. The following file types are supported:

  • .reqif or .xml: Plain ReqIF/RIF file without embedded objects.

  • .reqifz or .zip: Archive that contains one or multiple ReqIF or RIF file(s) with embedded objects, and the embedded objects.

Note

Image Magick must be installed and configured to see the thumbnails of imported OLE Objects. See the Include thumbnails for OLE DOORS and ReqIF imports section for details.

TIP

Embedded image or attachment previews are preserved during the ReqIF Import/Export process.

Importing ReqIF Files

You can import ReqIF/RIF files singly, or several at once. ReqIF/RIF files may contain one or multiple Specifications. If multiple, you map them to different Polarion Documents. When importing a ReqIF file for the first time, a Polarion Document is created for each Specification in the ReqIF file. Subsequent imports of the same ReqIF file into the same space automatically map to the respective Polarion Document, the content of which is updated and synchronized with the content of the ReqIF file.

To import a ReqIF or RIF file into Polarion:

  1. Open the project that should host the imported requirements. Be sure you have the necessary permissions to create new Documents.

  2. In Navigation, expand Documents and Pages and expand the node of the space into which you want to import, (or you can create a new space), and select Index.

  3. In the Index page toolbar, click (Create New).

  4. In the dialog's Import section , click the link labeled ReqIF Document.

  5. In the next dialog, select the interchange file stored on a local or network drive and click Start.

  6. Wait for the initial import to finish. If the file is large the process can take a while.

  7. When the Import Document page appears. Select the specification(s) you want to import and map all selected Specifications in the ReqIF file to a space (the current space is used by default), and a LiveDoc Document. See figure below.

    If you import an updated version of a ReqIF document you previously imported, the target LiveDoc value will be pre-filled and can't be changed.

  8. When your Specification to Document mapping is complete, click the Next button.

Figure 15.16. ReqIF Import: Document Mapping

ReqIF Import: Document Mapping

The first part of the ReqIF import operation is mapping Specification(s) to Polarion Document(s)

Mapping Attributes, Types and Fields

Once the initial import phase is complete, the Import Document page is updated and presents options for mapping Document types attributes to Work Item types and fields, and Delete Options for each Specification.

Figure 15.17. ReqIF Import: Attribute Mapping

ReqIF Import: Attribute Mapping

The second part of the ReqIF import operation is mapping Specification attributes to Work Item fields and types

The Import Document page contains a separate section for each Document to be created by the importer. Each section is demarcated by a header, which displays the Document name. The first subsection is delete options. These control what happens if an object has been removed from the ReqIF Specification since the last Polarion import. You can ignore this section when importing a Specification for the first time.

A ReqIF Specification may contain different object types. For each of these object types you must configure the Polarion Work Item type to be created. Because some requirements tools don't support different types but implicitly define object without text as headings (e.g. IBM DOORS), the "virtual" types "Heading" and "Requirement" will be shown if there is only one object type in the Specification.

Below the Object Type is a list of all attributes defined for the specific ReqIF type. You should map each of those attributes to an attribute of the selected Polarion Work Item type. Each attribute has a control that exposes value mappings (see figure above). You can define value mappings for all kinds of attributes, but it is mandatory to map all available values of an enumeration attribute. (You will not be able to start import until this is done.)

When all mapping is complete, click the Start Import to execute the import of the configured Specifications. when the import process is finished, an overview page with a table listing, and providing access to the created Polarion Documents opens.

Exporting Documents to ReqIF

You can export Polarion Documents to ReqIF files of any supported type. You can export a single Document or multiple Documents to a single ReqIF file. Each exported Document corresponds to a Specification in the exported ReqIF file. As with import, some configuration and mapping is necessary during the export process.

There are two ways to launch export to ReqIF:

  1. From the Index page of any space. Export from here will always be to a new ReqIF file - you cannot export to update an existing, previously imported ReqIF file this way. You can export multiple Documents to a single ReqIF file.

  2. From the Actions menu of a Document in the Document Editor. You can only export the open Document. However, you will have several options for the ReqIF output:

    • Update existing ReqIF specification: changes will be written into an existing specification in an existing ReqIF file.

    • Add as new specification to an existing ReqIF file: a new specification will be created in an existing ReqIF file.

      DOORS Note

      DOORS (and some other requirements tools) have the limitation that links can only exist among items in the same ReqIF file. Thus, if you want to import links created in Polarion to such a tool, you should first export the LiveDoc that contains the Work Items that are target of the links and then export the LiveDoc that contains the linking items to the generated ReqIF file.

    • Create new ReqIF file: export to a new ReqIF or RIF 1.2 file.

To export from a space's Index page:

  1. Navigate to the Index page of the space that contains the Polarion Document(s) you want to export.

  2. In the table, check the row(s) of the Document(s) to be exported.

  3. On the page toolbar, click the Export button and choose Export to ReqIF File.

  4. Map types and attributes as described in Mapping Types and Attributes, below.

  5. Click the Start Export button to launch the exporter process.

To export a Document in the Document Editor:

  1. In Navigation, expand Documents and Pages, browse to the Document you want to export, and double-click to open it. If there are many Documents, you can use the search field at the top of the Navigation panel.

  2. With the Document open in the Document Editor, click the Actions Menu button and choose ReqIF Round-trip & Export Document.

  3. Select the desired option for the ReqIF file output and click Start.

  4. Map types and attributes as described in Mapping Types and Attributes, below.

  5. Click the Start Export button to launch the exporter process.

Mapping Types and Attributes

When presented with the Export Polarion LiveDoc Document page, you must configure export options and mappings in order to complete the export process. The first section for each Specification presents several options:

  • Export new Work Items and update document structure means that new Work Items will be added to the ReqIF file, and Work Items will be moved within the file (change parent, change position). Usually you do that only if you "own" the reqIF file; that is, the file was initially exported by you.

  • Update ReqIF metadata means that attributes and available values for enumeration attributes will be added according to the mapping configuration. You definitely should do that only if you own the ReqIF file.

  • DOORS compatibility mode means there will be some additional processing to make the ReqIF file compatible with DOORS. You should use this option only if the exported ReqIF file will be directly imported into DOORS without using any additional tools (e.g. Requisis Rex, Atego Excerpt or Agosense). Currently this setting:

    1. Instructs Polarion to wrap images as OLE objects (increasing the size by orders of magnitude)

    2. For RIF: Add a special DOORS-dependent section to the exported file.

    3. For RIF: Control naming of default attributes (Object Heading + Object Text vs. Title + Description)

Mapping basically is the same as for import except that some default attributes will be added automatically if you are creating a new ReqIF file. For ReqIF, the defaults are added according to the suggestion of the ReqIF Implementers Forum. For RIF, the defaults are Title and Description or Object Heading and Object Text when running DOORS Compatibility mode.

When Update Metadata is enabled, you can add any supported Polarion attribute to the ReqIF file. The configuration of the ReqIF fill will be adjusted accordingly.

When all mapping is complete, starting export will trigger download of the generated ReqIF file. Give this some time, as some browsers may not show generation and download progress. You will see an message when the process is finished, and any errors during export will be reported.

TIP

An alternative path to reach the mapping and export options page is via space Index page > Export > Export to ReqIF File. That option will export all selected Polarion Documents into a new ReqIF file, and the configuration page will include an interface to configure the file name and type.

Reusing Mapping Configurations

When importing or exporting from/to ReqIF, you can save the mappings you define as templates. You can then reuse the mappings for subsequent imports/exports. Each of the section headers on the mappings page has a drop-down actions menu, which provides actions for saving the current mapping as a template, or loading a previously saved template. Mapping configuration templates can be created in both global and project scopes.

Figure 15.18. ReqIF Mapping Templates

ReqIF Mapping Templates

Reusing ReqIF import/export mapping configurations