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.

(warning) 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.

On this page:

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".

JSON File Example
{
    "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.

Bundled Custom Fields List
  1. com.atlassian.jira.plugin.system.customfieldtypes:textfield

  2. com.atlassian.jira.plugin.system.customfieldtypes:textarea

  3. com.atlassian.jira.plugin.system.customfieldtypes:datepicker

  4. com.atlassian.jira.plugin.system.customfieldtypes:datetime

  5. com.atlassian.jira.plugin.system.customfieldtypes:float

  6. com.atlassian.jira.plugin.system.customfieldtypes:select

  7. com.atlassian.jira.plugin.system.customfieldtypes:radiobuttons

  8. com.atlassian.jira.plugin.system.customfieldtypes:project

  9. com.atlassian.jira.plugin.system.customfieldtypes:multiversion

  10. com.atlassian.jira.plugin.system.customfieldtypes:version

  11. com.atlassian.jira.plugin.system.customfieldtypes:userpicker

  12. com.atlassian.jira.plugin.system.customfieldtypes:url

  13. com.atlassian.jira.plugin.system.customfieldtypes:multiselect

  14. com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes

  15. com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker

  16. com.atlassian.jira.plugin.system.customfieldtypes:multigrouppicker

  17. com.atlassian.jira.plugin.system.customfieldtypes:grouppicker

  18. com.atlassian.jira.plugin.system.customfieldtypes:cascadingselect

  19. com.atlassian.jira.plugin.system.customfieldtypes:readonlyfield

  20. com.atlassian.jira.plugin.system.customfieldtypes:labels

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.

Custom Field Example
 "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 FieldNotesExample
UsersThis 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
"users": [ 
	{
        "name" : "someuser",
        "groups" : [ "jira-users", "my-custom-group" ],
        "active" : true,
        "email" : "user1@example.com",
        "fullname" : "User 1"
	}
]
VersionTo 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
 "versions": [
          {
              "name": "version_1"
          }
      ],
Project Key and Issue KeyYou 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
{
    "projects": [
        {
            "name": "Sample data",
            "key": "SAM",
			"type": "software",
            "issues": [
                {
					"key" : "SAM-123",
                    "status" : "Open",
                    "reporter" : "admin",
                    "summary" : "Parent case",
                    "externalId": "123"
                }
            ]
        }
    ]
}
CommentsThis example shows how you can import multiple comments for an issue.
Comment Example
{
    "projects": [
        {
            "name": "Sample data",
            "key": "SAM",
            "issues": [
                {
                    "status" : "Open",
                    "reporter" : "admin",
                    "summary" : "Parent case",
                    "externalId": "1",
                    "comments": [
                        {
                            "body": "This is a comment from admin 5 days ago",
                            "author": "admin",
                            "created": "2012-08-31T17:59:02.161+0100"
                        },
                        {
                            "body": "This is a comment from admin 1 day ago",
                            "author": "admin",
                            "created": "2012-08-31T17:59:02.161+0100"
                        }
                    ]
                }
            ]
        }
    ]
}

Worklogs

This example shows the syntax to import worklog detail.
Worklog Example
"worklogs": [
        {
            "author": "admin",
            "comment": "Worklog",
            "startDate": "2012-08-31T17:59:02.161+0100",
            "timeSpent": "PT1M"
        },
        {
            "author": "admin",
            "startDate": "2012-08-31T17:59:02.161+0100",
            "timeSpent": "PT3H"
        }
    ]
ComponentComponents 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
            "components": [
                "Component", //Component specified only by name
                { // Component specified by object
                    "name": "SomeName",
                    "lead": "admin",
                    "description": "Some description"
                }
            ],
Issues with Time TrackingTime 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
            "issues": [
                {
                    "summary" : "My Example Time Tracking issue",
                    "externalId": "1",
                    "originalEstimate": "P1W3D",
                    "timeSpent": "PT4H",
                    "estimate": "P2D",
                    "worklogs": [
                        {
                            "author": "admin",
                            "comment": "Worklog",
                            "startDate": "P-1D", //can be a Period or DateTime
                            "timeSpent": "PT1M"
                        },
                        {
                            "author": "admin",
                            "startDate": "2014-01-14T17:00:00.000+0100",
                            "timeSpent": "PT3H"
                        }
                    ]
                }
            ]

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.

  1. Log in to Jira as a user with the Jira Administrators global permission.
  2. Choose Administration () > System. Select Import & Export > External System Import to open the Import external projects page.
  3. Select JSON to open the JSON File import page.
  4. Upload your JSON file.
  5. 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.

(info) 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.

Known issues:

Problems importing attachments with Chinese/Japanese/Korean characters

It's been reported that when attachments contain characters issues get created without these attachments. See JRASERVER-64674.

Last modified on Sep 29, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.