CSV Import Summary Field: Why It's Required and How It Breaks Your Data
Gabriela Perdum
Author
14 min readSeptember 19, 2026
Key takeaways
END STATE: a CSV import that updates an existing Jira issue's custom field, including an Assets/Insight object field, without accidentally overwriting the Summary, verified against Atlassian's own documented import behaviour and checked back through the API afterward.
Three separate Atlassian CSV-import tools exist (Create work items using the CSV importer, External System Import, and the newer import experience), and all three independently require a non-empty Summary column at setup, even though only External System Import documents what a blank Summary does on an update row.
On an update row (Work Item Key present), a blank Summary column preserves the existing summary; a populated Summary column overwrites it. That is Atlassian's own documented behaviour, quoted from its current External System Import doc.
A cross-project CSV needs Project Name, Project Key and Project Type columns, or Jira Cloud refuses to continue without them — a real correction one importer made to a first answer in the source thread, not documented behaviour by itself.
Jira Cloud's REST API returns one 404 message for both 'you can't see this issue' and 'this issue genuinely doesn't exist': {"errorMessages":["Issue does not exist or you do not have permission to see it."]}. Read that ambiguity as a reason to re-check via search, not as proof either way.
The community thread this tutorial is built from never confirmed why the original ticket seemed to disappear. It reappeared on its own a day later. Present that honestly: what's documented, what was observed, and what's still unexplained are three different things, and only the first one is safe to build a process around.
Calvin had roughly 30,000 tickets that needed a single Assets custom field updated. To be safe, he tested on one first: a six-column CSV — Project Name, Project Key, Project Type, Issue Key, Summary, and the Assets field — uploaded through Jira Cloud's CSV importer. No errors. "1 work item updated successfully." Then he went to look at the ticket, PRO-222, and it was gone: "You may have no access or it does not exist," no search for the summary or key turned it up, and the API returned 404.
That thread is where this tutorial starts, and it is also why this tutorial does not end with a tidy "and that's what caused it." Jira's CSV importer really does always require a populated Summary column — that part is documented, verified, and easy to get wrong. What it does to an issue when you get it wrong is murkier than the thread first suggests, and the honest version of that story is more useful than a clean one would be. Jira reporting success while quietly doing something other than what you asked is not a new problem here either — a Jira form smart value can write nothing to a field and still report success, which is the same shape of trap from a different corner of the product.
Note
Prerequisites
Jira admin or project-admin access with permission to run a CSV import (External System Import needs Jira admin; the simpler per-project importer needs project admin).
A CSV file, or the ability to export one from wherever your update data lives.
If you're updating a custom field like Assets/Insight, know its field ID before you start (Step 3 shows how to find it).
A sandbox or a small test batch. Every step below is written to be run on a handful of rows before you run it on thousands.
1
Know which CSV importer you're actually using. The three tools have different rules.
2
Map the Summary column correctly for an update, and understand what blank versus populated actually does.
3
Map a custom field safely, including an Assets/Insight object field.
4
Add the project columns a cross-project import needs.
5
Read a "not found" result correctly before you assume the worst.
6
Test at scale safely, and know what a test can and can't tell you.
Why the Summary Field Is Always Required
Jira Cloud actually has three separate CSV-import code paths, and knowing which one you're in matters before anything else.
Create work items using the CSV importer is the simple one — reached from Filters → Search work items → More actions → Import work items from CSV. It is scoped to one project, and its own documentation is blunt about the one field it cannot do without: "Summary — This is the only required field" and "You must map a CSV field to the Summary field." It also has a hard limit worth knowing up front: "The bulk work item creation option for CSV imports can't map work items with a parent-child hierarchy relationship... To map hierarchies, use the CSV external system import instead."
External System Import is the one Calvin used, and the one this tutorial is mostly about. It is reached from Jira Settings → System → External System Import → CSV, and it is the tool that supports updating existing issues, not just creating new ones. Its documentation states the requirement the same way: "Each CSV file must possess a heading row with a Summary column... The header row must contain a column for Summary data."
The newer "new import experience", aimed at third-party migrations, makes the same demand in its own words: "When importing a file, the summary field is always required."
Three independently maintained Atlassian tools, three independent statements of the same rule. None of them will let you past the field-mapping step without a Summary column mapped to something, even when every other field you actually care about is a custom one.
How to Update Existing Issues Without Overwriting the Summary
This is where External System Import differs from the simpler importer, and where Calvin's problem actually started. External System Import's own documentation states the update mechanism directly: "To update existing work items, your CSV file needs to contain a column that maps to Work Item Key. If a work item exists for a given key, it will be updated." Its worked example is the part worth memorising: a row with the Work Item Key repeated and the Summary column left blank updates other mapped fields (the doc's own example uses votes and labels) without touching the summary at all. A separate row, same shape, with the Summary column populated, "will change the summary."
So the rule for an update-only CSV, stated plainly: map the Summary column to something, because the importer requires it to exist as a column, but leave the cell itself blank on every row where you don't want the summary touched. A populated Summary cell on an update row is not an error, and the importer will not warn you — it will just overwrite the summary, silently, exactly as documented.
How you know it worked: after the import, spot-check a handful of the updated issues' summaries against what they were before. If they're unchanged and only your target field moved, the blank-Summary path worked as documented. If a summary reads "Test Summary" or whatever placeholder text was in that column, it was overwritten — that's the mechanism above, not a bug.
Calvin's actual CSV column was a single Assets object field, and the accepted answer in the thread quoted Atlassian's own Assets-specific KB, word for word: "You'll need at least three columns: Work Item Key, Summary, and Custom Field. During this setup, the Summary column can be left empty." And the reason given for leaving it empty is stated as prevention, not as an error-avoidance claim: "An empty Summary column will prevent unnecessary or unwanted updates to the Issues' Summary." That's the same mechanism as the previous step, just documented a second time specifically for Assets fields, because it's the case people get wrong most often — they're focused on the one field they're changing and don't think about the one Jira always asks for.
Before you map any custom field, find its real ID. Two similarly-named custom fields are easy to mix up, and mapping the wrong one is a much worse mistake than a Summary overwrite — worse because nothing in the import warns you about it either. This is a real field on a live Jira Cloud site, found the same way you'd find yours:
bash
1curl-s-H"Authorization: Basic $AUTH""https://your-site.atlassian.net/rest/api/3/field"\2| python3 -c"
3import json,sys
4for f in json.load(sys.stdin):
5 if f.get('custom') and 'object' in (f.get('schema') or {}).get('custom','').lower():
6 print(f['id'], f['name'], f['schema'].get('custom'))
7"
The schema.custom value tells you what you're actually mapping: cmdb-object-cftype is an Assets/Insight object field. Knowing the real customfield_11149 ID before you go anywhere near the import wizard means that if two similarly-named Assets fields exist on the same site, you can confirm which one you actually mapped by checking the field's ID afterward, rather than relying on a display name alone.
How you know it worked: the response should list every custom field with object in its schema.custom value, each with a real customfield_NNNNN ID next to it. If your target field isn't in that list, filter on a different keyword — schema.custom names vary by app (cmdb-object-cftype is Assets/Insight specifically) — before you trust any name you see in the importer's own dropdown.
Cross-Project Imports Need the Project Columns
Calvin's CSV had Project Name, Project Key and Project Type columns, and the accepted answer initially treated them as redundant with the Work Item Key. Calvin corrected that in the thread, and it's worth recording as his own tested finding rather than something Atlassian documents explicitly either way: "the CSV importer in cloud is telling me I require it, if I'm importing fields across projects. It will not let me continue without them unless I specifically choose the project." If your CSV spans more than one project, add those three columns; if it's a single project, External System Import lets you pick the project once in the wizard instead and skip them.
How you know it worked: the field-mapping step is where this surfaces. If the importer refuses to proceed past mapping and complains about the project, that's the columns being required, not a permissions problem — add them and re-map.
Read a "Not Found" Result Correctly
Here's where the thread gets interesting, and where the story has to be told straight rather than cleaned up.
Calvin's ticket, PRO-222, returned a 404 after his import: "You may have no access or it does not exist." The accepted answer in the thread pointed out that this is one message covering two different situations — a permissions problem and a genuinely missing issue look identical from the outside. That distinction is Gabriela's own observation in the thread, not something Atlassian's documentation states explicitly, and it's worth verifying yourself rather than taking on faith. Querying the REST API for an issue that doesn't exist on a live Jira Cloud site returns exactly this:
1{"errorMessages":["Issue does not exist or you do not have permission to see it."],"errors":{}}
Same ambiguity, same two causes folded into one sentence, confirmed directly from the API rather than the UI's wording. If you hit this after a CSV import, the useful next step is not to assume the worst — search for the issue by something other than its key (a distinctive value in another field, or the reporter and rough creation time), and check whether your account's permissions on that project changed recently. Both are more common causes than data loss.
How you know it worked: run the same GET /rest/api/3/issue/<key> call against a key you know is fine. It should return 200 with the issue's fields, not the errorMessages body above — that confirms your token and permissions are working normally, which narrows a 404 on the issue you actually care about down to "permissions on that one item" or "genuinely gone," rather than a token problem affecting everything.
Test at Scale Safely
This is the honest part of the story, and it's the reason this tutorial ends with a test rather than a fix.
Calvin re-ran his import with the Summary column blank, and it worked: "did it again with summary as empty and it looks like it worked." But PRO-222, the original ticket, stayed unreachable at that point — "Tried the API call on PRO-222 and its unfortunately showing 404, other IDs work however. So will definitely be keeping that summary part blank!" Gabriela's later reply in the thread flagged the causal question as open, not settled: the run that lost PRO-222 had both a populated Summary and the project columns present together, and the successful re-run changed only one of those two things at once — which one actually mattered was never isolated.
And then the thread's last message undercuts the story further. The same day, Calvin wrote back: "gave it some time, and it looks like its appeared back today! Maybe it was an indexing issue of some sort? But even the API returns '200 OK' odd but will definitely do a 10 row check just incase." No reply after that settles what actually happened. The ticket came back on its own, with no import run responsible for its return, and "an indexing issue" is Calvin's own guess, not a confirmed cause.
So the documented fact and the observed story are two different things, and this tutorial keeps them separate on purpose: documented — a populated Summary on an update row overwrites the existing summary, verified directly from Atlassian's current External System Import page. Observed, once, unconfirmed — an issue became briefly unreachable after an import with a populated Summary and project columns together, and reappeared a day later for no import-related reason anyone identified. Still open — whether the Summary overwrite, the project columns, an indexing delay, or something else entirely caused the disappearance.
Given that, the safe process is the one Gabriela's later reply recommends: before running a CSV update at scale, run it against ten rows in a sandbox first, with the project columns present and the Summary column blank, then re-query every one of those ten issues by key through the API a few minutes later. If all ten come back clean, that's real evidence for your specific CSV shape and your specific site — evidence this tutorial's own source thread never quite got to collect.
How you know it worked: ten issues updated, ten issues still resolvable by key through the API afterward, with only the intended field changed. That's a test that actually answers the question Calvin's thread left open, on your own data, before it matters at 30,000 rows instead of one.
If you're auditing what a migration actually moved rather than what a CSV import changed, a Jira migration has its own version of this problem, one JQL clause deep — a query that silently reads a missing field as zero results instead of an error, which looks exactly as clean as a working query until someone checks by hand.
Where this leaves you
Key takeaways
You now have a CSV update that maps the Summary column deliberately, leaves it blank on update rows on purpose, adds project columns when the import spans more than one project, and finds a custom field's real ID before mapping it — checked against Atlassian's own current documentation for all three CSV-import tools, not just the one you happen to be using.
You now have a way to read a Jira 404 correctly: one message, two causes, confirmed against the live REST API's own error text, and a second API call that tells you which cause you're actually looking at.
You now have a ten-row sandbox test that answers, on your own data, the question the source thread never settled — whether your specific CSV shape is safe to run at scale — before you run it at scale.
This does not cover why Calvin's original ticket became briefly unreachable and then came back on its own. That was never confirmed, by Atlassian or by the thread, and this tutorial does not invent an answer it doesn't have. Treat it as the reason to test first, not as a solved mystery.
This does not cover the field-mapping UI itself step by step, or Assets/Insight object schema design — only the Summary-column trap and the parts of custom-field mapping that interact with it.
