Creating issues using the CSV importer

Creating issues and sub-tasks

On this page

Use the CSV importer to bulk create or update issues. If you need to create subtasks or add new fields, you'll need to be a system admin and use Importing issues instead.

Before you use the CSV importer, make sure you have the Create Issue project permission and the Bulk Change global permission for the project you want to create or update issues in.  

 

On this page:

Prepare the CSV file

You can base the structure of your CSV file off the default Microsoft Excel CSV format. Fields should be separated by commas, and any content that must be treated literally (such as commas, new lines, and carriage returns) should be enclosed in quotes. Microsoft Excel and OpenOffice automatically quote values in cells, so there's no need to quote these values manually. 

CSV file requirements

Requirement Details
Each CSV file must have an unpunctuated header row with a Summary column

The CSV file import wizard uses the CSV file header row to determine how to map data from the file's 2nd row and beyond to fields in Jira.

Make sure the header:

  • doesn't contain any punctuation apart from the commas separating each column
  • contains a column for Summary data
Delimit columns and fields with commas

For example, this is valid:

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", admin, admin, 1, ,

This is not valid:

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", admin, admin, 1

 

How to structure data in the CSV file

Data type CSV file structure
Summary This is the only required field.
Affects Version(s) You can import issues with multiple 'Affects Versions' by entering each version in a separate column.
Attachments

You can attach files to issues created from your CSV file. To do this, specify the URL of your attachment in an Attachments column within your CSV file.

Assignee, Summary, Description, Attachment, Comment
Admin, "Issue demonstrating the CSV attachment import", "Please check the attached image below.", "https://jira-server:8080/secure/attachment/image-name.png", "01/01/2012 10:10;Admin; This comment works"
Admin, "CSV attachment import with timestamp,author and filename", "Please check the attached image below.", "01/01/2012 13:10;Admin;image.png;file://image-name.png", "01/01/2012 10:10;Admin; This comment works"

Note that URLs for attachments support the HTTP and HTTPS protocols and can be located anywhere that your Jira Cloud site can access.

Cascading choice custom fields

You can import values to a cascading choice custom field using the following syntax:

Summary, My Cascading Custom Field
Example Summary, Parent Value -> Child Value

The '->' separator allows you to import the hierarchy.

You can't yet import multi-level cascading select fields via CSV. You can track progress on that limitation here: JRASERVER-34202 - Allow CSV import to support Multi-Level Cascading Select plugin fields Open .

Comment Body You can import issues with multiple comments by entering each comment in a separate column.
Component(s) You can import issues with multiple components by entering each component in a separate column.
Data that spans multiple lines

Use double-quote marks (") in your CSV file to capture data that spans multiple lines. For example, Jira treats the following as a valid CSV file with a single record:

Summary, Description, Status
"Login fails", "This is on
a new line", Open
Due Date Please use the date format specified on the second step of the CSV import wizard.
Fix Version(s)

You can import issues with multiple 'Fix Versions' by entering each version in a separate column.

Issue Type If not specified in your CSV file, imported issues will be given the default (i.e. first) Issue Type, as specified in your Jira instance. For more information, see Defining issue type field values
Labels

You can import issues with multiple labels by:

  • entering each label in a separate column or
  • putting all labels in one column, deliminated by a space
Multiple values that need to be aggregated into single issue fields 

You can import multiple values into a single Jira field that accepts multiple values (e.g. Fix (for) Version, Affects Version, Component, Labels). To do this, your CSV file must specify the same column name for each value you wish to import to the same field. The number of column names specified must match the maximum number of values to be aggregated into the mapped field.

For example:

IssueType, Summary, FixVersion, FixVersion, FixVersion, Component, Component
bug, "First issue", v1, , , Component1,
bug, "Second issue", v2, , , Component1, Component2
bug, "Third issue", v1, v2, v3, Component1,

In the above example, the Component field of the second issue and the Fix Version field of the third issue will generate multiple values in the relevant field after importing.

Multi-select custom fields

Your CSV file can contain multiple entries to populate the Multi Select Custom Field with multiple values. For example:

Summary,Multi Select,Multi Select,Multi Select
Sample issue,Value 1,Value 2,Value 3
Original Estimate The value of this field needs to be specified as number of seconds.
Other fields If you wish to import any other fields, you can map them to Jira custom fields. If the custom field is a date field, please use the date format specified on the second step of the CSV import wizard.
Priority If not specified in your CSV file, imported issues will be given the default (i.e. first) Priority as specified in your Jira instance. For more information, see Defining priority field values
Project CSV data is imported on a per-project basis. You can either specify an existing project(s) as the target, or the importer will automatically create a new project(s) for you at time of import.
Remaining Estimate The value of this field needs to be specified as number of seconds.
Special characters

Use double-quote marks (") around a section of text to treat special characters in that section literally. When the data is imported, these special characters are stored as part of Jira's field data. Examples of special characters include carriage returns/enter characters, commas, etc.

To treat a double quote mark literally, you can add another double quote mark character:

"Clicking the ""Add"" button results in a page not found error"

In Jira, this displays as:

Clicking the "Add" button results in a page not found error
Time Spent The value of this field needs to be specified as number of seconds.
Work log entries

Your CSV file can contain worklog entries. For example:

Summary,Worklog
Only time spent (one hour),3600
With a date and an author,2012-02-10 12:30:10;wseliga;120
With an additional comment,Testing took me 3 days;2012-02-10 12:30:10;wseliga;259200

Note that you need to use seconds in order to track time spent.

Running the CSV file import wizard

  1. From the Jira Cloud application header, click Issues > Import issues from CSV
  2. Choose a CSV file to import. 
  3. If you have a configuration file from a previous import, check Use an existing configuration file. If you leave the box unchecked, Jira creates a new file at the end of the import.
  4. Click Next and fill in the required information. If your CSV file is not comma-delimited, specify a new CSV Delimiter. If the separator is a tab, enter "/t".
  5. Click Next and map the column headers of your CSV file to the fields in your selected project. To also map the value of the field, check Map field value. You must map a CSV field to the issue summary field, as all issues created must have a summary. 

  6. Click Next one more time and select which CSV field values selected in the previous step you want to map to issue field values. For example, you might want to map the CSV field value of "Feature Request" to the Jira issue type field value "New Feature".

  7. Click Validate to check for errors or warnings.
  8. Click Begin Import. If you'll import another CSV file with similar field value mappings later, save the configuration file. 

Please note:

  • When mapping field values, leave a field cleared or clear any content within it if you wish to import the value as is.
  • If you are importing a username-based CSV field (e.g. Reporter or Assignee) and you do not check the Map field value option for this field, then the import process will automatically map imported usernames from the CSV file to (lowercase) Jira usernames.

  • If you experience any issues with the import or you want more information about the process, you can download a detailed log.

If you have questions or problems during the CSV import process, contact Atlassian support.

Last modified on Sep 12, 2017

Was this helpful?

Yes
No
Provide feedback about this article

Not finding the help you need?

Ask the community

Powered by Confluence and Scroll Viewport.