Generating and editing ReqIF import mapping files

ReqIF import only supports requirements and requirement documents. Other item types, such as test cases, are not supported.

ReqIF imports to Perforce ALM require a mapping file, which associates ReqIF types to ALM types. Mapping files are text-based files that use YAML, which is easy to edit and understand.

The first time you import a ReqIF file, you need to create a mapping file. The best way to create one is to generate it from the ReqIF Import dialog box in ALM. After you upload the ReqIF file, ALM can generate a file that automatically maps values in the ReqIF file to the equivalent ALM item or field. See Default mappings in ReqIF mapping files. You can then edit the file to create additional mappings to ensure your data is imported correctly. You use field codes or labels to indicate how to map ReqIF to ALM types.

A mapping file is specific to ReqIF types. You may be able to reuse a mapping file for subsequent imports with similar data, or you can use an existing one as a starting point and then modify it as needed.

Perforce can help you create mapping files for your ReqIF imports. Contact Perforce Sales for information.

1. After uploading a ReqIF file in the ReqIF Import dialog box, click Generate New File on the Upload Mapping File page.

The Download New Mapping File dialog box opens.

2. Enter a File name. The default filename is <ReqIF_Filename>_mapping.yaml.

3. Click Save.

The file opens using the associated application for your operating system.

4. Click View Field Codes on the Upload Mapping File page in the ReqIF Import dialog box.

The Perforce ALM ReqIF Import Mapping Values page opens. This page lists the ALM fields that you can map to ReqIF data in the mapping file. The page includes the following fields, field codes, and other information to use in mapping files. Field codes for custom fields are prepended with Z_ (e.g., Z_RQ_UNCERTAINTY).

Requirement document fields — Editable system fields, custom fields except calculated fields, user fields, Attachments field
Requirement types
Requirement fields — Editable system fields, custom fields except calculated fields, user fields, Attachments field
Link types — Parent/child link definitions that allow for requirements as both parents and children
Link properties
List fields
List values — Values for dropdown lists included on the mapping values page

Requirement and document fields have an Attachments field, which lets you map ReqIF XHTML fields with embedded files to ALM items as attachments. ReqIF XHTML fields may contain file types that are not supported in ALM multi-line text fields, such as PDFs and Microsoft Word documents. If you map a ReqIF XHTML field with non-image attachments to a ALM multi-line text field, the attachments are automatically attached to items during import.

5. Open the mapping file you downloaded in an advanced text editor that supports formatting of YAML files, such as Notepad ++ or Visual Studio Code.

Using an advanced editor provides syntax highlighting and the ability to expand and collapse sections in YAML files, which makes them easier to edit it. For example, you can search for 'HALMMapping' to highlight all areas where you need to map ReqIF data to ALM.

You may find it easier to edit the mapping file if you put the mapping file and import mapping values pages side-by-side on your screen.

6. Use the mapping values page to map ReqIF and ALM data.

When the mapping file is generated, ReqIF information is pulled from the ReqIF file selected for import and a property named HALMMapping is added to it in the mapping file. This property is used to associate ReqIF data types with ALM items. Use the field code or field label from the Import Mapping Values page in the HALMMapping sections to indicate which ALM types to map to the corresponding ReqIF types. See ReqIF mapping file structure and contents for more information about the mapping file.

7. Save the mapping file.

8. Upload the mapping file in the ReqIF Import dialog box. See Performing a ReqIF import.