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 set up 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 migration/webhook endpoint to register your webhooks after your app has received the enabled lifecycle event.

The App migration platform notifies the endpoint below when migrations are ready or available on the server app.

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 your cloud app has registered with the App migration platform.

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 with an empty list to delete or replace existing webhooks for a specific cloud ID.

See an example

This section shows you an example of a request and response to delete existing webhook URLs for a specific cloud ID. For example, if you want to delete all existing webhooks, you can use PUT /migration/webhook with an empty list.

• 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":[]}'

• Sample response

  1

  200 OK

Pre-migration setup on your server app

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

Prerequisite

• Enable feature flags for app migration in the server instance of Confluence.
  • Use the following link to enable the Confluence feature flag migration-assistant.app-migration.feature: <Confluence_URL>/admin/darkfeatures.action

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. Only one listener should be registered per server app, however multiple server apps can send data to a single cloud app. 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 that 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.

Make sure to always use the latest version available.

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

This option has no dependency between Cloud Migration Assistants and your app.

1
2
3
4
5

<dependency>
  <groupId>com.atlassian</groupId>
  <artifactId>atlassian-app-cloud-migration-listener</artifactId>
  <version>1.0.2</version>
</dependency>

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

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

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

1
2
3
4
5

<dependency>
    <groupId>com.atlassian</groupId>
    <artifactId>atlassian-app-cloud-migration-osgi</artifactId>
    <version>1.0.0</version>
</dependency>

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

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

This option does the following:

• Tracks changes on the OSGi context
• 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.26.1</version>
</dependency>

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

See a comparison of the libraries.

A version catalogue and information about their end-of-life policy can be found on the library version page.

Implement the interface

You will need to implement a listener interface. Depending on the library you are using this can be DiscoverableListener, AppCloudMigrationListenerV1 or CloudMigrationListenerV1. The methods to be implemented are:

atlassian-app-cloud-migration-listener

See an example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

@Override
public void onStartAppMigration(String transferId, MigrationDetailsV1 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);
        }
    }
}

@Override
public String getCloudAppKey() {
    return "my-cloud-app-key";
}

@Override
public String getServerAppKey() {
    return "my-server-app-key";
}

@Override
public Set<AccessScope> getDataAccessScopes() {
    return Stream.of(
            APP_DATA_OTHER, PRODUCT_DATA_OTHER, MIGRATION_TRACING_IDENTITY, MIGRATION_TRACING_PRODUCT
    ).collect(Collectors.toCollection(HashSet::new));
}

Register the listener (options 2 and 3 only)

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

See an example

1
2
3
4
5
6
7
8
9

public class MyPluginComponentImpl implements MyPluginComponent, DisposableBean {

  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:

See an example

The example that follows uses deregisterListener to deregister the listener.

1
2
3
4

@Override
public void destroy() throws Exception {
    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.

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.

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.

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.

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

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.

About the Feedback channel API

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

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

• Sample request

  1
  2
  3

  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

If you implement the listener interface, your cloud app must use the Status API to report on the overall progress of your app migration to the Jira/Confluence admin user in the Cloud Migration Assistant user interface.

Your cloud app must send the following to settle the transfer at the end of the migration:

• SUCCESS, FAILED, or INCOMPLETE status
• a percentage
• an optional message

About the Status API

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

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/progress/26925583-10bd-49fb-b67c-15fc2447a97b' \
  --header 'Content-Type: application/json' \
  --data-raw '{
                  "status" : "IN_PROGRESS",
                  "percent": 90,
                  "message" : "Migration is at the last stage. Refer this link {{link:http://myapp.com}} for different stages of migration."
              }'

• Sample response

  1

  200 OK

Format your status message

Your status message can include links to provide further information or troubleshooting. Refer our documentation for information on the format of status messages.