A spreadsheet can arrive in Jira with every row accounted for and still lose the information a tester needs. Actions may become a block of description text, expected results may attach to the wrong step, and requirement keys may remain ordinary text instead of coverage links. An import-success message does not establish that the migrated cases are usable.
To import test cases from Excel to Jira, first choose the destination test-management app and its deployment-specific importer. Then preserve case identity, map ordered steps and requirement relationships, and reconcile a small pilot against explicit expectations before moving the remaining library.
Native Jira CSV import operates on Jira work items, traditionally called issues. It can map fields and supported relationships, but a column named Test Steps does not tell Jira how to construct an app's action, data, and expected-result records. Creating a work type named Test does not supply those semantics either.
For structured manual cases, use the selected app's documented import format. Some advanced paths can carry app-specific serialized fields through native CSV import, but that requires the app's representation. It is different from mapping readable spreadsheet step rows directly.
The worked path below uses Xray Data Center's Test Case Importer, following the vendor's Server/Data Center documentation family. It imports manual cases from CSV, so Excel is the preparation tool rather than the file format submitted to this importer. Confirm the installed Xray and Jira versions with the administrator before using the documented menus and mappings.
Do not reuse the mapping unchanged in Xray Cloud. Its importer documents a different mandatory-field set, including Issue Id, Summary, and Test Type. Tricentis Test Management for Jira has another approach: its Excel template uses Step Description, Step Data, Expected Result, and Requirements, with merged Summary cells for a multi-step case. It documents comma-separated entries for multiple requirements. Neither that merged-cell structure nor that list convention belongs in the Data Center CSV example below.
A migration needs both a durable identity for each case and a reliable way to reconstruct its ordered steps. Keep the untouched workbook, then prepare a separate migration copy. Resolve ambiguous groupings before exporting, while the source author can still explain them.
In the Xray Data Center importer, Test Case Identifier groups CSV records belonging to the same case. A source column named TCID can hold XL-001 on every step row of one case and XL-002 on every step row of another. Those repeated identifiers are intentional. Assigning a different identifier to every step would destroy the grouping.
A grouping identifier is not an existing Jira Issue Key. Keep the original external case ID in a configured, supported custom field as well, and maintain a source-to-target ledger after import. The ledger should connect XL-001 to the actual Jira Test key returned or confirmed afterward. Do not assume that repeating XL-001 in a later file will update or deduplicate a previously imported Test.
Give each case a stable destination home and an accountable maintainer before importing it. Avoid copying the same specification into separate release folders merely to organize a batch. The guidance on repository folders, labels, and ownership helps establish those filing decisions without changing a case's identity.
Prepare one CSV data record per manual step, repeating TCID through the case group. Keep groups together and arrange their records in the intended step sequence. A local StepOrder column can support sorting and review, but do not assume that an unmapped number controls the destination order.
The following mapping uses the Data Center importer, not a universal Jira schema. Source column names are illustrative; destination fields must exist in the installed configuration.
Source Column | Xray Data Center Mapping | Preservation Check |
|---|---|---|
TCID | Test Case Identifier | Same value throughout one case group; different value for another case |
Summary | Summary | Case title on the first record of the group, following the vendor's continuation-row pattern |
Action | Action | One action per step record, in the intended sequence |
Data | Data | Input belongs to that action, not to the next record |
Result | Expected Result | Expected outcome remains attached to its step |
Requirement1 | Link "Tests" | Existing requirement key, using the configured coverage relationship |
Requirement2 | Link "Tests" | Another requirement in a separate column, mapped the same way |
ExternalID | Configured external-ID custom field | Original case identity remains available after import |
StepOrder | Local audit column, not mapped in this example | Sort and verify before export; retain in the source ledger |
Xray's documentation requires Test Case Identifier, Summary, and Action mappings for this path. Mapping only those required fields would still lose other unmapped content. Include data, results, requirements, and applicable case metadata deliberately. Check that custom fields apply to the Test issue type and that the project's Test screens and required fields are configured correctly.
Keep preconditions and case-level context distinct from step data. Map them only to suitable supported fields in the actual installation. Do not silently turn historical Actual Result or Status columns into expected results; those describe execution evidence, which needs a separate migration decision.
Use cases that expose structural errors rather than selecting only short, single-step examples. This illustrative payment pilot contains two source cases. XL-001 checks an approved payment and covers PAY-41 and PAY-42. XL-002 checks a declined payment and covers PAY-41. These identifiers and fixtures are examples, not records from a real Jira site.
The display below combines case ID and step position for review. In the actual CSV, TCID is its own repeated column; the displayed step number is not part of that identifier.
Case and Step | Action | Data | Expected Result |
|---|---|---|---|
XL-001, step 1 | Open checkout | Résumé, mug | Checkout is ready |
XL-001, step 2 | Enter approved payment | card-approved | Payment details accepted |
XL-001, step 3 | Select "Pay" | Empty | Order confirmed, followed by Payment captured on a new line |
XL-002, step 1 | Open checkout | Résumé, mug | Checkout is ready |
XL-002, step 2 | Submit declined payment | card-declined | Decline displayed; no confirmed order |
Populate Summary, ExternalID, and a migration-batch label on each case's first record, leaving those case-level continuation cells empty as in the vendor's examples. For XL-001, put PAY-41 in Requirement1 and PAY-42 in Requirement2 on that first record. For XL-002, put PAY-41 in Requirement1 and leave Requirement2 empty. Map both requirement columns to the coverage link field. Do not put the two keys into one comma-separated field for this Data Center mapping.
The expected result is two new cases, five steps, two distinct requirement keys, and three case-to-requirement relationships. There should be no duplicate cases. Counting distinct requirement keys alone would miss a lost relationship because PAY-41 belongs to both cases.
Export with a known delimiter and encoding, then inspect the exported file rather than relying only on Excel's display. This example uses semicolon-delimited UTF-8 CSV. A value containing a semicolon or an embedded newline must be quoted; a literal double quote inside a quoted field is doubled. A comma-delimited file would also require quoting the comma in Résumé, mug. Empty cells must retain their separators.
Keep the final expected result for XL-001 as one field containing an embedded newline, not as another step record. The illustrative CSV was round-tripped locally through a CSV parser to check its cells, quoting, Unicode, grouping, and counts. That check verifies the file structure, not Xray's behavior in a tenant. Count parsed records, not physical text lines: a newline inside a field increases line count without adding a case or step.
A requirement key must identify an existing target requirement. If requirements were migrated separately, translate source references through the approved old-to-new key map first. Search for missing, mistyped, or inaccessible keys before import. A plausible-looking PAY-41 string is not proof that the intended requirement exists or that the importing user can access it.
For newly created Tests, the Data Center documentation specifies Link "Tests" for requirement coverage. Confirm the actual configured coverage relationship and its direction with the administrator. A Test should cover the requirement; an arbitrary relates-to link or a key pasted into Description does not establish the same relationship. Inspect the reverse relationship and coverage view on the requirement after the pilot.
Treat this link mapping as a create-path capability. The documented importer section describes links for newly created Tests, so do not promise it will repair requirement links when updating existing Tests. Handle that work through a separately verified linking operation and reconcile it independently.
The documented non-administrator Data Center route requires Bulk Change and Create Issues permissions. Updating existing cases also requires Create and Edit permissions for the affected issues. Have the administrator confirm visibility, issue security, and applicable linking permissions for both Tests and requirement targets, especially across projects. Folder operations have additional configuration and permissions; omit optional folder mapping until those are verified.
Use an account with the required access, not a broad administrator grant chosen solely to bypass a failed pilot. An administrator's successful import does not show that maintainers can subsequently find, edit, or review the cases.
The following is a procedure for an authorized migration operator. It is not a report of an import performed for this example.
Investigate differences by mechanism. One case containing both payment paths suggests a grouping mistake. Five created Tests suggests step rows were treated as separate cases. Correct titles with missing results suggests an omitted or incorrect field mapping. A requirement key visible only in Description suggests text was imported instead of a relationship.
Totals are necessary but insufficient. Two cases can still contain swapped steps, and three links can point to the wrong requirements. Compare the actual source-to-target pairs and ordered step contents. Stop on unexplained differences rather than accepting a successful importer screen as reconciliation.
Create and update are different migration modes. A new-case file must not accidentally map source IDs into Issue Key. An update file needs the actual existing Jira keys, with each target deliberately approved in the ledger.
For this Data Center path, Xray documents that an update key must belong to the selected project and identify an existing editable Test with Manual Test Type. Its manual steps are overwritten by the CSV's new step specification, including step custom fields. This is not an append operation. To add a final check through this importer, provide the complete desired step list, not only the extra step, or earlier steps can be lost.
Other fields follow the applicable native Jira import rules. Do not infer a universal meaning for blank update cells across products. Tricentis Test Management for Jira explicitly warns that blank Excel fields delete existing values during updates and recommends starting from exported existing data. That warning belongs to its own importer; it is not a rule to transpose to Xray Cloud or Data Center.
If an import times out or its outcome is unclear, inspect the destination before retrying. A batch label and external-ID ledger help distinguish created, updated, missing, and ambiguous cases. Replaying a create file can create duplicates; replaying an update can replace steps again. Reconcile the actual state first.
An export is useful recovery evidence, but it is not a guaranteed rollback. Xray can serialize Manual Test Steps as JSON inside a CSV export, which differs from this readable step-row format. Rehearse restoration through the appropriate supported path. A definition export does not establish that execution history, attachments, permissions, or every relationship can be reconstructed. Full project restoration has administrator, configuration, and version constraints, so agree on recovery scope before overwriting production cases.
Approve the migration when case identity, ordered step content, requirement relationships, duplicate checks, and intended-user access all match the agreed expectations. For new cases, record which created keys could be removed under an approved recovery plan. For updates, retain the before-state and tested restoration procedure; deleting the updated case would not restore it.
Move the remaining library in bounded batches with a reviewed ledger and a controlled editing window. Keep source files unchanged until acceptance, and assign someone to resolve exceptions rather than letting later batches hide them. The next batch should start from a reconciled destination, not from the assumption that the previous upload finished correctly.
A green automated test history can help a developer identify a safe-looking change while leaving a QA lead unable to answer a different question:…
A checkout test appears under Payments, again in a Smoke folder, and once more under the latest release. When the payment rules change, someone…
A Jira story is Done, a test case is linked, and the related bug is Closed. Can the release owner conclude that the story's…
Create traceable test cases, prepare release-specific test runs, and keep approved coverage current as the product changes.
