Last updated Nov 22, 2022

Rate this page:

Connect data residency migrations is currently available as an Early Access Program (“EAP”). There is currently no customer experience associated with this EAP.

Please note, as an EAP feature:

  • It is not advised to deploy solution into production
  • There will not be any deprecation notice / period for breaking changes that may get introduced

By participating in this Early Access Program (“EAP”), and adding the data residency migration hook into your app descriptor, you acknowledge the Atlassian Privacy Policy and that access to any of our APIs, SDKs or other Atlassian developer assets is subject to the Atlassian Developer Terms.

Supporting data residency migrations

To support data residency migrations, you must:

  • support data residency by specifying the relevant locations in your descriptor
  • support the data residency migration hook specified in the lifecycle field in the descriptor and the subsequent hooks part of the lifecycle of a migration

A new lifecycle can be specified as follows:

1
2
{
  ...
  "lifecycle": {
    "installed": "/installed",
    "dare-migration": "/my-cool-migration-hook"
  },
  ...
}

This makes your app eligible to receive the following compulsory hooks:

  • /schedule
  • /start
  • /status
  • /commit
  • /rollback

We will append this hook onto your declared dare-migration lifecycle in the descriptor, for example: /my-cool-migration-hook/schedule.

These new lifecycles don't come from the product. Instead, they come from a new service. This is to facilitate the migration process while the product is down.

The service will continue to communicate with apps by signing the JWT token with the sharedSecret. You should continue to verify the request as described on Understanding JWT for Connect apps.

Data residency migrations lifecycle

EndpointDescriptionRequest payloadResponse
POST /scheduleWhen a product admin schedules a migration, the service will notify eligible apps via this endpoint to schedule a migration. Use this to do any preparatory work prior to the migration.
1
2
{
“startTime”: “2021-12-26T00:00:00.000Z”, 
“endTime”: “2021-12-27T00:00:00.000Z”, 
“location”: “EU”
}
If your app responds with a non-2xx, the app migration will be marked as a failure and won't receive further hooks (besides the rollback hook) for the same migration.
POST /startOnce the site is taken offline, the service will notify eligible apps that have successfully responded to the schedule hook via this endpoint to begin the migration.
1
2
{
 “startTime”: “2021-12-26T00:00:00.000Z”,
 “endTime”: “2021-12-27T00:00:00.000Z”,
 “location”: “EU”
}
If your app responds with a non-2xx, the app migration will be marked as a failure and won't receive further hooks (besides the rollback hook) for the same migration.
GET /statusThis endpoint will be called by the service to fetch the status of an ongoing migration. The statuses the service will specifically be looking for are:
  • failed
  • ready-to-commit
For failed, there will be a series of errorResponseCodes you may wish to report back with to provide more insight into the failure reason. This is described further under the Error Codes heading.

A ready-to-commit will mean that the app has finished its migration and is awaiting a /commit lifecycle upon completion.

Beyond that, you can use any statuses you wish. However, upon completion, any status that isn't ready-to-commit will receive a rollback hook.

Once the migration starts, we'll also be regularly polling the apps for their status. If all apps have either failed or are ready-to-commit, then the migration can end, and the site can be brought back online.

{}Failed status - service will update the app migration’s status to failed:
1
2
{
“status”: “failed”,
“errorResponseCode”: “E0004”
}
App is awaiting a /commit hook. The service, once the migration ends, will send a /commit hook:
1
2

{
“status”: “ready-to-commit”
}

POST /commitOnce the site is brought back online, the service will query the status of each app that has started the migration.

The service will ask apps to commit via this endpoint if they’ve reported that they're ready-to-commit.

Specifically, this is to commit the copied data to the new region.

{}If your app responds with a non-2xx, the app migration will be marked as a failure and will receive a rollback hook.

POST /rollbackOnce the site is brought back online, the service will query the status of each app which has started the migration.

The service will ask apps to roll back via this endpoint if they’ve reported that they aren't ready-to-commit.

Specifically, this is intended to roll back the non-destructive copy operation to the new region.

{}Not applicable.

Error Codes

To help diagnose problems with migrations, we’re adding a set of standardised error codes that your app can report back to us with when you’re reporting back with a non-2xx to the hooks or the status retrieval.

Error CodeReason
E0001The migration was not scheduled.
E0002The app does not support the target region (versioning issues).
E0003The app does not support migrations (versioning issues).
E0004The app has too many concurrent migrations.
E9999Generic failure code.

Considerations

There are a few considerations you should think about when deciding to implement data residency migrations for Connect apps.

  • App migrations will be performed while the site is down
  • App migrations will be performed at a product-level - customers cannot choose individual apps to migrate
  • Eligible apps will have at most 24h to migrate data
  • The eligibility of an app to be migrated will be decided at the scheduling time

Lifecycle of a Connect data residency migration

  1. The product admin will schedule a migration of eligible apps via AdminHub.
  2. Our service will notify eligible apps via the /schedule endpoint.
  3. The site will be unavailable at the scheduled time.
  4. Our service will notify apps that successfully responded to the /schedule endpoint to begin the migration via the /start endpoint.
  5. The site will be brought live at the specified end time or once all app migrations are complete.
    • If the migration window is over, our service will query the apps that successfully started the migration for their status via /status.
      • If the status is ready-to-commit, our service will send a /commit hook.
      • If the status is anything else, our service will send a /rollback hook.
    • If all app migrations have completed (i.e. responded failed or ready-to-commit when polled or reported back early):
      • If the status is ready-to-commit, our service will send a /commit hook.
      • If the status is anything else, our service will send a /rollback hook.
  6. Connect will then update the installed region of the apps that have finished the migration process in the specified window.

Testing Connect data residency migrations

Currently, there is no automated way to test connect app data residency migrations. However, you can manually test migrations by raising a support request.

The requirements for a manual migration are:

  • an app that supports data residency and migrations
  • the app must be installed on the site you want to trigger a migration for
  • the user making the request must be at least a product admin of the site or have the consent of someone who is

The manual migration testing process differs from the actual migration flow in the following ways:

  • the product isn't brought offline - migrations are done live during testing
  • you can specify any migration window, with a minimum duration of 1 hour
  • the product doesn't have to be pinned
  • the migration can go to any location, regardless of which one the product is pinned to

To perform a manual migration test:

  1. Visit the developer support page.
  2. Click App Migration.
  3. Click Request for App Data Residency Migration Test.
  4. Fill out the provided template where:
    • App key refers to the addonKey specified in your descriptor.
    • Premium Cloud URL refers to the host name of the site you'are trying to trigger a manual migration test for.
    • Product refers to either Jira or Confluence.
    • Start time refers to when the migration will begin. Uses UTC+0 time.
    • End time refers to when the migration will end. If not specified, this will be set to 24 hours after the provided start time. Uses UTC+0 time.
  5. If you are not an admin of the site, acquire consent from an admin of the site on the ticket.

This process is intended for testing purposes only and should NOT be utilised to perform migrations on your customer sites.

Rate this page: