/
Configuring ReqIF Field mappings

Configuring ReqIF Field mappings

Overview

DATA CENTER ONLY

The ReqIF Field Mapping ensures that requirement data transfers accurately between systems. Since different systems use varying field names and structures, mapping aligns attributes (e.g., Priority, Status, Owner) so information is preserved and understood consistently. This prevents data loss, maintains context, and enables smooth collaboration across heterogeneous toolchains.

A mapping is required in order to Import and Export ReqIF in the easeRequirements Project Tree View.

To configure ReqIF Field mappings, select Requirements > ReqIF Field Mapping in the Jira main navigation bar. The user must have “ReqIF Field Mapping“ permissions to access the page. See Managing User Permissions.

ReqIF capabilities are available from easeRequirements Standard Datacenter version 5.4 or higher. Starting with this version, the dark feature key for the ReqIF feature will no longer function, and an easeRequirements Ultimate license is required to continue using it.

Add New Mapping

  • Go to Jira navigation > Requirements > ReqIF Field Mapping.

  • Select Add New Mapping

Mapping Name

Enter a name for the mapping.

Project

Select the projects where this mapping will be used.

  • If no projects are specified, the mapping is valid for all projects.

  • Some field values (e.g., Issue Type) can only be mapped when projects are selected.

  • Only mappings with a specified project can be used for import

Issue Specification Type

Indicate the specification type used for issue documents or issue lists in ReqIF.

Folder Specification Type

Indicate the specification type used for folders in ReqIF.

Specification Object Identifier

Indicate the unique key or ID that identifies each requirement in the ReqIF file (e.g., Issue Key).

Rich Text Rendering

Select a mode of evaluation for rich text in fields values.

  • Jira Mode: Uses the original Jira Wiki Markup exported from Jira.
    Select this option when both export and import are done within Jira to ensure a lossless transfer.

  • XHTML Compatibility: Wraps the XHTML content of ReqIF files from external tools inside Jira’s {html} macro. The raw XHTML is stored as-is and rendered through Jira’s Wiki Renderer.
    Select this option if you need roundtrips between Jira and external tools, so formatting is preserved across environments.

Note: To enable XHTML rendering in Jira:

  1. Go to Manage Apps in Jira.

  2. Find the Wiki Renderer Macros plugin.

  3. Enable the HTML category.

If the HTML category is not enabled, Jira will display the raw XHTML instead of rendering it.

  • XHTML Conversion: Parses the XHTML content of ReqIF files from external tools and converts it into Jira Wiki Markup, so it displays natively without the {html} macro.
    Select this option if your data will remain in Jira after import.

Relations

Map the link relations in Jira.

Folders

Map the fields for easeRequirements folder items in Jira. Recommended fields to include in the mapping:

  • Folder Name

  • Folder Description

  • Folder Attachment

General

Map the fields for issues in Jira. Recommended fields to include in the mapping:

  • Summary (the Jira headline of an issue)

  • Description

  • Issue Type (mandatory if Project is specified)

  • Status

For fields with a predefined list of values (e.g., Issue Type), you can map each enumeration to the corresponding value in your target system.

  • By default, the mapping action for enumerated fields is set to “Skip”, meaning the field will not be modified unless you specify a mapping.

  • Exception: Issue Type is mandatory and cannot be skipped.

  • The default mapping values are applied only during ReqIF import when evaluating the mappings.

The Issue Key field cannot be selected in the mapping, as it is always included by default in the ReqIF file export.

Issue Type Field Mapping

When the mapping specifies selected Project(s), Issue Type field mapping is enabled.

  • At the bottom left of the mapping dialog, you can “Add Mapping for <your_selected_issuetype>”, which allows custom field mapping for each issue type.

  • Any issue type left unmapped will follow the General mapping.

Add New Mapping from ReqIF file

To map the fields quickly, an existing ReqIF file can be used for automatic field mapping extraction.

  • Go to Jira navigation > Requirements > ReqIF Field Mapping.

  • Select Add new mapping File from ReqIF file at the Add New Mapping dropdown

  • Upload a file with a *.reqif or *.reqifz extension and wait for the mapping dialog to load the extracted details.

  • Review the mapping generated from the file. Modify or add details as needed.

  • Select Create.

Edit Mapping

  • Go to Jira navigation > Requirements > ReqIF Field Mapping.

  • In the desired ReqIF Field Mapping, select Edit.

  • Make the desired changes.

  • Select Update.

Delete Mapping

  • Go to Jira navigation > Requirements > ReqIF Field Mapping.

  • In the desired ReqIF Field Mapping, select Delete.

  • Confirm the deletion by selecting Delete.

ReqIF Import from External Systems

ReqIF files can be exported and imported across systems that support the ReqIF standard. However, only the following external requirements management systems have been verified with easeRequirements for Jira: IBM Doors Next, Jama, and Polarion.

When creating mappings for import of ReqIF files from external systems,

  • Select XHTML Conversion as the Rich Text Rendering configuration for importing rich text fields. External systems export rich text fields as XHTML, while Jira supports the wiki markup.

  • Ensure that you indicate an Issue Type for unmapped XML values during import or specify the XML value to map to the Issue Type field. This will ensure the requirements of the configured Issue Specification Type are imported.

ReqIF Import to a JEditor Field

JEditor (Rich Text Editor for Jira) is a Jira plugin that replaces the Wiki markup or native rich text supported by Jira when configured as Renderer for a selected text field.

When mapping a text field that does not use JEditor to a field that uses JEditor, select XHTML Compatibility as the Rich Text Rendering configuration for importing rich text fields.

Unsupported Fields for Mapping

  • FORM_TOKEN

  • COMMENT

  • THUMBNAIL

  • LAST_VIEWED

  • WORKRATIO

  • SUBTASKS

  • SECURITY

  • TIMETRACKING

  • RESOLUTION_DATE

  • WORKLOG

  • TIME_SPENT (Export Only)

  • AGGREGATE_TIME_SPENT

  • AGGREGATE_TIME_ESTIMATE

  • AGGREGATE_TIME_ORIGINAL_ESTIMATE

  • AGGREGATE_PROGRESS

  • PROGRESS

  • VOTES

  • VOTERS

  • WATCHES

  • WATCHERS

  • Custom fields with type Cascading Select List

Known Limitations

  • Issue Key: Always included in the export.

  • Project Creation: Projects cannot be created via ReqIF.

  • Pages: Confluence pages are not supported for ReqIF import or export.

  • Custom Field Search: Matching is based on field name. If multiple custom fields share the same name, issues may occur.

  • Multiple-Step Status Transitions: Not supported.

    • Example: For a workflow Open → In Progress → Done

      • If you export an issue in the Open state and re-import it as Done, the intermediate In Progress step is skipped.

      • The issue will remain in the Open state because multiple-step status transitions are not yet supported.

  • ReqIF File: The file must contain the SPECIFICATIONS and SPECIFICATIONS-SPEC-HIERARCHY objects for a successful import to easeRequirements for Jira.

References