Creating issues using the CSV importer

Creating issues and sub-tasks

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

If you have the Create Issue project permission and the Bulk Change global permission for the relevant projects, you can create issues in bulk using a comma-separated value (CSV) file. CSV files are text files that represent tabulated data, and are supported by most systems that handle tabulated data, such as spreadsheets (MS Excel, Numbers) 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.

Your administrator has access to more import options. 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:

  1. Preparing your CSV file
  2. Running the CSV import wizard
  3. Saving your configuration for future use

On this page:

Preparing your CSV file

The Jira Importers plugin assumes that your CSV file is based off a default Microsoft Excel-styled CSV file. Fields are separated by commas, and any content that must be treated literally, such as commas and new lines/'carriage returns' themselves are enclosed in quotes.

(info) For Microsoft Excel and OpenOffice, it is not necessary to quote values in cells as these applications handle this automatically.

CSV file requirements

In addition to being 'well-formed', CSV files have the following requirements:

  • Each CSV file must possess a heading row with a Summary column

The CSV file import wizard uses a CSV file's header row 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.

The header row must contain a column for 'Summary' data.

  • Commas (as column/field separators) cannot be omitted

For example, this is valid:

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", admin, admin, 1, ,

... but this is not valid:

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", admin, admin, 1

Encapsulating Jira data structure in your CSV file

Capturing 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

Treating special characters 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

Aggregating multiple values into single issue fields

You can import multiple values into an issue field that accepts multiple values (e.g. Fix (for) VersionAffects 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.

(warning) 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.

Importing 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
Admin, "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"
Admin, "CSV attachment import with timestamp,author and filename", "Please check the attached image below.", "01/01/2012 13:10;Admin;image.png;file://image-name.png", "01/01/2012 10:10;Admin; This comment works"

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

Importing issues into multiple projects

You can import issues from your CSV file into different projects through a CSV file import. To do this:

  • Your CSV file requires two additional columns whose headings should be named similarly to Project Name and Project Key.
  • Ensure that every issue represented in your CSV file contains the appropriate name and key in these columns for the projects to which they will be imported.
    (info) The project name and key data is the minimum project data required for importing issues from a CSV file into specific projects.
IssueType, Summary, Project Name, Project Key
bug, "First issue", Sample, SAMP
bug, "Second issue", Sample, SAMP
task, "Third issue", Example, EXAM

In the example above, the first and second issues will be imported into the 'Sample' project (with project key 'SAMP') and the third issue will be imported into the 'Example' project (with project key 'EXAM') , assuming you match the 'Project Name' and 'Project Key' fields in your CSV file to the Project name and Project key issue fields, respectively during the CSV file import wizard.

Importing work log entries

Your CSV file can contain work log entries. 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

To track time spent, you need to use seconds.

Importing to multi select custom fields

Your CSV file can contain multiple entries for the one Multi Select Custom Field. For example:

Summary,Multi Select,Multi Select,Multi Select
Sample issue,Value 1,Value 2,Value 3

This will populate the Multi Select Custom Field with multiple values.

Importing cascading choice custom fields

You can import values to a cascading choice custom field using the following syntax:

Summary, My Cascading Custom Field
Example Summary, Parent Value -> Child Value

The '->' separator allows you to import the hierarchy.

NOTE: Currently Jira does not support importing multi-level cascading select fields via CSV ( JRA-34202 - Getting issue details... STATUS ).

Running the CSV file import wizard

Before you begin: If your Jira installation has existing data, you should back it up

  1. Select Issues > Import Issues from CSV to open the Bulk Create Setup page. (If you do not have the option Import issues from CSV, your Jira Admin must update the Jira Importers plugin to version 6.2.3 or above.)
  2. On the Setup page, select your CSV Source File.
    Leave the Use an existing configuration file checkbox cleared if you do not have a configuration file, or if you want to create a new configuration file. Configuration files specify a mapping between column names in your CSV file's header row and fields in your installation.
    • If you select this option, you will be asked to specify an Existing Configuration File.
    • If you do not select this option, then at the end of the CSV file import wizard, Jira will ask you if you want create a configuration file that you can use for subsequent CSV imports.
  3. Click the Next button to proceed to the Settings step of the CSV file import wizard. Complete the required fields.
    • 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'.
  4. Click the Next button to proceed to the Map fields step of the CSV file import wizard. Here, you can 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, tick the checkbox for Map field value.
    (info) Note: You must map a CSV field to the issue's summary field. This ensures the issues created have a summary.

  5. Click the Next button to proceed to the Map values step of the CSV file import wizard. On this step of the import wizard, you can select which specific CSV field values you want to map to which specific issue field value. For example, your issue types you may have a CSV field value of "Feature Request", which you may want to map to the issue type field value "New Feature".
    (info) Please note:

    • Any fields whose Map field value checkboxes were selected in the previous step of the CSV file import wizard will be presented on this page.
    • 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 select the Map field value checkbox for this field in the previous step of the CSV file import wizard, then the importer will automatically map imported usernames from the CSV file to (lowercase) Jira usernames.
      (info) Regardless of whether or not you select the Map field value checkbox, Jira will automatically create usernames based on the data in your CSV file if they have not already been defined in Jira. 

    • When importing descriptions with line breaks, do not select the Map field value checkbox as Jira might then remove the line breaks. 

  6. Click the Begin Import button when you are ready to begin importing your CSV data into Jira. The importer will display updates as the import progresses, then a success message when the import is complete.
  7. If you're confident your import is correctly set up, click the Begin Import button. Your import will begin and once complete you will be informed of any errors. If you'd like to check your import first, click the Validate button and Jira will validate your import and inform you of any expected errors or warnings. You can then go back and correct these before running your full import.

(info) Note:

    • If you experience problems with the import (or you are curious), click the download a detailed log link to reveal detailed information about the CSV file import process.
    • If you need to import another CSV file with the same (or similar) settings to what you used through this procedure, click the save the configuration link to download a CSV configuration file, which you can use at the first step of the CSV file import wizard.

Congratulations, you have successfully imported your CSV data into Jira! If you have any questions or encounter any problems, please contact Atlassian support.

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, see Defining issue type field values

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

Labels

Import issues with multiple labels by:

  • entering each label in a separate column or
  • putting all labels in one column, deliminated by a space

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

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.

Known issues

Problems populating multi-select fields

In case your issues get created but the multi-select fields are not populated, contact your administrator so that they can re-run the import using JIRA admin tools.

Importing restricted custom fields

 Issues might happen when there is project with single issue type only and there is required custom field with Context set in that project. For details and the workaround, see JRASERVER-41584.

Last modified on Oct 18, 2019

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.