Migrations API (MAPI) is now in General Availability!
Hello, migrations community! I’m excited to share some news regarding a new tool to help improve your migration experience. In our continued efforts to improve the migration capabilities that we provide to you, we took your feedback on wanting more customization with your migrations and developed the Migrations API, or MAPI. MAPI layers on top of your cloud migration assistants and helps you control, move, and automate the migration of your data to the cloud.
A massive thank you to those who participated in the early access and beta programs. We value your input and want you to know that you have helped us (and continue to help us) shape and improve not only MAPI, but our entire migrations experience.
Continue reading to learn more about MAPI and how you can take advantage of this new tool!
What is the Migrations API (MAPI)?
The Migrations API is a free cloud service that Atlassian admins, solutions partners, and Marketplace partners can use to perform, automate, and customize migration tasks using code via a public API. MAPI is a cloud-based API that communicates with the cloud migration assistants (CMAs) for Jira and Confluence as well as our cloud services.
To use MAPI, you must have an active cloud site and the following cloud migration assistant versions on your self-managed instance:
- Jira Cloud Migration Assistant: 1.11.4 and above
- Confluence Cloud Migration Assistant: 3.9.6 and above
Mapi requires knowledge of APIs to be used effectively. Read our referenced documentation to see if your team can take advantage of MAPI!
Note: MAPI supports migrations to the cloud for self-managed (Server or Data Center) instances of Jira and Confluence.
Why should I use MAPI?
The primary benefit of MAPI is the extensibility that it provides you. 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 2,000 Confluence spaces and want to migrate 1,000 of them to your cloud instance. If you were to use the Confluence Cloud Migration Assistant, you'd have to select the 1,000 spaces manually to migrate them.
With MAPI, you can specify migration jobs for groups of projects and spaces. Then, you can schedule and automate the migration of the groups without having to select each project or space individually.
Common use cases of MAPI in action are:
- Creating a custom migration definition to include spaces, users, groups, apps, entities, projects (even archived ones), dashboards, filters, and boards
- Performing pre-migration checks on multiple migrations
- Automating migrations to happen incrementally or synchronously or setting up a long-running phased migration
- Reducing manual efforts and limitations with CMA UI for large-scale migrations
- Monitoring the progress and status of a migration that you either automated or are running through the CMAs
For instructions and to learn more about these use cases, read our developer documentation.
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 or Confluence 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 for your self-managed instance, 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.
We’re excited for you to try out the Migrations API. To get started, head over to the Migrations API space at Atlassian Developer.
We’d love to hear from you as you engage with MAPI. If you have any questions or feedback, please let us know below or reach out to support for more help.
Quick Links:
Was this helpful?
Thanks!
Michael Lanoie
0 comments