This resource represents JQL search auto-complete details. Use it to obtain JQL search auto-complete data and suggestions for use in programmatic construction of queries or custom query builders. It also provides operations to:
Returns reference data for JQL searches. This is a downloadable version of the documentation provided in Advanced searching - fields reference and Advanced searching - functions reference, along with a list of JQL-reserved words. Use this information to assist with the programmatic creation of JQL queries or the validation of queries built in a custom query builder.
To filter visible field details by project or collapse non-unique fields by field type then Get field reference data (POST) can be used.
This operation can be accessed anonymously.
Permissions required: None.
read:jira-workread:field:jiraConnect app scope required: READ
This request has no parameters.
Returned if the request is successful.
Lists of JQL reference data.
1
2
3
4
5
6
7
8
9
10
11
12
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
const response = await api.asUser().requestJira(route`/rest/api/3/jql/autocompletedata`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());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
{
"jqlReservedWords": [
"empty",
"and",
"or",
"in",
"distinct"
],
"visibleFieldNames": [
{
"displayName": "summary",
"operators": [
"~",
"!~",
"is",
"is not"
],
"orderable": "true",
"searchable": "true",
"types": [
"java.lang.String"
],
"value": "summary"
},
{
"auto": "true",
"cfid": "cf[10880]",
"displayName": "Sprint - cf[10880]",
"operators": [
"=",
"!=",
"in",
"not in",
"is",
"is not"
],
"orderable": "true",
"searchable": "true",
"types": [
"com.atlassian.greenhopper.service.sprint.Sprint"
],
"value": "Sprint"
}
],
"visibleFunctionNames": [
{
"displayName": "standardIssueTypes()",
"isList": "true",
"types": [
"com.atlassian.jira.issue.issuetype.IssueType"
],
"value": "standardIssueTypes()"
},
{
"displayName": "issuesWithText()",
"supportsListAndSingleValueOperators": "true",
"types": [
"com.atlassian.jira.issue.issuetype.IssueType"
],
"value": "issuesWithText()"
}
]
}Returns reference data for JQL searches. This is a downloadable version of the documentation provided in Advanced searching - fields reference and Advanced searching - functions reference, along with a list of JQL-reserved words. Use this information to assist with the programmatic creation of JQL queries or the validation of queries built in a custom query builder.
This operation can filter the custom fields returned by project. Invalid project IDs in projectIds are ignored. System fields are always returned.
It can also return the collapsed field for custom fields. Collapsed fields enable searches to be performed across all fields with the same name and of the same field type. For example, the collapsed field Component - Component[Dropdown] enables dropdown fields Component - cf[10061] and Component - cf[10062] to be searched simultaneously.
Permissions required: None.
read:jira-workread:field:jiraConnect app scope required: READ
boolean
array<integer>
Returned if the request is successful.
Lists of JQL reference data.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"includeCollapsedFields": true,
"projectIds": [
10000,
10001,
10002
]
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/jql/autocompletedata`, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());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
{
"jqlReservedWords": [
"empty",
"and",
"or",
"in",
"distinct"
],
"visibleFieldNames": [
{
"displayName": "summary",
"operators": [
"~",
"!~",
"is",
"is not"
],
"orderable": "true",
"searchable": "true",
"types": [
"java.lang.String"
],
"value": "summary"
},
{
"auto": "true",
"cfid": "cf[10061]",
"displayName": "Component - cf[10061]",
"operators": [
"=",
"!=",
"in",
"not in",
"is",
"is not"
],
"orderable": "true",
"types": [
"com.atlassian.jira.issue.customfields.option.Option"
],
"value": "cf[10061]"
},
{
"auto": "true",
"cfid": "cf[10062]",
"displayName": "Component - cf[10062]",
"operators": [
"=",
"!=",
"in",
"not in",
"is",
"is not"
],
"orderable": "true",
"types": [
"com.atlassian.jira.issue.customfields.option.Option"
],
"value": "cf[10062]"
},
{
"auto": "true",
"displayName": "Component - Component[Dropdown]",
"operators": [
"=",
"!=",
"in",
"not in",
"is",
"is not"
],
"searchable": "true",
"types": [
"com.atlassian.jira.issue.customfields.option.Option"
],
"value": "\"Component[Dropdown]\""
}
],
"visibleFunctionNames": [
{
"displayName": "standardIssueTypes()",
"isList": "true",
"types": [
"com.atlassian.jira.issue.issuetype.IssueType"
],
"value": "standardIssueTypes()"
}
]
}Returns the JQL search auto complete suggestions for a field.
Suggestions can be obtained by providing:
fieldName to get a list of all values for the field.fieldName and fieldValue to get a list of values containing the text in fieldValue.fieldName and predicateName to get a list of all predicate values for the field.fieldName, predicateName, and predicateValue to get a list of predicate values containing the text in predicateValue.This operation can be accessed anonymously.
Permissions required: None.
read:jira-workread:issue-details:jiraConnect app scope required: READ
string
string
string
string
Returned if the request is successful.
The results from a JQL query.
1
2
3
4
5
6
7
8
9
10
11
12
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
const response = await api.asUser().requestJira(route`/rest/api/3/jql/autocompletedata/suggestions?fieldName=reporter`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"results": [
{
"displayName": "<b>Ac</b>tiveObjects (AO)",
"value": "ActiveObjects"
},
{
"displayName": "Atlassian Connect (<b>AC</b>)",
"value": "Atlassian Connect"
},
{
"displayName": "Atlassian Connect in Jira (<b>AC</b>JIRA)",
"value": "Atlassian Connect in Jira"
}
]
}Parses and validates JQL queries.
Validation is performed in context of the current user.
This operation can be accessed anonymously.
Permissions required: None.
read:jira-workread:field:jira, validate:jql:jira, read:jql:jiraConnect app scope required: READ
string
Requiredarray<string>
RequiredReturned if the request is successful.
A list of parsed JQL queries.
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
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"queries": [
"summary ~ test AND (labels in (urgent, blocker) OR lastCommentedBy = currentUser()) AND status CHANGED AFTER startOfMonth(-1M) ORDER BY updated DESC",
"issue.property[\"spaces here\"].value in (\"Service requests\", Incidents)",
"invalid query",
"summary = test",
"summary in test",
"project = INVALID",
"universe = 42"
]
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/jql/parse?validation={validation}`, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
{
"queries": [
{
"query": "summary ~ test AND (labels in (urgent, blocker) OR lastCommentedBy = currentUser()) AND status CHANGED AFTER -5d ORDER BY updated DESC",
"structure": {
"orderBy": {
"fields": [
{
"direction": "desc",
"field": {
"encodedName": "updated",
"name": "updated"
}
}
]
},
"where": {
"clauses": [
{
"field": {
"encodedName": "summary",
"name": "summary"
},
"operand": {
"encodedValue": "test",
"value": "test"
},
"operator": "~"
},
{
"clauses": [
{
"field": {
"encodedName": "labels",
"name": "labels"
},
"operand": {
"encodedOperand": "urgent, blocker)",
"values": [
{
"encodedValue": "urgent",
"value": "urgent"
},
{
"encodedValue": "blocker",
"value": "blocker"
}
]
},
"operator": "in"
},
{
"field": {
"encodedName": "lastCommentedBy",
"name": "lastCommentedBy",
"property": [
{
"entity": "issue",
"key": "propertyKey",
"path": "path.in.property",
"type": "user"
}
]
},
"operand": {
"arguments": [],
"encodedOperand": "currentUser()",
"function": "currentUser"
},
"operator": "="
}
],
"operator": "or"
},
{
"field": {
"encodedName": "status",
"name": "status"
},
"operator": "changed",
"predicates": [
{
"operand": {
"arguments": [
"-1M"
],
"encodedOperand": "startOfMonth(-1M)",
"function": "startOfMonth"
},
"operator": "after"
}
]
}
],
"operator": "and"
}
}
},
{
"query": "issue.property[\"spaces here\"].value in (\"Service requests\", Incidents)",
"structure": {
"where": {
"field": {
"encodedName": "issue.property[\"spaces here\"].value",
"name": "issue.property[spaces here].value",
"property": [
{
"entity": "issue",
"key": "spaces here",
"path": "value"
}
]
},
"operand": {
"encodedOperand": "(\"Service requests\", Incidents)",
"values": [
{
"encodedValue": "\"Service requests\"",
"value": "Service requests"
},
{
"encodedValue": "Incidents",
"value": "Incidents"
}
]
},
"operator": "in"
}
}
},
{
"errors": [
"Error in the JQL Query: Expecting operator but got 'query'. The valid operators are '=', '!=', '<', '>', '<=', '>=', '~', '!~', 'IN', 'NOT IN', 'IS' and 'IS NOT'. (line 1, character 9)"
],
"query": "invalid query"
},
{
"errors": [
"The operator '=' is not supported by the 'summary' field."
],
"query": "summary = test"
},
{
"errors": [
"Operator 'in' does not support the non-list value '\"test\"' for field 'summary'."
],
"query": "summary in test"
},
{
"errors": [
"The value 'INVALID' does not exist for the field 'project'."
],
"query": "project = INVALID"
},
{
"errors": [
"Field 'universe' does not exist or you do not have permission to view it."
],
"query": "universe = 42"
}
]
}Converts one or more JQL queries with user identifiers (username or user key) to equivalent JQL queries with account IDs.
You may wish to use this operation if your system stores JQL queries and you want to make them GDPR-compliant. For more information about GDPR-related changes, see the migration guide.
Permissions required: Permission to access Jira.
read:jira-userread:user:jira, read:jql:jira, validate:jql:jiraConnect app scope required: READ
array<string>
Returned if the request is successful. Note that the JQL queries are returned in the same order that they were passed.
The converted JQL queries.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"queryStrings": [
"assignee = mia",
"issuetype = Bug AND assignee in (mia) AND reporter in (alana) order by lastViewed DESC"
]
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/jql/pdcleaner`, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
7
8
9
10
11
{
"queriesWithUnknownUsers": [
{
"convertedQuery": "assignee = unknown",
"originalQuery": "assignee = mia"
}
],
"queryStrings": [
"issuetype = Bug AND assignee in (abcde-12345) AND reporter in (abc551-c4e99) order by lastViewed DESC"
]
}Sanitizes one or more JQL queries by converting readable details into IDs where a user doesn't have permission to view the entity.
For example, if the query contains the clause project = 'Secret project', and a user does not have browse permission for the project "Secret project", the sanitized query replaces the clause with project = 12345" (where 12345 is the ID of the project). If a user has the required permission, the clause is not sanitized. If the account ID is null, sanitizing is performed for an anonymous user.
Note that sanitization doesn't make the queries GDPR-compliant, because it doesn't remove user identifiers (username or user key). If you need to make queries GDPR-compliant, use Convert user identifiers to account IDs in JQL queries.
Before sanitization each JQL query is parsed. The queries are returned in the same order that they were passed.
Permissions required: Administer Jira global permission.
manage:jira-configurationread:jql:jiraConnect app scope required: ADMIN
array<JqlQueryToSanitize>
RequiredReturned if the request is successful.
The sanitized JQL queries for the given account IDs.
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
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"queries": [
{
"query": "project = 'Sample project'"
},
{
"accountId": "5b10ac8d82e05b22cc7d4ef5",
"query": "project = 'Sample project'"
},
{
"accountId": "cda2aa1395ac195d951b3387",
"query": "project = 'Sample project'"
},
{
"accountId": "5b10ac8d82e05b22cc7d4ef5",
"query": "invalid query"
}
]
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/jql/sanitize`, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());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
{
"queries": [
{
"initialQuery": "project = 'Sample project'",
"sanitizedQuery": "project = 12345"
},
{
"initialQuery": "project = 'Sample project'",
"sanitizedQuery": "project = 'Sample project'",
"accountId": "5b10ac8d82e05b22cc7d4ef5"
},
{
"initialQuery": "project = 'Sample project'",
"sanitizedQuery": "project = 12345",
"accountId": "cda2aa1395ac195d951b3387"
},
{
"initialQuery": "non-parsable query",
"errors": {
"errorMessages": [
"Error in the JQL Query: Expecting operator but got 'query'. The valid operators are '=', '!=', '<', '>', '<=', '>=', '~', '!~', 'IN', 'NOT IN', 'IS' and 'IS NOT'. (line 1, character 9)"
],
"errors": {}
},
"accountId": "5b10ac8d82e05b22cc7d4ef5"
}
]
}Rate this page: