Report progress

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.

This example screenshot shows how the Cloud Migration Assistant displays status updates:

Status updates are also included in progress logs.

The Cloud Migration Assistant doesn't display status updates from your cloud app in real time. It can take up to 90 seconds from the time your cloud app provides a status update for the message to display in the Cloud Migration Assistant.

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 {{link: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 but some entities are not migrated or when the migration is cancelled (for details, see Transfer cancellation).
  • FAILED: Use when the migration doesn't run to completion because it encounters a problem.
• 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.
• 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 {{link:http://documentation.example.com/}}."
            }'

Status messages

Format

A status message can combine text and links. To include a link, use this format:

{{link:<URL>}}

Here's an example of a status message that includes a link:

App data transfer is finished. To complete the migration, follow the instructions at {{link: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 (inclusive of links) to 250-300 characters so that it displays within the text area in the Cloud Migration Assistant.