Creating issues using the CSV importer
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
|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:
|Delimit columns and fields with commas||
For example, this is valid:
This is not valid because the last column is not delimited:
How to structure data in the CSV file
CSV file structure
|Summary||This 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:
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-34202Allow CSV import to support Multi-Level Cascading Select plugin fields OPEN .
|Comment Body||Import 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 (
|Due Date||Please use the date format specified on the second step of the CSV import wizard.|
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.|
You can import issues with multiple labels by:
|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.
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:
|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.|
Use double-quote marks (
To treat a double quote mark literally, you can add another double quote mark character:
In Jira, this displays as:
|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:
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.
- From the application header, click Issues > Import issues from CSV
- Choose a CSV file to import.
- 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.
- 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".
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.
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".
- Click Validate to check for errors or warnings.
- 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.