---
title: "Profile Migration from Jira DC to Jira Cloud"
canonical: "https://support.appfire.com/space/TSH/1800340975/Profile%20Migration%20from%20Jira%20DC%20to%20Jira%20Cloud"
format: markdown
---
> ⚠️ **Important - in case your TFS4JIRA Synchronizer has profiles pointing to multiple Jira DC instances:**
> ⚠️
> ⚠️ - You must migrate each of your Jira DC instances separately
> ⚠️ - Only enable profiles connected to the instance you want to migrate and disable all remaining profiles
> ⚠️
> ⚠️ Failure to do so can result in incorrect field mappings, causing the migrated profiles to be broken.
# 3. Configuration
> ℹ️ It can be helpful to have Jira DC, 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 a valid migration token are registered for the migration.
3.1.1. Generate API token
> ⚠️ The API token should be created for the user with sufficient Jira Cloud privileges. Otherwise, synchronization will not work after the profile migration. See [https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800209893](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800209893)
1. Go to the *[API Tokens](https://id.atlassian.com/manage/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 ](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)for more information.
3.1.2. Generate Migration Token
> ⚠️ 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.
> ⚠️
> ⚠️ The token can be regenerated 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.
Select the *Cloud Self-hosted Migration* tab.
2. Under the *Migration Token* heading, click **Generate Token**.
3. 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.
> ❌ Synchronization profiles using [Synchronization filters](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800669442) 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 the *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](https://support.atlassian.com/migration/docs/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](https://appfire.atlassian.net/servicedesk/customer/portal/11) if you require assistance.
How to trigger TFS4JIRA migration process
Once you have configured JCMA, proceed to the *Migration Assistant home *page.
1. From your Jira DC instance, go to **Settings** > **System.**
2. Scroll down the left panel, and select **Migrate to Cloud** from the *Import and Export* category.
The *Migration Assistant home* page opens.
3. Click **Begin assessing** or **Continue assessing** from the *Assess your apps* category.
4. 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.
5. Click **Check for errors**. It takes a few moments to scan for any errors. When the check is complete, click **Review migration**.
6. Review any warnings and configuration settings.
> ⚠️ 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 migration progress is automatically calculated and displayed dynamically as each migration step is completed. The progress indicator reflects real-time progress for migration parts:
1. Adjusting migration profiles - Retrieves and updates profile configurations.
2. Migrating issue properties - Migrates synchronized attachments, comments, and links. This is the longest part of the migration process and can take up to several hours to complete, depending on the Jira instance size and the number of issues, tasks, attachments, links, and comments synchronized.
3. Uploading adjusted profiles to synchronizer - Sends updated profiles back to Synchronizer, enables successfully migrated profiles, and disables 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.
> 📝 - The migration follows a sequential process where each step must complete successfully before the next begins. If any step fails, the entire migration stops and is marked as failed. This ensures data integrity throughout the process.
> 📝 - A migration failure on a single profile doesn’t block other profiles from being migrated.
During migration process, you can click the three-dot **Menu** under **Actions** for each migration part to:
- **[Re-run](https://appfire.atlassian.net/wiki/spaces/1768883568/pages/1800274562)**** **- start the migration again for the failed steps
- **View logs** - to download progress logs for the selected migration part
- **Cancel** - this option is currently display-only and does not stop the migration when clicked
# 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
Migration 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.
Example 1. Successful migration, for multiple Synchronizer instances
```none
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
```
Example 2. Failed migration with some profiles migrated successfully
```
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
> ✅ 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](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800669442)** - 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 DC 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 can 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](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800929848) 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 DC 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
You can rerun a failed or incomplete TFS4JIRA migration without having to create a new migration plan within 12 days of the original attempt. For the details on how to use it, consult the JCMA [Re-run app migration](https://support.atlassian.com/migration/docs/manage-and-view-the-details-of-jira-migration-plans/#Re-run-a-Marketplace-app-migration) instruction by Atlassian.
App migration is split into 3 separate transfers that can you can re-run independently:
1. **Adjusting migration profiles **
2. **Migrating issue properties **
3. **Uploading adjusted profiles to synchronizer**
This lets you rerun only the failed part of the migration instead of rerunning the entire process, saving time and reducing potential errors.
## 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 a single 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](https://appfire.atlassian.net/servicedesk/customer/portal/11) for assistance with migrating TFS4JIRA data using multiple TFS4JIRA instances.
# 8. Privacy
When migrating Jira DC 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 secure 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](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800962147).
## Related articles
- [Installing TFS4JIRA Synchronizer](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800962313)
- [Installing TFS4JIRA Cloud Native App](https://appfire.atlassian.net/wiki/pages/createpage.action?spaceKey=148176899&title=Installing%20TFS4JIRA%20Cloud%20Native%20App)
- [Use the Jira Cloud Migration Assistant to migrate](https://support.atlassian.com/migration/docs/use-the-jira-cloud-migration-assistant-to-migrate/)
- [API Token authentication in Jira Cloud](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800210416)
- [Manage API Tokens for your Atlassian Account](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)
- [Permissions needed by TFS4JIRA Synchronizer](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800209893)
- [Feature Comparison: Cloud Native vs Self Hoste](https://appfire.atlassian.net/wiki/spaces/TFS4JIRA/pages/148177909)d
- [Synchronization Filters](https://appfire.atlassian.net/wiki/spaces/TFS4JIRA/pages/148176956)
- [How to update legacy filters and start using JQL and WIQL filtering](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800929848)
## Support
If you need any assistance with your TFS4JIRA migration, please contact our [Support](https://appfire.atlassian.net/servicedesk/customer/portals) team!