Versions Compared

Old Version 21

changes.mady.by.user Jeff Gleeson

Saved on

compared with

New Version Current

changes.mady.by.user Jeff Gleeson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 Feature Comparison: Cloud Native VS Self Hosted 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 Installing TFS4JIRA Synchronizer 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)

Note

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.

Expand
title2.1. What TFS4JIRA settings are updated

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.

Expand
title2.2. What TFS4JIRA settings are not updated

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

  1. Check-ins configurations

Contents
Table of Contents
minLevel1
maxLevel4
outlinefalse
typelist
printablefalse
Support

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

Note

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

Info

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:

  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.

Expand
title3.1.1. Generate API token
Note

The API token should be created for the user with the sufficient Jira Cloud privileges. Otherwise, synchronization will not work after the profile migration. See Permissions needed by TFS4JIRA Synchronizer

  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.

Expand
title3.1.2. Generate Migration Token
Note

This token is valid for 90 days. Once expired, TFS4JIRA Synchronizers will not be able to register in the corresponding Jira Cloud site for the JCMA-driven migration process.

Token may be re-generated and updated at any time.

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

Warning

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.

  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.

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.

Note

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.

Expand
titleHow to trigger TFS4JIRA migration process

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.

Note

Two pre-migration warnings are always displayed (as shown below). If you see the Synchronizers in Jira Cloud Self-hosted Synchronizer page - ignore these warnings.

  1. TFS4JIRA migration token check - A token must be generated in TFS4JIRA cloud to secure and identify all TFS4JIRA Self-hosted Synchronizers connecting to the new Jira cloud site.

  2. TFS4JIRA self-hosted migration registration check - All TFS4JIRA Self-hosted Synchronizers must register with TFS4JIRA cloud using the token previously generated to establish a secure migration channel.
    Once you have completed these tasks, continue with the migration.

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.

Tip

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.

Expand
titleMigration progress details

Migration progress is updated when the following steps are executed:

  • WAIT_FOR_PROFILES_AND_MIGRATE: 20% - profiles are retrieved and mappings / metadata is updated. This typically takes a few minutes.

  • ISSUE_PROPERTIES_MIGRATION: 50% - issue properties migration is started. This is the longest step of the migration process and can take up to several hours to complete - depending on the Jira instance size and number of issues, tasks, attachments, links, and comments synchronized.

  • MIGRATED_PROFILES_UPLOAD: 80% - migrated profiles are uploaded into TFS4JIRA Self-hosted Synchronizer.

  • MIGRATED_PROFILES_ACKNOWLEDGE: 90% - profiles upload is completed.

  • MIGRATION_FINISHED: 100% - migration finished successfully.

  • MIGRATION_FAILED: 100% - migration finished with errors (all profiles failed, or issues properties migration failed).

  • MIGRATION_INCOMPLETE: 100% - migration finished with errors (some profiles could not be migrated).

  • MIGRATION_CANCELLED: 100% - migration was cancelled.

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

Expand
titleMigration status details

Available profile migration statuses:

  • READY_TO_MIGRATE - Profile is uploaded to TFS4JIRA Cloud, but has not been migrated yet.

  • MIGRATED - Profile was migrated. Waiting for the issue properties migration to finish before it is sent back.

  • FAILED - Profile migration has failed.

  • RETRY - Profile migration has run into the issue but will be be retried. For example, rate limiting took place during fetching required mappings.

  • SENT - Migrated profile has been sent back to the Self-hosted Synchronizer. Waiting for the confirmation that it was saved correctly.

  • SAVED_IN_SYNCHRONIZER - The Self-Hosted Synchronizer confirms the migrated profile was saved correctly.

  • FAILED_TO_BE_SAVED_IN_SYNCHRONIZER - Migrated profile has not been saved in the Self-hosted Synchronizer. An error has occurred during saving.

Expand
titleExample 1. Successful migration, for multiple Synchronizer instances
Code Block
languagenone
Status of "Migration demo" migration MIGRATION_FINISHED due to "All profiles have been sent back to synchronizers."
  * Synchronizer "synchronizer-instance-id-1”"
    * Profile "Profile A": SAVED_IN_SYNCHRONIZER
    * Profile "Profile B": SAVED_IN_SYNCHRONIZER
    * Profile "Profile C": SAVED_IN_SYNCHRONIZER
  * Synchronizer "synchronizer-instance-id-2"
    * Profile "Profile A": SAVED_IN_SYNCHRONIZER
    * Profile "Profile B": SAVED_IN_SYNCHRONIZER
    * Profile "Profile C": SAVED_IN_SYNCHRONIZER
    * Profile "Profile D": SAVED_IN_SYNCHRONIZER
    * Profile "Profile E": SAVED_IN_SYNCHRONIZER
    * Profile "Profile F": SAVED_IN_SYNCHRONIZER
Expand
titleExample 2. Failed migration with some profiles migrated successfully
Code Block
Status of "Demo migration 3" migration MIGRATION_FAILED due to "Migration of 2 profiles out of 3 has failed"
  * Synchronizer "synchronizer-instance-id-1"
    * Profile "Profile 1": FAILED
      * Reason: Failed to update mapping of custom field with id: 10302 due to missing cloud mapping
    * Profile "Profile 2": MIGRATED
    * Profile "Profile 3": FAILED
      * Reason: Failed to find mapping for user Test

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

Tip

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

Info

If the TFS4JIRA migration fails at a point where it is sending profiles back to the Self-hosted synchronizer(s), and some profiles are not saved, then duplicated profiles will be created if app migration is re-run. To avoid profiles duplication, remove any previously migrated profiles before using the re-run feature.

For example: there are four profiles to migrated, three of them were saved correctly on the Self-hosted instance. But fourth one did not fully migrate. Re-run will create duplicates of those three profiles and create the fourth which failed to be saved previously.

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 Data Policy.