Important - in case if your TFS4JIRA Synchronizer has profiles pointing to multiple Jira Server/DC instances.
You must migrate each of your Jira Server/DC instances separately
Only enable profiles connected to the instance you want to migrate and disable all remaining profiles
Failure to do so may result in incorrect field mappings, so the migrated profiles are broken.
3. Configuration
It can be helpful to have Jira Server, Jira Cloud, and TFS4JIRA Synchronizer UI open in separate browser tabs so you can quickly navigate between them.
3.1. Jira Cloud tokens generation
To use the Migration feature of the TFS4JIRA Synchronizer, you must generate two tokens:
API token - used in the migrated profiles to connect to Jira Cloud for data synchronization purposes.
Migration token - used to authorize the TFS4JIRA Synchronizer connection to Jira Cloud during the JCMA driven migration process. Only TFS4JIRA Synchronizers with the valid migration token are registered for the migration.
3.2. TFS4JIRA Self-hosted Synchronizer configuration
TFS4JIRA version 10.0.0 or higher has a Migration tab to add the tokens you generated earlier to establish a connection between TFS4JIRA Synchronizer and your Jira Cloud site.
Go to your TFS4JIRA Self-hosted Synchronizer and click the Migration tab to go to the Jira Cloud Migration page.
Under Migration token, enter the Migration token you generated earlier (see #3.1.2)
Under Jira Cloud Access, provide the Email of the Jira Cloud user that created the Jira API Token you generated earlier (see #3.1.1)
You can also select Enable new profile after successful migration at this time. When this option is selected, migrated profiles are enabled by default. At the same time, the old profiles are disabled.
If this option is not selected, the migrated profiles are created but not enabled by default, and the old profiles remain active.
Synchronization profiles using Synchronization Filters with JQL/WIQL support WILL NOT be enabled automatically even if the option is selected. The filter migration must be reviewed to ensure it is correct before the profile can be enabled. This information is printed in the migration logs.
Click Test to confirm a connection between Jira Cloud and TFS4JIRA Self-hosted. A successful connection to Jira cloud produces a success message.
When you’ve entered all information, click Save. Registered Synchronizers appear on the Jira Cloud Self-hosted Synchronizer page (the same page where Migration token was generated).
Click the Cloud Self-Hosted Migration tab, and the Synchronizers with a valid migration token are displayed in the TFS4JIRA Self-hosted Synchronizers list.
It may take up to 2 minutes for the TFS4JIRA Synchronizer to appear on the list.
The Synchronizer Id and Migration token expiration date (Expires column) are shown.
At this point, the TFS4JIRA Self-hosted Synchronizer contacts TFS4JIRA Cloud for instructions regarding the migration.
If the Synchronizer instance is not visible on the page after ~2 minutes:
Confirm it has Internet access and can connect to Jira Cloud instance
Confirm the Migration token is valid and not expired
4. Trigger migration
Follow the configuration guidelines provided in Atlassian’s Use the Jira Cloud Migration Assistant to migrate document.
TFS4JIRA migration requires the latest version of TFS4JIRA to be installed on the Jira Cloud instance, even though JCMA allows migration to proceed with an earlier version. Confirm you are using the latest version of TFS4JIRA on your Jira Cloud instance. Contact Support if you require assistance.
5. Migration progress and status updates
Once migration is started with JCMA, the TFS4JIRA migration steps are:
Retrieve profiles from each Self-hosted Synchronizer registered for the migration.
Update profiles. (Field and metadata mappings are updated inside the profiles.)
Migrate issue properties. (Information about synchronized attachments, comments and links is stored in Jira’s issue properties. )
Send updated profiles back to Synchronizers.
Enable successfully migrated profiles and disable old ones if the corresponding option was selected.
When the migration is successful, a new profile appears on the TFS4JIRA Synchronizer’s synchronization profile list. New profile names are generated based on the original profile name and the migration date.
If the issue properties migration fails, the entire migration fails.
A migration failure on a single profile doesn’t block other profiles from being migrated.
6. Post-migration
6.1. Migration logs
Once the migration is complete, you can download and review the logs to help find any issues. This is especially helpful for the profiles that failed to be migrated, so the issues are fixed before the next migration attempt.
Go to your Jira Cloud site, select Self-hosted synchronizer from the Apps menu, and click the Migration Logs tab.
From this page, you can see the following information about recent migrations: Name, Start time, End time, and Status.
Locate the required migration in the list and click the Download icon to download the log text file. Migration logs follow the format shown in the examples below.
The log provides the following:
Overall migration status
Status of profiles migration grouped by Synchronizer instances
The Synchronizer Id is the same as the Id displayed in the TFS4JIRA Self-Hosted Synchronizer list
When the migration is unsuccessful, the related errors are displayed
6.2. Validate migrated profiles
Once you have migrated your TFS4JIRA profiles to use Jira Cloud, we recommend performing a few checks. Go to your TFS4JIRA Self-hosted Synchronizer and review the new profiles (one-by-one) to confirm:
The link between Jira and Azure DevOps now points to the Jira Cloud site
Click the Mappings tab and review the mappings between Jira and TFS/Azure DevOps fields to confirm they are correct
Click the Filters tab and confirm that filters have been migrated correctly
Review projects, users, and groups to confirm that information was successfully migrated to your Jira Cloud instance
Lastly, you can enable the newly created profile and observe periodic synchronization to confirm it works correctly.
Remember that successfully migrated profiles may be enabled automatically if the corresponding option was selected during TFS4JIRA Self-hosted Synchronizer configuration (step #3.2). The exception is with profiles using Synchronization Filters - they always have to be enabled manually!
7. Special cases and troubleshooting
7.1. JQL migration
While migrating JQL used in TFS4JIRA filters, TFS4JIRA:
Does not replace any project names or keys (assuming they did not change)
Does not attempt to update any status, priority, or issue type mapping. The names should not change during Server to Cloud migration
Updates custom field references in JQL, but only those referred to via id. For example, “
cf[10011]
"Attempts to replace user mentions in JQL with values that Jira Cloud understands
7.2. Legacy filters migration
Some profiles may rely on legacy filters functionality that do not utilize JQL / WIQL capabilities. TFS4JIRA doesn’t support automatic migration of such profiles and they should be updated to use new filtering capabilities first. Refer to How to update legacy filters and start using JQL and WIQL filtering for instructions.
7.3. Priority field migration
JCMA only migrates Priority field values referenced in the migrated projects; so not all Priority values may get migrated. JCMA compares Priority based on the name and color/icon.
If a priority with the same name but different color exists in Jira Cloud, JCMA creates a new priority instead of merging them.
A Priority value called High in Jira Server may be migrated as High (migrated) to Jira Cloud. As the result, in Jira Cloud, there will be two Priority values called High and High (migrated)
Given the above behavior, Priority mappings are not updated in the migrated profiles. Modify mappings in the migrated profiles to keep then Priority valued with (migrated) suffix.
To delete Priority values with (migrated) suffix, you don’t need to change anything regarding Priority mapping. During the deletion of the corresponding Priority value in Jira, you can choose the new Priority value to be assigned for the affected issues.
7.4. Retrying the migration
If the migration fails and some or all profiles are not migrated successfully, the migration should be repeated. Alternatively, you can create the missing profiles manually. The decision depends on the manual effort and time it takes to repeat the automated migration.
Fix the errors reported in the migration logs
Clean up Jira Cloud site to enable another round of migration with JCMA. For example, delete the migrated projects or start over with a new site
Run the migration again
7.5. How to check Self-hosted Synchronizer instance Id?
The Synchronizer’s Id is visible at the bottom of every page in the user interface, to the right of the Synchronizer’s version.
7.6. Multiple TFS4JIRA instances on one machine
In some cases, customers install multiple instances of TFS4JIRA Self-hosted Synchronizer on one machine. This can raise an issue when migrating TFS4JIRA data, as each Synchronizer can have the same ID, causing the migration to fail.
Contact Support for assistance with migrating TFS4JIRA data using multiple TFS4JIRA instances.