Zephyr Scale Server to Zephyr Scale Cloud Migration Guide

Applies to Zephyr Scale Server/Data Center 9.1, last modified on November 30, 2023

Note:

  • Use the Jira Cloud Migration Assistant (JCMA) provided by Atlassian, to migrate Zephyr Scale data.

  • Raise a ticket in our support portal if you need to use Jira Site Import for migration. Our Cloud Migration Manager is there to help you out.

Pre-migration steps

Allow the required domains for JCMA

Make sure your network firewall allows connections from your Jira Server to the domains used by the JCMA (check the "For JCMA plugin host communication" list)before migration.

In Jira Server

  1. Upgrade Zephyr Scale Server to the latest version here: Release Notes

  2. Back up the data of your server instance.

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

    Note: If you use Jira version 8.14, the migration assistant automatically installs on your server instance.

    To install the plugin manually:

    • Go to Settings > Manage apps in Jira Server or Data Center..

    • Choose Find new apps in the sidebar.

    • Enter Jira Cloud Migration Assistant in the search bar.

    • Click Install, once you find the plugin:

      Jira Cloud Migration Assistant

      Click the image to enlarge it.

      You can also install the plugin from the Atlassian Marketplace.

  4. Increase the log level for com.adaptavist, com.kanoah, and com.smartbear to INFO.

  5. Select all dependent projects that you want to migrate in the same migration plan. The table below explains the three types of dependencies that projects can have:

    Dependancy Description

    Call to test functionality

    Test Cases’ scripts can call/refer to Test Cases from other projects.

    Cycles with Cases from different projects

    It’s possible to add Test Cases from multiple Projects in a Cycle.

    Test Plans with Cycles from different projects

    When setting up a Test Plan, it’s possible to add Cycles that belong to different Projects.

    Issues links between projects

    The traceability feature enables links from Jira issues from different projects to a Scale entity.
Note:You can make a use of the following REST API Endpoint to see the projects for which the Zephyr Scale is Enabled or Disabled:
  • Method: GET
  • Endpoint: https://api.zephyrscale.smartbear.com/v2/projects
  • Request Response shows the Enabled parameter as True or False, here True means Enebled , False means Disabled.
  • Enabled means that the particular project is making use of Zephyr Scale.

In Jira Cloud

  1. Create an XML backup of your empty Jira Cloud instance in case you need to reset it.

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

  3. Delate projects from Jira Cloud awith the same name or project key as Jira Server projects.

What data gets migrated

Remember that Zephyr Scale Server/Data Center and Cloud versions are not exactly the same. Check the comparison of product features. We can still add to migration some of the data from features that are not available in Cloud version. Read the table below to make sure what data can/cannot be migrated.

What is migrated What is NOT migrated
  • Projects (the project itself, whether permissions are enabled in the project, whether Zephyr Scale is enabled, what issue types are disabled in the project)
  • Permissions
  • Priorities (including custom priorities but you cannot create custom priorities on Cloud currently)
  • Statuses
  • Folders
  • Labels (and the relationships between labels to entities so you see the correct labels on each entity)
  • Environments
  • Datasets (and the options within a dataset)
  • Test cases (along with the test script, and the steps if it’s a step-by-step test case)
  • Test data
  • Test case parameters (and the values passed via call to test)
  • Test plans
  • Test cycles
  • Test executions (and steps within test executions)
  • Traceability (issue links and weblinks)
  • Custom fields (and the options within single-choice or multi-choice select list custom fields)
  • Custom field values (the values in all of the entities)
  • Change history
  • Rich text attachments (for all fields where rich text attachments are usable)
  • Attachments
  • Iterations (not visible yet on Cloud)
  • Saved filters
  • Test case, cycle, and plan comments
  • Traceability to Confluence pages as web links
  • All data from the Zephyr Scale global administration page (global project administration, analytics, thresholds, global access restrictions, and global project restrictions)
  • Automatic traceability links section of project settings
  • Folder custom fields

Begin the migration

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 documentation:

Use the Jira Cloud Migration Assistant to migrate

The Migrate to cloud button

Click the image to enlarge it.

Important: Make sure to select both the Zephyr Scale app and the relevant Jira projects in the same migration plan, as shown in the image below. If you select just the app but no projects, the migration will be marked as COMPLETE, but Zephyr data will not actually be migrated.

You can create multiple migration plans, each having a set of Jira projects, but each plan must also include the Zephyr Scale app. The JCMA will only migrate the Zephyr data for the Jira projects in that plan.
Migration plan with one project

Click the image to enlarge it.

Track migration progress

Because the JCMA is still in beta, its progress feedback might take around 10 minutes to be updated. It is possible (and common) that the progress will jump from 0% to 100%. If you do not see the progress moving, wait for 10 minutes and see if it is still stuck.

We expect that progress tracking will be improved when the JCMA hits General Availability in 2022.

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

Migration complete

Click the image to enlarge it.

You can watch your Jira Server’s atlassian-jira.log file for errors during the migration. More detailed information about the export process can be obtained by increasing the log level for com.adaptavist to INFO.

Migration status

The possible statuses are:

Status Description Action required

RUNNING

Zephyr Scale data migration is in progress.

Monitor the progress updates you receive and wait for the process to change the status.

If more than 10 minutes have passed and you do not see an update, contact Zephyr Scale Support.

COMPLETE

The process has completed successfully, and all data was migrated.

Review your new cloud project to validate the migration.

INCOMPLETE

The process has completed, but some data was excluded from the migration due to validation problems.

Review the log file that is provided to understand what data was excluded and why. Sometimes data will be skipped for valid reasons, such as traceability that references Jira issues that no longer exist, or attachments which reference files that no longer exist.

If there is any doubt about the entities that have been skipped, contact Zephyr Scale Support.

FAILED

The migration process was interrupted due to an unexpected error, and the execution of the migration was stopped at that point. There will be data missing from the migration as the rest of the process was aborted.

Please review the log file provided and contact Zephyr Scale Support for further investigation.

Post-migration steps

After successful migration to Cloud, make sure the following domains and subdomains are allowed in your network so the users can access the full functionality of Zephyr Scale Cloud.

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 Scale Community or contact our Customer Care team.

See Also

Cloud Migration FAQ
Cloud Migration Alternatives
Zephyr Scale Features - Server/Data Center vs Cloud

Highlight search results