(Updated) Migrations API is now in Open Beta!

[#1]

Tech-savvy admins, we’ve got some exciting news for you: The Migrations API (MAPI) is now in open beta!

What is the Migrations API (MAPI)?

The migrations API is an open application programming interface (API) that admins can use to perform, customize, and automate Atlassian migration tasks using code. MAPI is a cloud-based API that communicates with the cloud migration assistants for Jira and Confluence as well as cloud services. It works with the following Cloud Migration Assistant versions:

• Jira Cloud Migration Assistant: 1.10.16 and above
• Confluence Cloud Migration Assistant: 3.9.6 and above

Note: MAPI requires knowledge of APIs in order to use. Read our reference documentation to see if MAPI is something that your team can take advantage of!

Why should I use MAPI?

The main benefit of the migrations API is the extensibility. Each of the migration tasks can be extended, altered, or automated. By opening up the migration tasks, you can build workflows and customizations that can help save time and reduce errors.

For example, say you have thousands of projects and spaces in Jira, but you are unable to migrate all at once because you already have data in your cloud site or you need to apply different parameters to each. With MAPI, you can specify migration jobs for groups of projects and spaces. Then, you can schedule the migrations of those groups to happen automatically without having to select each project or space individually.

How does it work?

MAPI takes migration activities that happen on self-managed instances and cloud instances and represents them as a series of asynchronous tasks. MAPI opens them for communication with 3rd-party migration tools, such as scripts, applications, and command-line interfaces (CLIs).

MAPI handles API standardization and authorization using basic auth for REST APIs. The REST API is protected by the same restrictions that apply in the standard Jira web interface. These restrictions mean that if you don't log in, or if you log in and don't have permission to view something in Jira or Confluence, you won't be able to view it using the REST API either.

To start, you will need your Atlassian username and password. Make sure this account has site or org admin permissions on the destination cloud site. Then, after acquiring an API token and a personal access token, you will be able to access MAPI and begin writing scripts.

Our documentation includes collections for Postman and OpenAPI as well as scripts for the following programming languages: Python, curl, Node.js, Java, and PHP.

What functionality can I expect from the beta?

With the MAPI beta, you can use APIs to perform, customize, and automate the following migration activities. To learn more about these use cases, read our developer documentation.

• Create a migration definition
  • Choose the parameters for a migration, selecting the source server site and type (Confluence or Jira), the destination cloud site, and things to be included in the migration (spaces, usersAndGroups, apps, globalEntities, jsm, ar, projects).
• Run pre-migration checks
  • Run the same pre-migration check available in the migration assistants (system, users, groups, customers, projects, boards, roadmaps, and apps)
• Perform a migration
  • Migrate data from your self-managed instance to your cloud instance using a migration definition. The code can include additional parameters, such as scheduling, automation, and notification triggers.
• View status on pre-migration checks and migrations
  • Check the status of Pre-migration checks and migrations. There are four statuses: IN_PROGRESS, FINISHED (SUCCESS), FINISHED (WARNING), and FINISHED (FAILED).

We’re excited for you to try out Migrations API. No sign-up is needed, just head over to the Migrations API space at Atlassian Developer to get started. We are also releasing MAPI to our specialized solution partners who may be able to use MAPI to save you time and unblock migration challenges.

We’d love to hear from you, so if you have any questions or feedback, please let us know below or reach out to support for more help.

Quick Links:

MAPI Developer Documentation

MAPI Troubleshooting