Community resources
Community resources
Community resources
Automating Zephyr Scale Migrations Between Jira Data Center Instances: An Open-Source Key Remapping
Migrating Zephyr Scale Between Jira Data Center Instances: An Open-Source Key Remapping Tool
TL;DR: The standard Zephyr Scale export/import process reassigns new keys to everything, silently breaking all cross-references between test cases, test runs, and test plans. I couldn’t find a tool that solved this, so I built one. It uses content-based signature matching to remap keys automatically across all three entity types—preserving your test data relationships without manual intervention. The code is open source, GitHub.
Background
I recently needed to migrate Zephyr Scale test data from one Jira Data Center instance to another as part of a larger consolidation effort—and this is going to be a continual process as we ingest a large number of other Jira Data Center instances into ours.
The standard export/import process works on the surface, but it reassigns new IDs and keys to everything. Test cases that were PROJ-T123 become TARGET-T456, and all the references in test runs and test plans silently break. You end up with imported data that looks complete but is internally incoherent.
I couldn’t find an existing tool that handled this remapping automatically, so I wrote one. This post explains the approach and shares the code.
What Breaks During Migration
When you export and import Zephyr Scale data between instances, four things go wrong:
- Test cases get new keys in the target instance
- Test runs reference the old test case keys, which no longer exist
- Test plans reference both old test case and test run keys
- Folder structures do not transfer automatically
The result is imported data that appears complete but has broken relationships throughout. Fixing this manually at scale—matching hundreds of old keys to new ones across test runs and plans—is the kind of work that takes days and is nearly impossible to do without errors.
The Approach: Content-Based Signature Matching
The core insight is this: when you import test cases, the keys change but the content stays the same. So if you can match entities by their content rather than their keys, you can build a reliable mapping between old and new—and use that mapping to fix all the downstream references.
How the Matching Works
After importing test cases to the target, the tool:
- Loads the original source export file
- Queries the target instance to get the newly imported test cases
- Builds a content-based signature for each test case on both sides
- Matches source signatures to target signatures to create a key mapping file
Test cases are matched using a combination of name (normalized), description or objective (normalized), and the first two test script steps. Test runs are matched using name, description, environment, version, and number of test items. This approach is robust as long as test case names and descriptions are reasonably unique within a project—which is true in the vast majority of real-world projects.
Before You Run the Tool
The tool handles data migration and key remapping, but it expects the structural elements to already be in place in the target instance. Before running, you’ll need to:
- Create the target project in Jira
- Recreate the folder hierarchy in Zephyr Scale (the tool preserves folder assignments, but the folders must exist)
- Set up any custom fields used by your test cases
- Configure environments, versions, and other Zephyr Scale settings to match your source
All operations on the source instance are read-only (GET requests only), so there’s no risk of modifying your source data during the migration.
The Migration Process
The migration runs in three sequential phases, each building on the key mapping produced by the previous one.
Phase 1: Test Cases
- Export test cases from the source instance
- Clean the data (remove IDs, timestamps, and fields that cause import conflicts)
- Import cleaned test cases to the target instance
- Query both source export and target instance, match by content signature, build key mapping file
Phase 2: Test Runs
- Export test runs from the source instance
- Replace old test case key references with new keys using the Phase 1 mapping
- Clean and import test runs to the target instance
- Query both source and target, match by content, build test run key mapping file
Phase 3: Test Plans
- Export test plans from the source instance
- Replace both test case and test run key references using both mapping files
- Import test plans to the target instance
Each phase is self-contained—if something goes wrong, you can re-run that phase without starting over from the beginning.
Real-World Results
On our first migration run with the tool:
Metric | Manual Approach | With Tool |
Key remapping | Manual spreadsheet matching | Fully automated |
Reference integrity | Best-effort, error-prone | Validated programmatically |
Source instance risk | Possible accidental writes | Read-only, zero risk |
Repeatability | Starts from scratch each time | Reusable across all ingestions |
Time for remapping phase | Days of manual work | Minutes |
Because this is a continual effort—we’re ingesting multiple Jira Data Center instances over time—having a repeatable, automated process is essential. Running this manually even once would be painful; running it a dozen times would be untenable.
Getting Started
The tool is open source and available at GitHub.
Requirements
- Python 3.6+
- requests library
- Personal Access Tokens (PATs) for both Jira instances
- Target project created with Zephyr Scale structure in place (folders, custom fields, environments, versions)
Configuration
Configuration files go in the config/ directory:
config/source_base_url.txt
config/source_pat.txt
config/source_proj_key.txt
config/target_base_url.txt
config/target_pat.txt
config/target_proj_key.txt
Running the Migration
python 0_run_zephyr_migration_orchestrator_v2.py
The orchestrator walks you through the three phases in sequence, generating mapping files between each phase that are used as input for the next.
Things to Know Before You Run It
A few important considerations to set expectations:
- You must manually recreate the Zephyr Scale folder structure, custom fields, environments, and versions in the target before running—the tool handles data and key remapping, not structural setup
- Content-based matching assumes test case names and descriptions are reasonably unique within a project. If you have many identically-named test cases with identical descriptions and steps, matches may be ambiguous
- Attachments are not currently handled and would need to be migrated separately
- Designed for Data Center; Cloud API endpoints differ slightly and would require modification
For most real-world projects these constraints are non-issues. If your project has significant numbers of duplicate test case names, you’ll want to review the mapping file before proceeding to the next phase.
Lessons Learned
The Key Insight: Import First, Map Second
The temptation when facing a key remapping problem is to try to pre-compute everything before importing. That doesn’t work well with Zephyr Scale because you don’t know the new keys until after the import. Flipping the order—import first, then build the mapping by comparing what you sent with what arrived—makes the problem tractable.
Content Signatures Are More Reliable Than You’d Expect
I was initially skeptical that matching by content would be robust enough for production use. In practice, test cases with meaningful names and descriptions match reliably. The first two script steps add enough signal that even test cases with similar names usually resolve correctly.
Phase Isolation Saves Debugging Time
Structuring the migration as three independent phases—each producing a mapping file—means you can inspect the mapping after each phase before committing to the next. Catching a matching issue after Phase 1 is far less painful than discovering it after you’ve already imported test plans.
Built with AI: A Claude Code Story
Like my CMJ migration toolkit, this tool was built collaboratively with Claude Code, Anthropic’s AI-powered CLI assistant. The content-signature matching approach emerged through iterative discussion—I described the key remapping problem, and working through the solution together surfaced the “import first, match second” insight that makes it work.
The experience reinforced the same lesson: AI amplifies domain expertise rather than replacing it. I knew the Zephyr Scale data model and what a valid migration needed to look like; Claude Code helped me build the implementation quickly and think through edge cases I would have hit later in testing.
None of This Works Without the Right Customer
Tools like this don’t get built—or validated—in a vacuum. A critical ingredient in making this tool production-ready was having a customer who was genuinely invested in getting it right.
Ryan Stroup dedicated real time and attention to this effort: testing the migration pipeline against his projects’ actual data, validating that the content-based matching was producing correct key mappings, and confirming that every requirement of his projects was met before sign-off. That kind of engaged partnership is what separates a tool that works in theory from one you can trust on real test data.
The matched-key validation step in particular benefited enormously from Ryan’s hands-on testing—edge cases in test case naming and structure only surface when you run against production data with someone who knows what correct looks like. If you’re planning to use this tool, I’d encourage the same model: a willing, thorough collaborator on the customer side is just as important as the automation itself.
One Challenge Left to Solve
One area I didn’t have time to tackle is automating the recreation of the Zephyr Scale project structure itself—folders, custom fields, environments, and versions—from the source instance to the target. Right now that’s a manual prerequisite step, which works fine for a single migration but adds friction when you’re ingesting many instances repeatedly.
In theory this should be achievable via the Zephyr Scale REST API: query the source structure, then recreate it in the target before the data migration begins. In practice I haven’t validated how reliably the API supports all the edge cases involved, so I left it as a manual step rather than ship something half-baked.
If you’ve already solved this or want to collaborate on it, I’d love to hear from you in the comments. It’s on my list to revisit.
Conclusion
Zephyr Scale migrations between Data Center instances are deceptively tricky—the standard export/import gets the data across, but the broken key references leave you with test data that looks complete and isn’t. Content-based signature matching solves the remapping problem without requiring any manual key tracking.
If you’re facing a similar consolidation effort—especially a repeated one—I hope this tool saves you the days of manual work it would otherwise take.
The code is on GitHub. Issues and PRs are welcome.
Questions or feedback? Drop a comment below. I’d especially like to hear from anyone who’s tackled this problem a different way, or who has run into matching edge cases I haven’t encountered yet.
1 comment
I hope it is helpful! The largest project I have run it on had around 13,000 test cases/runs, and around 175 test cycles. It runs wells. Next month it will start getting used quite a bit and I will update the GitHub repo if needed. I am working on a tool for bringing Zephyr Essentials into Scale I will post when done.