TestRail to Zephyr Scale Migration: CSV vs REST API

Runshift — Sun, 26 Jul 2026 14:49:14 +0000

If you're planning a TestRail to Zephyr Scale migration in 2026, there are three things worth knowing before you start that most documentation doesn't make clear upfront: the product has been renamed in a way that's easy to get wrong, the "simple" import method only migrates a fraction of your data, and the timing might matter more than you think.

Atlassian is sunsetting Data Center — and that changes the calculus

Atlassian stopped selling new Data Center licenses on 30 March 2026, with full end-of-life set for 2029. If your organization has any Jira migration on the roadmap this year, there's a good chance it's Cloud-bound — and if TestRail is still your test management tool, this is a natural point to move that at the same time rather than as a separate project six months later. Migrating test data into a Zephyr Scale instance that's about to move from Data Center to Cloud anyway often means doing the work twice.

The naming trap: "Zephyr Scale" doesn't exist anymore (sort of)

Here's where a lot of migration research goes sideways early. SmartBear renamed its Zephyr product line, and the naming is genuinely confusing if you're not deep in it:

What used to be called Zephyr Scale is now marketed as "Zephyr — Test Management and Automation for Jira" — the flagship, full-featured product.
What used to be called Zephyr Squad is now "Zephyr Essential — Test Management for Jira" — a lighter-weight tool with a different data model entirely.

Most people still search "Zephyr Scale" out of habit, so that's the term used here — but the products themselves are genuinely different, not just renamed.

It gets more confusing. SmartBear's own support documentation confirms that licenses for legacy Zephyr Squad Cloud were automatically rebranded as "Zephyr Essential" in the Atlassian Marketplace and Jira's app management screen — for billing purposes only. That means an organization can see "Zephyr Essential" listed on their instance without having actually upgraded to the new Essential experience at all. If you're planning a migration into the flagship Zephyr product, checking the label alone isn't enough to confirm what you're actually working with.

CSV import only gets you part of the way there

This is the gap that catches most teams by surprise. Zephyr Scale's CSV import — the method most guides default to, because it's the simplest — only migrates test cases and their fields. It does not bring across:

Test cycles or test plans
Execution history
Attachments
Issue links to Jira

If your migration is genuinely just "I need my test case library moved over," CSV import is fast and sufficient. But most real migrations — anything with meaningful execution history, traceability requirements, or attachment volume — need more than that, and CSV simply can't reach it.

The REST API is where the real migration happens

Zephyr Scale's REST API is a fully supported part of the product (same standing as CSV import — not an unsupported workaround), and it's the only path that reaches test cycles, executions, attachments, and issue links. The tradeoff is real: it means writing or adapting a script rather than clicking through an import wizard.

One distinction worth being precise about: the API itself is supported by SmartBear. Any script you or a tool writes against it is your own code — normal and expected, just worth knowing going in, since it means debugging is on you, not a support ticket.

The error you're most likely to hit

If you're scripting a migration via the API, the most common failure isn't a bug in your code — it's a mismatch in how the two platforms identify users. Jira Cloud identifies users by an internal accountId, not by username or email (a platform-wide change made in 2019 for GDPR reasons). TestRail identifies users by username or email. Any API field that references a person — an owner, an assignee, an executor — will throw a 400: user not found error if your script passes a TestRail username straight through, or if that person doesn't have a Jira account in the target instance yet.

The fix is straightforward once you know to look for it: provision every TestRail user as a Jira user first, and build a mapping table using Jira's user search endpoint before you migrate anything — not as a fix mid-script.

Cloud vs. Data Center changes your actual endpoints

Worth stating plainly: if you're setting up a new migration today, you're very likely on Jira Cloud, given the sunset timeline above. But Zephyr Scale Cloud and Zephyr Scale Data Center run genuinely different APIs — different versions, different base URLs, different authentication. Instructions written for one won't directly apply to the other, and feature parity between the two isn't guaranteed.

Where to go from here

This covers the shape of the problem — the naming, the CSV ceiling, the API reality, and the version split. Actually executing a migration means field-by-field mapping, a real API workflow (folder creation, test case creation, cycle and execution linking, attachment handling), and knowing which errors are coming before they happen.

That's the gap the TestRail → Zephyr Scale Migration Guide fills — a complete, Cloud-first playbook covering both the CSV and REST API paths, full field mapping, Cloud/Data Center-specific guidance, and the troubleshooting most teams only learn by hitting it themselves.

DEV Community: Runshift