TFS4JIRA - Self-Hosted Profile Migration from Jira Server/DC to Jira Cloud

Owned by Jeff Gleeson
Last updated: Nov 11, 2023
13 min read

This instruction covers the migration of TFS4JIRA Self-hosted Synchronizer profiles from pointing to Jira Server/DC to pointing to Jira Cloud. As the same TFS4JIRA Self-hosted Synchronizers are used after the migration, there are no functional differences between Jira Server/DC and Jira Cloud.

Currently, there is no automated migration path from TFS4JIRA Self-hosted to TFS4JIRA Cloud Native, but it’s on our roadmap. See https://appfire.atlassian.net/wiki/spaces/TFS4JIRA/pages/148177909 to learn more about the differences between those solutions.

1. Introduction

TFS4JIRA is a powerful combination of Jira plugin and Self-hosted Synchronizer web application, allowing you to automatically synchronize TFS and Azure DevOps work item changes to Jira and vice versa. But what do you do when you want to switch from Jira Server or Data Center to Jira Cloud? How do you ensure that your TFS4JIRA synchronization profiles are updated from your Jira Server or Data Center instance to your new Jira Cloud site?

TFS4JIRA’s new Jira server-to-cloud migration feature, together with Atlassian’s Jira Cloud Migration Assistant (JCMA), automates updating your existing TFS4JIRA Self-hosted profile configuration to your Jira Cloud site.

2. Before you begin

Before proceeding with your migration, confirm the following:

  1. TFS4JIRA Server plugin version 10.0.0 or higher is installed on your Jira Server instance.

  2. TFS4JIRA Self-hosted Synchronizer version 10.0.0 or higher is installed and has access to the internet. See https://appfire.atlassian.net/wiki/spaces/TFS4JIRA/pages/148177967 for installation details.

  3. TFS4JIRA synchronization profiles to be migrated are enabled.

  4. The latest JCMA version is installed on your Jira Server instance.

  5. The latest version of the TFS4JIRA Cloud plugin is installed on the Jira Cloud site. (TFS4JIRA Cloud can also be installed as part of the Apps configuration in JCMA)

The following profiles will not be migrated:

  1. Draft and inactive (disabled) profiles.

  2. Profiles referencing projects that are not migrated to Jira Cloud with JCMA.

  3. Profiles with invalid credentials to Azure DevOps / TFS.

  4. Profiles pointing to Jira Cloud (migration is not needed for such profiles).

  5. Profiles using legacy version of filters (those without JQL / WIQL support), see Troubleshooting - #7.2.

Knowing what information is copied when updating the profile settings for your Jira Server instance to Jira Cloud is helpful before starting the migration process. The following profiles settings will be updated:

  1. URL link changes from pointing at Jira Server to Jira Cloud

  2. Mappings between Jira and Azure DevOps / TFS environments (comments, attachments)

  3. JQL query filters

  4. Custom fields mappings

  5. User mappings

  6. Active Directory information

During this process, a profile copy is created in TFS4JIRA Self-hosted Synchronizer containing the updated settings. Depending on the migration process configuration (described below), the newly created profiles may be automatically enabled while old (migrated) profiles are disabled.

Equally important is knowing what is not updated during this process. The following information is not included:

  1. Check-ins configurations

Contents
Support

If you need any assistance with your TFS4JIRA migration, please contact our Support team!

Important - in case 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, with the migrated profiles being broken.

3. Configuration

3.1. Jira Cloud tokens generation

To use the Migration feature of the TFS4JIRA Synchronizer, you must generate two tokens:

  1. API token - used in the migrated profiles to connect to Jira Cloud for data synchronization purposes.

  2. 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.

  1. Go to the API Tokens page and click Create API Token. The Create an API token dialog opens.

  2. Enter a label and click Create.

  3. Save the API token, as it's used later as part of the TFS4JIRA Synchronizer configuration.

Refer to Manage API Tokens for your Atlassian Account for more information.

  1. Go to your Jira Cloud site, click Settings > Apps. When the Apps panel opens, select the Self-hosted Synchronizer under the TFS4JIRA heading.

    The Self-hosted Synchronizer - TFS4JIRA page opens.

  2. Select the Cloud Self-hosted Migration tab.

  3. Under the Migration Token heading, click Generate Token.

  4. Save the Migration token, as it’s used later as part of the TFS4JIRA Synchronizer configuration.

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.

  1. Go to your TFS4JIRA Self-hosted Synchronizer and click the Migration tab to go to the Jira Cloud Migration page.

  2. Under Migration token, enter the Migration token you generated earlier (see #3.1.2)

  3. 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)

  4. 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.

  1. Click Test to confirm a connection between Jira Cloud and TFS4JIRA Self-hosted. A successful connection to Jira cloud produces a success message.

  2. 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).

  3. Click the Cloud Self-Hosted Migration tab, and the Synchronizers with a valid migration token are displayed in the TFS4JIRA Self-hosted Synchronizers list.

  4. 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.

4. Trigger migration

Follow the configuration guidelines provided in Atlassian’s Use the Jira Cloud Migration Assistant to migrate document.

Once you have configured JCMA, proceed to the Migration Assistant home page.

From your Jira Server instance, go to Settings > System, scroll down the left panel, and select Migrate to Cloud from the Import and Export category. Selecting Migrate to Cloud could also take you to the Migrations dashboard page. If it does, click Migration Assistant home to go to the Migration Assistant home page.

  1. Click Begin Assessing or Continue Assessing from the Assess your apps category.

  2. When the Assess your apps page opens, locate TFS4JIRA in the list and confirm the status is set to Needed in cloud. Click Done to return to the Migration Assistant home page. Here you can prepare your apps for migration.

  3. Click Check for errors. It takes a few moments to scan for any errors. When the check is complete, click Review migration.

  4. Review any warnings and configuration settings.

5. When you are ready, click Run. You can then track the migration process.

5. Migration progress and status updates

Once migration is started with JCMA, the TFS4JIRA migration steps are:

  1. Retrieve profiles from each Self-hosted Synchronizer registered for the migration.

  2. Update profiles. (Field and metadata mappings are updated inside the profiles.)

  3. Migrate issue properties. (Information about synchronized attachments, comments and links is stored in Jira’s issue properties. )

  4. Send updated profiles back to Synchronizers.

  5. Enable successfully migrated profiles and disable old ones if the corresponding option was selected.

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

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 https://appfire.atlassian.net/wiki/spaces/TFS4JIRA/pages/328729450 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.4.1. Re-run app migration

Re-run app migration was introduced by Atlassian in version 1.9.4 of JCMA. You can rerun a failed or incomplete TFS4JIRA migration without having to create a new migration plan. For the details on how to use it - consult Re-run app migration instruction by Atlassian.

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.

8. Privacy

When migrating Jira Sever profiles to Jira Cloud profiles, we send the profile data to our Cloud infrastructure where it is used to synchronize your Jira Cloud project with Azure DevOps/TFS. This data includes JQL and WIQL queries, profile names, Jira and Azure DevOps/TFS usernames and emails used in mappings, and any other mapped fields and values. This data is stored in our infrastructure on a secured SQL database hosted on Google Cloud Platform. The data is stored for a maximum of 90 days from the start of the migration, or deleted immediately after a successful migration.

More details here .