Get started with Jira
New to Jira? Check out our guides for new administrators and users.
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.
You will need the Create Issue project permission and the Make bulk changes global permission for the projects you want to create issues in. Note that your administrator can perform more advanced bulk imports.
Recommended data size
When importing large projects, we recommend splitting your data to reduce performance concerns and ensure the optimal speed of the import.
Recommended number of issues per file | 1500 issues |
|---|---|
Estimated time to import | Approximately 1 hour (This would also depend on the size and complexity of your data and setup) |
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:
1
2
Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", bob@example.com, bob@example.com, Task, ,This is not a valid example:
1
2
Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", bob@example.com, bob@example.com, 1How 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:
1
2
3
Summary, Description, Status
"Login fails", "This is on
a new line", OpenSpecial 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:
1
2
3
4
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.
Please be aware that only a limited number of issue fields support multiple values. The CSV importer will not allow you to import aggregated data into issue fields that only support a single value.
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.
1
2
3
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"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'):
1
2
3
4
IssueType, Summary, Project Name, Project Key
bug, "First issue", Sample, SAMP
bug, "Second issue", Sample, SAMP
task, "Third issue", Example, EXAMWork log entries
Your CSV file can contain work log entries. Use seconds to track time spent. For example:
1
2
3
4
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;259200Multi-select custom fields
Your CSV file can contain multiple entries to populate the Multi Select Custom Field with multiple values. For example:
1
2
Summary,Multi Select,Multi Select,Multi Select
Sample issue,Value 1,Value 2,Value 3Cascading 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:
1
2
Summary, My Cascading Custom Field
Example Summary, Parent Value -> Child ValueJira Cloud doesn't support importing multi-level cascading select fields by CSV. You can track the suggestion here: JRACLOUD-34202
Running the CSV file import wizard
Select Filters > Advanced issue search.
Click more ( ••• ) > Import issues from CSV.
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 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 separate columns with the same header name. |
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, see Defining 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. 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 | Creating users For any system field that is a user type, we support:
You can choose to have the importer automatically create Jira users for any values of the Assignee or Reporter field.
Updating users Portal-only customer data in Jira Service Management behaves differently than other user accounts data. If the portal-only customer data is different in the import and the destination, then we use the destination data. |
Mandatory fields | When importing to projects with mandatory fields, you must include the field in the *Create issue* screen associated to the issue type being used. For more information, see Specifying field behavior. |
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. You can't import Select List (cascading) custom field types using this method. Instead, select Settings () > System > External System Import to import Select List (cascading) fields. |
If you have any questions or encounter any problems during the CSV import process, please contact Atlassian support.
Was this helpful?
Still need help?
The Atlassian Community is here for you.