Highway Three Solutions

Zephyr for Jira: Migrating to the Cloud

#Add-Ons#Cloud Migration

Atlassian products have the ability to be extended through custom development of add-ons for Jira cloud and plugins for Jira server / DC products. These modifications can really enhance the system, but with the coming change to server licensing, these modifications must be migrated to the cloud. We will be looking at Zephyr, a popular add-on/plugin for Jira.

Zephyr is an Agile Test Management Solution used for test planning, tracking, and automating. It provides test metrics, reports and analysis for insight into your application. It is easy to use and setup. Simply install onto your instance and you are ready to create your test cases. Zephyr has support for both cloud and server environments. Between its cloud and server offers, Zephyr for Jira has an almost equal feature set (the cloud version currently has fewer features).

Zephyr relies on a custom issue type Test that has a special look and feel, as well as custom behaviours. It contains Test Steps and Execution, in addition to the normal Jira issue properties. The intent is that you run through a test case by executing the Test and run through the test steps. You relate the Test to other issues or releases; e.g., is blocked by

Zephyr Test Relations

Technical details

Zephyr only has a few resources that are stored within Jira. A custom issue type Test that we mentioned earlier. Test Steps, a resource that is contained within the issue type Test that forms your test cases. Also within a Test are executions. While executing you can attach files (images, outputs, etc), these are also stored against the execution or Test Steps. You can run what are called Cycles which are groupings of tests. You can further group cycles into Folders. Below is a table of these resources;

Feature Server Cloud Migrated Requires Scripting To Migrate Migrated Using Zephyr Migration Tool
Test - Issue type
Test Step - Each test issue my have any number of Test Steps
Executions - Each test may be executed any number of times
Attachment - test / execution / step each can have documents attachment to them
Cycle - Test Cycle is a grouping of tests. Released vs unreleased, ad hoc vs scheduled
Folder - A mechanism to Group Cycles

Migration: Server to Cloud

We will focus on the path to migrate the above-described objects from a server instance to a cloud one. Zephyr has data parity between its cloud and server. As a result, we can be fairly confident that all features in a server instance will eventually exist within the cloud. But how do we migrate?

The information that is available to guide us on our migration journey is pretty limited. One post by Alexey Matveev gives a nice overview of the options for using a Zephyr migration tool; however, it does not seem to migrate many of the Zephyr resources associated with a test case. Cycles/folders, historical data about executions, and attachments are not migrated, i.e., only test steps are migrated using the Zephyr migration tool. This tool should only be run after the Jira data has been migrated, and the test issue type gotcha has been resolved.

The other option available for migrating these resources is to use Zephyr API. The good news is there are API endpoints for creating all of the above resources. The bad news, there are no publicly available scripts for pulling and pushing data from one environment to another.

Only the Test issue type is migrated using a full site import (lift and shift strategy) or the Jira Cloud Migration Assistant (JCMA). This means no matter what style of migration you are doing, you must implement some sort of scripting to move all of the Zephyr artifacts. To do this you will have to enable the Zephyr API, you can do this by installing Zephyr’s ZAPI add-on (both server and cloud). This exposes endpoints that are crucial for migrating data. A GET request will be made to the server and a corresponding Post to the cloud for each Atlassian artifact (some batch requests may be performed to better optimize network utilization)..

Migration Gotchas:

  • The lift and shift strategy is a common one. The full site migration will remove the Zephyr plugin. Therefore, Zephyr's test issue type is not defined which breaks the instance after Zephyr is re-installed. To fix this, before re-installing Zephyr, you must bulk change the test issue type to a temporary issue type (e.g., test-temporary ). Then install Zephyr and then bulk change the temporary issue type back to the test issue type. Remove the temporary issue type.
  • If Zephyr was previously installed into a Jira Cloud instance then ZAPI will not install. Zephyr for Cloud is supposed to have ZAPI’s API and materials already in it so it shouldn’t make too much of a difference. Having ZAPI just guarantees the Create Test will pop up an option when using Zephyr


Zephyr has developed its cloud app to be almost equivalent to its server one which makes migrating this app very manageable. This migration has a few tricky steps, some gotchas. You need to program a solution to migrate ALL of your test cases; nothing that would present any significant issues to an experienced individual.


Contact us for more information on migrating to Jira Cloud