Migrate Jira or Confluence from on-premises to cloud using APIs

You can now use an API to create a migration definition, run pre-migration checks or a migration, and view statuses and track progress for both pre-migration checks and migrations. You can also see the programatically created migration in the Migration Assistant for both Jira and Confluence.

Prerequisites

The APIs are supported by the following CMA versions:

• JCMA: 1.11.4 and above

• CCMA: 3.9.6 and above

Go through the pre-migration checklist

Before you start going through the steps described on this page, make sure you check off the items from the pre-migration checklist for the product you're migrating. Not going through these points may lead to obscure errors and issues with your migration.

Connect to cloud site

Before you use the API, connect or reconnect to your cloud site using the Jira or Confluence migration assistant. Learn how to renew your cloud token

Get server ID

You can view your Jira server ID by going to Administration > System > System info. Learn how to find your server ID

You can view your Confluence server ID by going to Gear icon > General Configuration > System Information > Server ID. What is the Confluence Server ID

Generate cloud API token

Learn how to generate a cloud API token

Generate server personal access token

Learn how to generate a personal access token

Authorization

The migration API uses basic auth. Learn more about basic auth for REST APIs.

Your user name is the email address of your Atlassian Cloud account. Make sure this account has site or org admin permissions on the destination cloud site.

Your password is your cloud API token. Learn how to generate a cloud API token

How to migrate step-by-step

1. Create a migration

The API creates an immutable migration job definition for a given source and destination. It returns a jobId which can be used to execute pre-migration checks and run the migration on the Server/Data Center instance.

Endpoint

POST /migrations/public/v1/jobs

Documentation

2. Check migration job definition

The API is used to get the job definition for the jobId that was created in step 1.

Endpoint

GET /migrations/public/v1/jobs/{jobId}

Documentation

3. Attach your cloud site to Jira or Confluence Server/Data Center

Attach the cloud site to which you are migrating to your Jira or Confluence Server/Data Center instance using the migration assistant.

Endpoint

POST {server_url}/rest/migration/latest/public/v1/attach?cloudUrl={cloud_site_url}

Where:

• {server_url} is the URL of your Jira or Confluence Server/Data Centre instance
• {cloud_site_url} is the URL of the cloud site to which you are migrating, which should look like https://.atlassian.net/

Headers

You need to provide an additional header Content-Type with value application/json in the request.

Overview

You must attach every cloud_site_url for which you've created a job to CMA, otherwise the job won't run.

Attaching a cloud_site_url is valid for 24 hours. After 24 hours elapse, you will need to attach it again.

Authorization

Jira Server or Data Center

If you’re using Jira 8.22 or later, you can use OAuth 2.0. Learn how to use OAuth 2.0

If you’re using Jira 8.14 or later, generate a personal access token. You can then pass the token in parameters as Authorization: Bearer {access_token}. Learn how to generate a personal access token.

You can also use basic auth with the username and password you use to access Jira Server.

Confluence Server or Data Center

If you’re using Confluence 7.17 or later, you can use OAuth 2.0. Learn how to use OAuth 2.0

If you’re using Confluence 7.9 or later, generate a personal access token. You can then pass the token in parameters as Authorization: Bearer {access_token}. Learn how to generate a personal access token.

You can also use basic auth with the username and password you use to access Confluence Server.

Response (application/json)

Cloud URL attached - 200:

1
2
{
    "cloudUrl": {cloud_site_url},
    "expiryTime": "{expiry_timestamp}"
}

Invalid request - 400:

The destination cloud site is not authorized with the server. Please authorize the cloud site and retry. You need to reconnect to your cloud site.

4. Create a task to execute a migration or run pre-migration checks

Use the jobId obtained in step 1 to create a task - either a pre-migration check or a migration.

Pre-migration checks won't move any of your data, but will help you identify any issues before you execute your migration proper. Note that running a migration task also executes pre-migration checks before moving to the actual migration.

The endpoint returns a taskId, which you can then use to check the status or definition of your tasks.

Endpoint

POST /migrations/public/v1/jobs/{jobId}/tasks

Documentation

5. Get task definition

Use a pair of jobId and taskId to check the definition of a specific task.

Endpoint

GET /migrations/public/v1/jobs/{jobId}/tasks/{taskId}

Documentation

6. Get tasks created for a particular jobId

Use a jobId to get all tasks grouped under a specific job.

Endpoint

GET /migrations/public/v1/jobs/{jobId}/tasks

Documentation

7. Check the status of your tasks

This API returns the status of your tasks.

For the jira-onpremises-to-cloud flow, progress details are also available. However, these are only point in time progress updates. If you call the status API for a node which is done, you won’t see any progress data. This also means that for nodes that go through multiple phases (e.g. import and export) you’ll only see progress in the current phase.

Because the response could contain a lot of statuses, this API returns paginated responses.

Endpoint

GET /migrations/public/v1/jobs/{jobId}/tasks/{taskId}/status

Documentation

Requests and responses

The statuses for check tasks will have information around the overall status of pre-migration checks. These can be searched with level=check or level=check,{check_type} for specific checks.

The statuses for migrate tasks will have information about the overall status of the migration and the overall status of individual scopes defined in step 1 (create a migration). You can think of these scopes as subtrees whose root is migrate.

For Confluence migrations, the following scopes have separate statuses: spaces, usersAndGroups, apps, globalEntities.

For Jira migrations, the following scopes have separate statuses: projects, usersAndGroups, jsm, ar, apps.

You can search for these granular statuses by querying the status tree.

If you're migrating apps, you might see that the overall migrate status is FINISHED, but apps remain IN_PROGRESS. This isn't an error: app migration happens after core migration and is independent from it.

All statuses are populated in an eventually-consistent manner. You might have to wait before you start seeing the status for everything.

For a migrate task, always first check the status of the check level and then proceed to check the status of the migrate level. The check level status will show an error if a migration couldn't be scheduled for some reason.

Check out samples of using the status API: : Status API Examples

Pre-migration check statuses and outcomes