---
title: "Xray Pre-Migration Best Practices"
canonical: "https://docs.getxray.app/space/XRAY/1154613253/Xray%20Pre-Migration%20Best%20Practices"
format: markdown
---
> Macro (rw-ui-expands-macro)
>
> > Macro (rw-expand)
>
> > Macro (toc)
# Introduction
This documentation provides a comprehensive, step-by-step guide for migrating Xray Data Center data to Xray Cloud.
It is designed to:
- Follow best practices for Xray migration.
- Minimize risks and avoid migration failures.
- Provide clear instructions for every stage, from planning to production execution.
By following this guide, you can ensure a successful Xray migration, with all Projects, [Test Runs](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301502714), attachments, and dependencies migrated safely to the Cloud.
> ℹ️ For detailed information about how to plan the Xray migration and the process that needs to be followed, please refer to the dedicated documentation:
> ℹ️
> ℹ️ 1. [How to plan the Xray Migration to the Cloud](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/1152811013). This documentation is designed to guide you through the entire migration process, helping with planning, running test migrations, and executing the production migration.
> ℹ️ 2. [How to use the Jira Cloud Migration Assistant (JCMA) to migrate Xray properly.](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/1154351109) This guide shows how to use the Jira Cloud Migration Assistant (JCMA) to migrate Xray from Jira Server/Data Center to Cloud, focusing on strategy selection, Xray installations, prerequisites, and migration monitoring.
> ℹ️ 3. [Troubleshooting Xray Migration](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/1154711555). This page is intended to troubleshoot Xray migrations from Jira Server/Data Center to Cloud. It provides guidance on common issues, diagnostics, and recommended solutions to ensure a smooth migration.
> ℹ️
> ℹ️ Please [contact the Xray Team](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) to obtain all the documentation and tips, and to also schedule a meeting to discuss the Xray migration process.
> ℹ️ Please avoid creating multiple tickets for the same migration. **Keep all migration-related discussions in a single ticket **to prevent miscommunication, keep the conversation organized, and ensure all relevant information is available if escalation is required. We appreciate your understanding.
# Operations
## Project Usage and Maintenance
- **Project Usage:** ensure no one is actively using the projects being migrated, either on the Jira Cloud or Jira Data Center.
- **Avoid Maintenance:** do not perform Jira upgrades, re-indexing, restarts, or database operations during the migration. These activities may cause failures or data inconsistencies.
## Test Migrations
- We strongly recommend completing **at least two successful Xray Test migrations** prior to your production migration.
- Test migrations must mirror production planning exactly.
- A valid Xray app license is required to migrate Xray data; otherwise, Xray data won't be migrated to the Cloud.
- Test migrations help validate your environment, verify your Jira and Xray configuration, identify potential issues, and familiarize your team with the migration process before moving production data.
> ❌ **Proceeding directly to production without a validated Test migration may result in:**
- Migration failures or unexpected behavior.
- Longer migration windows due to unforeseen issues.
- Additional investigation and troubleshooting during the production migration.
- Delays if issues require intervention from the Development team.
## Verify Sub-Tasks and Xray Health Check
Before starting the migration, ensure that Jira Sub-Tasks are enabled and that Xray is fully operational. This is because the Xray Sub-Test Execution Issue type depends on Jira’s sub-task functionality.
If Sub-Tasks are disabled, the Sub-Test Execution Issue type may be missing, which can prevent proper migration.
### Steps to Verify and Enable Sub-Tasks
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> Go to *Jira Settings* → *Issues.*
>
> > Macro (rw-step)
>
> Locate the *Sub-tasks* section.
>
> > Macro (rw-step)
>
> If Sub-Tasks are disabled, enable them.
>
> > Macro (rw-step)
>
> After enabling Sub-Tasks, access *Xray Health Check*:
>
> - Go to *Apps* → *Manage your Apps* → *Health Check.*
>
> > Macro (rw-step)
>
> On the Health Check screen, click *Re-install Xray*.
>
> > ℹ️ This reinstallation is safe and will not affect your existing Xray data.
The Xray Health Check must be like the example below before starting any Migrations. To access it, navigate to *Jira Cloud* → *Marketplace Apps* > *Left Side Menu* > *Health Check *(Figure 1 - 1).
## User Access and Licensing
- Limit user access during migration. Creating, updating, or deleting Issues can cause failures.
- Ensure a valid Xray license is active on the instance before starting migration.
## Choose the Appropriate Migration Stage
When creating a migration plan, select the **Production** option under **Migration Stage** for the Test migration (Figure 2 - 1).
Starting a Test migration with the **Production** migration type provides more representative validation before proceeding with the final production migration.
> ⚠️ A successful migration status does not necessarily mean all data was migrated. Xray Cloud migrations can complete even when some items are not migrated. Therefore, **after each Test migration, it is important to review the Xray migration report to verify the migration results and identify any items that were not migrated successfully.**
Once a migration is complete, Xray generates a migration report detailing what was migrated successfully and whether any items failed.
**As a best practice, always review this report after the migration finishes, regardless of the migration type selected.**
To review the report:
- Go to *Jira Cloud* → *Atlassian Marketplace Apps* → *Migration* (located in the left-side menu under the Xray options).
- Select the migration name from the list.
- Review the generated migration report to verify the migration results and identify any failed or missing items.
## Xray Issue/Works Types and Issue/Work Linking Links
### Xray: Issue Types / Work Types
- In **Xray Data Center**, the Issue type is called: `Pre-Condition`
- In **Xray Cloud**, the Issue type is called: `Precondition`
The names must match **exactly** between the Data Center and Cloud **before starting the migration**.
> ℹ️ You can perform the renaming in either Jira Data Center or Jira Cloud; it does not matter which you use. What matters is that the Issue types have the same name in both instances.
In addition to the Precondition, we recommend verifying the names of other Xray Issue types to ensure consistency:
- Test.
- [Test Plan](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/160366867).
- Test Execution.
- [Test Set](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/162332685).
- [Sub Test Execution](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/160367310).
To learn how to edit these, please access the [Atlassian Documentation](https://support.atlassian.com/jira-cloud-administration/docs/add-edit-and-delete-an-issue-type/).
## Compare the Xray Works/Issues Types Hierarchies
Before starting the migration, verify that the Work Type Hierarchy is configured identically in both your Jira Data Center and Jira Cloud instances.
- Navigate to: *Jira Cloud* → Work items → *Work types*
Compare each Xray work type and ensure that the hierarchy level is the same in both environments. For example:
| Work Type / Issue Type | Jira Data Center | Jira Cloud |
| --- | --- | --- |
| Precondition | 0 | 0 |
| Test | 0 | 0 |
| Test Set | 0 | 0 |
| Test Plan | 0 | 0 |
| Test Execution | 0 | 0 |
| Sub Test Execution | -1 | -1 |
> ℹ️ The Work Type hierarchy **must** match between the source (Jira Data Center) and destination (Jira Cloud) instances.** Any differences in the hierarchy levels may cause the Xray migration to fail or lead to unexpected migration results**, such as incorrect parent/child relationships. Before running the migration, ensure that the hierarchy configuration is identical in both environments
**Example: **Figure 3 shows the expected Work Type hierarchy for the Xray Issue types in Jira Cloud. Before starting the migration, compare your Jira Data Center and Jira Cloud configurations and confirm that both instances have the same hierarchy levels for all Xray work types.
### Requirement <> Test Links
The Issue Link used for Requirement Coverage is slightly different between Xray Cloud and Xray Server/DC. To ensure that Xray Cloud will recognize these links, the Issue Link Type must be edited on Server/DC to match the link used by Xray Cloud:
- You can rename or adjust the Issue link either in Xray Cloud or Xray Data Center.
- The key requirement is that the **Issue link type matches exactly** in both instances, including:
- Link name.
- Outward description.
- Inward description.
Please see Figure 4 - 1 for reference:
> ℹ️ If you rename the link in Xray Cloud to match the one in Data Center, you may still receive the warning in the Pre-Cloud Migration Flight Checker. This happens because Xray Data Center is not connected to the Cloud, so the checker cannot verify the link directly from DC.
> ℹ️
> ℹ️ Similarly, if you rename the link in Xray Data Center to match Cloud, and the Issue link type matches in both environments, the Flight Checker can still report this warning in some cases. In this case, it can be safely ignored, and you can proceed with the migration.
## Xray Custom Fields
Make sure that the following Xray-created custom fields are added to the Test Execution Issue screen and are visible to all users in all Projects that you are migrating.
- [Begin Date](https://getxraydocs.atlassian.net/wiki/spaces/XRAY740/pages/48432493).
- [End Date](https://getxraydocs.atlassian.net/wiki/spaces/XRAY740/pages/48432493).
- [Revision](https://getxraydocs.atlassian.net/wiki/spaces/XRAY740/pages/48432493).
## Jira Data Center: Issue Security Schemes
Issue Security Schemes can restrict Xray’s access to Issues during migration. If security schemes are applied to Projects containing Xray Data, the migration may fail or produce incomplete data.
This is because during the migration, Xray Cloud will attempt to access Xray Issues on the Cloud side via the Jira REST API, but access will be denied if they are locked behind an Issue Security Scheme. However, this is only necessary during the migration process itself. Once the migration is completed, you can then remove the *Any logged in user permission* option from all Issue Security Levels, both on DC and Cloud.
### Required Actions
Temporarily set all security levels to *Any logged-in user* for all Projects (Figure 5 - 1), or remove the security schemes for all the Projects.
> ⚠️ This change is temporary after the migration; you can restore your original security schemes ([Editing an Issue security scheme).](https://confluence.atlassian.com/adminjiraserver/configuring-issue-level-security-938847117.html)
## Xray Preflight Checks
Before starting any migration, it is essential to run the Xray Preflight Checker. This ensures your projects are ready and avoids issues related to Project dependencies or Xray links.
### Purpose of Preflight Checks
The Preflight Checker helps you:
- Identify Xray links to data outside the selected Projects.
- Ensure all Projects with shared dependencies are included in the migration.
- Avoid missing links or data inconsistencies in the Cloud instance.
> ℹ️ Migrating Projects with dependencies separately can cause migration failures. Always include all dependent Projects in the same migration batch.
These checks are meant to help you plan your migration by accounting for Xray-related constraints. The checks will let you know if:
- The group of Projects that you are migrating contains any Xray links to data outside of these Projects.
- If there are any such links, Xray will let you know which Projects should be added to the migration to avoid missing links in the Cloud instance. This check should be done before any migration begins.
### Where to Access
- Location: *Administration* → *Manage Apps* → *Xray* → *Cloud Migration.*
- Here is a table listing all instance Projects. Select all the Projects for your migration and then click *Validate*. If there are no errors, you can leave this page and proceed with your migration through the [Jira Migration Assistant](https://support.atlassian.com/migration/docs/jira-cloud-migration-assistant/). If there are any errors, you can see the details and steps to fix the issues.
**Example from Figure 6:** Project `Priscila` was selected for migration. The Preflight Checker found links to other Projects not included in the migration: `YANG`, `SOFT`. Include these missing Projects in the migration to avoid issues.
After selecting the missing Projects for the preflight checks (Figure 6 - 1), validate (Figure 6 - 2). There are no more errors, meaning that the Projects can be migrated together safely.
We can now return to the Jira Migration Assistant and plan our migration across both Projects. Please see Figure 7 - 1; 2.
## Preloading Xray Data Before Migration
[Atlassian provides a feature](https://support.atlassian.com/migration/docs/migrate-jira-attachments-in-advance/) that lets you migrate Jira attachments in advance, saving you time on migration day. Xray is integrated with the Preload Attachment.
It is essential to have **Xray version 7.8.2 or the latest** installed, as this version includes the attachments feature. Additionally, you will need to ensure that **JCMA is updated to version 1.12.16 or higher**. Below is a step-by-step guide on how the preload process works:
We strongly recommend performing the Xray preload **at least four–five days before the planned migration**, especially for instances with a large volume of attachments. Depending on the size of the attachments, Xray may require additional time to process the preloaded data.
### Xray Version Requirements
- **Minimum required version:** 7.8.2 (required for preloading attachments and other migration features).
- **Recommended:** always use the latest Xray version to benefit from performance improvements, bug fixes, and migration enhancements.
### JCMA Version Requirements
- **JCMA ≥ 1.12.16:** no feature flags are required. The option *Preloadable app data only* is available on the Projects screen (Figure 6 - 1).
- If the option does not appear, contact Atlassian to enable the feature flag.
Please see Figure 8 - 2 for reference.
### Allow Sufficient Time for Xray Preload Attachment Processing
We strongly recommend performing the Xray preload **at least four or five days before the planned migration**, especially for instances with a large volume of attachments. Depending on the size of the attachments, Xray may require additional time to process the preloaded data.
> ℹ️ The Xray preload does not work exactly like the standard Jira preload. The process involves the following steps:
- Jira exports the relevant data and attachments to Atlassian's S3 storage.
- Once the preload is completed for all projects, Atlassian sends an event to Xray indicating that the preloaded data is available.
- Xray then starts processing the preloaded attachments.
- Once Xray completes this processing, the attachments are stored in Xray's S3 storage and are ready to be used during the migration.
Therefore, **the completion of the Jira preload does not necessarily mean that the Xray attachments are already ready for migration**. Allowing four or five days, or more for larger attachment volumes, gives Xray sufficient time to complete its processing.
> ℹ️ **Tip:** Once the preload has completed for all projects, inform Xray Support so we can verify whether Xray has started processing the preloaded attachments. If you see an Incomplete or Error status, check the [Xray Preload Attachment Statuses documentation](https://docs.getxray.app/space/ProductKB/289669151/[Xray]+Server%2FDC+to+Cloud+Migrations+(JCMA)+-+Understanding+the+Xray+Preload+Attachment+Statuses) for the recommended actions. If further investigation is needed and if you don’t have an already open Support ticket, open one and attach the Jira Support.zip file as soon as possible, as the logs can be overwritten by newer logs.
### Additional References
For more details on preloading app data before migration, see [Atlassian's official documentation](https://support.atlassian.com/migration/docs/preload-app-data-before-migration/).
Following these steps ensures the preload process works as expected, helping to achieve a smoother migration with minimal downtime.
> ℹ️ Go [here](https://docs.getxray.app/space/XRAY/301505508) to see more about Xray attachments.
## Archived Issues and Projects
- **Archived Issues:** Xray data for archived Issues is **not exported** during migration. The Jira Issues themselves will be migrated, but their associated Xray data will not appear in Cloud. **The migration will still succeed** in this case.
- **Archived Projects:** if a Project is archived, the migration will fail. All Projects must be unarchived before migration to ensure a successful transfer.
## Run Xray Integrity Checker in Jira Data Center Before Every Migration
It is important to run the [Xray Integrity Checker](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301668466) before every migration, whether it is a Test or production migration.
Running the Integrity Checker helps verify that Xray data in Jira Data Center is consistent and identifies potential data integrity issues to address before starting the migration.
We recommend running the Integrity Checker **in batches**, rather than checking all entities at once. For example, you can start by checking **Test Runs**, then **Test Steps**, and finally the remaining Xray entities (Figure 9).
## Xray and Jira Cloud Location
Ensure your Xray Cloud instance is **located close to your Jira Cloud / Data Center instance**.
For example, if your Jira Cloud is pinned in Germany and Xray Cloud is in the US, you may experience performance issues during migration and slower overall usage of Xray Cloud.
Both Jira Cloud and Xray Cloud must be in the same region or closer. Currently, Xray offers [data residency options](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUDDRAFT/pages/44838317) in the EU (Frankfurt - Germany), Australia, and the US.
## Migrating from Xray Standard/Xray Enterprise to the Cloud
When moving to the Cloud, confirm which apps you will need to fulfill your needs.
We recommend you compare[ the offers](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301697915) to select the best option for your use case. Also, be sure that if you select the Xray Cloud Standard, you are [aware of the storage limit](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUDDRAFT/pages/44838299) and [API rate Limit](https://getxraydocs.atlassian.net/wiki/spaces/ProductKB/pages/46268656).
> ⚠️ Learn more about the Xray tiers differences [here](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/465109002), or [contact our Sales team](https://www.getxray.app/contact-us) to learn more.
Below are the correct configurations depending on your migration path:
### Migrating Xray DC (Standard) → Xray Cloud (Standard)
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> Navigate to:** ***Jira Administration* → *Manage Apps* → *Xray* → *Cloud Migration*.
>
> Set the Cloud Migration target:** **`Xray Standard` and click *Save*.
>
> > Macro (rw-step)
>
> Go to: *Jira Administration *→ *Migration to Cloud Assistant home* → *Assess your apps*
>
> Select *Xray* (Figure 10 - 1) and then *Needed in Cloud* (Figure 10 - 2).
>
> 
### Migrating Xray Enterprise DC → Xray Cloud (Standard)
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> Navigate to:** ***Jira Administration* → *Manage Apps* → *Xray* → *Cloud Migration*.
>
> Set the Cloud Migration target:** **`Xray Standard,` and click *Save*.
>
> > Macro (rw-step)
>
> Go to: *Jira Administration *→ *Migration to Cloud Assistant home* → *Assess your apps *(Figure 11 - 1).
>
> 
### Migrating Xray DC (Standard) → Xray Enterprise Cloud
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> Before you start any process, you must install the Xray Enterprise app on your Jira Data Center.
>
> > Macro (rw-step)
>
> Navigate to:** ***Jira Administration* → *Manage Apps* → *Xray* → *Cloud Migration*.
>
> Set the Cloud Migration target:** **`Xray Enterprise` and click *Save*.
>
> > Macro (rw-step)
>
> Go to: *Jira Administration *→ *Migration to Cloud Assistant home* → *Assess your apps*.
>
> Select *Xray* *Enterprise*, and then *Needed in Cloud* (Figure 12).
>
> 
### Migrating Xray Enterprise DC → Xray Enterprise Cloud
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> Navigate to:** ***Jira Administration* → *Manage Apps* → *Xray* → *Cloud Migration*.
>
> Set the Cloud Migration target:** **`Xray Enterprise` and click *Save*.
>
> > Macro (rw-step)
>
> Go to: *Jira Administration *→ *Migration to Cloud Assistant home* → *Assess your apps*.
>
> Select *Xray* *Enterprise* (Figure 13 - 1) and then *Needed in Cloud* (Figure 13 - 2).
>
> 
> Macro (rw-ui-expands-macro)
>
> > Macro (rw-expand)
>
> If you have questions or technical issues, please [contact the Support team via the Customer Portal (Jira service management)](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28) or [send us a message using the in-app chat](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301501383).