Jira import from CSV: moving a task spreadsheet without losing fields

A Jira import from CSV almost never fails in a way that stops the job. It finishes, reports a count, and leaves a project full of work items where the due dates are empty, the subtasks are sitting at the top level, and three hundred labels have turned into one. The damage is quiet, and it shows up two weeks later when someone asks why the timeline is blank.

The importer itself is not the problem. It does exactly what the header row of the file tells it to do. Most of the work of a clean import happens in the spreadsheet, before anything is uploaded, and most of the loss happens because a column name did not match a field that exists on the other side.

Where a CSV import actually loses data

There are four places where fields go missing, and they are worth naming separately because the fixes are different.

The first is a column that has no matching field. The wizard reads the header row and offers a mapping screen. Any column left unmapped is dropped without complaint. A column called Owner will not become Assignee on its own.

The second is a field that exists but will not accept the value. Atlassian's documentation is specific about which fields tolerate invented values and which do not. For Resolution, Priority, and Work Type, missing values can be created during the mapping step. For Status, they cannot: the list is fixed, and a value that is not in it has to be mapped to something that is.

The third is multi-value data collapsing. Labels, components, and fix versions accept several values per work item, but a CSV has one cell per column. The importer handles this by reading repeated column names, which means a file with a single Labels column can only ever carry one label per row.

The fourth is date parsing. Dates fail more often than anything else, and they fail per row rather than per file, so an import can be ninety percent correct and still leave a scattering of work items with no due date at all.

None of these four produce a red error on the summary screen. They produce a smaller number than expected in a column nobody checks.

The header row is the mapping

Everything the importer knows about the file comes from row one. Atlassian's requirements for that row are short and strict.

The header row must contain a column for Summary data, and every work item must have something in it. Without a Summary the row has nothing to become. The documentation also advises keeping punctuation out of the header row, other than the commas that separate the columns, because the importer can misread it.

Commas cannot be dropped at the end of a row. A header with six columns needs six fields in every data row, even when the last two are empty. This is valid:

Summary, Assignee, Reporter, Work Type, Description, Priority
"Test work item", [email protected], [email protected], 1, ,

This is not, and it is the single most common reason a hand-edited file is rejected:

Summary, Assignee, Reporter, Work Type, Description, Priority
"Test work item", [email protected], [email protected], 1

Spreadsheet applications write the trailing commas automatically. Files that have been edited in a text editor, or generated by a script, are the ones that lose them.

For multi-value fields, the trick is repetition. The same column name appears as many times as the maximum number of values any single row needs:

WorkType, Summary, FixVersion, FixVersion, FixVersion, Component, Component
bug, "First work item", v1, , , Component1,
bug, "Second work item", v2, , , Component1, Component2
bug, "Third work item", v1, v2, v3, Component1,

Three FixVersion columns means up to three fix versions per row. If one work item in the export has five labels, the file needs five Labels columns and every other row needs four empty cells. Counting the maximum before exporting is faster than discovering it afterwards.

Hierarchy: getting subtasks and epics to land in the right place

Hierarchy is where a flat export from another tool does the most damage, because a spreadsheet has no natural way to express a parent.

Jira's CSV importer builds the relationship from three columns: Work item ID, Work type, and Parent. Each row gets a unique sequential number in the ID column, and a child row puts its parent's number in the Parent column. Two rules matter. Every ID has to be unique within the file, and the parent row must appear before its children in the file. A child that references a parent further down the file will not be linked.

WorkType, Summary, Work item ID, Parent
Bug, "First work item", 1, 
Story, "Second work item", 2, 5
Bug, "Third work item", 3, 
Sub-task, "Fourth work item", , 2
Epic, "Fifth work item", 5, 

In that file the sub-task attaches to the story, and the story attaches to the epic. Sorting the export so that epics come first, then stories, then subtasks, removes most of the pain. Referencing a parent that exists in the target project already works too, as long as the key is real.

The other structural column pair is Space name and Space key, which lets one file land in several projects. Every row needs both values filled in, and the wizard has to be set to take the destination from the file rather than from a single selected project. Splitting one export into several files, one per project, is usually easier to verify than one file with a project column, but the option exists when the source tool cannot separate them.

Dates, worklogs, and attachments

Date format is set once, for the whole file, on the project mapping screen. The field expects a pattern in Java SimpleDateFormat syntax, which means the pattern has to describe the file rather than the other way round. Two details from Atlassian's own troubleshooting notes save a lot of time here. Custom date fields default to yyyyMMddHHmmss, while Jira's system date fields such as Created, Updated, and Due Date use yyyy-MM-dd HH:mm:ss. A file that mixes two formats in different columns will fail on one of them, and the error names the value rather than the column.

The safest move is to normalise every date column in the spreadsheet to one ISO-style format before export, rather than trying to find a pattern that fits what the previous tool happened to write.

Worklogs go in a Worklog column and time spent has to be expressed in seconds. One hour is 3600. A fuller entry carries a comment, a timestamp, an author, and the seconds, separated by semicolons:

Summary,Worklog
Only time spent (one hour),3600
With a date and an author,2012-02-10 12:30:10;wseliga;120

