The Jira Importers plugin, which is bundled with Jira, allows you to import your data from a comma-separated value (CSV) file. This might be helpful when you are migrating from an external issue tracker to Jira.
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 feature allows you to import issues from an external (issue tracking) system which can export its data in a structured/tabulated format (preferably CSV).
Our main website highlights some top reasons why people migrate from such an external issue tracking system to Jira.
The CSV import process consists of:
- Preparing your CSV file (below).
- Running the CSV file import wizard (below).
- You can choose to map individual fields and field values during the import process.
- At the end of the CSV file import wizard, you will be given the option of creating a CSV configuration file, which contains the settings you configured while running through the CSV file import wizard. This is useful if you need to test your CSV file import on a test Jira server first before performing the import on a production system.
Please note:
- Several methods are available for importing data from other issue tracking systems into Jira. Depending on your other issue tracking system, it may be more appropriate to use one of these other methods than to first export your data from that system to a CSV file and then import that CSV file into Jira. If your other issue tracking system is listed on the Migrating from other issue trackers page, try using the appropriate method for that issue tracker (which is accessible from that page) to import data into Jira.
- If you want to raise a bug report or improvement suggestion about this feature, please do so within the Jira Importers plugin project.
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 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.
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:
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
Encapsulating Jira data structure in your CSV file
Capturing data that spans multiple lines
Use double-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
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:
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.
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.
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"
Admin, "CSV attachment import with timestamp,author and filename", "Please check the attached image below.", "01/01/2012 13:10;Admin;image.png;file://image-name.png", "01/01/2012 10:10;Admin; This comment works"
URLs for attachments support the HTTP and HTTPS protocols and can be any location that your Jira server must be able to access. You can also use the FILE protocol to access files in the import/attachments
subdirectory of your Jira home directory.
Creating sub-tasks
You can create sub-tasks of issues through a CSV file import, by encapsulating this structure in your CSV file. To do this:
- Your CSV file requires two additional columns whose headings should be named similarly to 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.
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
Sub-task, "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.
Importing issues into multiple Jira projects
You can import issues from your CSV file into different Jira projects through a CSV file import. To do this:
- Your CSV file requires two additional columns whose headings should be named similarly to Project Name and Project Key.
- Ensure that every issue represented in your CSV file contains the appropriate name and key in these columns for the Jira projects to which they will be imported.
The project name and key data is the minimum Jira project data required for importing issues from a CSV file into specific Jira projects.
IssueType, Summary, Project Name, Project Key
bug, "First issue", Sample, SAMP
bug, "Second issue", Sample, SAMP
task, "Third issue", Example, EXAM
In the example above, the first and second issues will be imported into the 'Sample' project (with project key 'SAMP') and the third issue will be imported into the 'Example' project (with project key 'EXAM') , assuming you match the 'Project Name' and 'Project Key' fields in your CSV file to the Project name and Project key Jira fields, respectively during the CSV file import wizard.
How to handle unresolved issues
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.
Importing worklog entries
Your CSV file can contain worklog entries. For example:
Summary,Worklog
Only time spent (one hour),3600
With a date and an author,2012-02-10 12:30:10;wseliga;120
With an additional comment,Testing took me 3 days;2012-02-10 12:30:10;wseliga;259200
To track time spent, you need to use seconds.
Importing to multi select custom fields
Your CSV file can contain multiple entries for the one Multi Select Custom Field. For example:
Summary,Multi Select,Multi Select,Multi Select
Sample issue,Value 1,Value 2,Value 3
This will populate the Multi Select Custom Field with multiple values.
Importing cascading choice custom fields
You can import values to a cascading choice custom field using the following syntax:
Summary, My Cascading Custom Field
Example Summary, Parent Value -> Child Value
The '->' separator allows you to import the hierarchy.
NOTE: Currently Jira does not support importing multi-level cascading select fields via CSV ( JRASERVER-34202 - Allow CSV import to support Multi-Level Cascading Select plugin fields GATHERING INTEREST ).
Updating existing issues
From version 4.3 of Jira Importers plugin you can update existing issues. Your CSV file needs to contain a column that during the import wizard is mapped to Issue Key. If an issue exists for a given key it will be updated. For example:
issue key,summary,votes,labels,labels
TT-1,Original summary,1,label1,label2
TT-1,,7,label-1,label-2
TT-1,Changed summary,,,
TT-2,Original summary 2,1,label-1,label-2
TT-2,,<<!clear!>>,<<!clear!>>,
First row will create an issue, second row will set votes to 7, and add two labels. Following row will change the summary. Issue TT-2 will be created with two labels, the second row will remove those labels with a special marker <<!clear!>>.
Importing a CSV to update existing issues will reset columns to their default values if they are not specified in the CSV.
Running the CSV file import wizard
Before you begin, please back up your Jira data.
- Log in to Jira as a user with the Jira Administrators global permission.
- Select Administration > System > Import & Export > External System Import.
- Select CSV to open the CSV File import page.
- On the CSV File import page, 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.
- Leave the Use an existing configuration file checkbox cleared if you do not have a configuration file or if you want to create a new configuration file. Configuration files specify a mapping between column names in your CSV file's header row and fields in your Jira installation.
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 for subsequent CSV imports (at this step of the CSV file import wizard).
- Click the Next button to proceed to the Setup project mappings step of the CSV file import wizard.
On the Setup project mappings page, you can either import all your issues into either one Jira project (new or existing), or multiple Jira projects (by ensuring that your CSV file includes the minimum Jira project data required — i.e. the Jira project name and key). 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 drop-down menu to select an existing Jira project.
- Select Create New from the drop-down menu and in the resulting Add A New Project dialog box, type the following:
- A new project Name
- A new project Key
This 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 Jira Project Name and Project Key.
This option is useful if you want to import issues from your CSV file into multiple Jira projects. See Importing issues into multiple Jira projects for details.
E-mail Suffix for New Users Enter 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. - Select a project and then do either of the following:
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 checkboxes 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.
- If you are importing sub-tasks, remember to match the Issue ID and Parent ID fields in Jira to those in your CSV file.
- If you are importing issues into multiple projects, ensure that you selected Defined in CSV during the Setup project mappings step above and remember to match the Project Name and Project Key fields in Jira to those in your CSV file.
- To modify the values of any fields' data in the CSV file before they are imported into Jira, select the Map field value checkboxes next to the appropriate fields.
- Click the Next button to proceed to proceed to the Setup value mappings step of the CSV file import wizard.
- On the Setup value mappings page, specify the Jira field values for each CSV file field value (which has been detected by the CSV file import wizard).
Please note:- Any fields whose Map field value checkboxes were selected in the previous step of the CSV file import wizard will be presented on this page.
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 checkbox 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 checkbox, Jira will automatically create usernames based on the data in your CSV file if they have not already been defined in Jira.
- Click the Begin Import button when you are ready to begin importing your CSV data into Jira. The importer will display updates as the import progresses, then a success message when the import is complete.
Note:- If you experience problems with the import (or you are curious), click the download a detailed log link to reveal detailed information about the CSV file import process.
- If you need to import another CSV file with the same (or similar) settings to what you used through this procedure, click the save the configuration link to download a CSV configuration file, which you can use at the first step of the CSV file import wizard.
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:
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. |
Issue Key | You can set the issue key for an imported issue. If an issue with a given key already exists in Jira, it will be updated instead. |
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 | Import issues with multiple labels by:
|
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. Also, see How to handle unresolved issues for helpful tips. |
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.
|
Watchers | If you have users specified as Watchers in your CSV file, and these users do not exist in Jira, they will not be imported. A user must be available in Jira before you can import them as a watcher on a specific issue. |
Other fields | If you 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. |