Last updated Feb 19, 2024

Migrate Jira or Confluence to cloud using public APIs

This API is still in beta. Its functionality may change as we approach GA.

You can now use an API to create a migration definition, run pre-migration checks or a migration, and view statuses 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

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 server ID by going to Administration > System > System info in jour server product. Learn how to find your 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

This 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 the cloud API token that you generated.

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

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. 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.

The response is in the form of a status tree, where the root level contains the overall status. You can also drill down on the details of the status to see which pre-migration checks failed and which spaces/projects failed or were successful.

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, arapps.

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.

Common errors

If you get the following message:

1
2
The cloud url is either not attached through the cloud migration assistant or the Server ID
{serverId} used in the job definition is incorrect, please attach the cloud site to the 
server/data center instance using the server attach API and verify the Server ID 

This means that you either haven't completed step 3 (attach your cloud site) or provided a wrong server ID in step 1 (create a migration).

Pre-migration check statuses and outcomes

Status

Outcome

Meaning

IN_PROGRESS

N/A

Pre-migration check is ongoing.

FINISHED

SUCCESS

Pre-migration check execution was successful and there are no actions to take.

FINISHED

WARNING

Pre-migration check execution was successful, but some actions require user attention. However, the migration isn't blocked.

FINISHED

FAILED

This is a blocking check. This combination can mean two things:
  • If the message says something like We couldn’t check ..., check execution didn’t go through properly. You have to refer to the Migration Assistant plugin logs or reach out to support to resolve the issue.

  • In other cases, there is a task you have to complete before proceeding with the migration.

Rate this page: