Zephyr Scale Server-to-Cloud Migration Guide

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

Important notice:

  • Zephyr Scale can only be migrated via Jira Cloud Migration Assistant (JCMA), provided by Atlassian.

  • Customers needing to migrate using Jira Site Import must raise a ticket in our Support portal. Our Cloud Migration Manager will follow up.

What data gets migrated

When migrating the Zephyr Scale Server data to Cloud using JCMA, some things are not migrated because the Cloud version lacks the corresponding features. Some of these features may be implemented in the future, most of them most probably won’t be, but then we could add them to the migration.

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, although 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

Pre-migration steps

Allow the required domains for JCMA

For the migration to work, make sure your network firewall allows connections from your Jira Server to the domains used by the JCMA (refer to the "For JCMA plugin host communication" list).

In Jira Server

  1. Upgrade Zephyr Scale Server to the latest available version. You can find 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 are using Jira version 8.14, the migration assistant is automatically installed in your server instance.

    To install the plugin manually:

    • In Jira Server or Data Center, 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.

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

  5. Select all dependent projects to be migrated in the same migration plan. The table below explains the three types of dependencies that projects may 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.

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 Scale Cloud in your Jira Cloud instance.

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

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