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