Map data from a CSV file

When you map data in, you can connect the information in your import columns to the issue fields in Jira. This allows you to customize how the data is presented and organized.

Admins can create and import data into both company-managed and team-managed projects.

Users with the permission to create projects can only create and import data into team-managed projects but won’t be able to move users into the new project. All user fields in the new project will be unassigned and user tags in comments will appear as plain text.

Read about Jira’s global permissions

Import dates and times

To import date and time data in Jira, select Date time format options, adjust the date and time formats to match the CSV file, and specify the date format used in the file using Java SimpleDateFormat syntax. Jira will read the dates and times based on the language and region preferences provided in the CSV file.

Map columns to fields

When importing data into Jira using a CSV file, each row of data from the CSV file will be imported as an issue into your new business or software project. In the Map project fields screen, all the column headers from the CSV file are listed.

If you import data from one of the listed apps or upload a configuration file to the import, some of the data from your CSV file will be mapped automatically. Make sure to double-check that the columns are mapped correctly. You will need to map the remaining columns from the CSV file to Jira fields.

Map project fields screen with one of the Jira field dropdowns selected

To map CSV columns to Jira fields:

Select the dropdown next to the CSV column you want to map and choose an existing field or create a custom field.
You can establish linked relationships between issues by selecting a link type under Map to a link type in the Jira fields dropdown.
If you want to exclude a column from import, uncheck the Include in import checkbox.

Summary is a required field in Jira. This field usually contains the task name or an overview of a task. Make sure to map the summary field to a CSV column to proceed with the import
Columns that aren’t mapped will be automatically excluded from import.

Linking issues

You can link issues to show dependencies and related work in Jira. You can set link types, such as blocks, is blocked by, clones, is cloned by, duplicates, is duplicated by, and relates to while mapping data from your CSV file to fields in Jira.

To establish linked relationships between issues, select a link type under Map to a link type in the Jira fields dropdown.

To import linked relationships, make sure to map a CSV column to Issue ID field n Jira. This is a required field if you want to import issue links.

Custom fields

Use custom fields in Jira to track and manage additional information specific to your team or organization's needs.

Jira provides a set of standard fields that can be used for most purposes, but custom fields allow you to capture and report on data that is unique to your workflow or business processes. Custom fields can be created for various types of data, such as text, numbers, dates, and dropdown lists, and can be added to screens, issue types, and projects as needed. With custom fields, you can enhance your instance's flexibility and tailor it to your team's requirements, improving data accuracy and helping you make informed decisions.

Tips for creating custom fields

Limit the number of custom fields in your import.
Avoid duplicating names of existing custom fields or standard Jira fields.
Use generic names for custom fields that can be reused in other places e.g., Objective instead of Marketing Objective

Map column data to a custom field

Jira fields dropdown menu with Create a new custom field option selected.

Select the dropdown next to the CSV column you want to map to a custom field.
From the dropdown, select Create a new custom field, then select the field type that best fits with your column field.

A new custom field will be created and will be named the same as the CSV column header.

Importing to multi-select custom fields

Your CSV file can contain multiple entries for 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 select custom fields

You can import values to a cascading select 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.

When there is no '->' separator, the child value will also be imported as a parent value.
When there is no parent value before '->' separator, you will see an error. Make sure to add a parent value and restart the import.

System and custom fields in Jira

The following are some helpful tips along with a list of the system fields and custom fields that we currently support in Jira.

System fields	Description
SUMMARY	Maps to Jira Summary field type. Supports any text content.
DESCRIPTION	Maps to Jira Description field type. Supports any text content.
ENVIRONMENT	Maps to Jira Environment field type. Supports any text content.
ISSUE_TYPE	Maps to Jira Issue type field type. Supports any text content (e.g., Task, Bug, Story)
STATUS	Maps to Jira Status field type. Supports any text content (e.g., To do, In progress, Done)
PRIORITY	Maps to Jira Priority field type. Supports any text content.
DUE_DATE	Maps to Jira Date field type. Supports any date without the time (e.g., 11/03/2023).
LABELS	Maps to Jira Labels field type. Supports any text content.
COMMENT	Maps to Jira Comment field type. Supports any text content along with author and date (e.g., date-time;author;body).
STATUS_CATEGORY	Maps to Jira Status category field type. Supports any string content (e.g., ToDo, IN_Progress, Done)
CREATED	Maps to Jira Date time field type. Supports any date and time (e.g., 11/03/2023 11:53pm)
UPDATED	Maps to Jira Date time field type. Supports any date and time. (e.g., 11/03/2023 11:53pm)
RESOLUTION	Maps to Jira Date time field type. Supports any date without the time (e.g., 11/03/2023).
CREATOR	Maps to Jira User field type. Supports any user Atlassian account ID.
REPORTER	Maps to Jira User field type. Supports any user Atlassian account ID.
ASSIGNEE	Maps to Jira User field type. Supports any user Atlassian account ID.
WATCHES	Maps to Jira Watches field type. Supports any multi-user field format.
WORKLOG	Maps to Jira Worklog field type. Supports these formats: body;date-time;user;timelogged date-time;user;timelogged user;timelogged timelogged
TIME_ORIGINAL_ESTIMATE	Maps to Jira Time orignal estimate. Supports any integer values in seconds. Values under 60 seconds will be represented as 0 min.
TIME_REMAINING_ESTIMATE	Maps to Jira Time remaining estimate. Supports any integer values in seconds. Values under 60 seconds will be represented as 0 min.
TIME_SPENT	Maps to Jira Time time spent. Supports any integer values in seconds. Values under 60 seconds will be represented as 0 min.

Custom fields	Description
Text field	Maps to Jira Short text field type. Supports any plain text content.
Paragraph	Maps to Jira Paragraph field type. Supports any rich text content.
Date	Maps to Jira Date field type. Supports any date without the time (e.g., 11/03/2023).
Time stamp	Maps to Jira Date time field type. Supports any date and time (e.g., 11/03/2023 11:53pm).
Number	Maps to Jira Number field type. Supports any valid number (e.g., 1234)
Labels	Maps to Jira Label field type. Supports any valid string. For multiple labels, make sure to follow the multi-select format where there is a column for each label
Dropdown	Maps to Jira Select field type. Supports any valid string and will create an option for all unique values in the column.
Multi-select	Maps to Jira Multi-select field type. make sure to follow the multi-select format below where there is a column for each value in the CSV.
Select list	Maps to Jira cascading select field type. Supports parent -> child format
Multi-user picker	Maps to Jira multi-user field type. To support multiple users, make sure to follow the multi-select format below where there is a column for each user in the CSV. Make sure the value is either an Atlassian account ID or email.
User picker	Maps to Jira user field type. Make sure the value is an email.
Checkbox	Maps to Jira multi-checkbox field type. Make sure it follows the multi-select format below where there is a column for each value of the field.
URL	Maps to Jira URL field type. Make sure the value is a valid URL.
Radio	Maps to Jira Radio button field type. Supports any valid string and will create an option for all unique values in the column.