Manage and monitor your Jira migrations
When you save or run a migration, it’s added to your Migrations dashboard where you can view the details and monitor the progress.
The dashboard lets you:
View the details of every migration, including summary of migrated data
Run, copy, edit, delete, and archive your migration
Monitor the progress of an ongoing migration and see the results
View pre-migration checks to see warnings and errors
View pre-migration and post-migration reports, and error logs
Migrations dashboard
You can access the dashboard by opening the Jira Cloud Migration Assistant:
Migration status
The table below describes the possible statuses for your migrations:
Status | Description |
|---|---|
SAVED | Your migration is saved and ready to run. |
RUNNING | Your migration is currently in progress. |
FINISHED | Your migration has finished, with all the tasks completed. |
INCOMPLETE | Your migration has finished, but there are errors or things that couldn't be migrated. This also means that some data (users, groups, projects, etc.) has been migrated. If you're on Jira Cloud Migration Assistant (JCMA) 1.21.0 or later, you may be able to retry the failed steps without migrating again. Otherwise, or if you've already selected Continue to app migration, you might need to delete the migrated data from your Cloud site before re-migrating the same projects. |
FAILED | Your migration failed. This might be because a project key already exists in the destination site or the migration hit an unexpected error. If you're on JCMA 1.21.0 or later, you may be able to retry the failed steps after you fix the cause. |
Migration details
You can view the following details for each migration plan by selecting View details from the migration dashboard.
Configuration overview
Overview of your migration that shows configuration details and migration status.
Data included in a migration
The This migration includes section that shows details and status of migrated items.
Logs and reports
The Logs and reports section that includes reports and errors logs to help you troubleshoot your migration.
You can download the following items:
Pre-migration report: Details on what is included in your migration.
Post-migration report: Details on what was and wasn’t migrated.
Error log: Errors related to your migration.
You can find explanation of errors from the log file in the troubleshooting guide.
Learn how to troubleshoot your Jira migration
Retry failed migration steps
If your migration is INCOMPLETE or FAILED, you can retry only the steps that failed, from the same migration plan. JCMA skips every step that already completed, and runs again only the failed steps and any steps that didn't run because of the failure. You don't need to create a new migration plan or delete partially migrated data from your Cloud site. Retrying doesn't create duplicate data.
Retrying covers core migration steps, such as project import, attachments, and assets upload. For example, if a project fails during import, retrying runs the import and attachment steps for that project. Retrying doesn't cover app migration. To retry an app migration, see Re-run a Marketplace app migration.
What happens when a step fails
Data shared across projects isn't imported yet. If a project fails during export, preprocessing, or import, JCMA doesn't import data shared across projects, such as filters and dashboards, so that none of it is missed. If only attachments fail, this data is still imported.
App migration waits. If any core migration step fails, app migration doesn't start automatically, and the migration shows App migration on hold. You choose whether to retry the failed steps or continue to app migration. Nothing happens until you choose. Data shared across projects, such as filters and dashboards, isn't imported until you retry the failed steps or continue to app migration. If your plan doesn't include Marketplace apps and you can't retry the failed steps, contact Atlassian Support for help migrating data shared across projects.
You get an email. JCMA emails the admin who started the migration, whether or not the migration plan includes Marketplace apps. The email shows how many steps failed and how many times the migration has been retried, and explains your options.
A countdown starts. The migration details show how many days you have left to retry.
Before you begin
Use Jira Cloud Migration Assistant 1.21.0 or later. We recommend 1.27.0 or later, which fixes some known issues with retrying.
Be a Jira system administrator on your source site, the same as for running a migration.
If the failure was caused by your data or configuration, find and fix the cause first. For example, if a step failed because a custom field is missing from your Cloud site, add the custom field before you retry. You can fix the cause on your source site or your Cloud site, and the retry uses your latest data. Retrying doesn't fix the original problem, so a step that failed for a reason you haven't addressed will fail again. If the migration details say the failure was caused by a temporary issue on our end, you can retry without changing anything. Learn how to troubleshoot your Jira migration
If you can't find the cause, contact Atlassian Support after the first failed attempt, before you retry. Support can help you find and fix the cause, so that your retry succeeds.
If your migration is large, contact Atlassian Support before you retry, and wait for Support to confirm before you select Retry failed steps.
Retry the failed steps
Open the Jira Cloud Migration Assistant and go to the Migrations dashboard.
Find the failed or incomplete migration and select View details.
Select Retry failed steps.
The migration status changes to RETRYING, and then to RUNNING. When the failed steps complete, the steps that depended on them run. Then data shared across projects is imported and app migration starts automatically.
Continue to app migration instead
If your migration plan includes Marketplace apps, you'll also see Continue to app migration. Select it to start app migration without retrying the failed steps. We recommend retrying the failed steps first, because apps that depend on the failed projects might not migrate successfully.
You can't undo this. App migration includes only the projects that migrated successfully, and you can't retry the failed steps from this migration plan afterwards. To migrate the failed projects, create a new migration plan for them.
Retry limits
You can retry a migration up to 3 times. If you need more retries, contact Atlassian Support to raise the limit.
You can retry a migration for a limited time after it started. The migration details show how many days are left. This is separate from the 12-day limit for re-running an app migration.
Retry attempts are counted separately from the automatic retries JCMA makes for temporary errors.
If Retry failed steps isn't shown, the migration isn't eligible for a retry (for example, because app migration has already started), or it has reached a limit. The migration stays INCOMPLETE or FAILED.
Marketplace app migration
Here you can find information related to app migration.
Monitor your Marketplace app migration
The details in the App migration progress section displays the following to monitor or review the progress of your app migration:
app status
app migration logs
Ordered migrations
Ordered migration is a sequencing solution for migrating Marketplace app from Data Center to Cloud using the Jira Cloud Migration Assistant (JCMA). It runs app migrations in dependency-aware groups rather than all at once. By organizing Marketplace apps into sequential groups, the platform ensures that the apps known to modify site data in complex ways complete their processes before other apps begin migrating.
This sequencing helps you avoid migration failures and data conflicts that occur when multiple Marketplace apps attempt to modify the same Cloud site components simultaneously.
Find out how ordered migrations work
Marketplace app migration statuses
Status | Description |
|---|---|
READY | The app data migration is ready to run. |
RUNNING | The app data migration is in progress. |
PAUSED | The app data migration is paused and will begin after the app migrations in previous group reaches either a SUCCESS or INCOMPLETE state. |
SUCCESS | The app data migration has finished successfully. |
INCOMPLETE | The app data migration has finished, but some data wasn’t migrated. Select Re-run to retry an incomplete app migration. If the app’s migration continues to be unsuccessful, contact your Marketplace Partner (app vendor) for support. |
FAILED | The app data migration has failed. Select Re-run to retry a failed app migration. If the app’s migration continues to fail, contact your Marketplace Partner (app vendor) for support. |
TIMED OUT | The migration timed out. This is because the app has exceeded the permitted time period to migrate data. You can contact the respective app vendor for information on how to proceed with migrating data for the app. |
If you have issues with any app for non-completion or failure to migrate, you should contact the Marketplace Partner (the app vendor) directly for support.
Marketplace app migration progress logs
The Cloud Migration Assistant provides log files you can download to monitor the migration progress and status of every app. You can find the View logs button on the ‘This migration includes' tab for each app.
To view app logs:
Open the migration plan screen.
Navigate to the This migration includes tab > Apps section > Activity logs column. You’ll find a View logs link for every app selected for migration.
Select View logs for an app to download a CSV file that details the progress of your app’s migration.
Note:
Log files have a 30-day event history limit. This means that logs will only list the most relevant events of the app’s migration in the last 30 days since the app’s migration started.
The log file begin with listing the most recent events, and are updated until you’ve downloaded the log file. You can download the file again for the most updated list of events.
Each log file is limited to the latest 4000 events.
The View logs link may be disabled if:
the app migration could not be found in cloud.
the logs have expired (has exceeded the 30-day event history limit).
the app does not have an automated path.
the app migration has not yet started.
Re-run a Marketplace app migration
You can re-run an unsuccessful app migration for individual apps that display a failed or incomplete status, without having to create a completely new migration plan. This feature allows the Cloud Migration Assistant to retry an app’s migration, and resolve issues that may have previously failed or left the app’s migration to be incomplete.
Re-running applies to app migrations only. To retry failed core migration steps, such as projects, see Retry failed migration steps.
To re-run an app, select Re-run in the ‘App migration progress’ table.
Re-run limits
Re-run the app migration within 12 days of when you first started running the original migration. The app re-run feature will not be available for apps after the 12-day time-limit.
This features is only available for apps that display the failed or incomplete status. It may not be available for certain apps that don’t support this feature.
Cancel a Marketplace app migration
You can cancel the migration of individual apps, if they appear to be stuck, take too long to migrate, or if you’ve changed your mind about migrating an app. This feature gives you better control over your app migration, as canceling a specific app does not affect the progress of any other apps you have in the migration.
After an app has started canceling, this action cannot be reversed.
We recommend that you:
Contact your Marketplace Partner before canceling an app migration to check the migration progress to avoid canceling an otherwise smoothly running migration
Check your CMA progress logs to understand the status of your app data migration
Contact your Marketplace Partner after canceling an app migration to verify if any app data was migrated to cloud, and for any further guidance they may provide
You can find the Cancel option under the Actions column.
Troubleshoot your migration
If you’re having problems with your migration, try looking for a solution in the troubleshooting guide.
Learn how to troubleshoot your Jira migration
After you migrate
Here’s what you can do after migration.
Post-migration report
Download the post migration report (.zip file) to know the status of the migrated data in your Cloud site. The report includes the following information:
Summary - This lists the summary data on what successfully migrated and what didn't migrate.
Requires attention - This lists items that require your attention, for example, items that were not supported via migration.
For details, check the Logs and reports section above.
Users and groups
To make sure your users and groups are set up correctly:
Review members of groups and approve their permissions by going to Administration > User management.
Add users to the general administrator groups if necessary. The generic groups are: "site-admins", "system-administrators", "atlassian-addons", "atlassian-addons-admin".
If you use an external user management system, check that your users have synced correctly.
When you are ready, invite your users. Go to Administration > Users > Show details and then Resend invite. When they first log in they may be prompted to set a new password and add personal details.
If you have the improved user management experience, go to Administration > Directory > Users > Show details and then Resend invite.
Projects
You can view the project on your Cloud site as soon as all the project data is migrated — even if your attachments haven't finished: Select the project name on your migration details page.
To check that your projects have migrated successfully:
Review projects and issues, or ask your users to review their own projects.
Check for any unusual instances of Former User. This means that we were unable to match content to a user.
Use JQL and quick filters to check for any instances of the phrase (migrated). If you find this, you will need to merge the (migrated) field with the existing version in Cloud for your filter to work.
Link your other Atlassian products by going to Settings (cog icon) > Jira settings > Products > Application links.
You can then install any other apps you wish to use and onboard your users.
More information and support
We have a number of channels available to help you with your migration.
For more migration planning information and FAQs, visit the Atlassian Cloud Migration Center.
Have a technical issue or need more support with strategy and best practices? Get in touch.
Looking for peer advice? Ask the Atlassian Community.
Want expert guidance? Work with an Atlassian Partner.
Support for Atlassian Server products ends in February, 2024. Learn more about the Server end of support timeline.
Was this helpful?