Create issues using the CSV importer

Comma-separated value (CSV) files are text files that represent tabulated data, and are supported by most systems that handle tabulated data, such as spreadsheets and databases. The CSV importer allows you to import data from external systems that can export their data in a tabulated format. It also allows you to create your own CSV file to perform bulk issue creation and updates.

Preparing your 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. Please note that Microsoft Excel and OpenOffice automatically quote values in cells, so there is no need to quote these values manually. 

CSV file requirements: 

• CSV files must be well-formed
• Each CSV file must possess a heading row with a summary column. The header row is used to determine how to map data from the CSV file's 2nd row and beyond to fields in your project's issues. The header row should avoid containing any punctuation (apart from the commas separating each column) or the importer may not work correctly.
• You can't omit commas for empty column values. For example, the second snippet below omits commas for the empty description and priority fields, which isn't allowed.

This is a valid example:

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", bob@example.com, bob@example.com, Task, ,

This is not a valid example:

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", bob@example.com, bob@example.com, 1

How to structure data in your CSV file

Data that spans multiple lines

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

Summary, Description, Status
"Login fails", "This is on
a new line", Open

Special characters that need to be treated literally

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

To treat a double quote mark literally, you can 'escape' them with another double quote mark character. Hence, the CSV value:

• "Clicking the ""Add"" button results in a page not found error"
  once imported, will be stored in Jira as:
• Clicking the "Add" button results in a page not found error

Multiple values that need to be aggregated into single issue fields

You can import multiple values into an issue 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 aggregate into the mapped issue 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 appropriate issue fields upon import.

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
bob@example.com, "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"
bob@example.com, "CSV attachment import with timestamp,author and filename", "Please check the attached image below.", "01/01/2012 13:10;bob@example.com;image.png;file://image-name.png", "01/01/2012 10:10;Admin; This comment works"

Issues that need to be imported to multiple projects

You can import issues from your CSV file into different projects through a CSV file import. To do this, add two columns to your CSV file with the "Project Name" and "Project Key" headings.

In the following example, the first and second issues will be imported into the 'Sample' project (with project key 'SAMP'), while the third issue will be imported into the 'Example' project (with project key 'EXAM'):

IssueType, Summary, Project Name, Project Key
bug, "First issue", Sample, SAMP
bug, "Second issue", Sample, SAMP
task, "Third issue", Example, EXAM

Work log entries

Your CSV file can contain work log entries. Use seconds to track time spent. 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

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

Cascading choice custom fields

You can import values to a cascading choice custom field using the following syntax. The '->' separator allows you to import the hierarchy:

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

Running the CSV file import wizard

1. Select Filters > Advanced issue search.
2. Click more ( ••• ) > Import issues from CSV. 
3. Choose the CSV source file that you want to import. Check the If you don't have a configuration file or you want to create a new one, leave the Use an existing configuration file option unchecked. Configuration files specify a mapping between column names in your CSV file's header row and fields in your installation. You will have the option of creating a configuration file at the end of the import process. 
4. Click Next and fill in the required information. If your CSV file uses a different separator character other than a comma, specify that character in the CSV Delimiter field. If the separator is a tab, this can be entered using the format "/t".

5. Click Next and map the column headers of your CSV file to the fields in your selected project. If you want to select specific Jira field values to map specific CSV values to, check the Map field value option. 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 specific 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 Begin Import when you are ready to begin importing your CSV data into Jira. If you want to check for any errors or warnings, click Validate before beginning your import. If you want to import another CSV file with similar settings (e.g. similar field value mappings), you can save the configuration by downloaded a CSV configuration file. 

Tips for importing CSV data into issue fields

Below are some helpful tips when importing data from your CSV file into specific issue fields:

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