How to migrate Zephyr data

[#1]

Hello,

In this article I would like to talk on how to migrate Zephyr data between Jira instances.

Zephyr is a plugin for Jira, which handles test management. The data of this plugin consist of test cases, test steps, executions and test cycles.

There are four types of possible migrations:

1. Cloud to Cloud.

2. Cloud to Server.

3. Server to Cloud.

4. Server to Server.

You can migrate the whole set of Zephyr data only for Jira Server to Server migration.

For all other cases, unfortunately, you can only migrate test cases and test steps. The reason is that plugin data are not stored in the Jira Cloud database, that is why standard backup/restore procedure does not backup or restore plugin data in Cloud.

Test Case migration

Test case is an issue of a certain issue type. By default the issue type is called Test. 

Since a test case is an issue, all test cases can be migrated by standard backup/restore procedure in Jira for all types of migration.

That is why there are no problems with migration of test cases.

Test step migration

Test step is an entity of a test case. There are can be multiple test steps for a test case. You can see how it looks like in Zephyr in the screenshot below:

Then question is:

How to migrate all test steps after we restored a Jira backup?

There are two choices:

1. You can use ZAPI.

This is a paid add-on, which provides Rest endpoints to Zephyr data. if you can afford to buy this add-on, then you can buy it, but you would still need to write a script or a program to migrate test steps using ZAPI. Actually, you can migrate all Zephyr data using ZAPI, but you would need to write code.

2. You can use Zephyr for Jira Importer Utility.

You can read how to use this utility here:

https://www.getzephyr.com/insights/getting-started-zephyr-jira-importer-utility

The only thing, which is not obvious in the guide, is, that when you map test step attributes to an excel sheet, you should use column numbers. For example, if you put a test step name in the first column in Excel, you should map this column as A for the Step row.

So this utility can import test steps. It is good to know, but how would we get all test steps for each issue?

It would be good luck to have all test steps for each issue in an excel file, but, unfortunately, that is a rare case, since users add test steps to Jira manually. That is why we need to get test steps from Jira.

You can get information about test steps, if you export all executions to a csv file (Test -> Search Test Executions -> Export). But you will get only test steps, which were ever executed, which means, that probably you will loose test steps, which were never executed. 

After you exported executions, you can load this file by the Zephyr for Jira Importer Utility. But there are the following drawbacks:

1. Exported file contains all executions, that is why if a test step was executed multiple times, then this test step will be loaded multiple times, and you will have multiple copies of the same test step for an issue.

2. If the import process stops or fails, then you have to start over. And all test steps, which were imported before the import stopped, will be imported again. Your test steps will be doubled.

3. The Importer can only import data for one project at a time.

Considering these drawback, you would need to write a script to prune your exported csv file so, that you could import test steps. And even if you do so, if the import suddenly stops, you would need to clean all imported test steps. Only after cleaning you can start the import process again to avoid duplicated test steps.

Conclusion

In my opinion all available solutions are not good fitted for Zephyr data migration. A program must be written for successful migration of Zephyr data and that is what I am currently doing.

Hope my article helps somebody.

[Gonchik Tsymzhitov]

Thanks for your article! 

[Matt Doar]

Been there, written the code!

"The reason is that plugin data are not stored in the Jira Cloud database" - which data do you mean, and where is it stored if not in the AO tables?

[Alexey Matveev]

The data are stored in the database of the Zephyr vendor for Jira Cloud. For Jira Server the data are stored in AO tables.

[Yves Martin]

Thanks.

A remark about << 2. If the import process stops or fails... And all test steps, which were imported before the import stopped, will be imported again. Your test steps will be doubled. >> - this can be avoided by refering test case issue key as "External ID".

Without access to ZAPI, it is not possible to migrate test executions.

For Server to Cloud migration, there is also option to extract Zephyr test cases for Importer thanks to Better Excel Exporter (only available for Server)

From my point of view, importer tool has been left "unfinished", with a very draft JSON format support.

@Matt DoarYou said "written the code!" - do you expect to publish it in any form or condition?

[Matt Doar]

No plans to publish, it was for ServiceRocket, so not mine to share

[Yves Martin]

I wonder if processing the Zephyr own-backup file may be an option to move everything, including test executions...

[Alexey Matveev]

As far as I know you can restore Zephyr own backup only to the same instance, from which you took the backup. I began to explore this opportunity, but I did not go to the end, because I chose another way. Anyway as far as I found out there are two files in the backup: with properties of the backup (you can see there the url from which it was taken and some hash codes) and the backup. As far as I found out the backup is an xml file in the protobuf format. Though I did not extract the backup file. As I said I went another way. But I think it is possible to work a bit with the backup to change it to your needs, but it will definitely take time.

[Solomon Cherian]

Hello @Alexey Matveev

Thanks for the document. I'm currently working on a migration from cloud to Server and is stuck on the Zephyr for Jira data..

Its been almost 11 months since your last comment. Just wanted to check if you have come across any solution for the cloud to server migration for Zephyr data?

Thanks,

Solomon

[houssem.laboudi]

Hello @Alexey Matveev 

I have a question regarding Zephyr tests tickets migration to Xray (Jira Cloud): How do we include tickets attachements  to be also migrated in addition to the other main information? 

Thank you in advance for your reply.

Best regards, 

Houssem

[Mohan Gandhi]

Hello @Alexey_Matveev__cPrime

I need to migrate my test cases along with attachments and link from MTM to Zephyr with Jira. 

Will importer utility support with attachments?  Appreciate your help and suggestion I nthis regard.

Thanks

Mohan 

[Tobias Meyer]

Hi All

We had similar problems merging zephyr data from one instance to another. We finally created a parametrised job to copy all zephyr data to the new instance. 

Check our blog for further details: https://kreuzwerker.ch/post/jira-merge-and-beyond 

There you can find all the steps needed. You can try to perform it yourselves or we would love to support you. 

Best regards

Tobias

[Gaurav Agrawal]

Hi All,

We have created "Jira for zephyr" data migration utility which migrates data from one Jira server instance to another server instance. Please find utility at github.

Regards,

Gaurav

[Anju K Antony]

Hello @Gaurav Agrawal ,

How the "Jira for zephyr" data migration utility will work? Will it help to copy all the zephyr data including cycle and folder structures

Regards,

Anju

[Gaurav Agrawal]

Hi @Anju K Antony .. yes there is api which migrate cycle from one instance to other. For attachments, there are separate step. You can fork the code and enhance in the way you want or get in touch with me for any help.

[Anju K Antony]

@Gaurav Agrawal can you help me.we are having many folders and cycles

[Gaurav Agrawal]

Please contact me at gagaurav336@gmail.com

[Joseph Blasi]

For Server to Cloud do we need to pay to renew server licensing and lose it??

Can you just put it in to trial mode update it and then move to Cloud and just pay for it on Cloud?

[Gaurav]

Hello @Gaurav Agrawal 

We have reviewed the utility and it definitely fits our use case. I have reached you over the mail, kindly check and let us know if a demo would be possible.

[Gaurav]

Hello @Alexey Matveev 

The article mentions that you were writing a utility to migrate the Zephyr data. Kindly share if the utility is available. We have a use case to consolidate the current Server data into an existing DC instance.