The CSV importer provides a powerful and flexible way to import data from a comma-separated file, which is a format supported by most applications (e.g. Microsoft Excel).

Note: Before you begin, please backup your JIRA data.

Using the JIRA Importers Plugin

The JIRA Importers Plugin can import your old data in CSV format. The web based configuration helps you migrate and map data.

For the very latest version of the JIRA Importers Plugin, please visit plugins.atlassian.com.

About importing from CSV

The 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. 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).
3. Log in to JIRA as a user with the 'JIRA System Administrators' global permission.
4. 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.
5. On the panel on the left, under the title 'Import & Export', click 'External System Import - Beta!'. Then select 'Comma-separated values (CSV)'.
6. The 'CSV Import Wizard: Setup' page will be displayed:
   Screenshot 1: the 'CSV Import Wizard: Setup' page
   
7. 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.
   • 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 2 below).
8. When you have finished specifying your field mappings, the 'Import Wizard: Settings' page will be displayed:
   Screenshot 2: 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.
9. The importer will display updates as the import progresses, then a success message when the import is complete.

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

Using JIRA's Built-in Importer

Importing from a CSV file is a three step process. First, you need to prepare and verify your CSV file. Next, create a mapping file by running the CSV import wizard. The mapping file is a plain text properties file that you can also manually edit. It will map your CSV fields to fields in JIRA. Finally, to perform the import, simply enter the location of your import file and your configuration file.

1. Preparing your CSV file

The first thing you need to do is to ensure that your CSV is a valid CSV format. A good way to check is to import your file into a spreadsheet (e.g. Microsoft Excel, Open Office) and see if the data is as expected. This is also a good opportunity to do any massaging of the data, if you wish.

If you have values that signify a blank value (e.g. <blank> or None), it's best if you simply remove them in this step.

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.

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

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

Importing Comments from CSV

If a row contains more columns than there are header columns, then the excess columns will be added as comments.

2. Running the CSV Import Configuration Wizard

The next step of the import process is to run the import configuration wizard to determine how the CSV data can be mapped to JIRA fields.

1. Log in as a user with the 'JIRA System Administrators' global permission.
2. 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.
3. On the panel on the left, under the title 'Import & Export', click 'External System Import. '
4. The 'Import Data' page will be displayed. Select 'Comma-separated values (CSV)'.
5. The 'Import issues from CSV file' page will be displayed. Click the 'CSV Import Wizard' link.
6. The 'CSV Import Wizard: Setup' page will be displayed:
   
   You can optionally specify the delimiter your CSV file used. Leave the field blank if you wish to use the (default) comma delimiter. Please note that the delimiter can only be one character long.
7. Click the link 'Start Import Wizard.

2.1 Project Configuration

The first step is to choose which project the issues will be imported into. You can import into a new project or an existing project. If certain project details (e.g. name and key) match an existing project, then the issues will be imported into an existing project. Note that if you are creating a new project, no validations are performed at this time - invalid data will result in a failure later, at import time.

If you want to import into multiple projects, you must map project information from the CSV file itself. That means that all rows must have the project information in them.

The recommended import method is a single project per CSV file, imported into an existing project.

2.2 Issue Field Mappings

The second step is to decide which CSV fields you want to import. The screen shows all the columns that are found in your CSV file, and a sample data row. On this screen you can map each column of your CSV file to system fields in JIRA, or leave as None to not import. You can optionally create new custom fields on the fly or import into an existing custom field.

System Fields

You can select multiple fields to be combined into Version and Component fields. For example, you can import from 'Raised Version' and 'Found in Version' into the 'Affects Versions' field. For Versions and Components, the importer will detect if the version exists in JIRA for the project. If it doesn't exist, then it will automatically created.

User fields (Assignee and Reporter) are assumed to be in a 'FirstName LastName' format. New users will be created with the username as 'FirstNameLastName'; spaces, apostrophes and brackets are stripped out. If the name only has one word, that one word will be used as the username.

In most cases when importing system fields values like Priority, >Issue Type, Status and Resolution, you will need to JIRADOC:map the field values. The mapping needs to be done even if the imported CSV file has the values set to 'valid' names, e.g. Issue Type set to 'Bug' or 'New Feature'. The only alternative to mapping the values is to change the CSV file such that it contains the exact IDs of JIRA's priorities, issue types, statuses and resolutions instead of their names. This requires you to determine the correct IDs and then update the whole CSV file, so it is easier to map the values during the import.

Time Tracking Fields

As of JIRA 3.7 you can now import into the 'Original Estimate', 'Remaining Estimate', and 'Time Spent' fields. For these fields to be available you must have enabled time tracking within JIRA. The importer expects the estimate or time spent to be expressed in seconds. A value that is not able to be converted to a numeric value will be ignored and not imported.

The portion of the importer that converts the raw string to a java.lang.Long which represents number of seconds is customizable. If you are trying to import data that needs to more intelligently process the value (more than just converting the string to a numeric value) you can write your own java class. It needs to implement the com.atlassian.jira.imports.csv.mapper.TimeEstimateConverter interface and you can direct the importer to use your class by specifying in the csv.properties configuration file the 'settings.advanced.mapper.time.estimate.converter' property (i.e. settings.advanced.mapper.time.estimate.converter=com.atlassian.jira.imports.csv.mappers.SimpleTimeEstimateConverter= com.atlassian.jira.imports.csv.mappers.SimpleTimeEstimateConverter)

Custom Fields and the importer

You can also map a column to an existing custom field or create a new custom field on the fly. Currently you can only create certain custom fields on the fly. All custom fields created this way will be globally scoped. Moreover, if the name matches an existing custom field, that existing custom field will be used instead. If you are worried about how this works exactly, we recommend that you create your custom fields first before importing them.

If you map to a select list custom field, all unique values will be created as options at import time. If you map to a multiple select field, its values should be separated by a comma. If the field values have commas in them, the commas should be escaped with a backslash. Thus the field:

"Wally\, I,Wally\, II"

would be translated into one field with multiple values:

• Wally I
• Wally II

Once again, no data validations are done at configuration time, so you should ensure that the data you are trying to import is of a compatible type.

2.3 Map Field Values

You may wish to map certain values in your CSV file to a different value. For example, you might map the field 'Severity' to JIRA's 'Priority' field. JIRA expects the ID of priorities that exist in JIRA. Thus for this field, you'll need to check the Map field value check-box. This will affect the next screen that you will come to.

Value Mappings

Value mappings determine how values from your CSV importer will be 'translated' to match the values expected by JIRA. This is usually required for fields such as 'Issue Type', 'Resolution', 'Priority' and 'Status', but can also apply to other fields. On this screen, all unique values for each field you selected to be mapped have been displayed. You can now map any of these values to their values in JIRA. Leave the field blank if you wish to import the value as-is. If you want to clear a field, enter the keyword <<blank>>.

On the 'Field Mappings' screen, each field has a checkbox under the heading 'Map values'. If you check these boxes you will be able to map the values of these fields when you progress to the next page.

For fields mapping to Resolution, Priority and Issue Type, you will get a select list with the available values in JIRA. In addition, you can quickly create values that do not exist in JIRA by clicking the green plus symbols.

For fields mapping to Status, you will get the select list with JIRA's available values, but no plus symbol for creating new status values.

For these four fields, there are two special options in the select list in addition to JIRA's available values:

• 'Import as blank' — this causes the JIRA value to be blank for that field. Note that, if you are importing Unresolved issues, you should create a field mapping for the Resolution field and set the value 'Unresolved' to 'Import as blank'.
• 'No mapping' ---  this attempts to import the value in the CSV file as-is. Note that using 'No mapping' for a field value will result in a failed import if the value is not valid for that JIRA field. For fields mapping to Status and Issue Type, default values are used when the 'Import as blank' option is selected.

2.4 Miscellaneous Information

You will be asked to enter some extra information on this screen, such as:

1. The domain name of the users that will be created in the system.
2. If you are importing date fields, you will also be asked to supply the date format that is used in your CSV file. Note that this could be different from the date format that is used in JIRA. All date fields will be interpreted using the format you supply.
   

2.5 Saving the Configuration File

The final step of the Wizard allows you to save the configuration file on your server. Saving the configuration file enables you to import more CSV files later without going through the Configuration Wizard again. Please ensure you enter a valid path. Alternatively, you can choose to continue on with the import without saving the configuration in a file.

You can also see a preview of the mapping file that will be saved.

3. Importing the CSV file

Once you have your configuration file, you can then import the CSV file into JIRA.

1. Log in as a user with the 'JIRA System Administrators' global permission.
2. 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.
3. On the panel on the left, under the title 'Import & Export', click 'External System Import. '
4. The 'Import Data' page will be displayed. Select 'Comma-separated values (CSV)'.
5. The 'Import issues from CSV file' page will be displayed.
6. Type the location of your CSV file and your configuration file, and click the 'Import' button.

The 'Settings' page gives you precise control over what will be imported on each import run.

Once the import has begun you will be able to follow the progress of the import, with the screen refreshing around every 10 seconds. You can change this rate by updating the field at the bottom of the page. The importer also give you statistics about what objects have been imported and time elapsed so you can have an idea as approximately how long the import will take. You can also choose to 'Abort' the import, which will cease importing after the current issue is done.

Known Issues

• The CSV Importer doesn't import all the objects available in JIRA at present. You can find these limitations at issue JRA-5774.
• There is a known problem that prevents the CSV Importer from being used with JIRA instances running on JBoss 4.x. This is due to a compatibility issue between the JBoss 4.x commons-collections.jar and the JIRA commons-collections.jar. The workaround is to replace the commons-collections.jar in JBoss 4.x with the more recent JIRA version. Please see JRA-6473 for further details.