Migration using Jira Cloud Migration Assistant (JCMA)
- Anna Ciepłota
- Magdalena Żaczek
- Piotr Koszela
The migration using JCMA is available for:
BigPicture/BigGantt version 8.11 and later
BigTemplate version 8.17.1 and later
If you don't know how to check the current version, refer to the Checking the App version article.
With the Atlassian JCMA tool, you can migrate selected projects or divide the migration process into a few stages. It is possible to:
Migrate Jira On-premise and the BigPicture / BigTemplate / BigGantt plugins to Jira Cloud.
Migrate only Jira On-premise without the BigPicture/BigGantt plugin to Jira Cloud.
After migration, the App data from Jira On-premise will overwrite data on Jira Cloud.
Make sure you have JCMA installed on your Jira. If you do not have JCMA installed:
Navigate to Jira Administration.
Go to ATLASSIAN MARKETPLACE in the left sidebar.
Select Find new Apps.
Search ‘Jira Cloud Migration Assistant’ and install it.
To find out more about JCMA, read the Use Jira Cloud Migration Assistant to migrate (legacy) article.
In case of any doubts, contact our Support.
What is not migrated
What If Scenario is not migrated.
JQL can be incomplete and may require manual changes. JQL is used in Scope definition → Additional Filtering and Quick Filters.
How to prepare for migration
The steps below are necessary to migrate the plugins to Jira Cloud. Ensure you have all the plugins (BigPicture, BigTemplate) installed on your Jira Cloud before you begin.
Jira Data Center
When you migrate from Jira Data Center to Jira Cloud, you will be asked to reinstall BigPicture to prepare a JCMA dump.
The reinstallation ensures data consistency in the dump by deactivating BigPicture on other nodes (Jira instances in a Jira Data Center cluster). The reinstallation prevents other nodes from making modifications to the database during database dump creation.
To reinstall BigPicture:
Uninstall the app.
Download the JAR file for exactly the same version:
Install the app with the file.
Creating a JCMA snapshot will restart the App and may take a significant amount of time and resources, so the process is recommended during non-business hours. Do not interrupt the process or disable the App until the JCMA snapshot is complete.
Prepare a JCMA snapshot in BigPicture on Jira On-premise:
Navigate to BigPicture App Configuration > Advanced > Database dumps > New dump > JCMA dump.
Enter a unique Migration name, as you will later need to identify this snapshot in JCMA and complete the Description field.
The provided Migration name can be edited later.
For BigPicture on Jira Cloud:
Navigate to Apps > BigPicture App Configuration > Advanced > Technical info > Others > Data migration.
Enable the Allow JCMA migration option.
On Jira On-premise:
Navigate to Jira Administration > System > Import and Export > Migrate to cloud > Assess your apps.
Assign the Needed in cloud status for each App.
Click Done.
Migration process
Initiate a migration process in JCMA:
Navigate to Jira Administration > System > Import and Export > Migrate to cloud.
Click the Create a migration button.
Get familiar with information about the migration process.
Provide the migration name (the one you used for creating the JCMA snapshot in BigPicture).
Tip: “Migration 3” and “migration-3” are different names. Make sure that the name matches exactly.Choose your destination Jira Cloud.
Click on the preferred migration method:
Choose what to migrate; or
Migrate all data at once.
If you have selected Choose what to migrate in the previous step:
Define your migration options, such as Projects, User and groups, and Apps.
When ready, click the Check for errors button.
Select All to migrate all the apps with an automated path that are marked as Needed in cloud in your app assessment.
If you select None, no apps will be migrated.
Proceed by clicking Review migration.
You can run your migration now or save it and come back later. You will not be able to add or remove projects after you have saved so if you would like to make any changes, perform them now.
After running the migration, you can track its progress from the Migration dashboard.
Info: During migration, your BigPicture on Jira Cloud will restart to reflect the state of the migrated BigPicture from Jira On-premise.
Once the migration is complete, the status will be updated accordingly.
(BigPicture Jira Cloud) You will see the Migration completed successfully message once you enter Apps > BigPicture App Configuration > Advanced > Technical info.
The message will disappear after the next BigPicture update.(Jira On-premise) The Progress column in the Migration dashboard (Jira Administration > System > Import and Export > Migrate to cloud) informs about the migration status.
You can also expand the Actions menu and click View details.You will find detailed information on the migration.
Additional instructions for the Migrate all data at once option
The following steps apply only to the Migrate all data at once option.
If BigPicture/BigGantt migration got stuck at 0% and there is no progress in the last 15 minutes, go to BigPicture/BigGantt on the target Jira Cloud instance.
If you see the following screen, it indicates the lack of sufficient permissions for add-ons on Jira Cloud. In this case, you must follow the procedures described on the Insufficient JIRA Permissions in BigPicture page.
Once you define sufficient permissions, return to BigPicture/BigGantt on Jira Cloud:
Go to App Configuration > Advanced > Technical info.
Under the Others > Data migration section, enable the Allow JCMA migration toggle switch.
Under the Pending data migration section, click the Trigger pending migration button.
After refreshing the page, you will see a message that the migration is in progress.
Now, you can return to the Migration dashboard on Jira On-premise and track the progress.
How to repeat migration
It is not recommended to reset Jira Cloud to solve migration problems. However, if there is no other way and you decide to reset Jira Cloud, you have to uninstall BigPicture first. Once BigPicture is uninstalled, you can reset Jira Cloud.
In case of any mistakes during the migration process in JCMA (for example, forgetting to provide the correct Migration name of your JCMA snapshot), you can run the migration process again.
Prepare a JCMA snapshot in BigPicture on Jira On-premise.
You can either:Edit the Migration name and use the same JCMA snapshot (if you entered the wrong Migration name for your JCMA snapshot).
Go to BigPicture App Configuration > Advanced > Database dumps and edit the JCMA snapshot you created before.or
Create a new JCMA snapshot as described in the How to prepare for migration section above.
Enable the Allow JCMA migration option in Apps > BigPicture App Configuration > Advanced > Technical info > Others > Data migration section on Jira Cloud.
This option needs to be enabled each time before migration.Go to the Jira Administration > System > Import and Export > Migrate to cloud > Assess your apps section.
Assign the Needed in cloud status for each App.
Click Done.
Initiate the migration process as described in the Migration process section.
After migration
Once the migration process is finished, it is recommended to check the following:
In Jira:
Review imported groups
You will see a message that imported groups need your review. Click on the banner to start reviewing or navigate to Directory > Groups.
You can select a group to review their pending product roles.
You can approve or deny a group.
When ready, the status Reviewed will appear next to a group.
Verify permissions
Check migrated custom fields
Migrated custom fields can be recognized by the (migrated) additional note.
To find out more about duplicates, refer to the Jira Cloud Migration Assistant duplicates and tracking entities article.
Duplicated fields after migration in Jira Cloud
During migration with JCMA to Jira Cloud you can see duplicated custom fields, Migrated and Locked ones. Custom fields marked as Migrated are used for default field mapping in Jira Cloud.
In BigPicture:
Field mapping in App Configuration > General > Fields
Scope definition in Boxes
Content of Boxes such as tasks, projects, etc.
Editing and assigning tasks (it can be necessary to correct permissions)
Individual resources
Permissions assigned in App Administration > Security
BigTemplate migration
The migration using JCMA is available for BigTemplate version 8.17.1 and later.
You can migrate BigTemplate alone or together with BigPicture using JCMA. As a result, the BigTemplate database and all files with templates are migrated to your Jira Cloud.
How to prepare BigTemplate for migration
Make sure you have BigTemplate installed on your Jira Cloud before you begin.
A JCMA snapshot for BigTemplate on Jira On-premise is created automatically.
On Jira On-premise:
Go to the Jira Administration > System > Import and Export > Migrate to cloud > Assess your apps section.
Assign the Needed in cloud status for BigTemplate.
Click Done.
BigTemplate migration process
We recommended performing a joined migration for all Apps - this way you can migrate both BigPicture and BigTemplate at the same time (see the migration process steps outlined above).
The migration process for BigTemplate is almost identical to BigPicture (two preparation steps are not needed when migrating only BigTemplate):