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:

  • JIRA does not provide a dedicated import tool for and
  • 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.

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",
            "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 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
"users": [ 
	{
        "name" : "someuser",
        "groups" : [ "jira-users", "my-custom-group" ],
        "active" : true,
        "email" : "user1@example.com",
        "fullname" : "User 1"
	}
]
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
{
    "projects": [
        {
            "name": "Sample data",
            "key": "SAM",
			"type": "software",
            "issues": [
                {
					"key" : "SAM-123",
                    "status" : "Open",
                    "reporter" : "admin",
                    "summary" : "Parent case",
                    "externalId": "123"
                }
            ]
        }
    ]
}
Comments This 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"
        }
    ]
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
            "components": [
                "Component", //Component specified only by name
                { // Component specified by object
                    "name": "SomeName",
                    "lead": "admin",
                    "description": "Some description"
                }
            ],
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
            "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 you begin, please back up your JIRA data.

  1. Log in to JIRA as a user with the JIRA Administrators global permission.
  2. Choose > 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. Choose your JSON file.
  5. Click the Begin Import button 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.

Last modified on Jul 13, 2017

Was this helpful?

Yes
No
Provide feedback about this article

Not finding the help you need?

Ask the community

Powered by Confluence and Scroll Viewport.