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 programmatically created migration in the Migration Assistant for both Jira and Confluence.

Prerequisites

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

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

3. Connect your cloud site

• Before you create a migration task, connect or reconnect to your cloud site. Checkout connect to cloud page.

How to migrate step-by-step

1. Create a migration job

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.

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

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

3. Attach your cloud site

The API attaches the destination cloud site to your Jira or Confluence on-premises instance using the migration assistant. 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, you have to reattach it.

Request details

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

where:

• {server_url} is the URL of your Jira or Confluence on-premises instance
• {cloud_site_url} is the URL of the cloud site to which you are migrating, example https://.atlassian.net/
• Headers: You need to provide an additional header Content-Type with value application/json in the request.
• On-premises authorization

Response (application/json)

Cloud URL attached - 200:

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

Invalid request - 400:

1
2
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. Note that running a migration task also executes pre-migration checks before moving to the actual migration.

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

You can also specify some advanced options like include/exclude or override checks. Checkout advanced features page.

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

5. Get task details

The API returns task definition and associated artifacts. Checkout migration error logs and reports page for artifact details.

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

6. Get all tasks created for a particular job

The API returns all tasks grouped under a specific job.

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

7. Check the progress/status of your tasks

The API returns the progress/status of your tasks.

However, the progress updates will only be point in time. 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.

Checkout migration status and progress details page for more details.

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