• Add
  • Comment
• Tools
  • Attachments (1)
  • Page History
  • Restrictions

  • Info
  • Link to this Page…
  • View in Hierarchy
  • View Source
  • Export to PDF
  • Export to Word

• Page restrictions apply
• Attachments:1
• Added by admin, last edited by Giles Gaskell [Atlassian Technical Writer] on Feb 06, 2012  (view change)

Preparing your CSV file

The JIRA Importers plugin assumes that your CSV file is based off a default Microsoft Excel-styled CSV file. Fields are separated by commas and any content that must be treated literally, such as commas and quotes themselves are enclosed in quotes. (Embedded quotes are repeated.)

For Microsoft Excel and OpenOffice, it is not necessary to quote values in cells as these applications handle this automatically.

CSV file requirements

In addition to being 'well-formed', CSV files have the following requirements.

Each CSV file must possess a heading row with a Summary column

The CSV file import wizard (below) uses a CSV file's header row to determine how to map data from the CSV file's 2nd row and beyond to fields in JIRA.

The header row should avoid containing any punctuation (apart from the commas separating each column) or the importer may not work correctly.

The header row must contain a column for Summary data.

Commas (as column/field separators) cannot be omitted

For example, this is valid:

... but this is not valid:

Encapsulating JIRA data in your CSV file

Capturing data that spans multiple lines

Use quote marks in your CSV file to capture data that spans multiple lines. For example, JIRA treats the following as a valid CSV file with a single record:

Treating special characters literally

Use double quote marks (") around a section of text to treat any special characters in that section literally. Once this data is imported into JIRA, these special characters will be stored as part of JIRA's field data. Examples of special characters include carriage returns/enter characters (as shown in the example above), commas, etc.

To treat a double quote mark literally, you can 'escape' them with another double quote mark character. Hence, the CSV value:

• "Clicking the ""Add"" button results in a page not found error"
  once imported, will be stored in JIRA as:
• Clicking the "Add" button results in a page not found error

Aggregating multiple values into single JIRA fields

You can import multiple values into a JIRA field that accepts multiple values (e.g. Fix (for) Version, Affects Version, Component, Labels). To do this, your CSV file must specify the same column name for each value you wish to aggregate into the mapped JIRA field. The number of column names specified must match the maximum number of values to be aggregated into the mapped field. For example:

In the above example, the third imported issue will have its Fix Version set to multiple values.

Be aware that only a limited number of JIRA fields support multiple values. The CSV importer will not allow you to import aggregated data into JIRA fields which only support a single value.

Importing attachments

You can attach files to issues created from your CSV file. To do this, specify the URL of your attachment in an Attachments column within your CSV file.

URLs for attachments only support the HTTP and HTTPS protocols.

Creating sub-tasks

You can create sub-tasks of issues, whose structure can be encapsulated in a CSV file. To do this:

• Your CSV file requires two additional columns whose headings should be named Issue Id and Parent Id.
• Ensure each regular (non sub-task) issue is given a unique (sequential) number in the Issue Id column. Do not include any value in the Parent Id fields for regular issues.
• To create a sub-task of a regular issue in your CSV file, reference the unique Issue Id number of the regular issue in the Parent Id column. Do not include any value in the Issue Id fields for sub-tasks.

Allowing comments in CSV files

Your CSV file can contain comments which are not processed by the JIRA import wizard. Any text appearing to the right of a hash (#) symbol on a line of text in the CSV file will be disregarded by the JIRA import wizard. For example:

Comments are useful if you want to add additional information to the CSV file that you do not want JIRA to import.

Running the CSV file import wizard

If your JIRA installation has existing data, then before you begin, backup your existing JIRA data.

1. Log in to JIRA as a user with the JIRA Administrators global permission.
2. Select Administration > System > Import & Export > External System Import > Import button associated with the Comma-separated values (CSV) option to open the CSV File import page.
   Keyboard shortcut: g + g + start typing external system import
   
3. Select your CSV Source File. If you want to change the file's encoding and CSV delimiter format, click the Advanced heading to reveal this option (as shown in the above screenshot).
     Note:
   
   • The file will be imported using the File encoding you specify here (which is UTF-8 by default).
   • If your CSV file uses a different separator character other than a comma, specify that character in the CSV Delimiter field.
4. Leave the Use an existing configuration file option check box cleared if you do not have a configuration file or if you want to create a new configuration file.
     Note:
   • If you select this option, you will be asked to specify an Existing Configuration File.
   • If you do not select this option, then at the end of the CSV file import wizard, JIRA will create a configuration file which you can use in subsequent CSV imports.
5. Click the Next button to continue.

6. On the Setup project mappings page, 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. Complete the following fields/options:

   Import to JIRA Project	Choose either of the following: Select a project and then do either of the following: Start typing the name (or key) of a project that already exists in JIRA or use the dropdown menu to select an existing JIRA project. Select Create New from the dropdown menu and in the resulting Add A New Project dialog box, specify the following: A new project Name A new project Key The will be used as the prefix for all issue IDs in your JIRA project. The Project Lead. Defined in CSV. Ensure that every issue in your CSV file includes data for the project name/key.

    

   • In the   field, do one of the following:
   • In the E-mail Suffix for New Users field, specify the address of the email domain for any new users specified in the CSV file which will be added to JIRA after the import.
   • In the Date format in import file field, specify the date format used in your CSV file.
   • 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 is 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.

Tips for importing CSV data into JIRA fields

Below are some helpful tips when importing data from your CSV file into specific JIRA fields: