Migrate with Jira Cloud Migration Assistant (JCMA)
- Karina Zoin
On this page:
Migrate Issue Matrix data from Jira Server/Data Center to Jira Cloud with Jira Cloud Migration Assistant (JCMA)
Issue Matrix offers automated migration of its configuration and data to the Cloud using the Jira Cloud Migration Assistant (JCMA). This way, you can transfer your issue matrices from Jira Server/Data Center to Jira Cloud instances. The migration is supported starting from Issue Matrix for Jira Server/Data Center version 3.6.0.
Migrate to a sandbox Jira Cloud site first
We recommend testing your migration on a sandbox Jira Cloud site first. This way, you can review the migration results to assess the impact on the production site. If you run into migration errors, you can make adjustments to your Jira Server/Data Center instances and repeat the migration. After the tests are done, start migrating your Issue Matrix data to your production Cloud site.
Check out Atlassian’s documentation on app migrations with JCMA.
Migration process
You perform the migration process on the Jira Data Center/Server instance that has Issue Matrix data you want to move to the Cloud.
High-level process
The migration process with JCMA involves three phases:
Assess Issue Matrix with JCMA. View details
Prepare Issue Matrix with JCMA. View details
Migrate the Issue Matrix data with JCMA. View details
Before starting the migration process, make sure to update the Jira Cloud Migration Assistant to its latest version. Check out Atlassian’s recommendations as well.
1. Assess Issue Matrix with JCMA
Assess Issue Matrix with JCMA to ensure its current version can be migrated to the Cloud. Learn more about assessing apps in JCМА from Atlassian’s documentation.
To assess Issue Matrix before starting the migration, follow these steps:
Log into your Jira Server/Data Center instance as an administrator.
In the Administration menu ( ), click System.
On the left-hand side, scroll down to Import and Export > Migrate to cloud. You’ll see the Migration Assistant home page.
Select Assess your apps > Begin assessing on the Migration Assistant home page.
On the Assess your apps page, choose the Needed in cloud option in the Status drop-down. If a green check mark doesn’t appear under the Can be migrated column, you’ll need to upgrade to Issue Matrix for Jira Server/Data Center version 3.6.0 or later.
Select Done to finish the assessment.
The video below shows you how to assess Issue Matrix in JCMA.
2. Prepare Issue Matrix with JCMA
During the Prepare your apps phase, JCMA will check if Issue Matrix is installed on your destination Jira Cloud site. For this purpose, you’ll be required to provide the base URL of your Jira Server/Data Center instance. During this phase, you’ll also be asked to agree to Issue Matrix’s privacy policy.
To prepare Issue Matrix for migration, follow these steps:
After you’ve assessed Issue Matrix, select Prepare your apps > Begin preparing on the Migration Assistant home page. You’ll have that option if you’re doing this step for the first time. However, if you have already prepared other apps, you’ll have the Continue preparing option instead, and you’ll need to select it.
On the next page, enter the base URL of your Jira Server/Data Center instance and choose the destination Jira Cloud site for migrating your Issue Matrix data.
After JCMA checks if Issue Matrix is installed on the destination Cloud site, you’ll be asked to confirm the app’s privacy policy. Select View policy on the Agree to app migration page.
Then, select Confirm in the Agree to app data migration window.
After returning to the Agree to app migration page, select Done at the bottom of the page. At this point, the Issue Matrix app will be ready to migrate.
The video below shows you how to agree to Issue Matrix’s privacy policy and prepare the app for migration with JCMA.
3. Create and run Issue Matrix migration with JCMA
Once you've finished assessing and preparing Issue Matrix, you're all set to create and run a migration using JCMA. Explore further guidance on migrating apps with JCMA in Atlassian's documentation.
To migrate the Issue Matrix Server/Data Center data to a Jira Cloud site:
Select Migrate your data > Create new migration on the Migration Assistant home page.
On the How it works page, select Connect to cloud.
Name your migration, choose a migration state, and verify your destination Cloud site. Then, select the Choose migration options button at the bottom.
On the Migration options page, select Choose what to migrate.
Set your migration options and make sure to include the projects associated with Issue Matrix data.
For the Apps option, select All to include Issue Matrix in your migration and select Apply changes.
Select Run pre-migration checks to check for any migration issues.
JCMA will display the results of all the pre-migration checks. Review any possible issues by expanding the relevant check.
Follow the resolution steps in the expanded checks before proceeding.
If no errors are detected, select Review your migration.
On the Review your migration page, select Run.
The App migration progress for Issue Matrix will be set to complete if no errors and warnings are encountered.
Issue Matrix configurations look different in Jira Server/Data Center and Cloud
Post-migration, the issue matrices will no longer be created through custom fields. Rather, they’ll have their own configuration section within your Cloud projects’ settings. The Cloud issue matrices retain the original names of the Issue Matrix custom fields.
The video below shows you how to migrate Issue Matrix data to the Cloud with JCMA.
Migration failures
If you run into Issue Matrix migration failures, you can download logs that contain the errors causing the failures. The video below shows you where you can download these log files.
Migration specifics
Migrating Issue Matrix configurations with JQLs
If your Server/Data Center Issue Matrix configurations contain JQLs, be aware that these expressions will be migrated unchanged. As a result, object names and IDs in the JQL expressions won’t be updated to match the correct names and IDs of the Jira Cloud objects. This limitation is due to JCMA’s core migration principles.
We’ve developed a mid-migration Vendor check that warns you about the existence of JQL expressions across the Issue Matrix configurations being migrated, the migration risks, and the way they’ll be moved to the Cloud. By expanding the check, you’ll be able to download a CSV report file listing all the expressions and their locations across the Issue Matrix configurations.
The check is run together with the rest of the JCMA pre-migration checks. Watch the video below to see where it appears and how to download the report.
Adjust object names and IDs in JQLs after the migration
In these cases, you’ll have to check the migrated JQL expressions of the Issue Matrix configurations and update them with the correct object names and IDs in the Cloud site.
Migrating Filter Mode Issue Matrix configurations
In Jira Cloud, there's no option to create Filter Mode Issue Matrix configurations. During migration to Jira Cloud, these configurations will be transformed into JQL issue matrices. In their configuration, the JQL field will contain the expression filter = filterID, where "filterID" refers to the ID of the filter that was set in the original configuration of the Filter Mode Issue Matrix on the Server/Data Center platform.
Jira Server/Data Center and Cloud configuration mapping by JCMA
Before migrating, make sure the Jira objects set in Issue Matrix configurations (like custom fields) are part of the projects you’re migrating. Otherwise, after migration, these parts of the Issue Matrix configuration won’t be set and will be missing.
Low migration success rates
During pre-migration checks, you'll be informed of low migration success rates for Issue Matrix. This is a common warning with newly integrated apps on JCMA, so there's no need to be concerned. You can safely proceed with the migration.