Migration via JCMA

Applies to Zephyr Squad Server 9.0.1 and 4.8, last modified on September 20, 2023

Recommended Server versions

For optimal performance and compatibility, we strongly advise to update Zephyr Squad to the most recent Server version available. If your license is not active, kindly raise a ticket, and our Sales team will assist you.

If you do not prefer upgrading to the latest server version, consider the following factors:

  • JCMA Support: JCMA (Jira Configuration Manager Assistant) support is exclusively available for Zephyr Squad Server version 6.x (for Jira Server versions 8.x.)
  • Large Project Consideration:In cases where any of your projects contain over 1,000 folders, ensure your minimum Zephyr Squad Server version is 8.0.2 for Jira 8.x or 9.1.2 for Jira 9.x.
  • Migration Customization:For versions 8.3.0 (Jira 8.x) or 9.4.0 (Jira 9.x), you have the option to selectively skip the migration of Test Executions and Test Steps change history data which accounts for approximately 60% of the total migration data.

Pre-migration steps

In Jira Server

  1. Upgrade Zephyr Squad Server to the latest available version. Kindly refer to Recommended Server versions above.

  2. Back up the data of your Zephyr Squad Server.

  3. Install the Jira Cloud Migration Assistant plugin in your Jira Server instance.

    Note: In Jira Server 8.14, the migration assistant is installed by default.

    To install the plugin manually:

    • In Jira Server, go to Settings > Manage apps.

    • Choose Find new apps in the sidebar.

    • Enter Jira Cloud Migration Assistant in the search bar.

    • Once the plugin is found, click Install:

      Jira Cloud Migration Assistant

      Click the image to enlarge it.

      Alternatively, you can install it from the Atlassian Marketplace.

In Jira Cloud

  1. Create an XML backup of your empty Jira Cloud instance for future use if you need to reset it.

  2. Install Zephyr Squad Cloud in your Jira Cloud instance.

  3. If you have already been using using Jira Cloud and it has projects with the same name or project key as Jira Server projects, delete those projects from Jira Cloud.

Migration steps

You can create multiple migration plans with different sets of Jira projects. To migrate Zephyr data, you must select the Zephyr Squad app together with the relevant Jira projects in the same migration plan, otherwise, the Zephyr Squad data will not be migrated (the migration will be stuck at 0%).

To start migrating your projects, users, and groups, navigate to Settings > System > Migrate to cloud in your Jira Server instance and follow the steps described in the Atlassian Jira documentation:

Use the Jira Cloud Migration Assistant to migrate

The Migrate to cloud button

Click the image to enlarge it.

Make sure to wait until the migration completes (the status must be Complete):

Migration complete

Click the image to enlarge it.

To review the migration status:

  1. Go to your Jira Cloud instance and navigate to Apps > Manage apps > JCMA Migration.

  2. Click the refresh button to view the current migration (the migration will appear in the list). Wait for the status to become Success:

    Migration dashboard

    Click the image to enlarge it.

    Note: Each migration in the list has the Action button. Clicking the button opens a dropdown that you can use to view the migration details and download the migration report and logs:

    Action menu

    Click the image to enlarge it.

Post-migration steps

Once you import the Zephyr Squad data into Cloud, you must check three main data points: Test Cases, Test Executions, and Cycles. This will help you validate whether your data on Cloud matches the data on Server.

Valdating Migrated Data

The best way to validate the imported data is to run some JQLs or ZQLs queries. The Test Summary page is expected to present different results on Server and Cloud.

You must check the following data points:

  • Number of Tests on Cloud

    To validate the number of tests:

    1. Go to Jira > Filters > Advanced Issue search

    2. Enter this JQL query in the search box:

      project=ProjectKey AND issuetype=Test
    3. Press Enter. Check the result displayed.
  • Number of Test Executions on Cloud

    To validate number of test executions:

    1. Go to Project > Squad > Search Test Executions

    2. Enter this JQL query in the search box:

      project=ProjectKey AND executionStatus in (status1, status2, status3)
      Note: Add all execution statuses separated by a comma.
    3. Press Enter. Check the result displayed.
  • Number of Cycles on Cloud

    To validate the number of Cycles:

    1. Go to Project > Squad > Cycle Summary

    2. Enter this JQL query in the search box:

      project=ProjectKey AND issuetype=Test
    3. Press Enter. Check the result displayed.

Add permissions

To view and edit migrated issues, your Jira account must belong to all migrated user groups. JCMA does not add your Jira account to migrated user groups for security reasons.

To add your Jira account to the group:

  1. Go to Settings > User management, then click Groups on the left.

  2. Click Show details for the needed group from the list of groups.

  3. Click Add group members to include your account to the group.

  4. Repeat these steps to add your account to other groups. See Atlassian documentation for details.

You may need to add the Project Role (atlassian-addons-project-access) to all the project permissions schemes because of Atlassian’s bug MIG-672.

Clear cache and reindex data

Once the migration status is Success, do the following:

  1. Select General Configuration in the Jira sidebar to open the Zephyr Squad Cloud settings.

  2. Scroll down the page and click Clear Cache and Clear Permission Cache:

    Clear cache

    Click the image to enlarge it.

  3. While staying on the General Configuration page, scroll up to the Re-Index section and re-index all your projects:

    • Select Project Metadata and click Re-Index.

    • Select Executions and click Re-Index.

    Re-index projects

    Click the image to enlarge it.

  4. On the same page, check the value of the Sort Cycles Order option. If it is Custom order, you also need to reset the sorting for the migrated projects:

    • Add the migrated projects to the Reset Custom Order list.

    • Click reset.

    Reset custom order

Now you can open your project in Zephyr Squad Cloud and validate the migrated data. If no issues are found, you can start working with your project.

Update Test Automation jobs

If you have Test Automation jobs that use ZBot, you need to configure a new ZBot agent for Zephyr Squad Cloud and modify the migrated jobs to use the new ZBot agent.

  1. Download and install ZBot for Zephyr Squad Cloud:

    https://atombuild.zephyr4jiracloud.com/atom.zip

    The installation instructions are in the README file inside the archive.

  2. In Jira Cloud, navigate to the Zephyr Squad > Test Automation page.

  3. Find jobs with Automation Type = ZBot. Edit each of these jobs and select the new ZBot agent.

    Updating ZBot test automation jobs

    Click the image to enlarge it.

    Selecting a ZBot agent in job settings

    Click the image to enlarge it.

Now you can execute and schedule these automation jobs again.

Retry migration

You can restart the JCMA migration within 14 days after it failed. To do that:

  1. Go to Apps > Manage your apps and click JCMA Migration.

  2. Click Action next to the failed migration.

  3. Select the Retry migration item.

    Retry item

    Click the image to enlarge it.

  4. Select any or all of the projects, or failed projects only, click Retry.

    Retry menu

    Click the image to enlarge it.

The migration will restart, and its status will change to IN PROGRESS.

Known issues and limitations

For the common JCMA issues and limitations, see the Atlassian documentation:

The following limitations are specific to the Zephyr Squad app data migration.

  • Data that is not migrated:

    • Tests with issue-level security and their details (steps, executions, and so on).

    • Archived tests and their details (steps, executions, and so on).

    • ZBot agents used by Test Automation jobs. You need to configure new Zbot and update the migrated jobs to execute automation tasks using newly created Zbot.

  • Miscellaneous:

    • Timestamps in issues might be different in Jira Server and in Jira Cloud. Since Jira Cloud uses UTC, there might be a shift in time zones if the Jira Server instance uses another time zone.

    • Sorting tests in the Cycle Summary by ID may produce incorrect sorting order.

FAQ

See our Cloud Migration FAQ for quick answers to some commonly asked questions.

Support and troubleshooting

Should you have any questions, please visit our Support Portal where you can search for an answer in Zephyr Squad Community or contact our Customer Care team.

See Also

Zephyr Squad Features - Server/Data Center vs Cloud
Cloud Migration FAQ

Highlight search results