Creating issues using the CSV importer

Creating issues and sub-tasks

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Use the CSV importer to bulk create or update issues. If you need to do any of the following, you'll need to be a system admin and use Importing issuesinstead:

  • create subtasks
  • import attachments
  • add new fields
  • import to multiple projects

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. New issues follow the workflow of the project you import to.

Your administrator has access to more import options designed specifically for other systems, such as Github, Fogbugz, and Bugzilla. If you are planning on importing from an external system a large amount of issues, administrators have access to advanced import functionalities by following: Migrating from other issue trackers, including Importing data from CSV.

There are two steps to using the CSV importer, and an optional third step:

  1. Preparing your CSV file
  2. Running the CSV import wizard
  3. Saving your configuration for future use

On this page:

Prepare the CSV file

You can base the structure of your CSV file on 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 because the last column is not delimited:

 

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
SummaryThis is the only required field.
Affects Version(s)Import issues with multiple 'Affects Versions' by entering each version in a separate column.
Cascading choice custom fields

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 BodyImport issues with multiple comments by entering each comment in a separate column.
Component(s)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
new line", Open
Due DatePlease 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 TypeIf 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 EstimateThe value of this field needs to be specified as number of seconds.
Other fieldsIf 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.
PriorityIf 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
ProjectCSV 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 EstimateThe 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 SpentThe 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

Before you begin: If your JIRA installation has existing data, you should back it up

  1. From the 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. 
     
    • 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.

     

    Congratulations, you have successfully imported your CSV data into JIRA! If you have any questions or encounter any problems, please contact Atlassian support.
Last modified on Sep 3, 2019

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.