ReqIF mapping file structure and contents

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

A YAML-based mapping file is required for ReqIF imports to Perforce ALM. A mapping file associates ReqIF and 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 ALM. See Generating and editing ReqIF import mapping files. After you upload the ReqIF file, ALM can generate a mapping file that automatically maps ReqIF types to the equivalent Perforce 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 ALM types. Use the field code or label from the Import Mapping Values page in the HALMMapping properties to indicate which ALM field to map to the corresponding ReqIF data.

Mapping files have the following structure and contents.

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.

On this page:

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 ]

mappingConfiguration

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 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, ALM saves the mapping file name for subsequent imports.

Example

mappingConfiguration:

description: Latest & Greatest

documentInfo

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	ALM requirement document field to map to the ReqIF type to. Each ReqIF Specification Type is always mapped to the ALM document item type because 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 an 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 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 ALM document field.
documentTypes	array of DocumentTypes	DocumentType objects. ReqIF Specification Type objects always map to Document in 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

objectTypes

Represents requirement types in the ReqIF file to map to 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 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 an ALM field, or the property of an 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

linkTypes

Represents a link definition. You can map a ReqIF relation to a 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 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 an ALM field, or the property of an 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.

fieldTypes

Represents the type of data in the ReqIF file that can be mapped to an ALM field, or the property of a 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	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 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 Perforce 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

documentTypes

Represents an array of documentType objects. ReqIF Specification Type objects always map to 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 an ALM field, or the property of an 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

dropdownFieldValue

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