Last updated May 8, 2023

Rate this page:

Migration path readiness checklist

These are the steps you must perform to assess the readiness of your migration path. They will allow customers to successfully migrate their server app data to your cloud app.

Types of migration paths

To understand which steps to follow, first identify your app's migration path:

Fully automated

Step 1: Implement the 'Progress reporting' feature

  • Use the Status API to implement the progress reporting feature in your cloud app. This allows your cloud app to:

    • send a IN_PROGRESS status at regular intervals of every 10 - 15 minutes to inform the customer that the app migration is running and report on its progress
    • send a SUCCESS status when the app migration is complete
    • send a FAILED status if the app migration has encountered an error and can't be completed
  • The CMA user interface displays the progress of your app migration, on the Migration details screen, letting your customers know when your server app data has successfully migrated to their cloud site and is ready to use:

    Migration details screen

Step 2: Test your 'Progress reporting' implementation

  • Test the progress reporting in the CMA. If you haven't published your migration path yet, enable dev mode to do this.

Step 3: Publish a new version of your server app to Marketplace

  • After you've tested your migration path, build your app and publish it to Marketplace. At this stage, your migration path availability still won't be displayed to customers.

Step 4: Publish the availability of your migration path

Assess your apps screen

  • Provide the cloudMigrationAssistantCompatibility field value to the Marketplace Migrations API. This field value should indicate the first version of your server app with the automated migration path implementation, published in the previous step. As your app is fully automated, this is the only value you'll need to provide to the Marketplace Migrations API.

  • The CMA will ask your customers to upgrade their server app to this version before running the migration.

Partially automated

Step 1: Implement the 'Progress reporting' feature

  • Use the Status API to implement the progress reporting feature in your cloud app. This allows your cloud app to:

    • send a IN_PROGRESS status message at regular interval of every 10 - 15 minutes to inform the customer that the app migration is running and report on its progress
    • send an INCOMPLETE status message when the automated part of the app migration is complete
    • send FAILED if app migration encountered an error and can't be completed
  • The status messages sent using the Status API displays in the CMA user interface, on the Migration details screen, letting customers know when your server app data has successfully migrated to their cloud site and is ready to use.

Migration details screen

Step 2: Test your 'Progress reporting' implementation

  • Test the progress reporting in the CMA. If you haven't published your migration path yet, enable dev mode first to test the progress reporting implementation.

Step 3: Publish a new version of your server app to Marketplace

  • After you have tested your migration path, build your app and publish it to Marketplace. At this stage, your migration path availability still won't be displayed to customers.

Step 4: Publish the availability of your migration path

  • Use the Marketplace Migrations API to inform customers about the availability of your migration path in the Assess your apps screen of the CMA:

  • As your app is partially automated, you'll need to provide the following field values to the Marketplace Migrations API:

    • cloudMigrationAssistantCompatibility: This value should indicate the first version of your server app with the automated migration path implementation, published in the previous step.
    • migrationDocumentation: This value should link to a page that indicates the manual actions your customer needs to perform after the INCOMPLETE app migration status message displays in the CMA.

Included in the core migration of the Cloud Migration Assistant

  1. Use the Marketplace Migrations API to inform customers about the availability of your migration path in the Assess your apps screen of the CMA.

    Assess your apps screen

  2. Provide the cloudMigrationAssistantCompatibility field value to the Marketplace Migrations API. This field value should indicate the first version of your server app that can be migrated with the CMA. In some cases, it can be the first version of your app. As your app is fully automated, this is the only value you'll need to provide to the Marketplace Migrations API.

    The CMA will ask your customers to upgrade their server app to this version before running the migration.

Checking your migration path

If your app has an automated path, the app assessment screen should reflect this. Refer to understanding app assessment for more information.

It is important turn dev-mode off to test what your customers will experience.

If you notice onStartAppMigration() is not being run with dev-mode off this means that your app is on our install-only list. In this case, you will need to contact support to request removal from this list.

Being on the install-only list means that your app has not implemented a server listener and will always be marked as COMPLETE in app migration. If your app is on this list, it could be due to earlier communications with Atlassian.

Rate this page: