Calculated or Scripted fields migration

On this page:

How to migrate calculated or scripted field?

Some custom fields may reference other custom fields by their native ID in a script contained in their configuration. Examples of such custom fields are "Calculated Number/Text/DateTime Field" part of Jira Misc Custom Fields by Innovalog and "Scripted Field" from Scriptrunner for Jira by Adaptavist. CMJ does move the configuration of the field as clear text, without parsing and replacing of any reference to another custom field (or another configuration element) by native ID.

This article explains how such configuration looks like, how it looks like after deployment, what steps need to be executed in order to fix the "scripted" configuration and how to avoid such situations.

Source configuration

We have two custom fields on Source as follow:

The configuration of "Calculated Number Field" is the following:

"Calculated Number Field" refers to "Number Field" by its native Id (customfield_10008). The script will remain unchanged when this custom field is deployed on Target. CMJ won't take into consideration the implicit reference between the fields. Once deployed the script will stop working correctly if the native IDs differ.

Target configuration (after deployment)

The two custom fields were not part of the configuration of the Target instance before the deployment. After a successful deployment using CMJ the two custom field are as follows:

The native IDs of the custom fields are different. That's because CMJ adds the new fields using Jira's internal API which assigns them the first possible non-occupied ID. Because of the fact, CMJ doesn't rely on native IDs when merging configuration but on other attributes (depends on the configuration element). In this case, CMJ will reuse them on a subsequent deployment even if the native IDs are different.

On another hand the configuration of the custom field remained untouched and still "Calculated Number Field" refers to "Number Field" by issue.get("customfield_10008");. This could be either missing or another field.

Manually change the references after deployment

In order to fix the configurations of the recently added/merged custom field, an edit of each one and replacing the references by ID with the new value is needed. CMJ does support "Persist deployed snapshot to current system native ID mappings". This option can be enabled from the General Settings page. Once enabled, every deployment will generate a mapping file. The last row of the audit log will contain a text similar to this: "Persisted snapshot to target native ID mappings in file ...\target\container\tomcat8x\cargo-jira-home\temp\deploymentSnapshotToTargetNativeIdMap_BotronSoft_8998591105496969158.json". This file contains a map for each configuration item with the ID from source and target. The rows that explain the custom fields are as follows:

"JiraCustomField": {
   "customfield_10008": "customfield_10016",
   "customfield_10009": "customfield_10017",
...

The key (first ID) is the id on the source, the value (second ID) is the value on target. This mapping let us know which is the new ID without having to look at the configuration or the DB.

The configuration of customfield_10017 (Calculated Number Field) should be changed to refer customfield_10016 instead of customfield_10008.

This can be done also automatically, by some script, that uses the JSON mapping and Jira's REST API.

Avoid referencing custom fields by native id

If the configurations of the calculated/scripted fields (and other configuration elements like Post Functions, Conditions, etc) references to other elements by their name instead of native ID will allow CMJ to migrate their configuration without having to alter the scripted part after each deployment. In the example given in this article the following line:

issue.get("customfield_10008"); 

could be replaced with:

issue.get("Number Field");

The name of the custom field will remain the same after deployment. If the same field is found on target it'll be reused. Having the native id for custom fields out of the scripts will enable the user of CMJ to move custom field configurations with confidence.