• Documentation

Create work items using the CSV importer

Comma-separated value (CSV) files are text files that represent tabulated data. Most spreadsheet and database systems support CSV files.

The CSV importer lets you import data from external systems that can export tabulated data. You can also create your own CSV file to perform bulk work item creation and updates.

You must have the following to do the things described on this page.

Role: Project admin, App admin

Permission: Create work items, Make bulk changes

Users without administrator permissions can import 250 work items per CSV file. If you're a Jira admin, check out the more advanced configuration.

The bulk work item creation option for CSV imports can't map work items with a parent-child hierarchy relationship (e.g. Initiative to Epic to Story to Subtask).

To map hierarchies, use the CSV external system import instead. Refer to Import data using a CSV file and CSV import parent-child mapping for details.

Prepare your CSV file

You can base your CSV file structure on the default Microsoft Excel CSV format. Fields should be separated by commas. Any content that must be treated literally (such as commas, new lines, or carriage returns) should be enclosed in quotes. Microsoft Excel and OpenOffice automatically quote cell values, so you do not need to quote these values manually.

CSV file requirements

  • CSV files must be well-formed.

  • Each CSV file must have a header row with a Summary column. The header row is used to map data from the CSV file to fields in your project’s work items.

  • The header row should not contain punctuation (apart from commas separating columns), or the importer may not work correctly.

  • Do not omit commas for empty column values.

Valid example:
Summary, Assignee, Reporter, Work Type, Description, Priority "Test work item", [email protected], [email protected], Task,
Invalid example (missing commas for empty fields):
Summary, Assignee, Reporter, Work Type, Description, Priority "Test work item", [email protected], [email protected], 1

Structure data in your CSV file

Data that spans multiple lines

Use double-quote marks (") to capture data that spans multiple lines. For example:

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 text to treat special characters literally. Once imported, the special characters will be included in the field data. To include a double quote mark, ‘escape’ it with another double quote mark.

For example:

"Selecting the ""Add"" button results in a page not found error"

Will be stored as:

Selecting the "Add" button results in a page not found error

Aggregating multiple values into a single field

To import multiple values into a field that accepts them (such as Fix Version, Component, or Labels), specify the same column name for each value. The number of column names specified must match the maximum number of values to be aggregated into the mapped field.

For example:

WorkType,Summary,FixVersion,FixVersion,FixVersion,Component,Component bug,"First work item",v1,,,Component1, bug,"Second work item",v2,,,Component1,Component2 bug,"Third work item",v1,v2,v3,Component1,

Here the Component field of the second work item and the Fix Version field of the third work item will generate multiple values in appropriate fields upon import.

Only certain fields support multiple values. The CSV importer will not allow you to import aggregated data into fields that only support a single value.

Attachments

You can attach files to work items by specifying the URL in an Attachment column.

For example:

Assignee, Summary, Description, Attachment, Comment [email protected], "Work item 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" [email protected], "CSV attachment import with timestamp,author and filename", "Please check the attached image below.", "01/01/2012 13:10;[email protected];image.png;file://image-name.png", "01/01/2012 10:10;Admin; This comment works"

Attachment URLs must use HTTP or HTTPS and be in a location that your Jira instance can access.

Import data into multiple projects

You can import work items 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 work item 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 work items from a CSV file into specific projects.

In the following example, the first and second work items will be imported into the 'Sample' project (with project key 'SAMP'), while the third work item will be imported into the 'Example' project (with project key 'EXAM'):

WorkType, Summary, Project Name, Project Key bug, "First work item", Sample, SAMP bug, "Second work item", Sample, SAMP task, "Third work item", 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

To populate a multi-select custom field with multiple values, use multiple columns with the same header. For example:

Summary,Multi Select,Multi Select,Multi Select Sample work item,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

Select list (cascading) custom fields can’t be imported this way. Track the feature suggestion. Instead, Jira administrators can go to Settings (), then System, then External system import.

Run the CSV file import wizard

To import work items from a CSV file:

  1. In the sidebar, select Filters, then select Search work items.

  2. Select More actions (•••), then select Import work items from CSV.

  3. Choose the CSV file you want to import. If you do not have a configuration file, leave Use an existing configuration file unchecked. Configuration files map the column names in your CSV file's header row to fields in Jira, and you can create one after you import.

  4. Select Next and fill in the required information. If your CSV file uses a different separator, specify it in the CSV delimiter field. If the separator is a tab, this can be entered using the format "/t".

  5. Select Next and map the column headers of your CSV file to the fields in your project. You must map a CSV field to the Summary field. To map specific Jira field values to specific CSV values, select Map field value.

  6. Select Next and map specific CSV field values to Jira field values, if needed. (For example, you might want to map the CSV field value “Feature request” to the Jira work type field value "New feature".)

  7. Select Begin import to start importing your CSV data. To check for errors or warnings, select Validate before importing. You can save your configuration for future imports with similar settings.

Note

  • When mapping field values, leave a field cleared or clear any content within it to import the value as is.

  • If you have any trouble with the import or want more information about the process, you can download a detailed log.

Tips for importing CSV data into Jira fields

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

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 work items with multiple components by entering each component in a separate column.

Affects version(s)

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

Fix version(s)

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

Due date

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

Work type

If not specified in your CSV file, imported work items will be given the default (i.e. first) Work Type, as specified in your Jira instance. More about defining work type field values. 

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

Labels

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

Priority

If not specified in your CSV file, imported work items 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 (userID)

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 work item* screen associated to the work type being used. More about specifying field behaviors.

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.

Still need help?

The Atlassian Community is here for you.
Ask the Community
On this pagePrepare your CSV fileStructure data in your CSV fileRun the CSV file import wizardTips for importing CSV data into Jira fields
CommunityQuestions, discussions, and articles