API to Fetch ID Mappings from Jira Cloud Migration Assistant

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Purpose

After JCMA 1.11.4 (Feature was added as Beta) performing a server to cloud (S2C) project-by-project (PbP) migration through Jira Cloud Migration Assistant (JCMA), the IDs of entities like issueId, projectId, commentId, etc. change on cloud. The PbP architecture is not designed to retain the IDs on cloud.

Sometimes, you may have made external integrations using these IDs, which would not work post migration. You might want to fix these integrations post migration.

This document provides a mechanism for you to fetch mappings of these IDs (serverId, cloudId) so you can use them to fix integrations.

A typical fix is to replace all serverIds with cloudIds in your integrations.

Fetch ID Mappings API

Below are details of an API to help you fetch ID mappings for your server and cloud site after migration.

The provided API is a server-side API and is in BETA phase. It can be removed in future JCMA versions and can be replaced by an alternative (e.g. a cloud based API).

Authentication

A server admin can use their credentials to authenticate their API calls using the following options:

Personal Access Token (PAT)

Using Personal Access Tokens

Username and Password

Basic authentication

API Request

GET:/rest/migration/latest/report/id-mappings

Query Parameters

Query Parameter

Description

cloudSiteUrl

The cloud site url on which the migration was performed.

e.g. https://{your-cloud-site}.atlassian.net

Note: The cloudSiteUrl should not have any trailing slashes (/)

invalidateCache (optional)

(default: false)
JCMA caches the ID mappings after the first call to the API. This cache is automatically invalidated if a new migration is performed from the instance.
invalidateCache is an optional parameter which can be set to true in case the users want to forcefully invalidate the cache.

Example API call using curl

curl -u {username}:{password} https://{your-server-base-url}/rest/migration/latest/report/id-mappings?cloudSiteUrl=https://{your-cloud-site}.atlassian.net&invalidateCache=false

Downloaded file path

Once the API is called, the id mappings file will be generated in {jira-home}/id-mappings where jira-home is the absolute jira home path on the Jira On-Prem instance. 

API Response

Response Status Codes

Explanation

202 
ACCEPTED

  • This is returned when ID mappings fetching is in progress by the server.

  • The user should retry the request every minute until the status code changes to 200.

200
OK

  • This is returned when the server has already fetched ID mappings and has generated a csv file.

  • application/octet-stream media-type is returned in the response and the user can download the stream of file contents.

404
NOT FOUND

  • This is returned when the API is not present - it’s possible that the Beta API is removed in future releases

400
BAD REQUEST

This is returned with the following messages -

  • No migrationScopeId found for the cloudSiteUrl - This could happen if the cloudSiteUrl is incorrect.

  • Unable to fetch containerToken for the cloudSiteUrl - This could happen if a container token doesn’t exist for the cloud site. Users can try connecting to the cloud site using the Connect to your cloud site step.

  • No existing migration could be found for the cloudSiteUrl - This could happen if a migration never happened for the server and cloud site pair.

  • Unable to create id mappings CSV file for the cloudSiteUrl - This could happen if the CSV file could not be created. Please check the permissions of the target/jira/home/id-mappings folder.




Last modified on Jun 20, 2024

Was this helpful?

Yes
No
Provide feedback about this article

In this section

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.