Last updated Sep 2, 2024

Re-run an unsuccessful migration

Available starting with these versions

  • Confluence Cloud Migration Assistant 3.4.14
  • Jira Cloud Migration Assistant 1.9.17

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

Requests to re-run a migration invoke the onStartMigration method, just like it was done for the original migration.

Implement the re-runnable listener (Connect only)

In case your app requires a different flow for re-runs, or perhaps you need to identify the original migration, you can implement the onRerunAppMigration method.

MethodInterfaceUse when
onRerunAppMigrationRerunnableDiscoverableListener

Your app requires access to the original transfer, such as when an app performs operations incrementally or performs operations that aren't idempotent.

Requires atlassian-app-cloud-migration-listener:1.2.0.

When you implement the re-runnable listener, the method onRerunAppMigration will take precendence over onStartMigration for re-runs.

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"
    }
}

Always settle the transfer

Even when re-running a migration, it's important to settle the transfer so that an admin can make another attempt if it's not successful. For guidance, see Progress reporting.

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.

Rate this page: