Migration via JCMA

Applies to Zephyr Squad Server 6.2 and 4.8, last modified on December 30, 2021

Important notice:

  • The app data migration via Jira Cloud Migration Assistant (JCMA) is in Public Beta to all users.

  • For more information about Atlassian’s app migration timelines, visit their blog and Cloud Roadmap.

Supported versions

JCMA support is available only for Zephyr Squad Server 6.x used in Jira Server 8.x.

Zephyr Squad Server 4.x (used in Jira Server 7.x) does not support JCMA.

Pre-migration steps

In Jira Server

  1. Upgrade Zephyr Squad Server to at least version 6.2.3 (this is the minimum recommended version for JCMA migration).

  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.

  4. Navigate to Apps > Manage apps > JCMA Migration and click Register listener to register your Jira Cloud instance for migration:

    Register listener

    Click the image to enlarge it.

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

Add permissions

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

To add it to the group:

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

  2. Click Show details for the needed group.

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

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

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