Use Vansah’s migration tool to bring supported Zephyr Essentials test cases, scripts, folders, cycles, and latest results into the same Jira space.
Confirm availability first: Contact Vansah before scheduling your migration. Continue with the steps below when the Zephyr Essentials migration option is available for your site. If it is not listed, confirm the next steps with Vansah.
Before you begin
Review What Migrates from Zephyr Essentials to Vansah? so you understand the field mappings and information that will need manual transfer.
Use a Jira administrator account that can also administer the Jira space you want to migrate.
Make sure Vansah is enabled in that Jira space and that you can access its Zephyr data.
The destination Jira space must have no Vansah test cases on the Vansah Board or in the Recycle Bin. If it already contains test cases, contact Vansah to plan the next steps before proceeding.
If Jira uses an IP allowlist, review Allowlisting Vansah IP Addresses for Plugin Migrations.
Prepare the required tokens
You will need three tokens. Keep them available for the validation step.
Token | What you need |
Zephyr Essentials token | A token with access to the source Jira space’s Zephyr data. Use SmartBear’s token instructions or the generation link in the migration screen. |
Jira API token | A token for the Atlassian account used for the migration. Use a token without scopes for this connection. The email entered during validation must belong to the account that created the token. See Atlassian’s API token instructions. |
Vansah API token | A token that can access the destination Jira space. Select Generate a token from Vansah in the migration screen, or see Using Vansah API Tokens. |
1. Open the migration tool
In Jira, go to Apps → Vansah.
Open the settings menu and select Plugin Migrations.
Select Zephyr Essential, the label used in the migration picker, then select Next.
Select the Jira space whose Zephyr data you want to migrate, then select Next.
2. Validate the tokens
Enter the Zephyr, Jira, and Vansah tokens in their matching fields.
If an email field appears, enter the email address for the account that created the Jira token. See why Vansah requests your email during migration.
Select Validate. Correct any field marked as invalid, then validate again.
When the tokens and email are accepted, select Next.
3. Map execution results and priorities
Match each Zephyr execution status to the Vansah result your team wants to use. For example, map your successful status to the appropriate passed result.
Make sure every source status has a mapping, then select Next.
Map each Zephyr priority to the appropriate Jira priority. Complete every source priority mapping, then select Next.
Review these choices carefully: they determine the results and priorities shown after migration.
4. Review and start the migration
Wait while Vansah prepares the data preview.
Review the listed categories and counts. Where a count is linked, open it to check the source data.
Read the notice on the preview screen. Once the migration starts, avoid making changes in Vansah until it finishes.
Select Confirm when you are ready to start importing. Vansah creates a migration job.
5. Monitor the job and check the imported data
After the job starts, you can close the setup screen. Open Migration History from the Vansah settings menu to return to it.
In Ongoing Migrations, find the job and select More → View Progress.
Review the status of each category. Wait until the job and all included categories have finished; a DONE status for one category does not mean the whole migration is complete.
Check Historical Migrations for completed jobs. Vansah also sends migration progress notifications to the email used for the migration.
Open Vansah in the Jira space. Check sample cases, scripts, images, work item links, Test Plans, and latest results against the source.
If you cannot continue
Problem | What to check |
A token is rejected | Check that it is valid, belongs to the correct account, and can access the selected Jira space. Verify the Jira token email and any IP allowlist. |
Next is unavailable during mapping | Map every source execution status or priority before continuing. |
Vansah reports existing test cases | Check the selected Jira space’s Vansah Board and Recycle Bin. Contact Vansah before removing data to make room for the migration. |
An earlier migration blocks a new job | Review Migration History first. An active or completed job prevents another migration for the same Jira space. Contact Vansah before clearing a failed or canceled job and trying again. |