Versions

Creating issues using the CSV importer

Creating issues and sub-tasks

On this page

Related content

No related content found

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.

You will need the Create Issue project permission and the Bulk Change global permission for the projects you want to create issues in. Note that your administrator can perform more advanced bulk imports. If you're an administrator, check out Importing data from CSV for more information.

On this page:

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.

Commas as column or field separates cannot be omitted: This is a valid example:

How to structure data in your CSV file

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:

URLs for attachments support the HTTP and HTTPS protocols and can be any location that your JIRA instance must be able to access.

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.

Make sure that every issue in your CSV file has a project name and project key in the relevant column. The project name and project key are the minimum project data required for importing issues from a CSV file into specific projects.

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'):

Running the CSV file import wizard

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.

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".

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.

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".

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.

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.

Tips for importing CSV data into issue fields

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

Issue Field

Import Notes

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.

Summary

This is the only required field.

Component(s)

You can import issues with multiple components by entering each component in a separate column.

Affects Version(s)

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

Fix Version(s)

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

Comment Body

You can import issues with multiple comments by entering each comment in a separate column.

Due Date

Please use the date format specified on the second step of the CSV import wizard.

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, seeDefining issue type field values.

You can also create new values on-the-fly during the import process.

Labels

You can import issues with multiple labels by entering each label in a separate column.

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, seeDefining priority field values.

You can also create new values on-the-fly during the import process.

Original Estimate

The value of this field needs to be specified as number of seconds.

Remaining Estimate

The value of this field needs to be specified as number of seconds.

Time Spent

The value of this field needs to be specified as number of seconds.

Users

You can choose to have the importer automatically create JIRA users for any values of the Assignee or Reporter field.

Users will be created as active accounts in JIRA. Users will need to get their passwords emailed to them the first time they log into JIRA.

Users with no real name will get the portion of their email address (login name) before the "@" character as their Full Name in JIRA.

If you are using External User Management, the import process will not be able to create users; instead, the importer will give you a list of any new users that need to be created. You will need to create the users in your external user repository before commencing the import.

If you have a user-limited license (e.g. personal license), and the number of required users is larger than the limit, then the import will be stopped. A page will be displayed showing a list of users that can't be created.

If Assignee and Reporter are not mapped, then no usernames are created.

Other fields

If you wish to import any other fields, you can choose to map them to specific JIRA custom field(s). If your custom fields don't exist yet in JIRA, the importer can automatically create them for you. If your custom field is a date field, please use the date format specified on the second step of the CSV import wizard.

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