Discover Jira Cloud products
Learn more about Jira Cloud products, features, plans, and migration.
Import data from JSON
The JSON import feature allows you to import issues from external issue trackers that cannot be exported to CSV files. 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.
Recommended data size
When importing large projects, we recommend splitting your data to reduce performance concerns and ensure the optimal speed of the import.
Recommended number of issues per file | 1500 issues |
|---|---|
Estimated time to import | Approximately 1 hour (This would also depend on the size and complexity of your data and setup) |
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
// JSON File Example
{
"users": [
{
"name": "abcde-12345-fedcba"
},
{
"name": "edcba-12345-abcdef"
}
],
"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": "abcde-12345-fedcba",
"labels": [
"impossible",
"to",
"test"
],
"watchers": [
"abcde-12345-fedcba"
],
"issueType": "Bug",
"resolution": "Resolved",
"created": "2012-08-31T17:59:02.161+0100",
"updated": "2012-08-31T17:59:02.161+0100",
"affectedVersions": [
"1.0"
],
"summary": "My chore for today",
"assignee": "abcde-12345-fedcba",
"fixedVersions": [
"1.0",
"2.0"
],
"components": [
"Component",
"AnotherComponent"
],
"externalId": "1",
"history": [
{
"author": "abcde-12345-fedcba",
"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": "bob@example.com",
"created": "2012-08-31T17:59:02.161+0100",
"uri": "http://optimus-prime/~batman/images/battarang.jpg",
"description": "This is optimus prime"
}
]
},
{
"status": "Open",
"reporter": "abcde-12345-fedcba",
"issueType": "Sub-task",
"created": "P-3D",
"updated": "P-1D",
"summary": "Sub-task",
"externalId": "2"
},
{
"status": "Closed",
"reporter": "abcde-12345-fedcba",
"issueType": "Sub-task",
"created": "P-3D",
"updated": "P-1D",
"resolution": "Duplicate",
"summary": "Duplicate Sub-task",
"externalId": "3"
}
]
}
]
}To specify a fix version for an imported issue, make sure you include the fixVersions in the issues object and versions in the projects object, and shown is the example above.
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.
com.atlassian.jira.plugin.system.customfieldtypes:textfield
com.atlassian.jira.plugin.system.customfieldtypes:textarea
com.atlassian.jira.plugin.system.customfieldtypes:datepicker
com.atlassian.jira.plugin.system.customfieldtypes:datetime
com.atlassian.jira.plugin.system.customfieldtypes:float
com.atlassian.jira.plugin.system.customfieldtypes:select
com.atlassian.jira.plugin.system.customfieldtypes:radiobuttons
com.atlassian.jira.plugin.system.customfieldtypes:project
com.atlassian.jira.plugin.system.customfieldtypes:multiversion
com.atlassian.jira.plugin.system.customfieldtypes:version
com.atlassian.jira.plugin.system.customfieldtypes:userpicker
com.atlassian.jira.plugin.system.customfieldtypes:url
com.atlassian.jira.plugin.system.customfieldtypes:multiselect
com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes
com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker
com.atlassian.jira.plugin.system.customfieldtypes:multigrouppicker
com.atlassian.jira.plugin.system.customfieldtypes:grouppicker
com.atlassian.jira.plugin.system.customfieldtypes:cascadingselect
com.atlassian.jira.plugin.system.customfieldtypes:readonlyfield
com.atlassian.jira.plugin.system.customfieldtypes:labels
com.pyxis.greenhopper.jira:gh-sprint
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
Custom field example
"customFieldValues": [
//Custom fields which accept 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 accept 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 (cascading select fields):
{
"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:
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
User example
"users": [
{
"name" : "abcde-12345-fedcba",
"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".
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Project key and issue key example
{
"projects": [
{
"name": "Sample data",
"key": "SAM",
"issues": [
{
"key" : "SAM-123",
"status" : "Open",
"reporter" : "abcde-12345-fedcba",
"summary" : "Parent case",
"externalId": "123"
}
]
}
]
}
Comments
This example shows how you can import multiple comments for an issue.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
Comment example
{
"projects": [
{
"name": "Sample data",
"key": "SAM",
"issues": [
{
"status" : "Open",
"reporter" : "abcde-12345-fedcba",
"summary" : "Parent case",
"externalId": "1",
"comments": [
{
"body": "This is a comment from admin 5 days ago",
"author": "abcde-12345-fedcba",
"created": "2012-08-31T17:59:02.161+0100"
},
{
"body": "This is a comment from admin 1 day ago",
"author": "abcde-12345-fedcba",
"created": "2012-08-31T17:59:02.161+0100"
}
]
}
]
}
]
}
This example shows how to import public comment visibility specifically for Jira Service Management projects.
1
2
3
4
5
6
7
8
9
10
11
12
"comments": [
{
"body": "This public comment",
"author": "557057:1a8aeee5-40e9-413a-9f4e-2f074f09644a",
"created": "2012-08-31T17:59:02.161+0100",
"updated": "2012-08-31T17:59:02.161+0100",
"properties":[{"key":"sd.public.comment","value":{"internal":"false"}}]
}
]
This example shows how to import private comment visibility specifically for Jira Service Management projects.
1
2
3
4
5
6
7
8
9
10
11
"comments": [
{
"body": "This private comment",
"author": "557057:1a8aeee5-40e9-413a-9f4e-2f074f09644a",
"created": "2012-08-31T17:59:02.161+0100",
"updated": "2012-08-31T17:59:02.161+0100",
"properties":[{"key":"sd.public.comment","value":{"internal":"true"}}]
}
]
Worklogs
This example shows the syntax to import worklog detail.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Worklog example
"worklogs": [
{
"author": "abcde-12345-fedcba",
"comment": "Worklog",
"startDate": "2012-08-31T17:59:02.161+0100",
"timeSpent": "PT1M"
},
{
"author": "abcde-12345-fedcba",
"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".
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Component example
"components": [
"Component", //Component specified only by name
{ // Component specified by object
"name": "edcba-12345-abcdef",
"lead": "abcde-12345-fedcba",
"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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
Issues with time tracking
"issues": [
{
"summary" : "My Example Time Tracking issue",
"externalId": "1",
"originalEstimate": "P1W3D",
"timeSpent": "PT4H",
"estimate": "P2D",
"worklogs": [
{
"author": "abcde-12345-fedcba",
"comment": "Worklog",
"startDate": "P-1D", //can be a Period or DateTime
"timeSpent": "PT1M"
},
{
"author": "abcde-12345-fedcba",
"startDate": "2014-01-14T17:00:00.000+0100",
"timeSpent": "PT3H"
}
]
}
]
Sprint
In this example, a new sprint named "New Sprint" is created directly from the JSON file and added to the board with rapidViewId = 30. If the sprint is closed, include this data in the state parameter (optional). The sprint state may be one of:
• "FUTURE" (the default)
• "ACTIVE"
• "CLOSED"
When importing an active or closed sprint, it's required for the start and end dates to be present - representing the start time and planned completion time. For closed sprints, the completion date is also required.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
Sprint
{
"projects": [
{
"name": "Project",
"key": "KEY",
"issues": [
{
"externalId": "51",
"priority" : "High",
"description" : "Test JSON import",
"status" : "TO DO",
"reporter" : "abcde-12345-fedcba",
"issueType" : "Bug",
"summary" : "Test JSON import",
"customFieldValues": [
{
"fieldName": "Sprint",
"fieldType": "com.pyxis.greenhopper.jira:gh-sprint",
"value": [
{
"rapidViewId": 30,
"state": CLOSED",
"startDate": "2018-01-01",
"endDate": "2018-01-01",
"completeDate": "2018-01-01",
"name": "New Sprint"
}
]
}
]
}
]
}
]
}
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
Choose > System
Select External System Import and select JSON.
If you don’t see the JSON option, you might be in the new import experience. Select switch to the old experience to use the JSON file import wizard.
Choose your JSON file and click Begin Import.
If your JSON file consists of Jira Service Management projects with comments, all the comments from your import file will become public after the JSON import.
If you have a problem with the import (or you're just curious), select download a detailed log to view detailed information about the JSON file import process.
Was this helpful?
Still need help?
The Atlassian Community is here for you.