API to Fetch ID Mappings from Jira Cloud Migration Assistant
Platform Notice: Cloud and Data Center - This article applies equally to both cloud 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
Summary
When migrating from server to cloud using JCMA (v1.11.4+), entity IDs (issue, project, comment, etc.) change and won't be retained in Cloud. This document explains how to fetch server-to-cloud ID mappings so you can update any external integrations by replacing old server IDs with the new cloud IDs.
This ID-mapping API is a server-side, BETA endpoint on the source instance — it may change or be removed in future JCMA versions. Use it for post-migration reconciliation, not as a permanent integration.
Solution
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 authenticates with their credentials against the source instance's JCMA API to fetch the server → cloud ID mappings after a migration run. Retain the exact endpoint/example from the body.
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 API call. This cache is automatically invalidated if a new migration is performed from the instance. invalidateCache is an optional parameter that can be set to true if 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. The application/octet-stream media type is returned in the response, and the user can download the stream of the file contents. |
404 NOT FOUND | This is returned when the API is not present - it’s possible that the Beta API will be 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 by following the "Connect to your cloud site" step. No existing migration could be found for cloudSiteUrl. This could happen if a migration never occurred 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. |
How do I know it worked?
The API returns a mapping table pairing source object IDs with their new cloud IDs.
Was this helpful?