• Article
  • Apr.12.2018

How to maintain custom fields in a Jira instance migration

  • Apr.12.2018
  • Reading time mins

You have two production Jira instances that need to be merged into one to optimize your company’s license costs. Your company has reorganized, or it has been acquired, and you have a number of Jira instances that duplicate tasks. There is a project in a test environment that is ready to be rolled into production.

These are just some examples where you need to migrate Jira projects. Yet merging instances and migrating data is, at best, an unwieldy and complex process that has to be done with minimal disruption to applications and end users. But even a simple aspect like maintaining custom fields during a Jira instance migration can be a major headache because it’s still largely a manual task.

Indeed, custom fields have an id that may change when migrated over to a new instance during a Jira migration. Adding to the complexity, custom field ids can be used in many different ways (groovy scripts, apps configurations, workflows, etc).

If you are dealing with a small data migration that only includes a few projects, you can use a Jira native project import to move data from one instance to another. It’s a whole other ballgame if you are dealing with larger Jira instances, where you need to move hundreds of custom fields, screens and permissions. To help you with this process, you can use a Jira app, like Project Configurator for Jira, to migrate the configuration.

Marketplace apps are a great option but they are not bullet-proof, particularly in the case of Project Configurator. For example, this app does not embed all the Jira Service Management project-specific settings (SLAs, reports, calendars, etc.) during the migration process and it also does not automatically create custom fields that are locked, such as Jira Software specific fields like Epic link. They must be created manually before the import. Project Configurator also can’t manage two fields with the same name and type. Finally, the backup file cannot easily be restored to a different Jira instance. In this case, you will have to adjust/update the ids manually beforehand during a Jira migration.

Despite the challenges, solutions are evolving to make these migrations less time-consuming. Here are some semi-scripted solutions to help you reduce the workload and minimize errors in a two-Jira instance migration scenario.

Migrating custom field ids

We need to update custom field ids (‘customfield_<id>’) wherever they are used in the backup files. The backup files could be native XML backups from Jira or any custom backup procedure available in some Jira apps, such as Elements Connect. To do this, you could use manual search/replace features from any text editor. But if you have 100 custom fields to rename, a manual process is not reliable.

Now let’s create a search and replace script that will ease the burden of this Jira migration task.

Step 1: Get all source custom field ids and transform the JSON output to CSV files

First, collect the list of all custom fields from the source and target instances into readable CSV files.

Apply the exact same thing for the the target Jira instance after the project import on the target instance.

Step 2: Import CSV files in a SQLite database in order to generate the sed script file

The aim here is to use SQL queries to read the CSV files in order to generate a set of “sed” command lines that will help us search and replace custom field ids.

Step 3: Use the replace script to update the backup file

In this case, our backup file is an Elements Connect configuration export (XML format). This configuration file contains custom field ids (dependencies between fields mostly).

Now we just have to run the “sed” script on the backup file, which will update all our custom field ids.

We can now re-import the backup file.

These basic scripted sequences help ensure a secure migration and can be reused for any type of global scale search and replace needed during the Jira migration merging process.

Getting migrations right is a complicated process. If you have other questions about how to migrate your Jira instances, get in touch with one of our Atlassian certified consultants below.


Contact Us

Related resources

View all resources