ReqIF mapping file structure and contents

A YAML-based mapping file is required for ReqIF imports to Helix ALM. A mapping file associates ReqIF and Helix ALM types.

The best way to create a mapping file for the ReqIF file you are importing is to generate one from the ReqIF Import dialog box in Helix ALM. See Generating and editing ReqIF import mapping files. After you upload the ReqIF file, Helix ALM can generate a mapping file that automatically maps ReqIF types to the equivalent Helix ALM item or field. See Default mappings in ReqIF mapping files.

A property named HALMMapping is added to each ReqIF type in the mapping file. This property is used to associate ReqIF data types with Helix ALM types. Use the field code or label from the Import Mapping Values page in the HALMMapping properties to indicate which Helix ALM field to map to the corresponding ReqIF data.

Mapping files have the following structure and contents.

Note:  If a subsection of the HALMMapping property is left empty or if a section of the mapping file is deleted, that ReqIF type is considered unmapped.

Conventions

propertyName: [ objectType ]

Indicates an array of objectType objects that get assigned to propertyName.

propertyName: { objectType }

Indicates a single objectType is assigned to propertyName.

[ propertyName:... ]

Indicates that propertyName is an optional property that is only included in the mapping file if it has a value. For example, if the ReqIF file does not use the LONG-NAME attribute, the reqifName property is not included in the YAML file.

Top-level mapping file sections

The mapping file contains the following top-level sections.

mappingConfiguration: { mappingConfiguration }

documentInfo: { documentInfo }

objectTypes: [ ObjectType ]

linkTypes: [ LinkType ]

Represents an object that contains information and options specific to the import, such as a description of the import.

mappingConfiguration:

description {string}

Properties

Property Type Description
description string Description of the import that the mapping file is used for. When the mapping file is generated from Helix ALM, description is automatically set to one of the following values based on the value found first in the ReqIF file: ReqIF header TITLE, ReqIF header COMMENT, ReqIF(z) filename.

When a ReqIF file is imported, description from the mapping file is saved and displayed when subsequent imports with the same ReqIF types are performed. If the description is not available in the mapping file, Helix ALM saves the mapping file name for subsequent imports.

Example

mappingConfiguration:

description: Latest & Greatest

Represents information about the types of requirement documents and how the types should be imported.

documentInfo:

HALMMapping

documentTypeField:

createOrMapUnmappedMenuItems: false

menuItemMapping: [ array of dropdownFieldValues ]

reqifDocumentType: <ReqIF specification type name or description >

menuItemName: string

reqifID: string

documentTypes: [ DocumentTypes ]

Properties

Property Type Description
HALMMapping.documentTypeField string Helix ALM requirement document field to map to the ReqIF type to.

Each ReqIF Specification Type is always mapped to the Helix ALM document item type because Helix ALM only supports one document type. If you want to preserve Specification Type values from the ReqIF file during import, you can map Specification Type to a Helix ALM string or dropdown custom field added for documents. See How specific ReqIF data is mapped and imported. You can leave Specification Type unmapped if you do not need to preserve the values.
HALMMapping.createOrMapUnmappedMenuItems boolean Indicates if values for a dropdown field that match between the ReqIF file and Helix ALM are automatically mapped and if any missing field values are automatically added during import. Only used for the reqifType property for dropdown types. true automatically maps the values and adds any missing ones. false does not automatically map values or add missing ones. Default is false.
HALMMapping.menuItemMapping array of dropdownFieldValues Dropdown field values for the Helix ALM document field.
documentTypes array of DocumentTypes DocumentType objects. ReqIF Specification Type objects always map to Document in Helix ALM.

Example

documentInfo:
  HALMMapping:
    documentTypeField: 'Z_DOCUMENT_TYPE'
    createOrMapUnmappedMenuItems: true
    menuItemMapping:
      reqifName: Software Requirement Specification
      HALMMapping:
        menuItemName: 'SRS'
      reqifID: _220d344c-b4bb-46ae-b709-40f9c1ff950bAsEnumValue
      reqifName: Stakeholder requirements Module
      HALMMapping:
        menuItemName: ''
      reqifID: _bd934ed6-817b-4703-b7e1-9ad351ad70f3AsEnumValue
  documentTypes:
    reqifName: Stakeholder requirements Module
    fieldTypes:
      reqifName: ReqIF.Description
      reqifType: XHTML
      HALMMapping:
        fieldCode: Description
      reqifID: _bd934ed6-817b-4703-b7e1-9ad351ad70f3_DESCRIPTION-DOORS-MODULE
      ...
    reqifID: _bd934ed6-817b-4703-b7e1-9ad351ad70f3
    reqifName: Software Requirement Specification
    reqifDescription: Describes the set of requirements for a sprint, iteration, milestone, release etc.
    fieldTypes:
      reqifName: ReqIF.Name
      reqifType: XHTML
      HALMMapping:
        fieldCode: RDNAM
      reqifID: _092452d0-d1a3-48ce-8d7a-819ae050c4e5
      ...
    reqifID: _220d344c-b4bb-46ae-b709-40f9c1ff950b

