Guidelines for Marketplace Partner migration documentation

As customers make the decision to move their Confluence or Jira core data from Data Center/server to cloud, it is important to give them information on migrating their app data. This page provides guidelines to Marketplace Partners who would like to do the following:

• create and publish app data migration documentation for customers
• surface a helpful URL to their app data migration documentation from within the Atlassian Cloud Migration Assistants

Atlassian does provide general recommendations to admins about what they should consider when migrating apps from server to cloud.

However, as each Marketplace Partner app is unique, we have made it possible for you to surface links in the Atlassian Cloud Migration Assistants to the URL of your choice, to point Confluence and Jira administrators to the migration documentation you've published.

How to surface a link to your documentation in the Cloud Migration Assistant

Use the Marketplace APIs to surface 3 kinds of migration documentation in the app assessment tool of the Jira/Confluence Cloud Migration Assistant:

• feature differences between your Data Center/server and cloud app
• migration documentation that includes migration instructions, and
• roadmap of your cloud app development

Things to consider before creating your migration documentation

• Clear migration documentation avoids customer confusion
  If they can't see the relevant documentation, your customers may assume you have no way to migrate their on-premise data to a cloud app. Provide clear information on how to migrate app data to remove any confusion about the availablity of a migration path to cloud.
  Provide migration path documentation for your app regardless of whether your customers decide to use the Cloud Migration Assistants for app data migration.

• Consider your customer's 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.
  Think about the use cases below while you create your migration documentation, to see which ones are applicable to your app.

  • The customer wants to automatically migrate app data using Atlassian’s Cloud Migration Assistant (CMA).
  • App data can be migrated with core data. For certain apps, a separate app data migration may not be required as the app data migrates along with the core Confluence/Jira product data. If your app enables such a migration, you must surface this capability to your customer in the Cloud Migration Assistant.
  • The customer partially migrates app data using the Cloud Migration Assistant.
  • The customer has no app data to be migrated.
  • The customer prefers to manually migrate their app data.

What to include in your migration documentation

• 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.
  Use the Marketplace API endpoint and featureDifferenceDocumentation field to surface links in the Cloud Migration Assistant to your documentation about feature differences between your Data Center/Server and Cloud app.

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

  See an example of a server/Data Center and cloud comparison for Jira/Confluence products in Atlassian's migration documentation.

• 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 Cloud Migration Assistant to your migration instruction documentation.

• Provide timelines and related announcements
  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:
  • a migration roadmap of your app's releases
    See an example of a timeline provided to Atlassian developers about changes to server/Data Center products.
    Use the Marketplace API endpoint and cloudVersionDevelopmentRoadmap field to surface links in the Cloud Migration Assistant to your documentation that provides a roadmap of your likely app development over the next period of time.

  • links to Atlassian roadmaps where available
    See an example of announcements in Atlassian migration documentation to customers about changes and updates in their migration plan.

• Compatibility
  Provide precise information about Jira/Confluence product versions and your app versions that are compatible and/or required to enable app data migration.

• General readiness
  Your customer will need to know how to prepare their product and app data for migration, and assess if they’re ready to migrate.

  Provide a pre-migration assessment checklist that your customers can refer. This allows customers to assess their general readiness to begin migration to cloud.

  Your pre-migration assessment checklist can include details about the following:

  • Dependencies
    Recommend that your customers check for dependencies between elements of their server data; like whether they’re migrating the correct projects/spaces to ensure that app data is not broken during/after migration.
  • Existence in cloud
    Where applicable, ensure that you document the entities that the customer must migrate as part of the core product migration for app data migration to be successful.
  • Duplication
    Recommend that your customers check for duplication between server and cloud, and that they clean up their server/cloud data, or accept behaviour like overwriting data or unsuccessful migration.
  • Differences
    Where applicable, if there are feature/other differences between the server and cloud version of your app, suggest ways in which your customer can alter their app data to ensure that migration is successful.

• Limitations and known issues
  Inform your customer about any factors that may limit you from offering them a complete app data migration path. This may include limits and/or known issues related to:

  • your app
  • Atlassian Cloud Migration Assistants. In such a scenario:
    • Link to jira.atlassian.com (JAC) tickets in your documentation that allow your customer to read more about Atlassian feature updates, watch JAC issues, or even submit a request themselves.

• Support options
  If you currently don't have customer support for your app, you should consider providing realistic options to support your customer if they experience problems or have enquiries related to the migration. The feedback from your customers can help you identify and prioritise any fixes and/or improvements to your app.