Re-run an unsuccessful migration

When a customer's app migration fails or is incomplete, they don't have to create a new migration plan. The admin can re-run it from the cloud migration assistant.

The option to re-run a migration makes it easier to:

• Recover from intermittent issues, such as networking problems and busy resources.
• Unblock a migration after troubleshooting a failure and making adjustments.

To re-run a migration from the assistant, an admin must select the option within 12 days of the original attempt. After 12 days, the option is disabled.

Prerequisites

To support re-running an unsuccessful migration:

• Your server app must implement the atlassian-app-cloud-migration-listener (version 1.2.0 is recommended). When you implement the listener, the re-run feature is automatically enabled, though you can opt out by request.
• Your cloud app must have settled the original migration transfer with a status of FAILED or INCOMPLETE.

We recommend testing the feature with your app to determine whether to make adjustments to your implementation. Learn how to re-run an app migration on the Atlassian Support site.

Re-run the migration

In your server app

There are two methods your server app can implement to re-run a migration, outlined in this table:

The difference between the two methods is that:

• The onRerunAppMigration method has an additional parameter, originalTransferId, that lets you identify the migration to re-run.
• The onRerunAppMigration method uses the reRunTransferId parameter to represent the new migration attempt, rather than transferId.

By default, requests to re-run a migration invoke the onStartMigration method. When you implement the re-runnable listener, requests invoke onRerunAppMigration instead.

To implement the onRerunAppMigration method, expose a listener that implements the RerunnableDiscoverableListener interface, and use this signature:

1
2
void onRerunAppMigration(AppCloudMigrationGateway migrationGateway, String originalTransferId, String rerunTransferId, MigrationDetailsV1 rerunMigrationDetails)

In your cloud app

When an admin chooses to re-run an unsuccessful app migration, the platform notifies your cloud app in the same way it does for an initial migration, using webhooks and events.

Each time a migration is re-run, the platform generates a new transferId. To identify the original migration, events generated during a re-run have an additional property, originalTransferId.

The originalTransferId property is only included in events generated during a re-run, and the value of the property remains the same even after an attempt to re-run the migration fails.

Here's an example re-run event:

1
2
{
    "eventType": "listener-triggered",
    "cloudAppKey": "my-cloud-app-key",
    "transferId": "e4166374-2345-4c31-918c-83b14eb644f6",
    "originalTransferId": "d241e03d-b205-3c5d-a5eb-805a49df0f38",
    "migrationDetails": {
        "migrationId": "8e60dc59-78d6-484f-966a-a09ff8be8ed0",
        "migrationScopeId": "442bdd69-622d-323d-889d-383b41d8e536",
        "name": "Migration of my Confluence page",
        "createdAt": 1597211035,
        "jiraClientKey": "unknown",
        "confluenceClientKey": "03a7cb4b-23b6-3a79-8916-8824a053e786",
        "cloudUrl": "https://cloud-site-under-migration.atlassian.net"
    }
}

Opting out

If you determine your app won't support re-running migrations, you can request that we add it to the exclusion list so that the option is not available in the migration assistant.

To add your app to the exclusion list, raise an issue with Developer and Marketplace support.