Download the ID mapping report after a Jira migration
The ID mapping report is being rolled out progressively. If you do not see the ID Mapping Report row yet, it is not enabled for your environment. You can still fetch ID mappings using the API in the meantime.
After a Jira migration finishes successfully, Jira Cloud Migration Assistant (JCMA) can give you an ID mapping report. This report is a CSV that maps the entity IDs from your source Jira site to the matching IDs in your destination Jira Cloud site.
Use it when you need to update anything that still points at your old IDs, such as scripts, integrations, saved queries, internal records or audit trails.
What's in the file
The CSV has three columns:
Entity Type - the kind of entity, written in a namespaced format such as
jira:issue,jira/classic:projectorjira/classic/software:rapidView, which is a board.Server ID - the identifier on your source site.
Cloud ID - the identifier on your destination Jira Cloud site.
Which entity types appear depends on what your migration included. A report can cover issues, projects, issue types, issue link types, custom fields, screens, workflows, filters, boards, priority schemes and project roles.
The two identifier columns are not always numeric. Workflow rows use the workflow name in the Server ID column and a UUID in the Cloud ID column. Allow for both if you parse the file with a script. The file also currently repeats its header row, so skip the second header row rather than reading it as data.
Before you begin
Install Jira Cloud Migration Assistant on your source Jira site.
Be a Jira administrator, or have permission to view and manage migration plans.
Complete a migration successfully. Failed migrations do not produce a report.
Download the report
In your source Jira site, open Jira Cloud Migration Assistant.
Open the migration plan you want a report for, then select View details.
Go to the Logs and Reports tab.
In the list of reports on that tab, find the row labelled ID Mapping Report.
Select Download to save the CSV. If the report is missing, stale or expired, select Generate first, then download it when it is ready.
JCMA creates the report automatically when a migration completes, so in most cases it is ready to download when you arrive. Generate is there for the cases where no usable report exists.
Generate a new report
Open the migration plan details, then go to Logs and Reports.
In the list of reports on that tab, find the row labelled ID Mapping Report, then select Generate.
Wait while the row shows that the report is being generated. JCMA checks for updates every 20 seconds.
When the row shows the report is ready, select Download.
Report states and what to do
State | What it means | What to do |
|---|---|---|
Not yet available | The migration is still running, so there is nothing to report on yet. | Wait for the migration to finish. |
Generating | The report is being created. | Wait. JCMA checks for updates every 20 seconds. |
Ready | The report is available and covers the current migration scope. | Select Download. |
Stale | Another migration finished for the same scope after this report was created. | Select Generate to get an up-to-date report. |
Expired | The report is older than the 14-day retention period and is no longer stored. | Select Generate to create a new report. |
No report available | No report has been created for this migration scope yet. | Select Generate. |
Error | The report could not be created, or the migration failed. | If the migration failed, fix the migration and run it again. Otherwise select Generate to retry, and contact Atlassian Support if it keeps failing. |
How reports are scoped and retained
A report belongs to a migration scope, which is the combination of your source site, your destination site and the product. It is not tied to a single migration run.
This has three consequences worth knowing before you plan a staged migration:
Reports are cumulative. A report covers every entity migrated for that scope, across all runs, not only the most recent run. This is why a report can list more entities than the run you are looking at.
Only one report is kept per scope. When a later migration completes for the same scope, it replaces the earlier report.
Reports are kept for 14 days. After that, the stored report is no longer available and you need to generate a new one.
If you need a record of a specific migration run, download the report before you start the next run for the same scope. Once a later run completes, the earlier report cannot be recovered, and generating a new report returns the combined results for all runs in that scope.
Handle the downloaded file carefully
The report maps the internal structure of your Jira sites, so treat it as internal data. Once you download the CSV, retention and access are yours to manage. Store it only as long as you need it for reconciliation, limit who can open it, and delete it when the work is done.
Troubleshooting
I cannot see the ID Mapping Report row
The report is still rolling out, so it may not be enabled for your site yet. Use the API to fetch ID mappings in the meantime, and contact Atlassian Support if you need to confirm your site's status.
The report stays in the generating state
Refresh the page and check the row again. If the report still has not completed after a long wait, select Generate to retry. It is safe to request a report again.
The download fails
Generate a fresh report and try again. If the download keeps failing, contact Atlassian Support.
The report lists more entities than I migrated in this run
This is expected. Reports cover the whole migration scope, so they include entities from earlier runs between the same source and destination.
What to include when you contact support
Your JCMA version
Your source Jira URL and destination Jira Cloud URL
The migration or execution ID
The state shown in the ID Mapping Report row
What you expected to happen, what happened instead, and when
Do not include credentials, tokens or customer data in anything you attach.
Was this helpful?