Importing Data From CSV

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

The CSV import process consists of:

1. Preparing your CSV file — see below.
2. 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:

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.

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

1. Before you begin, please backup your JIRA data.
2. Log in to JIRA as a user with the 'JIRA Administrators' global permission.
3. 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.
4. On the panel on the left, under the title 'Import & Export', click 'External System Import'. Then select 'Comma-separated values (CSV)'.
5. The 'CSV Import Wizard: Setup' page will be displayed:
   Screenshot 1: the 'CSV Import Wizard: Setup' page
   
6. 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
       
7. 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.
8. 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.