Jira CSV Import Preflight Guide

CSV import looks deceptively simple: prepare a spreadsheet, save it as CSV, map the columns, and click import.

The difficult part is that a CSV can be structurally valid and still produce the wrong result. Jira may reject the file, skip values, create new work items instead of updating existing ones, or import rows without the relationships you expected.

This guide covers the checks worth making before a non-trivial Jira CSV import.

1. Decide whether you are creating, updating, or migrating

Before checking the file, define the intended operation:

• Create: all or most rows should become new Jira work items.
• Update: rows should modify existing Jira work items.
• Migrate: the file may include hierarchy, users, historical dates, attachments, custom fields, and mixed create/update behavior.

This matters because the same CSV pattern can be normal in one context and dangerous in another. Blank Work Item Keys are normal when creating new items; in an update file, mixed populated and blank keys may mean some rows update while others create new items.

Check

• Is the intended operation explicit?
• Does every row belong in that operation?
• If the file mixes creates and updates, is that deliberate?

2. Verify the Summary source and every Summary value

Jira requires a Summary mapping. A source column can have another name — such as Title, Task Name, or Subject — but it must ultimately be mapped to Jira's Summary field.

Also check every row. Jira Cloud can block progress when the column mapped to Summary contains blank cells.

Risky example

Work Type,Summary,Priority
Task,"Prepare migration plan",High
Task,,Medium

Check

• Is there a clear Summary source?
• Are there blank or whitespace-only values?
• If the source header is unusual, will the importer recognize that it must be mapped to Summary?

3. Check field counts, quoting, and line breaks

CSV is not simply "values separated by commas." Descriptions and comments often contain commas, quotation marks, and line breaks. Those values must be quoted correctly. One malformed field can shift columns or cause a vague parser error.

Atlassian recommends enclosing content containing commas or line breaks in quotes.

Valid example

Summary,Description
"Login problem","The user clicks ""Sign in"", but the page returns to login."

Check

• Does every row have the same field count as the header?
• Are embedded quotes escaped?
• Are multiline values correctly quoted?
• Is the file valid UTF-8?
• Does it contain unexpected control characters?

4. Treat blank headers as potential silent data loss

A blank header does not always stop Jira from importing the file.

Risky example

Summary,,Priority
"Review permissions","This value has no field name",High

Check

• Does every populated column have a nonblank header?
• Are there trailing unnamed spreadsheet columns?
• Are there duplicate or nearly duplicate headers?

5. Distinguish Work Item ID from Work Item Key

These fields serve different purposes:

• Work Item Key identifies an existing Jira item, such as PROJ-123.
• Work Item ID in a migration CSV is commonly used as an import-local identifier so other rows can reference it.

Jira terminology has changed over time. Older documentation and exports may use Issue Key, Issue ID, and Issue Type; newer Jira Cloud screens may show Work Item Key, Work item ID, and Work Type.

Accidental-duplicate risk

Ticket,Summary
PROJ-123,"Correct existing item"
PROJ-124,"Update another item"

The values look like Jira keys, but Ticket is not an obvious Work Item Key header. If it is not mapped correctly, an intended update may create new items instead.

Check

• Does the file contain Jira-key-shaped values such as ABC-123?
• Is the header deliberately mapped to Work Item Key?
• Are some key values blank while others are populated?
• Does the same Work Item Key appear on multiple rows?

6. Validate Parent relationships inside the CSV

Hierarchy is one of the highest-risk areas. For self-contained hierarchy imports, each parent should have a unique Work Item ID, and each child's Parent value should reference that ID. Atlassian's current guidance likewise emphasizes unique IDs and explicit Parent mapping.

Example

Work item ID,Parent,Work Type,Summary
100,,Epic,"Portal migration"
101,100,Task,"Migrate authentication"
102,100,Task,"Migrate billing"

Common risks

• Parent exists, but there is no Work Item ID column.
• Parent values mix numeric IDs, Jira keys, and arbitrary text.
• Parent references an ID absent from the file.
• IDs are duplicated.
• A row references itself.
• Parent relationships form a cycle.

Important live-test observation

Check

• Is every nonblank Parent value defined by another Work Item ID in the file?
• Are Work Item IDs unique?
• Are Parent values consistently formatted?
• Are there self-references or cycles?
• Will you verify hierarchy after import?

7. Do not rely only on row order for hierarchy