Attachments are referenced by URL in an Attachment column, using HTTP or HTTPS, and the address has to be reachable from the Jira site doing the import. This is the step that quietly fails when an export came from a tool behind a login: the file lists a hundred attachment URLs, the importer cannot fetch any of them, and the work items arrive with no files. Exporting attachments to somewhere publicly readable first, or accepting that they will be re-uploaded by hand, is a decision worth making before the import rather than after.

Cascading select fields use an arrow between the levels, as in Parent Value -> Child Value. Multi-select custom fields follow the same repeated-column rule as labels.

File size, batches, and the configuration file

Atlassian publishes a recommended batch size rather than a hard limit: around 1,500 work items per file, taking roughly an hour to import. Larger files are not rejected, they just slow down and become harder to recover from. Running the job outside working hours is the other suggestion, for the same reason.

That number is a useful planning unit. A 6,000 item backlog is four files, four verification passes, and a day of attention rather than one upload and a hope. Splitting also gives a natural rollback story: if the second batch is wrong, the damage is confined to 1,500 items with known keys.

The wizard's Advanced section is where encoding and delimiter live. Encoding defaults to UTF-8, and a semicolon-separated file from a European locale needs the delimiter changed here or every row arrives as one long summary.

At the end of a successful run Jira writes a configuration file that records the mapping between the file's columns and Jira's fields. Saving that file is the difference between one import and a repeatable one. The second batch can reuse it, which removes the chance of mapping a column differently the second time round, and that kind of inconsistency is exactly what produces a project where half the work items have a due date.

Access matters too: the external system import sits under Settings, then System, then External System Import, and reaching it needs Jira administrator rights. On a site where that is somebody else's account, the person preparing the spreadsheet and the person running the import are different people, and the mapping decisions have to be written down rather than made live.

Updating existing work items with the same importer

The CSV importer is not only a create tool. A file containing a column mapped to Work Item Key will update the work items whose keys it names instead of creating new ones, which turns it into a bulk edit that goes through the same mapping screen.

Work item key,summary,votes,labels,labels
TT-1,Original summary,1,label1,label2
TT-1,,7,label-1,label-2
TT-2,,<<!clear!>>,<<!clear!>>,

Blank cells leave the existing value alone. The <<!clear!>> marker empties a field. This is the fastest way to fix a partially bad import without deleting anything, and it is also the fastest way to wipe a field across a thousand work items by accident, so a two-row test file on two known keys is worth running first.

Goal	Column that drives it	Failure mode if wrong
Create work items	Summary	Row skipped
Set a parent	Work item ID and Parent	Child lands at top level
Several labels or versions	Repeated column names	Only the first value arrives
Update rather than create	Work Item Key	Duplicate work items created
Clear a field	<<!clear!>>	Old value stays

A dry run that costs one hour

Import twenty rows into a throwaway project first. Pick rows that are deliberately awkward: one with five labels, one subtask, one item with a due date and a worklog, one with an assignee who is not yet a user on the site, one with a comma and a quotation mark inside the description.

Then open five of those work items and read them field by field against the spreadsheet. Counting work items tells you nothing, because the count is almost always right. Reading fields is what catches the collapsed labels and the empty dates while the fix still costs minutes.

Keep the configuration file from that run. It becomes the mapping for the real batches, and it is the only artefact that makes the second and third file behave like the first.

What to change first

Before touching the importer, take the export and count the maximum number of labels, components, and versions on any single row, then add that many repeated columns. That one step prevents the most common form of silent loss. If the migration is also a chance to reconsider the tool, the boards, chat, and timeline in Pinateca arrive configured rather than needing a field scheme first, and there is a one-click path for moving boards across from Trello when the source is Trello rather than a spreadsheet.

Q1. Why does a CSV import create work items but leave all the due dates empty?

The date format on the project mapping screen did not match the format in the file. Jira parses every date column with the single pattern given there, expressed in Java SimpleDateFormat syntax, and a value it cannot read is skipped rather than guessed. Normalise every date column to one format in the spreadsheet, then set that pattern once.

Q2. Does importing a CSV file require Jira administrator rights?

The External System Import screen used for CSV files sits under Settings, then System, and reaching it requires Jira administrator permissions. If those rights belong to someone else, prepare the file and the column-to-field mapping in writing so the person running the wizard does not have to make mapping decisions on the spot.

Q3. How many rows should one CSV file contain?

Atlassian recommends roughly 1,500 work items per file, with an import taking about an hour, and suggests splitting larger sets into separate batches run outside peak hours. Bigger files are not blocked, but they take longer and make a partial failure harder to unpick.

Q4. Can a CSV file edit work items that already exist?

Yes. Include a column mapped to Work Item Key, and rows whose key already exists are updated instead of created. Empty cells leave the current value in place, and the special marker <<!clear!>> empties a field. Test it on two known keys first, because a mapping mistake applies to every row in the file.

Q5. Why did only one label out of several come through?

A CSV cell holds one value, so multi-value fields are built from repeated column names. Three labels on a row needs three columns all named Labels. With a single Labels column the importer has nowhere to put the second and third values, and they are dropped without an error.