App Data Migration Developer

App Data Migration Developer

Last updatedOct 19, 2020

Rate this page:

Getting started

App data migration begins after the Jira or Confluence admin has migrated core product data to the cloud site. This page explains how Jira and Confluence app developers can prepare their data from server to cloud.

There are three main steps when migrating your app data:

  • Pre-migration: Prepare your server and cloud apps for data migration.
  • Migration: Migrate your data with the App migration platform.
  • Post-migration: Configure your cloud app for migration updates.

Features for the above steps are available now.

We have created sample applications that demonstrate how to use the App migration platform. The sections that follow explain the pre-migration and migration setup for your server and cloud app using examples from sample applications.

Pre-migration

  • On your cloud app: Register webhooks to receive notifications on a specific cloud site
  • On your server app: Enable your server app for migration

The sections that follow explain the pre-migration setup you will need to create on your server app and cloud site.

Pre-migration setup on your cloud app

This section explains how to setup the communication between your cloud app and the App migration platform.

Register webhooks to receive notifications on a specific cloud site

The webhook that you register is a callback URL to which the App migration platform sends information about migration events. A sample webhook URL looks like this: https://example.com/my-migration-listener. Ensure that the webhook is served over https.

Use the Notification API to register webhooks with the App migration platform. Registering webhooks allows the platform to notify you when specific events take place on your server app.

About the Notification API

The endpoints of the Notification API allow you to do the following:

  • Register webhooks
  • Get registered webhooks
  • Delete registered webhooks

The sections that follow explain all the above endpoints, and provide examples on how to use them.

Register webhooks

Use the endpoint below to register your webhooks. The App migration platform notifies this endpoint when migrations are ready or available on the server app.

MethodEndpoint
PUTmigration/webhook

The above endpoint must contain a non-empty set of JSON array with an absolute URL/s.

See an example

This section shows you an example of a request and response to register a webhook.

  • Sample request

    1
    2
    3
    curl -X PUT 'https://your-cloud-site/rest/atlassian-connect/1/migration/webhook' \
    --header 'Content-Type: application/json' \
    --data-raw '{"endpoints" : ["https://<your-url>/<your-notification-api>","https://<your-url>/<your-notification-api2>"]}'
  • Sample response

    1
    200 OK

Get registered webhooks

Use the endpoint below to get webhooks that are your cloud app has registered with the App migration platform.

MethodEndpoint
GETmigration/webhook

See an example

This section shows you an example of a request and response get registered webhooks.

  • Sample request

    1
    2
    curl -X GET 'https://your-cloud-site/rest/atlassian-connect/1/migration/webhook' \
    --header 'Content-Type: application/json'
  • Sample response

    1
    2
    3
    4
    5
    6
    {
        "endpoints": [
            "https://<your-url>/<your-notification-api>",
            "https://<your-url>/<your-notification-api2>"
        ]
    }

Delete registered webhooks

Use the endpoint below to delete webhooks for a specific cloud ID.

MethodEndpoint
POSTmigration/webhook/delete

See an example

This section shows you an example of a request and response to delete webhooks for a specific cloud ID.

  • Sample request

    1
    2
    3
    curl -X POST 'https://your-cloud-site/rest/atlassian-connect/1/migration/webhook/delete' \
    --header 'Content-Type: application/json' \
    --data-raw '{"endpoints" : ["https://<your-url>/<your-notification-api>"]}'
  • Sample response

    1
    200 OK

Pre-migration setup on your server app

This section explains how to setup the communication between your server app and the App migration platform.

Prerequisite

  • Enable feature flags for app migration in the server instance of Jira or Confluence.

    • Use the following link to enable the Confluence feature flag migration-assistant.app-migration.feature: <Confluence_URL>/admin/darkfeatures.action

    • Use the following link to enable the Jira feature flag com.atlassian.jira.migration.app-migration.feature: <Jira_URL>/secure/SiteDarkFeatures!default.jspa.

Register your server app with the App migration platform

Registering your server app for migration will allow you to:

  • Enable app migration in your server app
  • Get notified by the App migration platform when core data migration is complete, and app data migration starts. This will allow you to access/read mappings related to core product data (you can access the same mappings by making a request from your cloud site).
  • Upload your app-related data to Atlassian's secure cloud storage

Use the App cloud migration library

The App cloud migration library is an interface component that allows developers to create migration listeners on their server apps. The Cloud Migration Assistants (CCMA/JCMA) export the library’s classes in the runtime. The library has no external dependencies, which avoids conflicts with the tech stack your app uses.

This section explains two options for a dependency that you can add to utilize the App cloud migration library. This addition will allow your server app to integrate with the Cloud Migration Assistants.

Option 1: atlassian-app-cloud-migration-osgi

Description: This option has minimal dependency between Cloud Migration Assistants and your app.

1
2
3
4
<dependency>
    <groupId>com.atlassian</groupId>
    <artifactId>atlassian-app-cloud-migration-osgi</artifactId>
</dependency>

See an example of how to use the atlassian-app-cloud-migration-osgi dependency.

Option 2: atlassian-app-cloud-migration-tracker

Description: This option has additional features to track changes on the OSGi context. It behaves like a buffer for events that can be managed (like when the Cloud Migration Assistant restarts).

1
2
3
4
5
<dependency>
    <groupId>com.atlassian</groupId>
    <artifactId>atlassian-app-cloud-migration-tracker</artifactId>
    <version>1.15</version>
</dependency>

See an example of how to use the atlassian-app-cloud-migration-tracker dependency.

See a comparison of the two dependencies.

Implement the interface

You will need to implement the class AppCloudMigrationListener containing the following methods:

MethodDescription
onStartAppMigrationCore product migration is complete. Vendors can begin migration at this point.
getAddOnKeyThe cloud add-on to which the migration is being exported to.
See an example
1
2
3
4
5
6
7
8
9
10
11
12
 @Override
    public void onStartAppMigration(String transferId, MigrationDetails migrationDetails) {
        PaginatedMapping paginatedMapping = gateway.getPaginatedMapping(transferId, "confluence:page", 5);
        while (paginatedMapping.next()) {
            try {
                Map<String, String> mappings = paginatedMapping.getMapping();
                log.info("mappings = {}", new ObjectMapper().writeValueAsString(mappings));
            } catch (IOException e) {
                log.error("Error retrieving migration mappings", e);
            }
        }
    }

Register the listener

Use the class that you have implemented to register on the following gateway: AppCloudMigrationGateway

ListenerDescription
registerListenerAllows you to register a listener that will be invoked when the App Migration Platform is ready begin app migration, which happens after the admin has migrated the core data (Jira / Confluence product data).
See an example
1
2
3
4
5
6
7
8
9
public class MyPluginComponentImpl implements MyPluginComponent, DisposableBean {

    private static final Logger log = LoggerFactory.getLogger(MyPluginComponentImpl.class);
    private final AppCloudMigrationGateway gateway;

    public MyPluginComponentImpl(AppCloudMigrationGateway migrationGateway) {
        this.gateway = migrationGateway;
        this.gateway.registerListener(this);
    } 

The gateway will also expose the following methods to your app:

MethodDescription
deregisterListenerDeregisters the listener
getMigrationMappingByPageRetrieves the product mapping on the serve. Refer the 'Mappings' that follows for further details.
See an example

The example that follows uses deregisterListener to deregister the listener.

1
2
3
4
5
 @Override
    public void destroy() throws Exception {
        log.info("Deregistering listener");
        gateway.deregisterListener(this);
    }

Test the server app implementation in your local environment

You can test your implementation and changes locally through these steps:

  • Add the dependency to use the App cloud migration library

  • Install and run the Jira or Confluence Cloud Migration Assistant (JCMA/CCMA)

  • Ensure that you have enabled feature flags for app migration in the server instance of Jira or Confluence.

  • Have the latest plugin of your server app available with the listener

Mappings

The migration context provides information about how the data migrated from server is mapped in cloud. You can retrieve the mappings for a specific namespace by making a query to the App migration platform either from the server side, or from the cloud side of your app.

For example, the code that follows displays the response to a mapping request for the jira:issue namespace:

{ "95204": "93232", }

In the first row of this example, the issue that the Jira server identified as "95204" is mapped to "93232" in Jira cloud.

Read our docs for a complete list of namespaces you can query.

Retrieving mappings

You can query the App migration platform for data mappings on the server or on cloud side of your app. The platform responds with the same mapping response whether you make the request from the server or cloud.

Request mappings from your server app

Use the getMigrationMappingByPage method to retrieve the product mapping from your server app.

See an example

1
2
3
4
5
6
7
8
9
    PaginatedMapping paginatedMapping = gateway.getPaginatedMapping(transferId, "confluence:page", 5);
    while (paginatedMapping.next()) {
        try {
            Map<String, String> mappings = paginatedMapping.getMapping();
            log.info("mappings = {}", new ObjectMapper().writeValueAsString(mappings));
        } catch (IOException e) {
            log.error("Error retrieving migration mappings", e);
        }
    }

See an example in repository

Request mappings from your cloud app

Your cloud app can make requests to the Mappings API for mappings.

About the Mappings API

There are two ways of retrieving mappings.

You can either retrieve all mappings of a specific transferId and namespace in a paginated fashion, or you can specify up to 99 IDs of a specific transferId and namespace you'd like to resolve.

Refer our docs for more information on mappings and namespaces.

Migration: Export app data from server to cloud storage

The app migration platform uploads the app data to a secure cloud storage, and sends your cloud app the APP_DATA_UPLOADED event notification when upload is complete.

See an example

1
2
3
4
5
6
7
8
9
    OutputStream firstDataStream = migrationGateway.createAppData(transferId);
    // You can upload up to 5GB
    firstDataStream.write("Your binary data goes here".getBytes());
    firstDataStream.close();

    // You can also apply labels to distinguish data or to add meta data to support your import process
    OutputStream secondDataStream = migrationGateway.createAppData(transferId, "some-optional-label");
    secondDataStream.write("more bytes".getBytes());
    secondDataStream.close();

The example above is part of our sample application.

Recommendation: The App migration platform can upload multiple files in parallel, and may not organize export files in the same sequence that you upload. If the sequence of files you upload is important, you can use file labels to help you order the export files sequentially after retrieving it to your cloud site.

Migration: Access app data export in cloud storage

Your cloud app can use the App data retrieval API to access the app data exported to the secure cloud storage.

About the App data retrieval API

The endpoints of the App data retrieval API enable you to access the exported app data by performing the following tasks:

  1. Retrieve a list of s3keys uploaded by the server app under a particular transferId.
  2. Retrieve an S3 URL, signed by the App migration platform, for a given s3Key.

Limits: For compliance purposes, we have placed the following limits on the App migration platform:

  • The signed S3 URL expires one hour after your retrieve it. After the expiry time, your cloud app can request a new URL.
  • You must access the exported data within 5 days of receiving the first notification.
  • We recommend that you access data and mappings before the end of the mappings lifespan.
  • You can access exported data, mappings and progress reports for 14 days after you receive the first notification of your server app being triggered. After the 14-day period, any requests you make to the App migration platform will return a 400 error.
  • If the App data retrieval API responds to your request with a 429 error, you may have reached the request limit for the API. We recommend that you resend your request after a few minutes.

1. Retrieve list of exported app data

Use the following endpoint to request the App data retrieval API for a list of data uploaded by the server app under a particular transferId.

Note that you can access exported data, mappings and progress reports from the cloud storage location for 14 days after you receive the first notification of your server app being triggered. After the 14-day period, the App migration platform will return a 400 bad request error response to all requests that contain transferId.

MethodEndpoint
GET/migration/data/{transferId}/all

In the endpoint above, specify the transferId from which the app data was exported.

  • Sample request

    1
    curl -X GET "https://your-site.atlassian.net/rest/atlassian-connect/1/migration/data/26925583-10bd-49fb-b67c-15fc2447a97b/all"
  • Sample response

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    {
        [
            {
                "s3Key": "dbc96598-fc84-4c91-9e60-2fc01f705de7",
                "label": "my-data-export"
            },
            {
                "s3Key": "abc86558-jg32-5c82-9e60-2fc01f705de7"
            },
            {
                "s3Key": "f9d95eb3-924b-43d4-8115-447beca388c3",
                "label": "some-optional-label"
            }
        ]
    }

The label value is available only if your server app uploads app data with a label.

2. Retrieve a S3 URL for a s3key

Use the following endpoint to access the app data export from the cloud storage.

MethodEndpoint
GET/migration/data/{s3Key}

Replace {s3Key} with the s3Key you received with the list in the previous request.

  • Sample request

    1
    curl -X GET "https://your-site.atlassian.net/rest/atlassian-connect/1/migration/data/f9d95eb3-924b-43d4-8115-447beca388c3"
  • Sample response

    1
    2
    3
    {
     “url” : “http://s3DownloadableLink.”
    }

The example above is part of our sample application

Recommendation: Where possible, design your data retrieval process to be incremental, and consider merging data. Jira/Confluence admin users are likely to run multiple migrations that target the same cloud site.

Migration feedback

This section describes how to send feedback from your cloud app to the server product, and how to fetch feedback from your cloud app about the migration.

Send feedback from your cloud app

Your cloud app can use the Feedback channel API to send feedback about the migration to the Jira or Confluence server product.

New feedback will overwrite any existing feedback on the server product. The feedback object is a Map<String, Object>.

About the Feedback channel API

Use the following endpoint to send feedback from your cloud app to the server product:

MethodEndpoint
POST/migration/feedback/{transferId}

In the endpoint above, specify the {transferId} that you want to send feedback about.

  • Sample request

    1
    2
    3
    4
    curl -X POST 'https://your-site.atlassian.net/rest/atlassian-connect/1/migration/feedback/26925583-10bd-49fb-b67c-15fc2447a97b' \
    --header 'Content-Type: application/json' \
    --data-raw '{"key1" : ["your feedback1"],
                 "key2" : "value" }'
  • Sample response

    1
    200 OK

The example above is part of our sample application.

Fetch feedback from your cloud app

Your server app can use the App cloud migration library to retrieve feedback about the migration from your cloud app.

See an example

1
   Map<String, Object> cloudFeedbackResponse = gateway.getCloudFeedback(transferId);

Progress reporting

Your cloud app can use the Status API to report on the overall progress of your app migration to the Jira/Confluence admin user.

Note that there is a 14-day time-limit after you receive the first notification of your server app being triggered to access progress reports. After the 14-day period, the App migration platform will return a 400 error response to all requests for information using transferId.

About the Status API

Use the following endpoint of the Status API to send your App migration report to the Cloud Migration Assistant.

MethodEndpointPayload
POST/migration/progress/{transferId}{"status": "READY/IN_PROGRESS/SUCCESS/FAILED/SKIPPED/INCOMPLETE", "statusMessage": "string?", "percent" : int 0-100}

In the endpoint above, specify the {transferId} that you want to send progress status about.

  • Sample request

    1
    2
    3
    4
    5
    6
    7
    curl -X POST 'https://your-site.atlassian.net/rest/atlassian-connect/1/migration/feedback/26925583-10bd-49fb-b67c-15fc2447a97b' \
    --header 'Content-Type: application/json' \
    --data-raw '{
                    "progressStatus" : "IN_PROGRESS",
                    "percent": "90",
                    "statusMessage" : "Migration is at the last stage. Refer this link {{link:http://myapp.com}} for different stages of migration."
                }'
  • Sample response

    1
    200 OK

The feature to display your status message on the Jira/Confluence user interface is currently under developement for the Cloud Migration Assistants.

### Format your status message Your status message can include links to provide further information or troubleshooting. Refer our documentation for information on the [formatting structure of status messages](/platform/app-migration/getting-started/progress-status-messages).

Rate this page: