RFC-43: Migrating App Custom Field Types

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

  • Publish : 25th March 2024
  • Discuss : 29th Match 2024
  • Resolve : 7th April 2024

Summary of Project:

Atlassian is looking at how we can reduce app migration friction for our customers. Sometimes it is not a great experience due to manual steps and stuck or slow app migrations. Below we will look at a solution for migrating app custom fields by type to improve the current state.


We’ve noticed low usage of our existing Connect Custom Field migration feature. We’re interested in understanding why this is and how we can better assist you in migrating your specific app custom fields n.b. Atlassian custom field types are automatically migrated by the Jira Cloud Migration Assistant (JCMA).

The current solution is limited to migrating a specific instance of a custom field in server by name and type and expects it to already exist in cloud i.e. no new custom field will be created during migration. This works for locked custom fields but not for unlocked custom fields where the custom field name could be defined by the customer.

Proposed Solution

Add getSupportedCustomFieldTypeMappings to retrieve custom field type mappings in JiraAppCloudMigrationListenerV1:

public interface JiraAppCloudMigrationListenerV1 {
  Map<ServerAppCustomField, String> getSupportedCustomFieldMappings();

  // New
  Map<String, String> getSupportedCustomFieldTypeMappings()

public class ServerAppCustomField
  String fieldName;
  String fieldTypeKey;

An example where we migrate all custom fields of type custom-field-server-type:

public Map<String, String> getSupportedCustomFieldTypeMappings() {
  return Map.of(

The custom field type in this context is the suffix of the type key after the : e.g. for com.vendor.app:calculated-dateonly-field you would use calculated-date-only-field corresponding to the key field when you define your custom field type.

You can continue to use getSupportedCustomFieldMappings with getSupportedCustomFieldTypeMappings we will migrate all custom fields that fit into either map.

We hope by making JiraAppCloudMigrationListenerV1 API more flexible to migrate more app data in JCMA we can reduce the manual effort to migrate your app.


  1. If we add the feature to migrate custom fields by type i.e. don’t specify the custom field name will this be useful?
  2. Are there any other gaps to consider?

Thank you for helping improve app migrations.


We are currently working to implement the Migration Assistant for our App. I did not expect that the current version did not create any CustomField, which would explain why it did not work when I tried it out some month ago (but I also tried to migrate to a forge custom field).

These are the reasons why we currently do not support the migration of Custom Field Types:

  • Our App is an existing Connect App and our requirements can’t be solved using the connect framework (With Forge it will become possible with a few drawbacks)
  • Connect On Forge currently does not support the migration assistant (as far as I’m aware)

We need the following to work before we can migrate CustomField Types to Cloud:

  • Forge On Connect works with the Migration Assistant
  • We can migrate Custom Field Types to Forge Custom Field Types

Thanks for letting us know your use case. We are actively working on those features.

Hello there,

We have an integration between our main app, Projectrak, and the JCMA for the last 2 years+. But, although we have our own custom field types in Data Center, we are not migrating them because we have another way to handle the same use case in Cloud and we are not using custom fields for that there.

Thinking about other kind of use cases that may be out there, I think it may be important to know both the Data Center and Cloud custom field ID in the mappings so other configuration may take advantage of that to work from the scratch when the migration is finished.

Hope this feedback help, let me know if I can help you further with that.

Have a nice day!

Thank you for your feedback some follow up questions:

  1. What feature are you using in Cloud to replace custom fields on server? Maybe that might partially explain why we see less usage of this feature.
  2. We offer the serverCustomFieldId:cloudCustomFieldId map under the jira/classic:appCustomField namespace Retrieve data mappings | App migration platform however we are thinking of deprecating this and combining it with jira/classic:customField namespace. Do you see any problems with this change?

Thank you for your participation in this RFC we will now resolve it.

  • What did we hear?
    • There is need for this feature but it is not needed by all our Marketplace Partners.
    • There are no concerns around the design.
  • What did we change?
    • The proposed API is not finalized and will change.
  • What is coming next?