Migration via Zephyr Migration Tool

Applies to Zephyr Squad Server 6.2 and 4.8, last modified on November 22, 2021

Zephyr Migration Tool by SmartBear is a solution for migrating Zephyr Squad data from Jira Server to Jira Cloud. It is one of two possible migration approaches. You can use it if the other approach – Jira Cloud Migration Assistant is not available to you for some reason. This approach is recommended if your Jira instance is middle-sized and has few projects because Zephyr can migrate Zephyr Squad data only for one project at a time.

Important

  • The data should be migrated to a clear Jira Cloud instance because the backup will overwrite all the data in your Jira Cloud.

    For the full Jira backup instructions, refer to the Atlassian documentation.

  • Before starting the migration process, ask your users not to use either Jira Server or Cloud so that no new data is created while the migration is in progress.

How it works

Zephyr Migration Tool migrates one project at a time. That's why we recommend using it if you have few projects in your Jira instance.

The key point of the migration process from Server to Cloud is that Jira Server and Jira Cloud store the application data in different ways:

  • The Jira Server database stores both Jira and application data.

  • The Jira Cloud database stores Jira data only. The application data is stored on the servers of the application provider.

So, the data migration of the Jira data is performed differently from Zephyr Squad data migration:

  • The Jira XML backup transfers your local Jira Server data to the Atlassian servers.

  • Zephyr Migration Tool transfers Zephyr Squad data from your local Jira Server instance to SmartBear servers.

Data migration with Zephyr Migration Tool

Click the image to enlarge it.

This migration guide is split into parts:

  1. Import the Jira data into Jira Cloud using the Jira Server XML backup file.

  2. Migrate the Zephyr Squad data via Zephyr Migration Tool.

We recommend this approach if you don’t have large Jira instances and you want to migrate data by using XML files as Zephyr Migration Tool can migrate Zephyr Squad data only for one project per run.

The XML backup will overwrite all the data in your Jira Cloud. For full XML backup instruction, refer to the Atlassian documentation.

What data is migrated

Migration Tool migrates all Zephyr Squad data, except for these entities:

  • Zephyr Squad custom fields used at the Test Steps and Test Execution levels.

  • Execution history in the execution details section. It is used to track the transitions of an execution.

  • Defect links associated with executions at the execution or test step result level.

Requirements

  • Use a computer that meets the following minimum system requirements:

    • 64-bit operating system

    • 4-core CPU

    • 8 GB RAM

    The computer must have access to:

    • Jira Server with Zephyr Squad Server

    • Jira Cloud

    • Zephyr Squad Cloud API endpoint:

      https://prod-api.zephyr4jiracloud.com/connect

  • Install Java (version 1.8 is recommended) on that computer.

  • You must have the Jira System administrator permission in both Jira Server and Jira Cloud.

1. Import the backup file of Jira Server into Jira Cloud

Create a backup of Jira Server

Export all Jira data by using the XML backup in Jira Server. Follow these steps:

  1. Go to Administration > System.

  2. Scroll down to the IMPORT AND EXPORT section and click Backup system.

  3. Enter a name for your backup file in the File name field and click Backup.

As the compilation of a backup file is complete, the file will appear in the export folder of your Jira Server directory.

Import Jira data into Jira Cloud

The XML backup will overwrite all the data in your Jira Cloud, so we recommend using a clear Jira Cloud instance.
  1. If you have Zephyr Squad Cloud installed in your Jira instance, uninstall it.

  2. Create a backup file for your Jira Cloud instance before continuing.

    This is a mandatory requirement for XML Jira migration. Refer to the Atlassian documentation for details.

  3. Go to Administration > System.

  4. Scroll down to the IMPORT AND EXPORT section and click Restore system.

  5. Select how the user data will be processed, then click Import data.

  6. When the backup file is checked, it is recommended to disable the Outgoing Mail feature due to the following post-migration validation.

  7. Click Run import. This operation may take some time depending on the size of your backup file.

  8. Verify that all Jira data has been successfully imported and all the created Jira entities (projects, issues, and so on) have the same IDs both in Jira Server and in Jira Cloud.

Refer to the Atlassian documentation for details.

Add permissions

To view and edit migrated issues, your Jira account must belong to all migrated user groups. For security reasons, Migration Tool does not add your Jira account to migrated user groups.

To do this:

  1. Go to Settings > User management, then Click Groups on the left.

  2. Click Show details for the needed group.

  3. Click Add group members to include your account to the group.

Repeat these steps to add your account to other groups. See Atlassian documentation for details.

Install Zephyr Squad in Jira Cloud

  1. Rename the Test issue type imported from the Zephyr Squad Server to Test_Migrated in Settings > JIRA SETTINGS > Issues > Issue types menu.

  2. Go to Apps > Find new apps, enter Zephyr, and install the Zephyr Squad application from the Atlassian marketplace.

    This will create a new Test issue type.

  3. Ensure that Zephyr Squad's Test issue type is available in all issue type schemes. To do that:

    1. Go to Settings > Issues.

    2. Click Issue type schemes in the sidebar on the left.

    3. Review all issue type schemes. If a scheme does not have the Test issue type, add it to the scheme:

      1. Click the Edit link next to that scheme.

      2. Drag the Test issue type to the Issue Types for Current Scheme column.

      3. Click Save.

  4. Perform the bulk change of issues from Test_Migrated to Test using the Move Issues bulk action:

    1. Click the Search bar, then Issues at the bottom of the search menu.

    2. Click the Type filter and select Test_Migrated

    3. Click the three dots at the top right, then Bulk change all XX issue(s), where XX is the number of queried issues.

    4. Select all issues, scroll down to the bottom, and click Next.

    5. Select Move Issues and click Next.

    6. Select the Test issue type in the To column.

    7. Follow the prompts to complete the bulk move.

  5. Validate the migrated issues associated with the new Test issue type.

    There must be no issues with the Test_Migrated issue type. You can delete this issue type.

Re-index Jira Cloud metadata

  1. Navigate to Setting > Apps > Zephyr Squad > General Configuration.

  2. Scroll down to the Re-Index section and re-index all your projects by selecting Project Metadata and clicking Re-Index:

    Re-Index

    Click the image to enlarge it.

    Note: If All projects re-indexing fails, re-index every project separately.

2. Migrate Zephyr data using Zephyr Migration Tool

Zephyr Migration Tool migrates only one project per run. Refresh the page after the migration of the project is completed to process another project.

You can view the live log in the command-line window during the migration.

Download and customize Migration Tool

  1. DownloadZephyr migration tool and unpack it to a folder. The archive contains two files:

    • application.properties

    • Zephyr_for_Jira-server-to-cloud-migration-1.0.jar.

  2. Migration Tool uses parameters specified in the application.properties file by default.

Parameter Description
server.port

The port where the utility will run. 8080 by default.

migrationFilePath

The path to a folder where Zephyr Migration Tool will store its temporary files. Note: The folder must have read/write access and should be empty.

spring.thymeleaf.prefix

Do not change this value.

zfj.server.baseUrl

The URL of your Jira Server instance. For example:

zfj.server.baseUrl=${serverBaseUrl:http://10.10.10.119:9900/}

zfj.server.username
zfj.server.password

The username and the password you use to connect to your Jira Server instance.

zfj.cloud.accountId

The ID of your account in the Jira Cloud instance.

How to get the account ID

zfj.cloud.accessKey
zfj.cloud.secretKey

The access key and the secret key used to log in to your Jira Cloud instance.

zfj.cloud.baseUrl

Do not change this value.

migrate.step.results.attachment

Keep the value true if you want to migrate Test Result attachments, otherwise, change it to false.

migrate.test.steps.attachment

Keep the value true if you want to migrate Test Step attachments, otherwise, change it to false.

migrate.update.step.results

Keep the value true if you want to migrate Test Result updates, otherwise, change it to false.

Transfer Zephyr Squad data via Migration Tool

  1. Open the command-line prompt on your computer.

  2. Change the working directory to the folder where Zephyr Migration Tool and the application.properties files are located. For example:

    # On Windows

    cd C:\Path\To\ZMT

  3. Run the following command (written in a single line):

    java -jar Zephyr_for_Jira-server-to-cloud-migration-1.0.jar

    The application service will start at the port specified in the application.properties file if not specified in the command.

  4. Open your browser and enter localhost:<port>/beginMigration, where <port> is the port you specified in the application.properties file. For example:

    http://localhost:8080/beginMigration

    or

    http://127.0.0.1:8080/beginMigration

  5. On the subsequent page, specify the project ID and click Submit to start the migration process:

    Zephyr Migration Tool web interface

Post-migration

Once the migration completes (you will see the corresponding message in the log), validate the migrated data in your Jira Cloud instance. If there are no issues, you can start working with the migrated projects.

Support and troubleshooting

Should you have any questions, please visit our Support Portal where you can search for an answer in the Zephyr Squad Community or contact our Customer Care team.

See Also

Zephyr Squad Server-to-Cloud Migration Guides
Zephyr Squad Features - Server/Data Center vs Cloud

Highlight search results