--- title: "Jira Xray Cloud Migration Guide" canonical: "https://docs.getxray.app/space/XRAY/301473290/Jira%20Xray%20Cloud%20Migration%20Guide" format: markdown --- > Macro (rw-ui-expands-macro) > > > Macro (rw-expand) > > > Macro (toc) # Introduction This page provides an overview for Xray customers, Jira Administrators, and Atlassian/Xray Partners who are migrating from Xray Data Center to Xray Cloud using the Jira Cloud Migration Assistant (JCMA). It summarizes how Xray migration works, the main migration methods, and preparation steps, and provides links to detailed guidance in this page’s child pages. > ℹ️ Here you can find a high-level overview of Xray Cloud migration. For a successful migration, you should also plan your migration strategy, understand how to use the JCMA in detail, and contact the Xray Cloud Migration team. These topics are covered in the following 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. [How to use the Jira Cloud Migration Assistant to migrate Xray properly.](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/1154351109) This guide shows how to use the Jira Cloud Migration Assistant to migrate Xray from Jira Server/Data Center to Cloud, focusing on strategy selection, Xray installations, prerequisites, and migration monitoring. > ℹ️ 4. [Troubleshooting Xray Migration](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/1154711555). This documentation 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. > ℹ️ 5. [Xray Server and Xray Cloud](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301697915).** **This documentation helps you understand the differences between Xray Cloud and Xray Data Center**.** # Getting Started ## Welcome to Xray Cloud to DC/Server Migration Many organizations are moving to Jira Cloud. Atlassian provides the [JCMA](https://confluence.atlassian.com/cloud/use-the-jira-cloud-migration-assistant-to-migrate-from-server-to-cloud-993925215.html) to help you transition from an on-premises Jira instance (Server or Data Center) to Jira Cloud. Thanks to Xray’s integration with the JCMA, migrating Xray data from the Server/Data Center to the Cloud is straightforward when following the recommended steps. > ⚠️ 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. > ℹ️ - Avoid creating, modifying, or deleting Issues related to Xray or connected Projects during migration, as this can cause failures if more than 100 Issues are missing. > ℹ️ - Disable all automation and third-party app modifications to prevent exceeding this limit. > ℹ️ - Ensure all Jira projects are fully migrated; otherwise, Xray won’t find the expected Issues. > ℹ️ - Remove Issue security schemes or set them to "Any logged-in user" before migration to avoid permission-related failures. ## How the Xray Migration Process Works To provide a clear picture of the Xray migration process, it unfolds in the following steps: > Macro (rw-ui-steps-macro) > > > Macro (rw-step) > > **Jira Migration Complete**: the Jira Projects and their core data have been migrated to Jira Cloud via JCMA. > > > Macro (rw-step) > > **Xray Migration Starts**: once the Jira migration process is complete, the Xray migration process begins. > > > Macro (rw-step) > > **Data Export and Import:** Xray exports the data from the Data Center and imports it to the Xray Cloud. The duration depends on the size of your Xray data footprint. > > > ℹ️ The overall duration of migration depends on the Project size, the number of linked Issues, attachments, and other Xray entities. Preloading attachments and running preflight checks can help streamline the process. ## Key Points > ⚠️ As with any other move, you first need to conduct a comprehensive assessment. Avoid assessing and planning data migration too late in your migration journey. Xray is really integrated with Jira, so its migration can be as complex as Jira’s. - Xray migration must be performed alongside Jira migration. - Proper planning, Xray data set analysis, and adherence to migration steps are essential to avoid issues. - Determine the current Xray Data Center Version. - Evaluate differences between Xray Cloud and Xray Server/DC. - Evaluate the Xray Cloud offering - [Standard, Advanced, or Enterprise](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUDDRAFT/pages/380764204). - The Xray’s Cloud Migration team is available to support you at every step. - As a best practice, always review this report after the migration finishes, regardless of whether this is a Test or a Production migration. 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 Data Version: Minimum Required To use the Jira Cloud Migration Assistant with Xray, **you must be using a version higher than** **[Xray 7.4.2](https://docs.getxray.app/space/ProductKB/796688385/[Xray]Server%2FDC+to+Cloud+Migrations(JCMA)+Minimum+Xray+Data+Center+Version+Required+to+Migrate)****. **However, we strongly recommend upgrading to the **latest Xray version supported by your Jira Data Center version** before starting the test migration. Recent Xray releases include important migration enhancements, performance improvements, and bug fixes. **Starting with Xray 8.2.3**, the JCMA migration framework introduced significant improvements for large-scale migrations, including **parallel migration processing** and **dedicated migration service tracks**. Upgrading to the latest supported version helps ensure the best migration experience and allows you to benefit from the latest performance improvements, migration enhancements, and bug fixes. For more details about the improvements introduced in each Xray version, please access [here](https://getxraydocs.atlassian.net/wiki/spaces/ProductKB/pages/46269308). ## Importance of Performing Xray Test Migrations We strongly recommend completing **at least two successful Xray Test migrations** prior to your production migration. > ℹ️ Please [contact the Xray Cloud Migration Support team](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) as you begin planning your test migrations. We will provide guidance, share the recommended migration steps and best practices, and support you throughout your migration to Xray 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. > ℹ️ **Perform at least two successful Xray Test migrations **before your production migration. The first test migration helps identify and resolve issues, while the second confirms that the required changes have been successfully validated and that your environment is ready for production. This approach significantly increases the likelihood of a smooth and successful production migration. > ℹ️ **Use a single Xray Support ticket for each customer migration.** All questions, test migrations, production migration planning, and migration updates should be managed within the same ticket. This ensures that all migration history, discussions, and findings are centralized, allowing the Xray Support team to provide consistent and efficient assistance. ## Preloading Xray Attachments Before Migration Xray supports preloading attachments so they can be **migrated in advance of the main Xray migration**, helping reduce the time required during the migration window. More details in our documentation: [Preloading Xray Data Before Migration](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/1154613253/Xray+Pre-Migration+Best+Practices#Preloading-Xray-Data-Before-Migration) > ⚠️ **Important:** If you are using the Xray preload, we strongly recommend completing it **at least 4–5 days before your planned migration**. Xray may need additional time to process the preloaded attachments after the Jira preload completes, especially for large volumes of attachments. The Xray preload does not work exactly like the standard Jira preload. The process involves the following steps: 1. Jira exports the relevant data and attachments to Atlassian's’s S3 storage. 2. Once the preload is completed for all projects, Atlassian sends an event to Xray indicating that the preloaded data is available. 3. Xray then starts processing the preloaded attachments. 4. Once Xray completes this processing, the attachments are stored in Xray's S3 storage and are ready to be used during the migration. For more details about the Xray preload process and attachment statuses, please review the [Preloading Xray Data Before Migration](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/1154613253/Xray+Pre-Migration+Best+Practices#Preloading-Xray-Data-Before-Migration). Once the preload has completed for all projects, you can ask Xray Support to verify whether Xray has started processing the preloaded attachments. If you already have a migration support ticket, please use that ticket; otherwise, **[create a new support ticket](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28)** and include your migration details. ## Xray Support During Migrations The Xray Cloud Migration Support team is available to assist you throughout your migration process. Our support includes: - **Weekday support** for test migrations and migration planning. - **Meetings** to review the Xray migration process, discuss your migration plan, and answer any questions. - **Weekend support** for production migrations, subject to prior validation and scheduling. > ℹ️ To request weekend production migration support, you must complete **at least one successful production-like Test migration**. However, we strongly recommend completing **at least two successful Test migrations** to validate the migration process before proceeding to production. For the most representative validation, we recommend performing a production-like Test migration by migrating your **Jira Data Center production environment** to a dedicated **Jira Cloud Test site** with Xray installed. Test migrations should be completed **at least two weeks before** the planned production migration. This provides sufficient time to review the results, address any issues, and validate any required changes. We also recommend scheduling a meeting during the week of the production migration to review the plan and confirm everything is ready. > ℹ️ **Use a single Xray Support ticket for each customer migration.** All questions, Test migrations, production migration planning, and migration updates should be managed within the same ticket. This ensures that all migration history, discussions, and findings are centralized, allowing the Xray Support team to provide consistent and efficient assistance. ## Server/DC vs Cloud - Product Comparison If you are looking to migrate from Jira Server/DC to Jira Cloud, you need to consider the differences between Xray Server/DC and Xray Cloud. These differences might affect how your users work and interact with Xray. The ideas, goals, and major features are the same. However, while there is great similarity between them, there are a few subtle differences between the two versions. This is mainly due to: - **Jira architecture** - the way apps work in Server and Cloud is completely different. In Server, apps can integrate with many aspects of Jira, while on Cloud, there are a lot of integration points missing, e.g., not all JQL functions, Project Templates, calculated fields at agile boards (like Requirement status), etc. - **Product Age** - Xray Cloud is a newer product. Therefore, some features are not yet available (e.g., Historic Test Coverage report), although we plan to include them in future releases. Also, we took the opportunity to improve some features (e.g., [Project Level Settings](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUDDRAFT/pages/44838934)). - **Xray Data Center custom fields: ** - On Xray Cloud, the custom fields from Xray Data Center are no longer shown as traditional Jira custom fields due to architectural differences. - On Server/DC, Xray had direct access to Jira’s internal structures, enabling fields such as Manual Test Steps to appear on the Issue creation screen. In Cloud, apps cannot create Jira custom fields or modify Issue creation screens. - All native Xray fields (e.g., Test Steps, Test Type, Test Environments) are still fully available, but they are now displayed in the *Test Details* tab within the Issue view. - All data from the fields will be successfully migrated to Xray Cloud; it may simply appear in a different format. - To check the entire list and know where these fields are now displayed on the Xray Cloud, please access [this documentation page](https://getxraydocs.atlassian.net/wiki/spaces/ProductKB/pages/46268587). - For a full comparison between the Server/DC and Cloud versions of Xray, please refer to [Xray Server and Xray Cloud](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301697915). ## Xray Migration Limitations > ℹ️ 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: **it will not be migrated to the Cloud ([Miscellaneous](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301407212) settings section). - **Gadget Configuration: **the configuration of the [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: - 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. Read [this article](https://getxraydocs.atlassian.net/wiki/spaces/ProductKB/pages/140705894) to understand how to check which Projects are archived. > 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).