---
title: "How to Plan the Xray DC Migration to the Cloud"
canonical: "https://docs.getxray.app/space/XRAY/1152811013/How%20to%20Plan%20the%20Xray%20DC%20Migration%20to%20the%20Cloud"
format: markdown
---
> Macro (rw-ui-expands-macro)
>
> > Macro (rw-expand)
>
> > Macro (toc)
# Introduction
This documentation . It helps customers, Xray customers, and Xray Partners/Atlassian teams through the entire migration process, helping with planning, validation, test migrations, reviews, and the execution of the production migration.
> ⚠️ This guide does not cover the Xray migration process/best practices, how to use the Jira Cloud Migration Assistant (JCMA) to perform the Xray migration, or how to troubleshoot the Xray migration. Those topics are covered in the dedicated Xray documentation page.
> ℹ️ 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. [Xray Pre-Migration Best Practices](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/1154613253). This documentation provides a comprehensive, step-by-step guide for migrating Xray Data Center data to Xray Cloud.
> ℹ️ 2. [How to use the 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 document 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.
# Operations
## Discovery and Assessment
- Analyze the existing Xray Data Center environment by identifying the size of the Xray data:
- Depending on the total number of [Test Runs](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301502714), that migration can take some time, so this process to determine the size of the Xray data is really important. Also, be aware that updating the Xray Data version is necessary to take advantage of all the performance improvements, new features, and bug fixes.
- Determine dependencies between the Projects using the Xray Dependency map.
- Download the dependency map: shows which Projects are linked and helps identify which projects can be migrated together. Found under *Manage Apps > Xray > Cloud Migration > Preflight *(Figure 1 - 1).
- Once you click the *Download the dependency map* button (Figure 1 - 1), it downloads the following TXT file (Figure 2), showing which Projects are linked helps identify which Projects can be migrated together.
- Verify whether the migration will be planned as a single batch or multiple batches.
- Xray is incompatible with some apps during the migration; [be aware of this](https://getxraydocs.atlassian.net/wiki/spaces/ProductKB/pages/192380971). Please check our documentation**: **[Add-ons that are currently incompatible with Xray data migration](https://docs.getxray.app/space/ProductKB/192380971)
> ℹ️ Ask the [Xray Migration Team](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) to get all the documentation, tips, and also have a meeting to talk about 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.
### What is Considered a Big Customer Data
As mentioned above, understanding the size of your data is very important, as it significantly impacts the effort and time required for migration. The items that usually take the most time to migrate are:
- Test Runs are often massive in number.
- Attachments can be huge in size.
| **Object** | **Mapping to App Assessments Data** | **Guardrail** | **Risk** | **Recommendations** |
| --- | --- | --- | --- | --- |
| `Test runs` | `TOTAL_TEST_RUNS` | `<1M < 4` | Low | No actions needed |
| `TOTAL_TEST_RUNS` | `5M<10M` | Medium | [Contact Xray Support](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) |
| `TOTAL_TEST_RUNS` | `>10M` | High | [Contact Xray Support](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) |
| `Xray Attachment size` | `TOTAL_ATTACHMENT_SIZE` | `<100GB` | Low | No actions needed |
| `TOTAL_ATTACHMENT_SIZE` | `>100GB` | Medium | - [Contact Xray Support](https://jira.getxray.app/servicedesk/customer/portal/2/create/37)
- **Preload Xray attachments**: Atlassian provides a feature to migrate Jira attachments in advance. Xray is now integrated with this functionality, so you can preload Xray attachments before the migration day. This can reduce overall migration time. |
| `TOTAL_ATTACHMENT_SIZE` | `>1.5TB` | High | - [Contact Xray Support](https://jira.getxray.app/servicedesk/customer/portal/2/create/37)
- **Preload Xray attachments**: Atlassian provides a feature to migrate Jira attachments in advance. Xray is now integrated with this functionality, so you can preload Xray attachments before the migration day. This can reduce overall migration time. |
### Xray Recommendations for Customers with Large Datasets
- Preload Xray attachments using Atlassian’s attachment migration feature.
- Download and analyze the Xray Dependency Map.
- Analyze data size using Xray 8.2.2+ dependency grouping.
- Update Xray Data Center to the latest version. Please see [this article](https://getxraydocs.atlassian.net/wiki/spaces/ProductKB/pages/46269308).
- Ensure Xray Cloud is hosted in the same region as Jira Data Center to avoid performance issues.
### How to Identify the Size of the Xray Data in the Data Center
#### Option 1
Since the Xray DC version 8.2.2,** **the Xray Dependency map shows which Projects are linked and helps you identify which ones can be migrated in groups. Also, this shows you the total of Xray data for all the groups, etc.
You can find this in the Xray Preflight screen under *Manage Apps > Xray > Cloud Migration*. Please also share the dependency map with the Xray Support team.** **
#### Option 2
Running SQL queries in your database to know the size of your Xray instance in the DC. Please also share the results with the Xray Support team in a CSV format.
```
SELECT
p.pname,
p.pkey,
COUNT(CASE WHEN it.pname = 'Test' THEN 1 END) AS test_count,
COUNT(CASE WHEN it.pname = 'Pre-Condition' THEN 1 END) AS pre_condition_count,
COUNT(CASE WHEN it.pname = 'Test Set' THEN 1 END) AS test_set_count,
COUNT(CASE WHEN it.pname IN ('Test Execution', 'Sub Test Execution') THEN 1 END) AS test_execution_count,
COUNT(CASE WHEN it.pname = 'Test Plan' THEN 1 END) AS test_plan_count,
COALESCE(tr.test_run_count, 0) AS test_run_count,
COUNT(ao.ID) AS num_attachments,
ROUND(SUM(CAST(ao.FILE_SIZE AS NUMERIC) / 1048576), 2) AS total_filesize_MB
FROM project p
JOIN jiraissue j ON p.id = j.project
JOIN issuetype it ON it.id = j.issuetype
LEFT JOIN AO_8B1069_ATTACHMENT ao ON ao.ISSUE_ID = j.id
LEFT JOIN (
SELECT
ji.project,
COUNT(*) AS test_run_count
FROM AO_8B1069_TEST_RUN tr
JOIN jiraissue ji ON tr.TEST_EXEC_ISSUE = ji.id
GROUP BY ji.project
) tr ON tr.project = p.id
GROUP BY p.pkey, p.pname, tr.test_run_count
UNION ALL
SELECT
'TOTAL' AS pname,
'' AS pkey,
SUM(test_count),
SUM(pre_condition_count),
SUM(test_set_count),
SUM(test_execution_count),
SUM(test_plan_count),
SUM(test_run_count),
SUM(num_attachments),
SUM(total_filesize_MB)
FROM (
SELECT
COUNT(CASE WHEN it.pname = 'Test' THEN 1 END) AS test_count,
COUNT(CASE WHEN it.pname = 'Pre-Condition' THEN 1 END) AS pre_condition_count,
COUNT(CASE WHEN it.pname = 'Test Set' THEN 1 END) AS test_set_count,
COUNT(CASE WHEN it.pname IN ('Test Execution', 'Sub Test Execution') THEN 1 END) AS test_execution_count,
COUNT(CASE WHEN it.pname = 'Test Plan' THEN 1 END) AS test_plan_count,
COALESCE(tr.test_run_count, 0) AS test_run_count,
COUNT(ao.ID) AS num_attachments,
ROUND(SUM(CAST(ao.FILE_SIZE AS NUMERIC) / 1048576), 2) AS total_filesize_MB
FROM project p
JOIN jiraissue j ON p.id = j.project
JOIN issuetype it ON it.id = j.issuetype
LEFT JOIN AO_8B1069_ATTACHMENT ao ON ao.ISSUE_ID = j.id
LEFT JOIN (
SELECT
```
### Identifying Archived Projects with Xray Data
Before performing an Xray migration, it’s crucial to ensure that no archived Projects contain Xray data. If an archived project has Xray entities, the migration will fail. **All Xray Projects must be unarchived** before migration to guarantee a successful transfer.
This guide provides a **single SQL query** to view all projects, including their archived status and Xray-related details.
- Which projects are archived.
- Which projects are Xray Requirement Projects.
- Which projects contain Xray entities (Tests, Test Executions, Test Sets, etc).
Please note that the following SQL query is intended for **MySQL Server**:
```
SELECT
p.id,
p.pkey,
p.pname,
CASE
WHEN pn.propertyvalue = 1 THEN 'Archived'
ELSE 'Active'
END AS archived_status,
CASE
WHEN pt.propertyvalue LIKE CONCAT('%', p.id, '%')
THEN 'Yes'
ELSE 'No'
END AS is_xray_requirement_project,
CASE
WHEN EXISTS (
SELECT 1
FROM jiraissue ji
JOIN issuetype it ON ji.issuetype = it.id
WHERE ji.project = p.id
AND it.pname IN (
'Test',
'Test Execution',
'Test Set',
'Sub Test Execution',
'Test Plan',
'Pre-Condition'
)
) THEN 'Yes'
ELSE 'No'
END AS has_xray_entities
FROM project p
LEFT JOIN propertyentry pe
ON pe.entity_id = p.id
AND pe.property_key = 'jira.archiving.projects'
LEFT JOIN propertynumber pn
ON pn.id = pe.id
LEFT JOIN propertyentry req_pe
ON req_pe.property_key = 'requirement-coverage.projects'
LEFT JOIN propertytext pt
ON pt.id = req_pe.id
ORDER BY
archived_status DESC,
is_xray_requirement_project DESC,
has_xray_entities DESC,
p.pkey;
```
The result will be like the following (Figure 3):
### Setup Validation
- Prepare the Xray Cloud environment and the Xray Data Center.
- Validate that all processes for a successful migration are being followed correctly. Please review our documentation, *[Jira Cloud Migration Guide](https://docs.getxray.app/display/XRAY/Jira+Cloud+Migration+Guide)*, especially the section on *[Unsuccessful Migrations](https://docs.getxray.app/space/XRAY/301473290/Jira+Cloud+Migration+Guide#Unsuccessful-Migrations)*.
- [Inform the Xray team](https://jira.getxray.app/servicedesk/customer/portal/2/create/37), and if necessary, the Xray team can schedule a meeting to review the instance before starting any migrations.
### Test Migration Execution
- Perform the Test migrations the same way you plan to migrate in production; they must mirror the Production planning migrations.
- If the Test migration is successful, perform the post-checks and run additional Tests; a single migration Test is not enough.
- If the Test migration failed, [inform the Xray team](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) so that Xray Migration team can investigate and find the cause of the errors.
- When reaching out to the Xray Cloud Migration for assistance, please include the following:
- Migration plan name.
- Cloud URL.
- Jira Support ZIP file.
### Production Migration
After all Tests have been successfully completed, you’re ready to proceed with the Production Cloud migration.
> ℹ️ Before starting the Production migration, it’s important to have an early alignment conversation with the Xray Cloud Migration team to review your migration plan.
During the production migration, just like in the Test migration, make sure to:
- Disable all automations in Jira Data Center.
- Set Jira to read-only mode.
- Follow all Xray migration processes mentioned in the [Xray Cloud Migration documentation](https://docs.getxray.app/space/XRAY/301473290/Jira+Cloud+Migration+Guide#Required-steps-to-migrate).
> ⚠️ Please [inform the Xray team](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) before starting the migration so we can perform a quick review before you click *Run* or start creating the migration plan.
> 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).