Our independent web site highlights some top reasons why people migrate from such an external return tracking organization to Jira.
The CSV import process consists of the following stages:
- Preparing your CSV file (find the instructions below).
- Running the CSV file import wizard (find the instructions 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 can choose to create a CSV configuration file that 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.
several methods are available for importing data from early publish tracking systems into Jira. Depending on your early issue tracking system, it may be more appropriate to use a different import method rather of exporting data from that system to a CSV file and then importing that CSV file to Jira. If your other emergence tracking system is listed on the Migrating from other topic trackers page, try using the allow method to import data to Jira. You may besides want to use the Bulk issues import feature alternatively of External system consequence. Learn more about Bulk issues meaning in here .
On this page:
Preparing your CSV file
The Jira Importers plugin assumes that your CSV file is based off a default option Microsoft Excel-styled CSV file :
- Fields are separated by commas.
- Any content that must be treated literally, such as commas and new lines/”carriage returns” themselves are enclosed in quotation marks.
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 “ grammatical ”, CSV files have the follow requirements .
Each CSV file must possess a heading row with a Summary column
The CSV charge import charming ( see more details below ) uses a CSV file ‘s header row to determine how to map data from the CSV file ‘s 2nd rowing and beyond to fields in Jira. The header row should n’t contain any punctuation, except for the comma separating each column. otherwise, the importer may not work correctly. The header row must contain a column for the issue ‘s “ Summary ” data .
Commas (as column/field separators) cannot be omitted
For exemplar, the follow format is valid :
Summary, Assignee, Reporter, Issue Type, Description, Priority "Test issue", admin, admin, 1, ,
While this one is not valid :
Summary, Assignee, Reporter, Issue Type, Description, Priority "Test issue", admin, admin, 1
Encapsulating Jira data structure in your CSV file
In this section, you ’ ll find solutions for the following issues :
Capturing data that spans multiple lines
Use double-quote marks (
" ) in your CSV file to capture data that spans multiple lines. For example, during consequence, Jira will treat the pursue as a valid CSV file with a one record :
Summary, Description, Status "Login fails", "This is on a new line", Open
Treating special characters literally
Use double-quote marks (
" ) around a segment of text to treat any special characters in that section literally. once this datum is imported into Jira, these special characters will be stored as character of Jira ‘s field data. Examples of particular characters include carriage returns/enter characters, comma, etc. To treat a double quote grade literally, you can “ escape ” them with another bivalent quote grade character. For case :
- Your CSV file might contain the value like
"Clicking the ""Add"" button results in a page not found error".
- Once imported, it 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 battlefield that accepts multiple values. For case, Fix (for) Version, Affects Version, Component, or Labels. To do this, your CSV file must specify the lapp column name for each value you wish to aggregate into the map Jira field. The issue of column names specified must match the maximum number of values to be aggregated into the map sphere. For exercise :
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 this example, the Component playing field of the moment issue and the Fix Version field of the third issue will generate multiple values in allow Jira fields upon meaning .
Be mindful that merely a limited number of Jira fields support multiple values. The CSV importer will not allow you to import aggregated data into Jira fields that merely 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 in 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 entree. You can besides use the FILE protocol to access files in the
import/attachments subdirectory of your Jira home directory .
You can create sub-tasks of issues through a CSV file import by encapsulating this structure in your CSV charge. To do this :
- The CSV file must have two additional columns whose headings should be named similarly to Issue Id and Parent Id.
- Ensure that 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. Don’t set any value in the Issue Id fields for sub-tasks.
For exemplar :
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 this example, the fourth issue will be imported as a sub-task of the second issue, 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 spell charming .
Importing issues into multiple Jira projects
You can import issues from your CSV file into different Jira projects through a CSV charge meaning. To do this :
- The CSV file must have two additional columns whose headings should be named similarly to Project Name and Project Key.
- guarantee that every topic represented in your CSV file contains the appropriate name and key in those columns for the Jira projects to which they will be imported .
The project mention and key data is the minimal Jira project data required for importing issues from a CSV charge 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 this exercise, the beginning and moment issues will be imported into the “ Sample ” undertaking ( with project key “ SAMP ” ) and the third issue will be imported into the “ Example ” project ( with undertaking keystone “ EXAM ” ), assuming you match the “ project mention ” and “ Project Key ” fields in your CSV file to the Project name and Project key Jira fields respectively during the CSV file meaning charming .
Handl unresolved issues
For fields mapping to Resolution, Priority, and Issue Type, you will get a blue-ribbon number with the available values in Jira. In addition, you can promptly create values that do not exist in Jira by clicking the green plus symbols. For fields mapping to Status, you will get the choice list with Jira ‘s available values, but no asset symbol for creating modern condition values. For these four fields, there are two extra options in the blue-ribbon list in addition to Jira ‘s available values :
- “Import as blank”. If selected, 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 exemplar :
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 cascade choice customs sphere using the succeed syntax :
Summary, My Cascading Custom Field Example Summary, Parent Value -> Child Value
The ‘- > ‘ centrifuge allows you to import the hierarchy .
presently, Jira does n’t support importing multi-level cascade choose fields via CSV ( JRA-34202 – Getting emergence details … STATUS ) .
Updating existing issues From adaptation 4.3 of Jira Importers plugin, you can update existing issues. Your CSV file needs to contain a column that will be mapped to Issue Key during the meaning. If an write out exists for a given winder, it will be updated. For model :
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,,<>,<>,
The first course will create an issue, the second base row will set votes to 7 and add two labels. The pursue quarrel will change the compendious. Issue TT-2 will be created with two labels, but the second row will remove those labels with a limited 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, you need to back up your Jira data. To use the External organization consequence feature to import your issues to Jira :
- 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 encode and CSV delimiter format, select the Advanced heading to reveal this choice .
- The file will be imported using the File encoding type you specify here. The default file type is UTF-8.
- 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 shape file or if you want to create a raw configuration file. Configuration files specify a map between column names in your CSV file ‘s header row and fields in your Jira initiation .
- 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).
- Select Next 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. If you choose to import to multiple projects, ensure that your CSV file includes the minimum Jira project data required, which is Jira project appoint and key. Complete the postdate fields/options :
Import to Jira Project Choose one of the follow :
- Select a project. Use this option to import issues to an existing Jira project or create a new project and import issues to it.
- 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, fill in the following fields:
- Enter the project Name
- Enter the visualize Key
This will be used as the prefix for all issue IDs in your Jira project .
- Specify the Project Lead.
- Defined in CSV. Use this option to import issues to multiple Jira projects. Ensure that every issue in your CSV file includes data for the Jira Project Name andProject Key .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 that 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. Use this option to import issues to an existing Jira project or create a new project and import issues to it.
- Select Next to proceed to the Setup field mappings tone of the CSV file meaning charming .
- In the Setup field mappings page, map the fields in the CSV file to the issue fields in the selected project. In the Jira field column, select the Jira field that you want to map to the field from the CSV file. For more information about matching CSV fields to Jira fields, see Tips for importing CSV data into Jira fields below .
- The Summary field must be specified for one of your Jira fields and the Next button will remain unavailable until you do so.
- If your CSV file contains more than one of the like sphere name specified in its header rowing, the CSV file meaning ace will aggregate these into a single playing field, which will be marked by an icon at this tone of the ace .
- For CSV fields that have been aggregated by the CSV file import charming, you will lone be able to select Jira Fields that documentation 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. 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.
- Select Next 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 that has been detected by the CSV file import ace .
- Any fields which 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 message 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 selecting the Add new link next to the appropriate field .
- If you are importing a username-based CSV plain ( e.g. Reporter or Assignee ) and you did n’t select the Map field value checkbox for this field in the previous step of the CSV file consequence charming, then the importer will mechanically map imported usernames from the CSV file to ( small letter ) Jira usernames .
Regardless of whether or not you select the Map field value checkbox, Jira will mechanically create usernames based on the data in your CSV file if they have n’t been defined in Jira even .
- Select the Begin Import button when you are ready to begin importing your CSV data into Jira. The importer will display updates as the meaning progresses, then a success message when the import is complete .
- If you experience problems with the import (or you are curious), select the download a detailed log link to view 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, select 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 datum into Jira ! If you have any questions or encounter any problems, please contact Atlassian support .
Tips for importing CSV data into Jira fields
The following are some helpful tips when importing data from your CSV file into specific Jira fields.
|Jira Field||import Notes|
|project||CSV datum is imported on a per-project footing. You can either specify an existing Jira visualize ( sulfur ) as the target or the importer will mechanically create a new project ( s ) for you at clock time of spell .|
|drumhead||This is the alone command 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 break column .|
|Affects Version ( randomness )||You can import issues with multiple ‘Affects Versions ‘ by entering each version in a branch column .|
|Fix Version ( mho )||You can import issues with multiple ‘Fix Versions ‘ by entering each adaptation in a separate column .|
|remark torso||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 footstep of the CSV import charming .|
|Date Modified||Please use the go steady format specified on the second gear step of the CSV spell charming .|
|due Date||Please use the date format specified on the second step of the CSV import charming .|
|issue type||If not specified in your CSV file, imported issues will be given the default ( i.e. beginning ) Issue Type as specified in your Jira arrangement Defining consequence type airfield values. You can besides create new Jira values on-the-fly during the import process .|
|Labels|| consequence issues with multiple labels by :
|precedence||If not specified in your CSV file, imported issues will be given the default ( i.e. inaugural ) priority as specified in your Jira organization Defining precedence field values. You can besides create modern Jira values on-the-fly during the import march .|
|resolution||If not specified in your CSV file, imported issues will be given the default ( i.e. beginning ) resolution as specified in your Jira system Defining resolution field values. You can besides create new Jira values on-the-fly during the import process. besides, see How to handle unsolved issues for helpful tips .|
|condition||Can only be mapped to existing work flow statuses in Jira. If not specified in your CSV charge, imported issues will be given the default option ( i.e. first ) Status as specified in your Jira organization .|
|original estimate||The respect of this field needs to be specified as number of seconds .|
|Remaining estimate||The value of this field needs to be specified as count of seconds .|
|Time Spent||The value of this field needs to be specified as phone number of seconds .|
|Users|| You can choose to have the importer mechanically create Jira users for any values of the Assignee or Reporter discipline .
|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 drug user must be available in Jira before you can import them as a spectator 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 ( second ). If your customs fields do n’t yet exist in Jira, the importer can automatically create them for you. If your customs field is a date field, please use the date format specified on the moment step of the CSV import sorcerer .|
Importing issues in bulk
The Bulk issues meaning sport allows non-administrative users to import issues to Jira. External system consequence, which is described above, is available only for Jira Administrators. With Bulk issues significance, you should besides import issues from a CSV file. But the introduction steer and steps to run Bulk issues import differ from External system significance. The Bulk issues meaning functionality has the pursuit restrictions :
- New users won ’ metric ton be created .
- New projects won ’ thymine be imported. You should import issues only to existing projects .
- Custom fields and solution values can ’ thyroxine be created in issues .
Some fields in issues may be missing. See the complete list of such fields in
Missing fields for mapping when importing issues through CSV in Jira.
Prepare the CSV file with your Jira issues as trace here. To import the file :
- choose Issues > import issues from CSV
- Select the CSV file that you want to import .
- Leave the Use an existing configuration file checkbox cleared if you don ’ t have a configuration file or if you want to create a modern shape file. In this subject, Jira will create the configuration file that you can use for promote imports. If you select the checkbox, you should upload the existing configuration file.
- Select the adjacent button .
- Fill in the fields. Select the project where you want to import the issues, charge encoding character, delimiter, and date format .If the CSV file uses a different separator, specify the character in the Delimiter field rather of a comma. If the centrifuge is a tab, specify it as /t .
- Select the following clitoris .
- Map the fields in the CSV file to the issue fields in the selected stick out. If you want to map a specific field value in the CSV file to a specific Jira field value, select the Map field value checkbox.
You must map at least one field in the CSV file to the Jira Summary field because each Jira issue must have a drumhead. If, alternatively of the Jira discipline for map, you see the “ Don ’ thyroxine map this field ” note, it means that Jira can ’ deoxythymidine monophosphate provide the right map for the field from the CSV file. To solve this write out, see Missing fields for mapping when importing issues through CSV in Jira .
- Select the Next clitoris .
- If you selected the Map field value checkbox for some fields, you should map the values of these fields from the CSV file to the specific values of corresponding Jira issue fields. For example, you may want to map the CSV field value “ Feature Request ” to the Jira issue type ’ s field measure “ New Feature ” .
- If you want to check your shape for errors or warnings before running the import, choose Validate. If needed, you can download the detail log of the establishment.
- If needed, save the configuration for far use. For model, you may want to use the same field or value mappings for the adjacent imports .
- Select Begin Import when you ’ ra [ ms1 ] [ DS2 ] certain of the shape .
You ’ ve successfully bulk-imported your issues to Jira ! If you have any questions or problems, contact Atlassian corroborate. If you ’ re a Jira Administrator, we recommend using the External system meaning to avoid inconsistencies and errors .