Documentation for JIRA 4.0. Documentation for other versions of JIRA is available too.
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).
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.
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.
Note: Before you begin, please backup your JIRA data.
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 then 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.
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:
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
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).
If a row contains more columns than there are header columns, then the excess columns will be added as comments (though see JRA-7672).
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.
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.
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.
As no validations are performed on field mappings until data import occurs, please try to ensure that your data is correct and valid.
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.
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), any users you import over and above your user limit will be created in JIRA without permission to log in to JIRA. You will not be able to select which of your users are assigned login permissions under the user limit, when you perform the import. However, you can change this after the users are imported, by editing user permissions.
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.
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
)
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:
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.
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 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:
You will be asked to enter some extra information on this screen, such as:
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.
Once you have your configuration file, you can then import the CSV file into JIRA.
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.