JMESPath is a query language for JSON. Examples and a JMESPath tutorial can be found at the JMESPath site. It is used by the field code Action response details and the JWT parser function getFromJSON().
We describe how to get data from JSON objects which are returned as response from an action in after sending a REST request defined by the Atlassian Jira REST API.
How to work with JMESPath in general
We introduce the main search terms that allow you to extract the relevant information from a response. For more complex ones, please have a look at the JMESPath specification.
you can access the values as described in the table below.
|
What to get |
JMESPath |
Example |
|||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Attributes on the first level |
Use the name of the attribute. |
|
|||||||||||||||||||||||||||
|
Attributes on a lower JSON level |
Use the path to this attribute. |
|
|||||||||||||||||||||||||||
|
Access a certain element of a list attribute |
Use the index of the list |
|
|||||||||||||||||||||||||||
|
Get attributes of all list elements |
Use the * instead of an index and add the attribute name/path |
|
|||||||||||||||||||||||||||
|
Get a certain attribute of all elements and all level |
Use
|
|
|||||||||||||||||||||||||||
|
Filter data |
Add a comparison as index for an array |
|
|||||||||||||||||||||||||||
|
Compose new JSON out of the existing one |
Add the structure of the new JSON |
|
|||||||||||||||||||||||||||
|
Attribute is not available |
If an attribute/path is entered which does not exist in the JSON, null is returned |
|
How to work with JMESPath in JWT expressions
JMESPath is used by the field code Action response details and the parser function getFromJSON().
Syntactic rules
Escaping certain characters
When used in Action response details, the curly brackets have to be escaped:
|
character |
escaped character |
|---|---|
|
{ |
\{ |
|
} |
\} |
Example:
%{action.response.listWithComplexJSON[].\{"fullname":name.last\}}
When used in getFromJSON(), the quote has to be escaped
|
character |
escaped character |
|---|---|
|
" |
\" |
Example:
The custom field with the custom ID 10010 holds the value
"listWithComplexJSON": [
{
"key": "1",
"name": {
"first": [
"Tom",
"Bob"
],
"last": "Miller"
}
},
{
"key": "2",
"name": {
"first": [
"John",
"Jane"
],
"last": "Doe"
}
}
]
%{getFromJSON(%{issue.cf10010},"listWithComplexJSON[].{\"fullname\":name.last}")}
Parser expressions in JMESPath
You cannot use JWT field codes or parser expressions in JMESPath itself.
Conversion from JSON types to string
They always return a text, e.g. the boolean value true will be converted to the string value true, an array with elements of a flat data type (e.g. number) will be a comma separated string of the array elements. The null value is represented as an empty text.
If the result is not
-
null
-
boolean
-
string
-
number
but a JSON object itself, this JSON object will be converted to a text with JSON.stringify
The same is done if an array does not hold flat values but JSON objects.
These results may be stored in a custom field and being read with the new parser function getFromJSON() in a different post function.
Cast the text results
In case the result is not a text but e.g. a number or an array, you can cast it using the known functions from the parser like toNumber() or toStringList() and used as input for other parser functions or to set a field in post function like Create issue.
|
JWT parser expression |
Result |
Note |
|---|---|---|
|
|
v2,v5 |
|
|
|
v2 |
This is equivalent to |
|
|
21 |
|
How to use JMESPath for a Jira REST API response
The following JSON is an excerpt of the response returned by a GET /rest/api/3/issue call for issue PU-670
The following table using the field code Action response details.
|
What to get |
JMESPath |
Result |
|---|---|---|
|
Issue key |
|
PU-670 |
|
Display name of the creator |
|
Who am I |
|
Atlassian account Id from a single user picker custom field |
|
5fb3d09bf8b01200694cffb1 |
|
Get all labels |
|
Backend,Frontend |
|
Get the second label |
|
Frontend |
|
Get all sub-tasks |
|
|
|
Get the first sub-task |
|
|
|
Get the names of all fix versions |
|
v2,v5 |
|
Get the keys of all linked issues |
|
PU-684, PU-685, PU-677 The second * eases the access to all linked issues, independent of the direction (
|
|
Filter the sub-tasks by their issuetype and return the sub-task's summary and the status |
|
|