Last updated Nov 8, 2023

Migration documentation guidelines

As your customers decide to move their Confluence or Jira core data from Data Center/server to cloud, it's important to give them information about migrating their app data. We give them general recommendations about this in our Cloud migration guide. However, as each app is unique, it's helpful for each Marketplace Partner to provide migration documentation for their own apps, to help guide customers through the process.

You can surface a link to your documentation in the CMA. However, you should provide migration path documentation for your apps, regardless of whether your customers decide to use the CMA.

Why do I need to provide documentation?

If your customers can't see the documentation, they may assume you have no way to migrate their Data Center/server data to a cloud app. Providing clear information on how to do this will remove any confusion, and show them a migration path to cloud is available.

Surface your documentation in the Atlassian Cloud Migration Assistants (CMA)

The Marketplace APIs let you surface the following migration documentation in the app assessment tool of the Jira/Confluence CMA:

  • Feature differences between your Data Center/server and cloud app
  • Migration documentation that includes migration instructions

What to include in your migration documentation

Consider your customers' migration path options

There may be multiple migration path options available to customers, depending on how your app's migration path works, and the decision your customer makes to handle app data migration. While you create your migration documentation, think about the following use cases:

  • Your customer wants to automatically migrate app data using the CMA
  • Your customer partially migrates app data using the CMA
  • Your customer prefers to manually migrate their app data
  • Your customer has no app data to be migrated
  • Whether app data can be migrated with core data. For certain apps, the app data migrates along with the core Confluence/Jira product data, so doesn't need a separate app data migration. If this is possible with your app, surface this capability to your customer in the CMA.

Compare differences between Data Center/server and cloud features of your app

Moving to cloud is an important decision for your customers, and it involves change and uncertainty. Customers need to know if app features will remain the same or change in cloud.

You could provide a table in your documentation that gives your customers an easy comparison of features and functionalities between server and cloud. Here's an example.

Use the Marketplace API endpoint and featureDifferenceDocumentation field to surface links in the CMA to your documentation about feature differences between your Data Center/Server and Cloud app.

Provide clear migration steps

Document detailed, step-by-step, and easy-to-understand instructions on how to plan and perform a migration to cloud.

Use the Marketplace API endpoint and migrationDocumentation field to surface links in the CMA to your migration instruction documentation.

Clearly defined timelines about your app release plan and updates will help your customers prepare for app data migration. You can do this by giving your customers:

Provide a pre-migration assessment checklist

You could also provide a checklist so your customers can assess their readiness to begin migration to cloud.

It can include details about the following:

Next steps

For more information about your journey to cloud, see our journey to cloud hub in the Partner Portal. Request access to the Partner Portal.

Rate this page: