Creating issues using the CSV importer
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:
- Preparing your CSV file
- Running the CSV import wizard
- Saving your configuration for future use
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:
| ||
| 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
Data type | 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: | ||
| 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. | ||
| 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:
| ||
| 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:
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. | ||
| Special characters | 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. Congratulations, you have successfully imported your CSV data into JIRA! If you have any questions or encounter any problems, please contact Atlassian support.
- 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.