Atlassian Migration API: overview and benefits

Last week, Atlassian announced the general availability of the Migrations API (MAPI). This presents a great moment to explore the functionalities of this API, analyze its advantages and disadvantages, and suggest ways to leverage its potential.

The creation of MAPI is an effort by Atlassian to empower partners and power users engaged in cloud migrations. It aims to automate the repetitive tasks involved in planning and executing migrations. Currently, only Jira and Confluence are supported.

Although the availability of this API is a net positive in the cloud migration space, the lack of features is one of its major shortcomings. Let's dive in!

What does the MAPI do?

The MAPI allows us to create, attach, and fetch migration jobs, create and fetch migration tasks, and fetch the status of a specific migration task.

A migration job is essentially the migration plan. It contains the definition of the migration we want to execute. It is bound to a "flow" or migration type (either for Jira or Confluence) and contains all the necessary information for the migration to work: the source and destination sites as well as the scope (apps, users and groups, projects or spaces, product-specific features, etc.).

Upon the creation of a migration job, it must be attached to an on-prem instance, which has been previously prepared to run cloud migrations. This basically confirms that we have permission to access the system and are allowed to migrate its data.

Before using the MAPI, the migration manager must complete all the pre-migration assessments, which, in most cases, ensure a successful migration. Check the Jira Cloud Migration Assistant pre-migration checklist or Confluence pre-migration checklist to get a complete overview of the required preparation steps.

Once a migration job has been created and attached, we can create and execute migration tasks on it. There are only two types of tasks available at the moment: running the pre-migration checks or the migration. The status of each task can be consulted at any time.

There are two important aspects to consider: rate limiting and data retention. Rate limiting mainly affects the creation of migration jobs and tasks, allowing only five requests per minute. Additionally, the data retention policies of the API only allow the storage of information for a maximum of 30 days.

The good, the bad, and the ugly

The good: The MAPI is yet another tool in the migration manager's toolbox. Using it simplifies the creation, validation, and execution of complex migration plans, involving hundreds of projects, which otherwise would need to be selected manually, making these efforts repeatable. This means less overhead and a reduced risk of making errors.

The bad: The Achilles heel of the MAPI is its tiny feature set, allowing the planning and execution of a migration only after an instance has been fully prepared. It would be great if users were able to prepare some aspects of the instance such as apps, users, groups, and domains, among others. These steps must still be carried out manually and there is still potential to automate them.

Besides that, Atlassian should consider the possibility of editing or deleting an existing migration job prior to its execution. Sadly, there is no public roadmap yet, and it is hard to tell whether these will eventually come or not.

The ugly: The attaching flow of a migration job could be greatly improved. As already explained, we need access to both the cloud and the on-prem instance in order to attach a migration job that we created using the MAPI.

While preparing the on-prem instance, an administrator must always link the Cloud Migration Assistant (CMA) with the target cloud site. This means that the security tokens have already been exchanged, and there should be no need to send requests to the on-prem instance directly since the MAPI and the CMA can securely talk to each other and exchange this information.

Furthermore, it would be quite useful if MAPI exposed some search endpoints for already linked on-prem instances, such as, for example, retrieving a list of projects or spaces belonging to a given category, which can later be used to define the scope of a migration job.

How do we benefit from using Atlassian's MAPI?

Some of our colleagues have already developed scripts to automate the entire process described above, expediting plan creation during migration testing phases that involve multiple runs. Prior to MAPI, the manual selection of hundreds of projects or spaces was necessary.

Another potential use case for MAPI is the creation of a migration orchestrator, enabling remote configuration and execution of migrations through a simplified interface. Given the current limitations, this orchestrator may be best suited for small or phased migrations with low complexity (cloud-compatible apps). Integration with Jira Service Management could facilitate service requests, allowing customers to select projects or spaces for migration in phased approaches, streamlining the process and notifying customers upon completion.

Conclusion

While the Migration API is still in its early stages and lacks some desired features, there are specific scenarios where leveraging it over the Cloud Migration Assistant proves advantageous.

Pros

• A valuable tool for experienced migration managers with coding skills
• Potential reduction in overhead for large or complex migrations

Cons

• Attach API flow could be simplified
• Limited feature set
• Absence of a public roadmap