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.

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.

During the import process, the following data is copied from your CSV file into JIRA:

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. (For more information about JIRA projects, please see Defining a Project.)
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.
Assignee
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).
Description
Due Date	Please use the date format specified in your JIRA system (see Customising the Look and Feel).
Environment
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 system — see Defining 'Issue Type' Field Values. You can also create new JIRA 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 system — see Defining 'Priority' Field Values. You can also create new JIRA values on-the-fly during the import process.
Reporter
Resolution	If not specified in your CSV file, imported issues will be given the default (i.e. first) Resolution as specified in your JIRA system — see Defining 'Resolution' Field Values. You can also create new JIRA values on-the-fly during the import process.
Status	If not specified in your CSV file, imported issues will be given the default (i.e. first) Status as specified in your JIRA system — see Defining 'Status' Field Values. The JIRA 'Status' field is integral to JIRA workflow. To learn more, please see What is Workflow. To create a JIRA workflow, please see Configuring Workflow. To create a JIRA workflow scheme (which you can then associate with appropriate projects and Issue Types), please see Activating Workflow.
Summary	This field is required.
Votes
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.

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

For built-in JIRA fields (e.g. Fix-for version, Affects version, Component), if you wish to set more than one value for an issue, you will need to have a value per column in your CSV, with each column given a distinct name. For example:

IssueType,Summary,FixVersion_1,FixVersion_2
bug,"First issue",v1,
bug,"Second issue",v2,
bug,"third issue",v1,v2

In this example, the third imported issue will have its Fix-for version set to multiple values.

For custom fields the situation is different, and multiple values are comma-separated. See below for details.

CSV file encoding

JIRA will read the CSV file using the system encoding, which can be seen in Administration -> System Info. Make sure that you either save the CSV file with this encoding, or set -Dfile.encoding on startup to force the system encoding to be what you're using (utf8 is best).

How to import from CSV

Before you begin, please backup your JIRA data.
In JIRA's default permission scheme (associated with newly created projects), ensure that the 'Browse', 'Create' and 'Comment' permissions are granted to the group 'jira-users' (or a group with the 'JIRA Users' global permission).
Log in to JIRA as a user with the 'JIRA Administrators' global permission.
Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard.
On the panel on the left, under the title 'Import & Export', click 'External System Import - Beta!'. 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 file, then 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.