Custom Fields mapping

Owned by Service Account
Last updated: Sept 28, 2018 by Elena Kolesnik

As you may have noticed, you can choose a mapping file that allows you to define your own mapping of exported custom fields into existent ones in the KIWI™ Import page.

What is this file for?

It provides the app with rules that must be followed when mapping the custom fields you've exported into existent custom fields on the import instance. The mapping file is a plain text file that can be edited with any text editor.

Manually creating a custom field mapping file

  1. Create a new text file (choose any name) with the extension .cfmap in the following path: JIRA_HOME_FOLDER/kepler/kiwi
  2. Fill in the file with the mappings that you need
  3. Choose a custom field from your exported workflow that you want to be mapped, and get the custom field ID
  4. Get the custom field ID from Jira import instance where the exported custom field will be mapped
  5. Add a new line corresponding to the mapping in your mapping file as customfield_eeeee=customfield_iiiii, where customfield_eeeee is the ID of the custom field from the exported file and customfield_iiiii is the ID of the custom field from Jira import instance
  6. Repeat the operation for all the custom fields you want to map

Example

customfield_10303 = customfield_11100
customfield_10305 = customfield_11101
customfield_10312 = customfield_11102
customfield_10313 = customfield_11103
customfield_10321 = customfield_11104

The first row from the example above explains: "Map the custom field 10303 from my exported workflow into the custom field 11100 from this Jira system". The first column of the mapping file has the custom field IDs that you want to map from the exported workflow, and the second column contains the IDs of the custom fields from Jira server where the import is executed.

Import generated mapping files

A successful import will generate two mapping files: the current and the next mapping file in the JIRA_HOME_FOLDER/kepler/kiwi folder.

The next mapping file is named using the following pattern: <imported_workflow_name>_next_<timestamp>.cfmap. It contains all the mappings resulted from the import according to your used .cfmap file and according to your screen selection, including the created custom fields.For an update custom field action, a new entry with the match/mapping [the source custom field -> the destination custom field] is added to the file. For a create custom field action, the entry will contain the source custom field id mapped on the newly created custom field id. This file can be used for a future import on the same server.

The current mapping file is named using the following pattern: <imported_workflow_name>_current_<timestamp>.cfmap. It contains all the mappings(according to your used .cfmap file and according to your screen selection) for the custom fields existing on the Import server. For an update custom field action, a new entry with the match/mapping [the source custom field -> the destination custom field] is added to the file. Nothing is added to this file for a create custom field action.This file is useful for executing the same import on another server that is identical as a structure to the Jira Import server where the file was generated.

For both mapping files names <timestamp> represents the date when the file is generated, in the yyyyMMddHHmm format.

To merge two generated CF Maps files, you need to use the corresponding tool.

Getting a custom field ID

  1. Go to Administration -> Custom Fields
  2. Choose your desired custom field and click the cog icon 
  3. Set your mouse over the Configure link. In the link displayed on the bottom of the page you'll see the URL containing the custom field ID you're looking for.

4. Another way to get a custom field ID is by querying your data base if you have configured an external one. 

Mapping error messages

If the mapping file has wrong mappings, error messages are displayed for the corresponding actions at Step 2: Actions.

The problems that might occur are:

  • The exported custom field doesn't have the same type with the custom field that will be mapped to. In this case a message error appears:

  • Two or more custom fields are mapped into the same custom field. 

Both cases generate errors that won't let you to continue with the import until you fix them.

If your exported custom field were mapped several times in the mapping file, the last mapping will be used without generating any error message.

Tips and Tricks

The mapping file can force KIWI™ to avoid the automatic matcher for custom fields and create a brand new Custom Field with all its dependencies from the export system. To do this map the custom field to the empty string (leave a blank after the equals sign) like in the example below:

Force create a custom field
customfield_10304 = customfield_10222
customfield_10309 = 
customfield_10316 = 
customfield_10327 = customfield_10406

This mapping file will force the custom fields 10309 and 10316 from the export file creation on Jira import instance.