Generating and editing ReqIF import mapping files

ReqIF imports to Helix ALM require a mapping file, which associates ReqIF types to Helix 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 Helix ALM. After you upload the ReqIF file, Helix ALM can generate a file that automatically maps values in the ReqIF file to the equivalent Helix 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 Helix 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.

Tip:  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 mapping file (.yaml) is generated and downloaded. The filename is <ReqIF_Filename>_mapping.yaml.

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

The Helix ALM ReqIF Import Mapping Values page opens. This page lists the Helix 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).

Note:  For most users, fields that you do not have security permissions to work with are not included in the list and you cannot import them. If you have permissions to administer fields, you will see all fields in the list, but cannot import fields you do not have permission to edit when adding or editing items.

  • 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

Note:  Requirement and document fields have an Attachments field, which lets you map ReqIF XHTML fields with embedded files to Helix ALM items as attachments. ReqIF XHTML fields may contain file types that are not supported in Helix 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 Helix ALM multi-line text field, the attachments are automatically attached to items during import.

3. 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 Helix ALM.

Tip:  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.

4. Use the mapping values page to map ReqIF and Helix 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 Helix ALM items. Use the field code or field label from the Import Mapping Values page in the HALMMapping sections to indicate which Helix ALM types to map to the corresponding ReqIF types. See ReqIF mapping file structure and contents for more information about the mapping file.

5. Save the mapping file.

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