Atlassian guidance recommends listing hierarchy in parent-before-child order. However, in our July 2026 test, a child placed before its parent still imported with the correct relationship.

The conservative approach remains:

• place parents before children;
• use unique import-local IDs;
• verify relationships afterward.

A successful import message is not proof that hierarchy was preserved.

8. Normalize destination-dependent values

Fields such as Status, Priority, Work Type, Component, Version, and custom select fields depend on the target Jira configuration. When importing into an existing Jira space, Atlassian states that fields, statuses, work types, and custom fields must already exist there.

The CSV cannot prove those values exist, but it can reveal suspicious inconsistencies.

Risky example

Summary,Status,Component
"First item","In Progress","Billing"
"Second item","in progress","billing"
"Third item","In Progress ","Billing "

Check

• Do values differ only by capitalization?
• Do values contain leading or trailing spaces?
• Are there spelling variants?
• Does the destination contain every required value?
• Does the chosen importer allow value mapping for those fields?

9. Use one deliberate date convention

Jira's date import depends on the importer format matching the CSV values. Atlassian notes that mismatches can make dates malformed or cause them to be skipped.

Risky example

Summary,Due Date
"First item","2026-09-30"
"Second item","30/09/2026"
"Third item","09/10/2026"

The final value is ambiguous: it could mean 9 October or 10 September.

Check

• Does each date column use one consistent pattern?
• Are day/month values ambiguous?
• Are date-only and date-time values mixed?
• Does the selected Jira date format match exactly?
• Has spreadsheet software silently reformatted the dates?

10. Check user identifiers

Assignee, Reporter, and Creator values may fail to resolve if the file uses display names or inconsistent identifiers.

Risky example

Summary,Assignee
"First item","jane@example.com"
"Second item","Jane Smith"
"Third item","712020:abcdef123456"

The CSV cannot confirm whether a user exists or has permission in the destination site.

Check

• Does each user column use one identifier style?
• Are display names being used where email or account ID may be required?
• Do the users exist and remain active?
• Are privacy-hidden email addresses involved?
• Have Reporter/Creator preservation requirements been tested separately?

11. Check attachment URLs from Jira Cloud's point of view

A path that works on your computer may be unreachable from Jira Cloud.

Usually unsafe

file:///Users/alice/Desktop/report.pdf
C:\Migration\report.pdf
http://localhost:8080/report.pdf
http://192.168.1.20/report.pdf

Check

• Is every attachment URL HTTP or HTTPS?
• Can it be reached without access to a private network?
• Does it require login or a temporary token?
• Will it remain available during the import?
• Does the URL expose credentials in its query string?

12. Run a disposable test import and reconcile the result

A file-level preflight reduces risk, but it cannot replace a controlled Jira test.

For a non-trivial migration:

1. Use a disposable test project or space.
2. Import a representative subset.
3. Verify row counts, hierarchy, fields, dates, users, links, and attachments.
4. Record the mapping configuration.
5. Correct the CSV.
6. Repeat until the result is predictable.
7. Only then run the real import.

Jira provides different import paths and capabilities, including the External System Import route for imports into an existing space.

Compact Jira CSV preflight checklist

Before importing, confirm:

Free automated file check

Jira CSV Preflight checks many of the file-level risks above, including structural CSV errors, blank Summary values, hierarchy risks, mixed create/update identifiers, key/ID mapping traps, ambiguous dates, user identifier patterns, value collisions, and private attachment URLs.

Privacy note: uploaded files are transmitted to the test server, processed in memory, and not intentionally retained by the application. The application does not store uploads in a database or permanent upload directory. During the prototype stage, use sanitized or non-confidential files and do not upload secrets or highly sensitive production data.

What a file-only checker cannot verify

No offline CSV checker can confirm all destination-specific behavior. You must still verify in Jira:

• whether users exist and are active;
• whether fields are available in the target space;
• whether statuses and work types exist;
• whether custom-field options and contexts match;
• whether permissions allow the import;
• whether workflows accept mapped values;
• whether the selected importer exposes every feature you need.

The goal of preflight is not to guarantee success. It is to catch preventable risks before they become expensive cleanup.

Sources and further reading

• Atlassian: Prepare a CSV file for import
• Atlassian: Map CSV data to Jira fields
• Atlassian: Import data to Jira using CSV
• Atlassian: Import work into an existing Jira space
• Atlassian: Keep parent-child relationships during CSV import
• Atlassian: Dates are not properly imported from CSV

Last reviewed: 11 August 2026.