TestCollab's Import from Xray feature connects directly to your Jira (+ Xray) Cloud instance and brings your test repository across.
This guide covers:
What to gather from Jira and Xray before you begin
How to run the import, step by step
What to expect once it finishes
What You'll Need to Gather
The wizard validates your details in two groups : Xray first, then Jira. Collect these six values up front:
Value | Where it comes from |
Xray REST API URL | Your Xray API endpoint (a sensible default is pre-filled) |
Xray Client ID | Xray API Key |
Xray Client Secret | Xray API Key |
Jira host | Your Atlassian site domain |
Jira email + API token | Your Atlassian account |
Jira project key | The Jira project holding your Xray tests |
Here's how to find each one.
1. Xray REST API URL
This is the API endpoint the importer calls to talk to Xray.
The field comes pre-filled with the global default: https://xray.cloud.getxray.app/api/v2
Most customers can leave it unchanged.
If your Xray data is hosted in a specific region, enter that region's Xray API URL instead. (The field shows a hint: "Use the correct Xray API URL if your Xray data is hosted in a specific region.")
2 & 3. Xray Client ID and Client Secret (Xray API Key)
Xray authenticates using an API key pair, a Client ID and a Client Secret. To generate them:
In Jira, open Apps → Xray, then go to Xray's Global Settings → API Keys (you'll need Jira administrator rights).
Create an API Key and assign it to a user account.
Xray generates a Client ID and a Client Secret, copy both now, as the secret is shown only once
4. Jira host
Your Atlassian site domain, hostname only
✅ Correct: mycompany.atlassian.net or https://mycompany.atlassian.net
🔴 Incorrect: https://mycompany.atlassian.net/jira
5. Jira email and Jira API token
To create a Jira API token:
Sign in to your Atlassian account and open id.atlassian.com → Security → API tokens.
Click Create API token, give it a label (e.g. TestCollab import), and copy the token; it's shown only once.
Use the email address of that same Atlassian account as your Jira email.
⚠️ The account behind this email + token must have permission to view the Jira project and its Xray tests. If it can't see them in Jira, the import can't either.
6. Jira project key
The short key of the Jira project that contains your Xray tests; for example, XSP.
Running the Import
The option to Migrate data is available under the Settings menu of a project.
💡 Import into a fresh, empty TestCollab project for the cleanest result.
The wizard has four steps shown along the top:
Authenticate → Confirm → Import → Summary.
Step 1 - Authenticate
Authentication is split into three guided panels, so you always know what's being checked.
Panel 1: Validate Xray Credentials
Enter your Xray REST API URL, Xray Client ID, and Xray Client Secret, then click Validate Xray credentials.
A green Validated tag confirms success.
Panel 2: Validate Jira Instance + User + Project Key
This unlocks once Xray is validated. Enter your Jira host, Jira email, Jira API token, and Jira project key, then click Validate Jira instance + project key.
On success, you'll see the project and its size
Panel 3: Configure Import & Continue Choose the Default assignee for imported test plans. Then click Continue.
🔒 Your secrets are encrypted in your browser before they're sent, and are permanently wiped once the import finishes, fails, or is cancelled.
Step 2 - Confirm
A preview screen summarizes exactly what will be migrated:
Test cases - Manual, Cucumber, and Generic types
Test repository folders → TestCollab suite hierarchy
Test sets → TestCollab test plans
Test plans → TestCollab test plans
For each test case, TestCollab preserves the title, description, priority, labels, steps (action and expected result), folder location, and test set/plan membership plus your Xray manual step data in a dedicated Xray Step Data custom field.
Review the summary, then click I understand, start import.
Step 3 - Import
Watch it work in real time. The progress view tracks each stage:
Authenticating with the source system
Importing folders
Importing test cases
Importing test sets & test plans
Finalising You'll see a live progress bar, a running "Last activity" line, and the Import ID. Need to stop?
If you click Cancel - anything already imported stays in TestCollab (it isn't rolled back).
💡 The import runs on TestCollab's servers, so it keeps going even if your network drops. Keep the page open to watch live progress.
Step 4 - Summary
When the import finishes, you get a clear scorecard (See Part 3 below).
What to Expect When It's Finished
The Summary screen gives you a complete, honest accounting of the import; no silent data loss.
You'll see:
Created test cases - the number of new tests added
Suites added - your folder hierarchy, rebuilt as suites
Test sets imported as plans and Test plans imported
A type breakdown - how many Manual, Cucumber, and Generic cases came across
Failed items (if any) and the total time taken
Click View imported test cases to jump straight into your newly populated project, or Done to close the wizard.
What's included and what isn't yet
✅ Migrated in this release
Test repository folders → suite hierarchy
Manual, Cucumber, and Generic test cases
Title, description, priority, labels, and steps (action + expected result)
Xray manual step data → Xray Step Data custom field
Xray key, type, labels, and priority → auto-created TestCollab custom fields
Test sets and test plans, with their membership preserved
Tips & Troubleshooting
Situation | What to do |
Xray validation fails | Re-check the Client Secret (it's shown only once - regenerate the API key if unsure) and confirm the Xray REST API URL matches your region. |
Jira validation fails | Confirm the host is a bare domain, the email matches the token's account, and that account can see the project in Jira. |
"Already imported" | This source project was already imported into this TestCollab project. Use a fresh destination project. |
FAQs
Is my data safe?
Yes. Credentials are encrypted in transit and at rest, never written to logs, and erased the moment the import reaches a final state.
Can I keep working during the import?
The import runs server-side and finishes on its own. Keep the import page open to watch live progress.
💡 You can keep working on other tab of the browser windows.
What happens if I cancel?
The import stops cleanly. Anything already imported remains in your project, nothing is deleted.
Can I run it again to pick up new tests?
Yes, but it may result in duplicates
Ready to migrate? Open your project, choose Migrate from Project Settings