Report progress for Connect

When you implement the listener interface in your server app, your cloud app must use the app migration platform's Status REST API to:

• Report progress on your app migration so that admin users can monitor it in the Cloud Migration Assistant.
• Settle the transfer at the end of your migration so that admin users know it's finished.

Status updates are included in progress logs.

The Cloud Migration Assistant doesn't display status updates from your cloud app in real time. We recommend sending a progress update about once a minute so that customers know the migration isn’t stalled.

Use the Status REST API

Use the Send migration progress operation of the Status API to report progress and settle the transfer. Your status update should include the status of the transfer, percent progress, and an optional message.

When reporting progress or settling the transfer, follow these best practices:

• Retry on 5xx errors: Retry using an exponential backoff strategy rather than failing an app migration on a single error. By making your migration path resilient to 5xx errors, you can avoid disrupting a customer migration unnecessarily. For more on retry strategies, refer to Rate limiting.
• Don't decrement progress values: The app migration platform ignores status updates when the value of the percent parameter is lower than a previously reported value for the same transfer. When an update is ignored, it doesn't display in the Cloud Migration Assistant or in progress logs, and admin users may think the migration is stalled.

Report migration progress

To report migration progress, make a request to Send migration progress operation with these values:

• Status: IN_PROGRESS We recommend reporting progress about once a minute.
• Percent: An integer from 1 to 99 that represents the progress of the migration.
• Message [optional]: A string that communicates more info about the progress of the migration. Message can include links to sites or entities involved in the migration.

Example request

Here's an example request to report progress using curl. A successful request returns an HTTP 200 response. For details about composing messages, refer to the Status messages section.

1
2
curl -X POST 'https://your-site.atlassian.net/rest/atlassian-connect/1/migration/progress/{transferId}' \
--header 'Content-Type: application/json' \
--data-raw '{
                "status" : "IN_PROGRESS",
                "percent": 90,
                "message" : "App data migration is in the last stage. For more info, refer to http://documentation.example.com."
            }'

Settle the transfer

To settle the transfer at the end of migration, make a request to the Send migration progress operation with these values:

• Status: When settling the transfer, use one of these values:
  • SUCCESS: Use when the migration runs to completion and all entities are successfully migrated.
  • INCOMPLETE: Use when the migration finishes without failures but some entities aren't migrated or manual steps are required on the cloud site. When settling a canceled migration transfer, use this status to indicate the cloud app was able to finish cleaning up (see Transfer cancellation).
  • FAILED: Use when the migration doesn't run to completion because it encounters a problem. When settling a canceled migration transfer, use this status to indicate the cloud app failed to finish cleaning up.
• Percent: When the result of a migration is SUCCESS, set percent to 100. Otherwise, set the value to an integer between 1 and 99 that represents the proportion of entities migrated. If not provided (or set as zero), the previous value will be kept.
• Message [strongly recommended]: When the status of a migration is INCOMPLETE or FAILED, always include a message that provides next steps or the reason for failure.

Example request

Here's an example request to settle the transfer using curl. A successful request returns an HTTP 200 response. For details about composing messages, refer to the "Status messages" section.

1
2
curl -X POST 'https://your-site.atlassian.net/rest/atlassian-connect/1/migration/progress/{transferId}' \
--header 'Content-Type: application/json' \
--data-raw '{
                "status" : "SUCCESS",
                "percent": 100,
                "message" : "App data migration is complete. For next steps, refer to http://documentation.example.com/."
            }'

Status messages

Format

Status messages are included in a log CSV file and are rendered as plain text. Here's an example of a status message:

App data transfer is finished. To complete the migration, follow the instructions at http://documentation.example.com/.

Length

Status messages can't contain more than 300,000 characters. Messages that exceed this limit are truncated to 300,000 characters, and the following string is appended: <truncated, message too large>.

We recommend restricting the length of your status message to 250-300 characters so that it displays within the text area in the Cloud Migration Assistant.