Rate this page:
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:
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.
The sections that follow explain the pre-migration setup you will need to create on your server app and cloud site.
This section explains how to setup the communication between your cloud app and the App migration platform.
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:
The sections that follow explain all the above endpoints, and provide examples on how to use them.
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.
Method | Endpoint |
---|---|
PUT | migration/webhook |
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
Use the endpoint below to get webhooks that are your cloud app has registered with the App migration platform.
Method | Endpoint |
---|---|
GET | migration/webhook |
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>"
]
}
Use the endpoint below with an empty list to delete or replace existing webhooks for a specific cloud ID.
Method | Endpoint |
---|---|
PUT | migration/webhook |
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
This section explains how to setup the communication between your server app and the App migration platform.
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.
Registering your server app for migration will allow you to:
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.
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.
atlassian-app-cloud-migration-tracker
Description: This option does the following:
1 2 3 4 5
<dependency>
<groupId>com.atlassian</groupId>
<artifactId>atlassian-app-cloud-migration-tracker</artifactId>
<version>1.21</version>
</dependency>
See an example of how to use the atlassian-app-cloud-migration-tracker
dependency.
See a comparison of the two dependencies.
You will need to implement the class AppCloudMigrationListenerV1
containing the following methods:
Method | Description |
---|---|
onStartAppMigration | Core product migration is complete. Vendors can begin migration at this point. |
getAddOnKey | The cloud add-on to which the migration is being exported to. |
1 2 3 4 5 6 7 8 9 10 11 12
@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);
}
}
}
Use the class that you have implemented to register on the following gateway: AppCloudMigrationGateway
Listener | Description |
---|---|
registerListener | Allows you to register a listener that will be invoked when the App migration platform is ready to begin app migration, which happens after the admin has migrated the core data (Jira/Confluence product data). |
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:
Method | Description |
---|---|
deregisterListener | Deregisters the listener |
getMigrationMappingByPage | Retrieves the product mapping on the serve. Refer the 'Mappings' that follows for further details. |
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);
}
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
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.
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.
Use the getMigrationMappingByPage
method to retrieve the product mapping from your server app.
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);
}
}
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.
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.
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.
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:
transferId
.s3Key
.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
.
Method | Endpoint |
---|---|
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.
Use the following endpoint to access the app data export from the cloud storage.
Method | Endpoint |
---|---|
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
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.
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:
Method | Endpoint |
---|---|
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.
Your server app can use the App cloud migration library to retrieve feedback about the migration from your cloud app.
1
Map<String, Object> cloudFeedbackResponse = gateway.getCloudFeedback(transferId);
Your cloud app can use the Status API to report on the overall progress of your app migration to the Jira/Confluence admin user.
About the Status API
Use the following endpoint of the Status API to send your App migration report to the Cloud Migration Assistant.
Method | Endpoint | Payload |
---|---|---|
POST | /migration/progress/{transferId} | {"progressStatus": "IN_PROGRESS/SUCCESS/FAILED/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/progress/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
Your status message can include links to provide further information or troubleshooting. Refer our documentation for information on the format of status messages.
Rate this page: