Last updated Dec 6, 2023

Manage your app info

The app migration platform allows you to manage the info customers use to assess your app in the Cloud Migration Assistant. You provide this info via the Marketplace Migrations REST API.

For more about how the migration assistant displays app info, check out How app assessment works.

To ensure that the migration assistant displays accurate info about your app, follow the guidance on this page for providing:

  • Migration path and compatibility info.
  • Links to migration documentation.

Migration path and compatibility info

The Can be migrated column of the assessment table lets customers know whether they can automatically migrate your app using the CMA.

Use the parameters described in this section to declare:

  • The type of migration path your app supports.
  • The versions of your server app that are compatible with your migration path.

Migration path type

To declare the type of migration path your app supports, use the Migrations REST API to provide a value for the migrationPath parameter.

The following table lists valid values. Customers can only use the CMA to automatically migrate your app when your migration path type is AUTOMATED or INSTALL_ONLY.

ValueUse when
MANUALYour app uses a manual process to migrate data to the cloud. As a result, customers can't use the CMA to migrate your app.
AUTOMATEDYour app implements a migration listener and supports automated migration via the CMA. (For details, check out Prepare your server app.)
INSTALL_ONLYYour app only requires access to core product data and doesn't need to migrate its own app data. As a result, customers can migrate your app automatically via the CMA.
DISCARDEDYour app doesn't have a migration, and there are no plans to implement one.
UNKNOWNA migration path isn't available for your app at this time.

Compatibility info

When you declare an AUTOMATED migration path, you must also declare which versions of your server app are compatible with it.

There are two parameters you can use when declaring server app compatibility info with the Migrations API:

ParameterDescriptionCMA support
cloudMigrationAssistantCompatibilityRangesAn array of compatibility ranges, each with its own start and end value. Ranges are inclusive, and null values are treated as wildcards.Supported starting with Jira Cloud Migration Assistant 1.9.7 and Confluence Cloud Migration Assistant 3.4.8.
cloudMigrationAssistantCompatibilityA string that declares the minimum server app version that is compatible with your migration path.Supported in all versions of the CMA.

The app migration platform gives precedence to cloudMigrationAssistantCompatibilityRanges. When you don't supply a value for the parameter, the platform uses the value of cloudMigrationAssistantCompatibility.

To ensure compatibility, we recommend using both parameters.

When you don't declare compatibility info for your app, customers can't use the CMA to migrate your app to cloud.

Here's an example value for the cloudMigrationAssistantCompatibilityRanges parameter that declares compatibility for all server app versions less than or equal to 2.0.0, versions 4.2.0 through 5.0.9, and all versions 8.3.0 and greater:

1
2
[
  {
    "start": null,
    "end": "2.0.0"
  },
  {
    "start": "4.2.0",
    "end": "5.0.9"
  },
  {
    "start": "8.3.0",
    "end": null
  }
]

In addition to migration path type and compatibility info, you can also use the Migrations API to provide links to your migration documentation so that customers can easily get info about your migration path.

The links displayed in the app assessment screen are outlined in this table:

ParameterLink toLink text in assessment screen
featureDifferenceDocumentationDocumentation that explains the differences between the server and cloud versions of your app.Exists in Cloud column: View differences link.
migrationDocumentationYour migration guide. (For more about creating migration documentation, check out Migration documentation guidelines.)Can be migrated column: Automated path and View path links.
migrationRoadmapTicketLinkA Jira ticket or other documentation customers can use to follow the progress of your migration path.Can be migrated column: Track request link.

To learn more about where and when these links surface in the assessment screen, check out How app assessment works.

Rate this page: