robotsnoindex

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. If you're an administrator, check out Importing and exporting data for more information.

The bulk issue creation option for CSV imports can't map issues with a parent-child hierarchy relationship (e.g. Initiative > Epic > Story > Subtask).

To map issue hierarchies, you must use a CSV External System Import option instead. Refer to Import data using a CSV file and CSV import parent-child mapping for details.

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:

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 VersionComponentLabels). 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.

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.

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

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

Jira Cloud doesn't support importing multi-level cascading select fields by CSV. You can track the suggestion here: JRACLOUD-34202 - Getting issue details... STATUS

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. 

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:

  • email

  • Atlassian Account ID

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 users are created.

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.