Zephyr for Jira: Migrating to the Cloud

December 1, 2020

<p>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 <a rel="noreferrer noopener" href="/blog/announcing-jira-service-manager" target="_blank">coming change to server licensing</a>, these modifications must be migrated to the cloud. We will be looking at Zephyr, a popular add-on/plugin for Jira.</p> <p>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).</p> <p>Zephyr relies on a custom issue type <strong>Test</strong> 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 <strong>Test</strong> and run through the test steps. You relate the <strong>Test</strong> to other issues or releases; e.g., <strong>is blocked by</strong></p> <figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="915" height="106" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/zephyr-for-jira-issue-is-blocked-by.png" alt="Zephyr Test Relations." class="wp-image-183" srcset="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/zephyr-for-jira-issue-is-blocked-by.png 915w, https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/zephyr-for-jira-issue-is-blocked-by-300x35.png 300w, https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/zephyr-for-jira-issue-is-blocked-by-768x89.png 768w" sizes="(max-width: 915px) 100vw, 915px"></figure> <h2 class="wp-block-heading">Technical details</h2> <p>Zephyr only has a few resources that are stored within Jira. A custom issue type <strong>Test</strong> that we mentioned earlier. <strong>Test Steps</strong>, a resource that is contained within the issue type Test that forms your test cases. Also within a Test are <strong>executions</strong>. 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 <strong>Cycles</strong> which are groupings of tests. You can further group cycles into <strong>Folders</strong>. Below is a table of these resources:</p> <figure class="wp-block-table alignleft h3-table"><table><thead><tr><th class="has-text-align-left" data-align="left"><strong>Feature</strong></th><th class="has-text-align-center" data-align="center"><strong>Server</strong></th><th class="has-text-align-center" data-align="center"><strong>Cloud</strong></th><th class="has-text-align-center" data-align="center"><strong>Migrated</strong></th><th class="has-text-align-center" data-align="center"><strong>Required Scripting to Migrate</strong></th><th class="has-text-align-center" data-align="center"><strong>Migrated Using Zephyr Migration Tool</strong></th></tr></thead><tbody><tr><td class="has-text-align-left" data-align="left"><strong>Test</strong> – Issue type</td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"></td><td class="has-text-align-center" data-align="center"></td></tr><tr><td class="has-text-align-left" data-align="left"><strong>Test Step</strong> – Each test issue my have any number of Test Steps</td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td></tr><tr><td class="has-text-align-left" data-align="left"><strong>Executions</strong> – Each test may be executed any number of times</td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"></td><td class="has-text-align-center" data-align="center"></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td></tr><tr><td class="has-text-align-left" data-align="left"><strong>Attachment</strong> – test / execution / step each can have documents attachment to them</td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"></td><td class="has-text-align-center" data-align="center"></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td></tr><tr><td class="has-text-align-left" data-align="left"><strong>Cycle</strong> – Test Cycle is a grouping of tests. Released vs. unreleased, ad hoc vs. scheduled</td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"></td><td class="has-text-align-center" data-align="center"></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td></tr><tr><td class="has-text-align-left" data-align="left"><strong>Folder</strong> – A mechanism to group Cycles</td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td><td class="has-text-align-center" data-align="center"></td><td class="has-text-align-center" data-align="center"></td><td class="has-text-align-center" data-align="center"><img decoding="async" class="wp-image-65" style="width: 32px;" src="https://wordpress.highwaythreesolutions.com/wp-content/uploads/2021/07/checkmark-bullet.svg" alt="Yes."></td></tr></tbody></table></figure> <h2 class="wp-block-heading">Migration: Server to Cloud</h2> <p>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?</p> <p>The information that is available to guide us on our migration journey is pretty limited. One post by <a rel="noreferrer noopener" href="https://community.atlassian.com/t5/Jira-articles/How-to-migrate-Zephyr-data/ba-p/985762" target="_blank">Alexey Matveev</a> 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.</p> <p>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.</p> <p>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).</p> <h2 class="wp-block-heading">Migration Gotchas</h2> <ul><li>The lift and shift strategy is a common one. The full site migration will remove the Zephyr plugin. Therefore, Zephyr’s <strong>test</strong> 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 <strong>test</strong> issue type to a temporary issue type (e.g., <strong>test-temporary</strong> ). Then install Zephyr and then bulk change the temporary issue type back to the test issue type. Remove the temporary issue type.</li><li>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 <strong>Create Test</strong> will pop up an option when using Zephyr.</li></ul> <h2 class="wp-block-heading">Summary</h2> <p>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.</p> <h2 class="wp-block-heading">Resources</h2> <ul><li><a class="h3-inline-link" rel="noreferrer noopener" href="https://zfjcloud.docs.apiary.io/#reference/zql/get-execution-attachment-list" data-type="URL" data-id="https://zfjcloud.docs.apiary.io/#reference/zql/get-execution-attachment-list" target="_blank">Zephyr Cloud API</a></li><li><a class="h3-inline-link" rel="noreferrer noopener" href="https://getzephyr.docs.apiary.io/#reference/cycleresource" data-type="URL" data-id="https://getzephyr.docs.apiary.io/#reference/cycleresource" target="_blank">Zephyr Server API</a></li><li><a class="h3-inline-link" rel="noreferrer noopener" href="https://zephyrdocs.atlassian.net/wiki/spaces/ZFJCLOUD/pages/2000060602/Generating+a+JWT+Authentication+Token+for+Zephyr+for+Jira+Cloud+API" data-type="URL" data-id="https://zephyrdocs.atlassian.net/wiki/spaces/ZFJCLOUD/pages/2000060602/Generating+a+JWT+Authentication+Token+for+Zephyr+for+Jira+Cloud+API" target="_blank">Zephyr Server API JWT token generation</a></li><li><a class="h3-inline-link" href="https://www.getzephyr.com/insights/getting-started-zephyr-jira-importer-utility" data-type="URL" data-id="https://www.getzephyr.com/insights/getting-started-zephyr-jira-importer-utility" target="_blank" rel="noreferrer noopener">Zephyr Import Utility</a></li></ul> <div class="wp-block-buttons is-content-justification-center is-layout-flex wp-block-buttons-is-layout-flex"> <div class="wp-block-button ctabutton is-style-h3-cta-button"><a class="wp-block-button__link" href="/contact" target="_blank" rel="noopener">Contact us for more information on migrating to Jira Cloud</a></div> </div> <p></p>