Represents requirement types in the ReqIF file to map to Helix ALM requirement types.

objectTypes:

[ reqifName: { string } ]

[ reqifDescription: { string } ]

HALMMapping:

itemType: { string }

fieldTypes: [ fieldType ]

reqifID: { string }

Properties

Property Type Description
reqifName string ReqIF type name from the ReqIF file selected to import. Only in the mapping file if in the ReqIF file and not empty.
reqifDescription string ReqIF type description from the ReqIF file selected to import. Only in the mapping file if in the ReqIF file and not empty.
HALMMapping.itemType string Display name (label) for the Helix ALM requirement type. If no value is specified, the ReqIF SpecObjectType is considered unmapped and no SpecObjects of this type will be imported.
fieldTypes array of fieldTypes Array of data types in the ReqIF file that can be mapped to a Helix ALM field, or the property of a Helix ALM object.
reqifID string Unique identifier that associates changes to the HALMMapping property to the ReqIF type. Do not edit or delete this value. If you do, you may see errors in the validation or import results reports.

Example

objectTypes:
  reqifName: Stakeholder requirements
  HALMMapping:
    itemType: 'Stakeholder Requirement'
  fieldTypes:
    reqifName: ReqIF.ChapterName
    reqifType: XHTML
    HALMMapping:
      fieldCode: Summary
    reqifID: _38813ff8-582b-4e83-a082-86e0f9bfd2ef

Represents a link definition. You can map a ReqIF relation to a Helix ALM link definition and map specific attributes to the link properties.

linkType:

[ reqifName: { string } ]

[ reqifDescription: { string } ]

reqifID: { string }

HALMMapping:

linkDefinition: { string }

fieldTypes: [ fieldType ]

Properties

Property Type Description
reqifName string ReqIF type name from the ReqIF file selected to import. Only in the mapping file if in the ReqIF file and not empty.
reqifDescription string ReqIF type description from the ReqIF file selected to import. Only in the mapping file if in the ReqIF file and not empty.
reqifID string Unique identifier that associates changes to the HALMMapping property to the ReqIF type. Do not edit or delete this value. If you do, you may see errors in the validation or import results reports.
HALMMapping.linkDefinition string Display name for the Helix ALM link definition. If no value is specified, the ReqIF SpecRelationType is considered unmapped and no SpecRelations of this type will be imported.
fieldTypes array of fieldType Array of data types in the ReqIF file that can be mapped to a Helix ALM field, or the property of a Helix ALM object.

Example

linkTypes:
  reqifName: Constrains
  reqifDescription: Link type indicating that a requirement constrains another. For example, a non-functional requirement constrains a system requirement.
  HALMMapping:
    itemType: 'Constrains'
  fieldTypes: []
  reqifID: _41aef835-8d3b-45f8-8967-7df6c4300f3b

Subsections in the mapping file

The following subsections in the mapping file provide additional properties in the top-level sections.

Represents the type of data in the ReqIF file that can be mapped to a Helix ALM field, or the property of a Helix ALM object.

[ reqifName: { string } ]

[ reqifDescription: { string } ]

reqifID: { string }

HALMMapping:

fieldCode: { string }

[ createOrMapUnmappedMenuItems: { boolean: false } ]

reqifType: { string }

[ menuItemMapping: [ dropdownFieldValue ] ]

Properties

Property Type Description
reqifName string ReqIF type name from the ReqIF file selected to import. Only in the mapping file if in the ReqIF file and not empty.
reqifDescription string ReqIF type description from the ReqIF file selected to import. Only in the mapping file if in the ReqIF file and not empty.
reqifID string Unique identifier that associates changes to the HALMMapping property to the ReqIF type. Do not edit or delete this value. If you do, you may see errors in the validation or import results reports.
HALMMapping.fieldCode string Helix ALM field code or field display name to make the ReqIF data to. If no value is specified, the ReqIF AttributeDefinition is considered unmapped and no AttributeValues of this type will be imported.
HALMMapping.createOrMapUnmappedMenuItems boolean

Indicates if values for a dropdown field that match between the ReqIF file and Helix ALM are automatically mapped and if any missing field values are automatically added during import. Only used for the reqifType property for dropdown types. true automatically maps the values and adds any missing ones. false does not automatically map values or add missing ones. Default is false.

reqifType

 string ReqIF attribute types as defined in the ReqIF specification. For example, String, Boolean, Enumeration. See Valid field data type mappings and String conversions
dropdownFieldValue enum A single item in a dropdown field. Only used for the reqifType property for Dropdown types.

Valid field data type mappings

ReqIF data type Can map to Helix ALM field type:
Boolean Check box, String
Integer Integer, Decimal number, String
Real Decimal number, String
Date Date, DateTime, String
String String, Multi-line string, Hyperlink
Dropdown Dropdown, String
XHTML Multi-line string, String

String conversions

All ReqIF data types can be converted to a string if you want to import a value for display purposes only. Some data types are converted during import.

ReqIF data type Converts to:
Boolean true or false
Integer Exact value
Real Exact value
Date Date/time in the format <date> <time> with the date in importing user's locale. For example, 7/13/2020 10:37 AM
String Exact value
Dropdown Exact value
XHTML Plain text

Example - dropdown field value

      reqifName: Artifact Format
      reqifType: Dropdown
      HALMMapping:
        fieldCode: 'Z_ARTIFACT_SET_TYPE'
        createOrMapUnmappedMenuItems: true
      menuItemMapping:
        reqifName: Collection
        HALMMapping:
          menuItemName: ''
        reqifID: _b7aaa30d-fb19-49c5-93f1-2873c323f0c9
        reqifName: Document
        HALMMapping:
          menuItemName: 'Document'
        reqifID: _af1a03e8-aba6-441a-86d9-cbbdaa60af92
      reqifID: _6c8e6222-6990-40b8-9f13-4bc8f20c7ea2

Example - XHTML field

      reqifName: ReqIF.Description
      reqifType: XHTML
      HALMMapping:
        fieldCode: RDDSC
      reqifID: _bd934ed6-817b-4703-b7e1-9ad351ad70f3_DESCRIPTION-DOORS-MODULE

Represents an array of documentType objects. ReqIF Specification Type objects always map to Helix ALM Document.

[ reqifName: { string } ]

[ reqifDescription: { string } ]

fieldTypes: [ fieldType ]

reqifID: { string }

Properties

Property Type Description
reqifName string ReqIF type name from the ReqIF file selected to import. Only in the mapping file if in the ReqIF file and not empty.
reqifDescription string ReqIF type description from the ReqIF file selected to import. Only in the mapping file if in the ReqIF file and not empty.
fieldTypes array Type of data in the ReqIF file that can be mapped to a Helix ALM field, or the property of a Helix ALM object.
reqifID string Unique identifier that associates changes to the HALMMapping property to the ReqIF type. Do not edit or delete this value. If you do, you may see errors in the validation or import results reports.

Example

reqifName: Stakeholder requirements Module
fieldTypes:
  reqifName: ReqIF.Name
  reqifType: XHTML
  HALMMapping:
    fieldCode: RDNAM
  reqifID: _09d0d94f-3a8f-4748-881e-8200ce80c525
reqifID: _bd934ed6-817b-4703-b7e1-9ad351ad70f3

Represents a single item in a dropdown field.

[ reqifName: { string } ]

[ reqifDescription: { string } ]

reqifID: { string }

HALMMapping:

menuItemName: { string }

Properties

Property Type Description
reqifName string ReqIF type name from the ReqIF file selected to import. Only in the mapping file if in the ReqIF file and not empty.
reqifDescription string ReqIF type description from the ReqIF file selected to import. Only in the mapping file if in the ReqIF file and not empty.
reqifID string Unique identifier that associates changes to the HALMMapping property to the ReqIF type. Do not edit or delete this value. If you do, you may see errors in the validation or import results reports.
HALMMapping.menuItemName string If no value is specified and the containing AttributeDefinition has createOrMapUnmappedMenuItems:false, the ReqIF AttributeDefinition is considered unmapped and no AttributeDefinitionEnumValues for this value will be imported.

Example

reqifName: Artifact Format
reqifType: Dropdown
HALMMapping:
  fieldCode: 'Z_ARTIFACT_SET_TYPE'
  createOrMapUnmappedMenuItems: true
  menuItemMapping:
    reqifName: Collection
    HALMMapping:
      menuItemName: ''
    reqifID: _b7aaa30d-fb19-49c5-93f1-2873c323f0c9
reqifName: Document
HALMMapping:
  menuItemName: 'Document'
  reqifID: _af1a03e8-aba6-441a-86d9-cbbdaa60af92
reqifID: _6c8e6222-6990-40b8-9f13-4bc8f20c7ea2