App migration transfers

A migration transfer is a representation of your app's migration. Over the course of the migration, your app primarily interacts with the transfer.

Transfer creation

When app migration starts (or when an unsuccessful migration is re-run), the platform creates a new transfer.

After the transfer is created, the platform triggers the migration listener on your server app, causing the onStartAppMigration() method to execute. At this point the transfer state is IN_PROGRESS.

Learn how to prepare your server app for migration

The platform also notifies your cloud app that migration has started by sending a listener-triggered event, which is published via webhook.

Learn how to prepare your cloud app for migration

During the transfer

During the migration, your cloud app is responsible for using the Status REST API to send progress updates so that admin users can monitor progress in the Cloud Migration Assistant.

Learn how to report migration progress

Settling the transfer

At the end of the migration, your cloud app must settle the transfer so that admin users know it's finished. The cloud app settles the transfer by using the Status REST API to set the transfer state to SUCCESS, FAILED or INCOMPLETE.

After you receive the first notification of your server app being triggered, you have 14 days to complete the migration. After the 14-day period, the platform sets the transfer state to TIMED_OUT and automatically settles the transfer.

Once a transfer is settled, data associated with the transfer is inaccessible. Subsequent REST API requests for that transfer ID return an HTTP 403 error.

Learn how to settle the transfer

Canceled transfers

When the admin user (or Atlassian support) cancels a transfer, the platform sets the transfer status to CANCELLATION_REQUESTED and notifies your cloud app by sending a transfer-cancellation-requested event via webhook.

If your cloud app doesn't acknowledge the cancellation by settling the transfer within 1 hour, the platform automatically settles the transfer. Once the transfer is settled, the state is set to CANCELED.

Learn more about transfer cancellation

Transfer state diagram

The following diagram illustrates the transfer lifecycle described in the previous sections: