Importing data from JSON
Version 4.3 or later of the Jira Importers plugin, which is bundled with Jira, allows you to import data from a JavaScript Object Notation (JSON) file.
JSON files are easy to read and encapsulate more structure and information than CSV files.
The JSON import feature allows you to import issues from an external (issue tracking) system which can export its data in a JSON format.
You may also wish to prepare your JSON file manually.
Please note that the import format used by the Jira Importers plugin is more basic than the import format available when using the Jira REST API.
Creating a JSON file for Import
If your current issue tracking system is unable to export in the JSON format, you may wish to create the file manually. To prepare the JSON file, you should use the standard JSON format and follow the pattern detailed below. The field values in the following example are set with illustrative purpose only. Use data from your instance to prepare the JSON file.
If you want to create sub-tasks for custom sub-task links, use exactly the same name as provided in the following example: "name": "sub-task-link".
{
"users": [
{
"name": "alice",
"fullname": "Alice Foo"
},
{
"name": "bob",
"fullname": "Bob Bar"
}
],
"links": [
{
"name": "sub-task-link",
"sourceId": "2",
"destinationId": "1"
},
{
"name": "Duplicate",
"sourceId": "3",
"destinationId": "2"
}
],
"projects": [
{
"name": "A Sample Project",
"key": "ASM",
"type": "software",
"description": "JSON file description",
"versions": [
{
"name": "1.0",
"released": true,
"releaseDate": "2012-08-31T15:59:02.161+0100"
},
{
"name": "2.0"
}
],
"components": [
"Component",
"AnotherComponent"
],
"issues": [
{
"priority" : "Major",
"description" : "Some nice description here\nMaybe _italics_ or *bold*?",
"status" : "Closed",
"reporter" : "alice",
"labels" : [ "impossible", "to", "test" ],
"watchers" : [ "bob" ],
"issueType" : "Bug",
"resolution" : "Resolved",
"created" : "2012-08-31T17:59:02.161+0100",
"updated" : "P-1D",
"affectedVersions" : [ "1.0" ],
"summary" : "My chore for today",
"assignee" : "bob",
"fixedVersions" : [ "1.0", "2.0" ],
"components" : ["Component", "AnotherComponent"],
"externalId" : "1",
"history" : [
{
"author" : "alice",
"created": "2012-08-31T15:59:02.161+0100",
"items": [
{
"fieldType" : "jira",
"field" : "status",
"from" : "1",
"fromString" : "Open",
"to" : "5",
"toString" : "Resolved"
}
]
}
],
"customFieldValues": [
{
"fieldName": "Story Points",
"fieldType": "com.atlassian.jira.plugin.system.customfieldtypes:float",
"value": "15"
},
{
"fieldName": "Business Value",
"fieldType": "com.atlassian.jira.plugin.system.customfieldtypes:float",
"value": "34"
}
],
"attachments" : [
{
"name" : "battarang.jpg",
"attacher" : "admin",
"created" : "2012-08-31T17:59:02.161+0100",
"uri" : "http://optimus-prime/~batman/images/battarang.jpg",
"description" : "This is optimus prime"
}
]
},
{
"status" : "Open",
"reporter" : "bob",
"issueType": "Sub-task",
"created" : "P-3D",
"updated" : "P-1D",
"summary" : "Sub-task",
"externalId": "2"
},
{
"status" : "Closed",
"reporter" : "alice",
"issueType": "Sub-task",
"created" : "P-3D",
"updated" : "P-1D",
"resolution" : "Duplicate",
"summary" : "Duplicate Sub-task",
"externalId": "3"
}
]
}
]
}Custom Fields
The JSON Importers plugin supports custom fields. Below is a list of custom fields that come bundled with Jira. If you have installed any additional plugins that have custom fields, these fields will also be supported, however they are not included in this list.
The custom field example below shows some syntax for adding custom fields, including an example of a cascading custom field. If the custom field is not listed above, the "fieldType" can be obtained from the Custom Fields configuration page, by inspecting the source HTML. The "value" is specific to each custom field, and you can find this by inspecting the Edit Issue page's source HTML.
"customFieldValues": [
//Custom Fields which accepts single values:
{
"fieldName": "My Awesome Text Field (single line)",
"fieldType": "com.atlassian.jira.plugin.system.customfieldtypes:textfield",
"value": "some text"
},
{
"fieldName": "My Awesome Select List (single choice)",
"fieldType": "com.atlassian.jira.plugin.system.customfieldtypes:select",
"value": "some select"
},
//Custom Fields which accepts multiple values:
{
"fieldName": "My Awesome Checkboxes",
"fieldType": "com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes",
"value": [ "multiple", "checkboxes" ]
},
{
"fieldName": "My Awesome User Picker (multiple users)",
"fieldType": "com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker",
"value": [ "admin", "fred" ]
},
//Custom Fields which accepts Options in hierarchy. That's only cascading select from standard JIRA pool.
{
"fieldName": "My Awesome Select List (cascading)",
"fieldType": "com.atlassian.jira.plugin.system.customfieldtypes:cascadingselect",
"value":
{
"": "Parent Value",
"1": "Child Value"
}
}
]Specific JSON File Examples
Further specific JSON file examples include:
| Supported Field | Notes | Example |
|---|---|---|
| Users | This example covers a full user. In this example, two groups have been specified. If a group does not exist already, the Jira Importers plugin will create it. |
User Example
|
| Version | To import an issue and specify, for example, a fixVersion, this fixVersion needs to be defined in the JSON file. Even if the Version is already in JIRA it must also be specified in JSON under projects. |
Version
|
| Project Key and Issue Key | You can assign a key to both the project and the issue. These keys can be different. This example will create a project with one issue, "SAM-123". |
Project Key and Issue Key Example
|
| Comments | This example shows how you can import multiple comments for an issue. |
Comment Example
|
Worklogs | This example shows the syntax to import worklog detail. |
Worklog Example
|
| Component | Components can be specified in a JSON file in two ways, by providing a name, or by providing an object. This example shows both. The Jira Importers plugin will always create a new component with "Default Assignee" switched to "Project Default", as you are unable to specify a "Default Assignee". |
Component Example
|
| Issues with Time Tracking | Time Tracking detail can be imported with an issue. This example shows you an issue with Time Tracking detail. The "originalEstimate", "timeSpent", and "estimate" values must be in Period format (Format ISO_8601 - Durations). The "startDate" value accepts both the DateTime and Period format. Please ensure Time Tracking is enabled in Jira before you start your import, otherwise the data will be ignored by the Jira Importers plugin during the import. |
Issues with Time Tracking
|
| Import settings | To create a project role named "Developers" granted to all project leads and assignees in the imported file, set the If this parameter is set to another value or isn't included at all, the mechanism won't be triggered. |
ImportSettings example
|
Dates can be represented in SimpleDateFormat "yyyy-MM-dd'T'HH:mm:ss.SSSZ" (example output: "2012-08-31T15:59:02.161+0100") or you can use relative dates like "P-1D" (which means one day ago).
Running the JSON File Import Wizard
Before importing data from a JSON file, disable any Security Levels in the target project. Some restrictions might prevent successful issue import.
Before you begin, back up your Jira data.
- Log in to Jira as a user with the Jira Administrators global permission.
- Choose Administration (
) > System. Select Import & Export > External System Import to open the Import external projects page. - Select JSON to open the JSON File import page.
- Upload your JSON file.
- Select Begin Import when you are ready to begin importing your JSON file 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 just curious), click the download a detailed log link to view detailed information about the JSON file import process. This information can also be useful if you encounter any errors with your import.
Congratulations! You have successfully imported your JSON projects into Jira! If you have any questions or encounter any errors, please contact Atlassian support.