View Source

About importing from CSV

JIRA ships with the JIRA Importers Plugin pre-installed, so that you can import your data from a comma-separated (CSV) file, which is a format supported by most applications (e.g. Microsoft Excel).

Please note that there a number of import methods available for importing data into JIRA from other issue tracking systems. It may be more appropriate to use a method other than the CSV importer, depending on what system you are importing data from. Details on other methods of importing data are available here.

Please raise bugs reports or improvement suggestions at JIRA Importer Plugin.

The CSV import process consists of:

Preparing your CSV file — see below.
Running the Import Wizard — see below. You can choose to map individual fields and field values during the import process.

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

JIRA Field	Import Notes
Project	CSV data is imported on a per-project basis. You can either specify an existing JIRA 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.
Date Created	Please use the date format specified in your JIRA system (see Customising the Look and Feel).
Date Modified	Please use the date format specified in your JIRA system (see Customising the Look and Feel).
Due Date	Please use the date format specified in your JIRA system (see Customising the Look and Feel).
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 systemDefining 'Issue Type' Field Values. You can also create new JIRA values on-the-fly during the import process.
Sub-Tasks	Firstly create a column for every 'Issue Id'(it can be any unique string), then create a second column for the 'Parent Id'. To import sub-tasks reference the Issue Id in the Parent Id column.
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 systemDefining 'Priority' Field Values. You can also create new JIRA values on-the-fly during the import process.
Resolution	If not specified in your CSV file, imported issues will be given the default (i.e. first) Resolution as specified in your JIRA systemDefining 'Resolution' Field Values. You can also create new JIRA values on-the-fly during the import process.
Status	Can only be mapped to existing workflow statuses in JIRA. If not specified in your CSV file, imported issues will be given the default (i.e. first) Status as specified in your JIRA system.
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 JIRA 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.
Other fields	If your wish to import any other fields, you can choose to map them to specific JIRA custom field(s). If your custom fields don't yet exist in JIRA, the importer can automatically create them for you.

Valid file format

The CSV importer assumes a Microsoft Excel styled CSV file. Fields are separated by commas, and enclosed in quotes if they contain commas or quotes. Embedded quotes are doubled.

For Microsoft Excel and OpenOffice it is not necessary to quote values in cells as these programs handle this automatically.

There are two requirements of the CSV, in addition to being well-formed in general:

The CSV file must contain a heading row. The CSV configuration wizard uses the CSV header row extensively. The header values should not have any punctuation (beyond the commas separating records) such as apostrophes or the importer may not work correctly.
As a minimum, the CSV file must contain a column for Summary data.
If multiple columns with the same name are mapped to a single JIRA field, the data from these multiple columns will be aggregated into that JIRA field upon import. Be aware that only a limited number of JIRA fields support multiple values. The CSV importer will not allow you to import aggregated data into JIRA fields which only support a single value.

You can also have multi-lined CSV. For example, here is a valid file with a single record:

Summary,Description,Status
Login fails,"This is on
a new line",Open

Commas cannot be omitted. For example, this is valid:

Summary,Assignee, Reporter, Issue Type, Description, Priority
test, admin, admin, 1, ,

... but this is not valid:

Summary, Assignee, Reporter, Issue Type, Description, Priority
test, admin, admin, 1

To import multiple values into a JIRA field that accepts multiple values (e.g. Fix-for version, Affects version, Component), your CSV file must specify the same column name for each value you wish to aggregate into the mapped JIRA 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 this example, the third imported issue will have its Fix-for version set to multiple values.

How to import from CSV

Before you begin, please backup your JIRA data.
Log in to JIRA as a user with the 'JIRA Administrators' global permission.
Bring up the administration page by clicking the 'Administration' link on the top navigation bar.
On the left navigation panel, click 'External System Import' in the 'Import & Export' section and then select 'Comma-separated values (CSV)'.
The 'CSV Import Wizard: Setup' page will be displayed:
Screenshot 1: the 'CSV Import Wizard: Setup' page
Select your CSV Import File and the relevant File encoding.
The file will be imported using the encoding you specify here, not the encoding specified for your JIRA system (which is shown in Administration -> System Info).
Click the 'Start Import Wizard' button at the bottom of the page (leave the 'Existing Confiuration File' field blank if you don't yet have a configuration file, or if you want to create a new file or update the one you have). This will guide you through creating a Configuration File:
- Project Configuration: You can either import all your issues into one JIRA project (new or existing); or import into multiple projects by including the project data in your CSV file.
  - Import issues into an existing JIRA project — type a project key (or project name) that already exists in JIRA.
  - Import issues into a new JIRA project — type a new 'Project Name', 'Project Key' and select which user will be the 'Project Administrator'. The importer will create your new JIRA project automatically.
  - Project information contained in CSV file — ensure that every issues in your CSV file includes data for the project name/key.
    The JIRA 'Project key' will be the prefix for the IDs of all issues in the given project.
    There is no warning or error message if you select an existing key (or existing project name with a different key). The importer will import issues to the project specified by the key (or project name).
- Field Mappings:
  - 'Summary' field is required. All other fields are optional.
    Screenshot 2: the 'CSV Import Wizard: Issue Field Mappings' page
- Field Value Mappings:
  - Leave a field blank if you wish to import the value as-is. If you want to clear a field, enter the keyword <<blank>>.
  - You can create missing Priority, Resolution and Issue type values in JIRA on-the-fly by clicking the icon next to the appropriate field.
  - Usernames — If you don't specify mapping, the importer will automatically map imported usernames to JIRA usernames (lowercase).
    Regardless of whether you specify mapping, JIRA will automatically create usernames for missing users unless you un-check the 'Create new users' option on the final 'Import Data' screen (see Screenshot 4 below).
    Screenshot 3: the 'CSV Import Wizard: Value Mappings' page
When you have finished specifying your field mappings, the 'Import Wizard: Settings' page will be displayed:
Screenshot 4: the 'Import Wizard: Settings' page
- 'Create new users' — It is generally recommended that you leave this set to 'ON'. Only select 'OFF' if you do not want JIRA to automatically create new usernames for imported users who do not already exist in JIRA.
- 'Create new versions' — It is generally recommended that you leave this set to 'ON'. Only select 'OFF' if you do not want JIRA to automatically create new versions for imported versions which do not already exist in JIRA.
- 'Create new components' — It is generally recommended that you leave this set to 'ON'. Only select 'OFF' if you do not want JIRA to automatically create new components for imported components which do not already exist in JIRA.
- 'Create new custom fields' — It is generally recommended that you leave this set to 'ON'. Only select 'OFF' if you do not want JIRA to automatically create custom fields for imported fields which do not have a corresponding field in JIRA.
- 'Maximum issues and failues' — If you wish, specify a maximum number of failed issues after which the importer will stop. If you want the import to continue regardless of any failures, leave this field blank. If your old issue-tracker has a large number of issues, it's generally a good idea to run first the importer on a limited number of issues (e.g. 100), then manually inspect the imported issues to confirm whether your configuration file was specified correctly. When the results are satisfactory, you can run the import with no limit.
The importer will display updates as the import progresses, then a success message when the import is complete. You can download the import log if you wish.

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