---
title: "How to Use the Jira Cloud Migration Assistant to Migrate Xray"
canonical: "https://docs.getxray.app/space/XRAY/1154351109/How%20to%20Use%20the%20Jira%20Cloud%20Migration%20Assistant%20to%20Migrate%20Xray"
format: markdown
---
> Macro (rw-ui-expands-macro)
>
> > Macro (rw-expand)
>
> > Macro (toc)
# Introduction
This guide explains how to use the [Jira Cloud Migration Assistant (JCMA)](https://support.atlassian.com/migration/docs/jira-cloud-migration-assistant/) to successfully migrate Xray from Jira Server or Data Center to Jira Cloud. It focuses on:
- Selecting the appropriate migration strategy.
- Configuring Xray correctly in JCMA.
- Understanding prerequisites and limitations.
- Executing and monitoring the migration process.
> Macro (panel)
>
> 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 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.
> 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.
> ⚠️ Before starting any Test migration, please [contact the Xray Cloud Migration Support team](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) and inform them about your migration plans. We will provide guidance, share all necessary steps, and support you throughout your migration to the Cloud.
> ⚠️
> ⚠️ 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
## 1 - Selecting the Migration Strategy
### 1.1 - Jira Cloud Migration Assistant
Atlassian provides the JCMA to help users transition from an on-premises Jira instance (Server or Data Center) to Jira Cloud.
Thanks to our integration with the JCMA, migrating from Xray Server/Data Center to the Cloud is straightforward and user-friendly.
### 1.2 - Creating a Migration Plan
When creating the migration plan, the Jira Cloud Migration assistance will provide options for the migration stage and then for the migration. It’s really important to select the correct ones.
### 1.3 - Choose the Appropriate Migration Stage
When creating a migration plan, select the **Production** option under **Migration Stage** for the Test migration (Figure 1 - 1).
Starting a Test migration with the **Production** migration type provides more representative validation before proceeding with the final production migration.
Please note that 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.
### 1.4 - Migration Options
The JCMA app provides two approaches for migrating to the Cloud:
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> **Choose What to Migrate (recommended). **This option allows you to select specific Projects, Issue types, or configurations to migrate. It offers flexibility by enabling a phased migration and reducing the risk of transferring unnecessary or outdated data.
>
> Select the option called **ALL** Project data by enabling the options from the image example below (Figure 2). From there, you can select the Projects to migrate.
>
> 
>
> > Macro (rw-step)
>
> **Migrate All Data At Once (not recommended). **This option migrates all data from your Server/Data Center instance to the Cloud in a single operation. While it may seem efficient, it’s important to note the following:
>
> - **Data Volume**: large datasets can prolong migration times and potentially lead to errors or interruptions during the transfer.
> - **Increased Complexity**: migrating everything at once may bring over unnecessary data, such as outdated configurations, unused custom fields, or inactive projects, which could clutter your Cloud environment.
> - **No Phased Testing**: unlike selective migration, this approach doesn’t allow for phased validation, making it harder to troubleshoot issues.
>
> For these reasons, **we recommend using the *****Choose What to Migrate*** option for most scenarios. However, if your dataset is relatively small or you’re confident in its consistency, the *Migrate All Data At Once* can be a viable option.
>
> > ℹ️ Atlassian has discontinued the *Migrate All Data At Once* option. Learn more [here](https://community.atlassian.com/t5/Atlassian-Migration-Program/Discontinuing-migrate-all-data-at-once-and-we-re-going-all-in-on/ba-p/2621674?utm_campaign=immediate_general_article&utm_content=topic&utm_medium=email&utm_source=atlcomm).
## 2 - Xray Migration Limitations
> Macro (panel)
>
> It is essential to align expectations before starting the migration.
- **Migration Drift Not Supported:** all linked data must be migrated together to ensure data integrity in the Cloud.
- **Automated Step Library: **the** **automated Steps Library will be migrated, but you need to perform a re-index. Check more details [here](https://getxraydocs.atlassian.net/wiki/spaces/ProductKB/pages/140509271).
- **Cucumber Settings **will not be migrated to the Cloud ([Miscellaneous](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301407212) settings section).
- **Gadget Configuration: **the configuration of [Xray gadgets](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301405409) will not be migrated.
- **Xray Notifications: **Xray Notifications (events) will not be migrated. Xray Cloud does not provide this feature.
- **[Document Generator](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUDDRAFT/pages/44838033)****: **templates migrated from the Server must be revised once there are some differences between the Server and Cloud versions.
- **Archived Issues: **the Xray data for archived Issues is not exported during the migration. Therefore, the Jira Issues will be exported, and after the migration, there will be no Xray data related to them on the Cloud side. So to summarize it:
- If you migrate archived Issues, the Xray data for those issues will not be migrated; however, the migration will not fail due to this.
- If you migrate archived Projects, then the migration will fail. In other words, projects must be unarchived for the migration to be successful.
- **Project-Level Settings **are transferred when migrating from Xray Data Center to Xray Cloud (except for [Default Column Layouts](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301672631)).
> ℹ️ If you want to migrate archived Projects, you first need to unarchive them.
> ℹ️
> ℹ️ Follow [this article](https://getxraydocs.atlassian.net/wiki/spaces/ProductKB/pages/140705894) to understand how to check which Projects are archived.
## 3 - The Jira Migration Process
Now that you've assessed, planned, and prepared the migration, you are ready to go to Jira Cloud Migration Assistant and start the migration.
If you want to know how to start the migration, please go to [Atlassian Documentation.](https://support.atlassian.com/migration/docs/choose-what-jira-data-to-migrate-using-the-assistant/)
### 3.1 - Migrating All Users
It is recommended that you select the option *All users and groups from the Jira directory* (Figure 3) when choosing which users to migrate in the Jira Migration Assistant. This is due to the way that Jira checks which users are related to a project, which will not consider users assigned to Test Runs.
### 3.2 - When the Xray Migration Starts
The Xray migration starts right after the Jira migration. While Xray is migrating Projects, the Xray app screens/actions will be disabled until the end of the migration. Those screens will display a warning and an action to let the user see the current progress of the migration. This progress shows details about what is being done (Figure 4).
### 3.3 - How to Check the Xray Migration Status
Xray Cloud also provides a page in the app administration section that lists all migration plans in progress and completed. Here, the Jira administrator can see the migration history and the ongoing migration plans. Learn more about it [here](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUDDRAFT/pages/44827873).
Access: *Jira Cloud* → *Gear Icon* → *Marketplace Apps* → Left Side Menu and click *Cloud Migration for the Xray* options. Then you see the Migration Report below (Figure 5).
## 4 - Migrating from Xray Standard/Xray Enterprise App 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 the Xray Sales team](https://www.getxray.app/contact-us) to know more.
Below are the correct configurations depending on your migration path:
### 4.1 - 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 6 - 1) and then *Needed in Cloud* (Figure 6 - 2).
>
> 
### 4.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 7 - 1).
>
> 
### 4.3 - Migrating Xray DC (Standard) → Xray Enterprise Cloud
> Macro (rw-ui-steps-macro)
>
> > Macro (rw-step)
>
> Before you perform any process, you must install Xray Enterprise on Jira DC.
>
> > 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 8).
>
> 
### 4.4 - 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 9 - 1) and then *Needed in Cloud* (Figure 9 - 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).