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. Here is a good opportunity to do any massaging of data you may wish to do.
If you wish to import data from one column into multiple JIRA fields, you should duplicate the column and rename it as something different.
If you have values that signifies a blank value (e.g. <blank> or None), it's best if you simply remove them in this step.
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. The CSV file must contain a heading
row. If a row contains more columns than there are header columns, then the excess columns will be
added as comments (though see JRA-7672.
You can also have multi-lined CSV. So this below is a valid file with a single record:
Summary,Description,Status
Login fails,"This is on
a new line",Open
Note
The CSV configuration wizard uses the CSV header row extensively. The header row should not have any punctuation, such as commas and apostrophes or the importer may not work correctly.
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 CSV importer is available from Administration -> Import &
Export -> External System Import.
First step is to choose which project the issues will be imported into. You can import into a new project or an existing project. Note that if you are creating a new project, no validations are performed at this time - it will fail at import time. Moreover, if certain project details matches an existing project (like name and key), then the issues will be imported into an existing project.
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 same 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 figure out 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.
Note
No validations are performed on fields mappings until data import occurs. So please try to ensure that your data is correct and valid. We recommend that the Issue Type and Summary fields are included as a bare minimum, or your import is likely to fail.
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 "Affects Versions" field. For Versions and Components, the importer will detect if the already exists in JIRA or not. If it doesn't then it will automatically created.
User fields (assignee & 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 the has one word, that one word will be used as the username.
System fields like priority, issue type, status and resolution expects your CSV file to have the id, not the text. It is very likely that you will have to map the field value.
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. You can only create certain custom fields on the fly at the moment. 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 items will be created at import time. If you map to a multiple select field, it's 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
Once again, no data validations are done at configuration time, so you should ensure that the data you are trying to import into a is of a compatible type.
Map field value
You may wish to map certain values in your CSV file to a different value. For example, you've mapped 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'll come to.
Value mappings are how values from your CSV importer can be "translated" to match that values expected by JIRA. This is usually required for fields like issue type, resolutions, priorities and statuses, but can equally be applicable for 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 you will notice that 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 statuses, resolutions, priorities and issue types, you will get a select list with the available values in JIRA. For resolutions, priorities and issue types you can also quickly create values that do not exist in JIRA by clicking on the green plus symbols. These constants will be created with some default values that you can change at a later time.
|
Miscellaneous information
| |
| | |
You will be asked to enter some extra information on this screen such as:
- Domain name of the Users that will be created in the system
- If you are importing date fields, you will also be asked to supply a date format. This is the date format of the dates that are in your CSV file, not the date format in JIRA. All date fields will be parsed with this date.
|
Saving the configuration file
| |
| | |
The final step of the Wizard is to save the file on your server. Please ensure you enter a valid path. You can also choose to continue on with the import without saving the file.
You can also see a preview of the mapping file that will be saved.
