Documentation for JIRA 4.4. Documentation for other versions of JIRA is available too.
The JIRA Importers plugin, which is bundled with JIRA, allows you to import your data from a comma-separated value (CSV) file. CSV files are text files representing tabulated data and are supported by most applications that handle tabulated data (for e.g. Microsoft Excel, databases, etc.).
The CSV import process consists of:
Please Note:
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 new lines/'carriage returns' themselves are enclosed in quotes.
For Microsoft Excel and OpenOffice, it is not necessary to quote values in cells as these applications handle this automatically.
In addition to being 'well-formed', CSV files have the following requirements.
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.
For example, this is valid:
Summary, Assignee, Reporter, Issue Type, Description, Priority "Test issue", admin, admin, 1, ,
... but this is not valid:
Summary, Assignee, Reporter, Issue Type, Description, Priority "Test issue", admin, admin, 1
Use quote marks in your CSV file to capture data that spans multiple lines. For example, upon import, JIRA will treat the following as a valid CSV file with a single record:
Summary, Description, Status "Login fails", "This is on a new line", Open
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"
Clicking the "Add" button results in a page not found error
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:
IssueType, Summary, FixVersion, FixVersion, FixVersion, Component, Component bug, "First issue", v1, , , Component1, bug, "Second issue", v2, , , Component1, Component2 bug, "Third issue", v1, v2, v3, Component1,
In the above example, the Component field of the second issue and the Fix Version field of the third issue will generate multiple values in appropriate JIRA fields upon import.
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.
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.
Assignee, Summary, Description, Attachment, Comment Admin, "Issue demonstrating the CSV attachment import", "Please check the attached image below.", https://jira-server:8080/secure/attachment/image-name.png, "01/01/2012 10:10;Admin; This comment works"
URLs for attachments only support the HTTP and HTTPS protocols.
You can create sub-tasks of issues, whose structure can be encapsulated in a CSV file. To do this:
For example:
IssueType, Summary, FixVersion, FixVersion, FixVersion, Component, Component, Issue ID, Parent ID, Reporter bug, "First issue", v1, , , Component1, , 1, , jbloggs bug, "Second issue", v2, , , Component1, Component2, 2, , fferdinando bug, "Third issue", v1, v2, v3, Component1, , 3, , fferdinando subtask, "Fourth issue", v1, v2, , Component2, , , 2, jbloggs
In the example above, the fourth issue will be sub-task of the second issue upon import, assuming you match the 'Issue ID' and 'Parent ID' fields in your CSV file to the Issue Id and Parent Id JIRA fields, respectively during the CSV file import wizard.
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:
Assignee, Summary, Comment Admin, "Test issue", "This is a comment that will be added to the issue once imported into JIRA" # And this is a comment that will not be processed by the JIRA import wizard.
Comments are useful if you want to add additional information to the CSV file that you do not want JIRA to import.
If your JIRA installation has existing data, then before you begin, backup your existing JIRA data.
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:
|
E-mail Suffix for New Users | Type the email address domain for any new users specified in the CSV file which will be added to JIRA during the import. |
Date format in import file | Specify the date format used in your CSV file. Use the syntax that complies with the Java SimpleDateFormat. |
Click the Next button to proceed to the Setup field mappings step of the CSV file import wizard.
On the Setup field mappings page, specify each CSV Field (determined by your CSV file's header row) you want to import into your chosen JIRA project by selecting their check boxes under the Import column on the left.
Please Note:
At least one of these fields must contain data for JIRA's Summary field.
If your CSV file contains more than one of the same field name specified in its header row, the CSV file import wizard will aggregate these into a single field, which will be marked by a symbol at this step of the wizard.
In the JIRA field column, select the JIRA fields you want to match to fields defined in your CSV file (i.e. each CSV Field you selected in the previous step). For more information about matching CSV fields to JIRA fields, see Tips for importing CSV data into JIRA fields below.
Please Note:
The Summary field must be specified for one of your JIRA fields and the Next button will remain unavailable until you do so.
For CSV fields which have been aggregated by the CSV file import wizard, you will only be able to select JIRA Fields that support multiple values.
Leave a field cleared or clear any content within it if you wish to import the value 'as is'.
You can create new Priority, Resolution and Issue Type values in JIRA (i.e. based on the data in your CSV file) by clicking the Add new ... link (e.g. Add new issue type 'subtask' shown in the screenshot above) next to the appropriate field.
If you are importing a username-based CSV field (e.g. Reporter or Assignee) and you do not select the Map field value check box for this field in the previous step of the CSV file import wizard, then the importer will automatically map imported usernames from the CSV file to (lowercase) JIRA usernames.
Regardless of whether or not you select the Map field value check box, JIRA will automatically create usernames based on the data in your CSV file if they have not already been defined in JIRA.
As of version 3.5.2 of the JIRA Importers Plugin, the option to Create New Users is no longer available.
Congratulations, you have successfully imported your CSV data into JIRA! If you have any questions or encounter any problems, please contact Atlassian support.
Below are some helpful tips when importing data from your CSV file into specific JIRA fields:
JIRA Field | Import Notes |
---|---|
Project | CSV data is imported on a per-project basis. You can either specify an existing JIRA project(s) as the target, or the importer will automatically create a new project(s) for you at time of import. |
Summary | This is the only required field. |
Component(s) | You can import issues with multiple components by entering each component in a separate column. |
Affects Version(s) | You can import issues with multiple 'Affects Versions' by entering each version in a separate column. |
Fix Version(s) | You can import issues with multiple 'Fix Versions' by entering each version in a separate column. |
Comment Body | You can import issues with multiple comments by entering each comment in a separate column. |
Date Created | Please use the date format specified on the second step of the CSV import wizard. |
Date Modified | Please use the date format specified on the second step of the CSV import wizard. |
Due Date | Please use the date format specified on the second step of the CSV import wizard. |
Issue Type | If not specified in your CSV file, imported issues will be given the default (i.e. first) Issue Type as specified in your JIRA system Defining 'Issue Type' Field Values. You can also create new JIRA values on-the-fly during the import process. |
Labels | You can import issues with multiple labels by entering each label in a separate column. |
Priority | If not specified in your CSV file, imported issues will be given the default (i.e. first) Priority as specified in your JIRA system Defining 'Priority' Field Values. You can also create new JIRA values on-the-fly during the import process. |
Resolution | If not specified in your CSV file, imported issues will be given the default (i.e. first) Resolution as specified in your JIRA system Defining 'Resolution' Field Values. You can also create new JIRA values on-the-fly during the import process. |
Status | Can only be mapped to existing workflow statuses in JIRA. If not specified in your CSV file, imported issues will be given the default (i.e. first) Status as specified in your JIRA system. |
Original Estimate | The value of this field needs to be specified as number of seconds. |
Remaining Estimate | The value of this field needs to be specified as number of seconds. |
Time Spent | The value of this field needs to be specified as number of seconds. |
Users | You can choose to have the importer automatically create JIRA users for any values of the Assignee or Reporter field.
|
Other fields | If your wish to import any other fields, you can choose to map them to specific JIRA custom field(s). If your custom fields don't yet exist in JIRA, the importer can automatically create them for you. If your custom field is a date field, please use the date format specified on the second step of the CSV import wizard. |