Migration Guide

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

Important

Zephyr Scale minimum required version for JCMA migrations is 9.21.1 or the latest.

If your Server licenses expired as part of Jira’s EOL, you will need to either use a 30-day trial Data Center license or request Atlassian to extend both Jira and Scale’s Server licenses.

To request an extension to Atlassian, please submit a request via https://getsupport.atlassian.com/ > “Billing, payment, and pricing” > “Product Trials”.

To expedite the approval process for a Server extension of our app, kindly copy our Sales Director, Richard Humphries, at [email protected] when creating your ticket.

  • Back up the data of your server instance.

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

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

  2. Choose Find new apps in the sidebar.

  3. Enter Jira Cloud Migration Assistant in the search bar.

  4. Click Install, once you find the plugin:

    manage-apps.png

  5. You can also install the plugin from the Atlassian Marketplace.

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

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

    Dependency

    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:

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 with 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

  • 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

What is NOT migrated

  • 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.

atlassian_doc.png

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.

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.

atlassian_doc.png

Note

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.

choose-your-migration-options.png

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.

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

complete.png

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 that 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

Do you have any questions? Visit our Support Portal where you can search for an answer in Zephyr Scale Community or contact our Customer Care team.

In this section:
© 2024
Publication date: