Migrate app custom fields from Jira server to cloud

Introduction

This tutorial shows you how to migrate your app’s custom fields for Jira from server to cloud. You’ll learn how to add the Jira server to cloud mappings for app custom fields, and migrate those app custom fields to cloud.
This tutorial is aimed at developers who are experienced with the app migration platform and the Connect framework. If you are new to either of these, we recommend that you read our getting started guide first.

See a sample app

This section provides a sample app that you can use to verify your implementation. Clone the repository that contains the source code of the sample app from Bitbucket.

Getting started

There are three main steps to migrate app custom fields from Jira server to cloud:

Step 1: Server app provides the app custom field mappings to be migrated

Step 2: Cloud app gets the ID mappings for migrated app custom fields

Step 3: Add the values of migrated app custom fields

Detailed steps

Step 1: Server app provides the app custom field mappings to be migrated

As part of product data migration, the Jira Cloud Migration Assistant (JCMA) maps the custom fields of your server app (the ones that apps have defined as custom fields) to the Jira issue fields reference of your cloud app.

On your server app, add the interface JiraAppCloudMigrationListenerV1 on top of the class that implements DiscoverableListener to provide a map of app custom fields that need to be migrated to cloud.

Here's the method you'll have to implement:

1
2
public interface JiraAppCloudMigrationListenerV1 {

    Map<ServerAppCustomField, String> getSupportedCustomFieldMappings();
    
}

The following table provides descriptions of field types used in the above code.

The method above returns a Map of server app custom field to cloud app Jira issue field where,

Refer MyPluginComponentImpl.java in the sample example that implements the methods of JiraAppCloudMigrationListenerV1.

Step 2: Get the ID mappings for migrated app custom fields

After your cloud app gets the listener-triggered event notification, your apps can use the existing pagination API to fetch the app custom field mappings using namespace jira/classic:appCustomField.

ID mappings are in the following format:

1
2
{
  "serverAppCustomField": "cloudAppJiraIssueField"
}

The following table provides descriptions of field types used in the above code.

Step 3: Add the values of migrated app custom fields

Your cloud app gets details of app custom fields based on the custom field key, using the existing Jira Cloud platform REST API. This detail helps find your server app custom fields that are mapped to cloud app Jira issue fields. This is done by finding the entries matching cloudAppJiraIssueField IDs that you receive in Step 2. JCMA maps the server app custom fields to cloud app custom fields as follows:

Sample server app custom field configuration

1
2
<customfield-type name="Money Custom Field" i18n-name-key="money-custom-field.name" key="money-custom-field" class="com.example.plugins.tutorial.jira.customfields.MoneyCustomField">
    <description key="money-custom-field.description">The Money Custom Field Plugin</description>
    <resource name="view" type="velocity" location="/templates/customfields/money-custom-field/view.vm"/>
    <resource name="edit" type="velocity" location="/templates/customfields/money-custom-field/edit.vm"/>
</customfield-type>

Corresponding sample cloud app Jira issue field configuration

1
2
"jiraIssueFields": [
    {
        "key" : "money-custom-field",
        "name" : {
            "value" : "Money Custom Field"
        },
        "description" : {
            "value" : "The Money Custom Field App"
        },
        "type": "number"
    }
] 

Your cloud app custom fields appear on the same screens as the corresponding server app custom fields. Your app custom field is visible for migrated project issues as shown in the snapshot below.

After your app custom field reference is available in Jira cloud, you can use the newly introduced bulk API to populate the app custom field values.

Following the steps in this tutorial should allow you to migrate the app custom field and their values, linked to the same Jira entities from Jira server to cloud.