Integrations Hub for Jira allows custom variables that can be used when generating an integration request. Under the hood, we're using JSONPath and Mustache to extract and substitute variables for integration request.
It's currently possible to substitute the following:
- Request URL
- Request headers
- Request body
- Request Authorization
General usage
Variables are accessed by using the curly braces notation of Mustache.
{{variable_name}}
or for an object, the dot notated getter name without the "get".
Example: {{my_object.name}}
. For the value of the getName()
of the my_object
variable
Value variables (Primitives/Strings ie.)
{{variable}} - Substitutes the variable value
Objects
{{object_name.user.name}} - Substitutes the object_name getUser().getName() value
Collections
Iterate through lists using the following Mustache pattern:
{{#title}}{{.}}{{/title}}
See Manage Arrays for further info
Formatting dates
Date objects can be formatted by using the following syntax. {{#date}}{{#format}}java_date_format_pattern{{/format}}{{/date}}
Example:
{{#issue.updated}} {{#format}} yyyy-MM-dd {{/format}} {{/issue.updated}} - Will format issue updated date. (since v.3.8.0)
Quick Formats (since v 4.4.0)
{{now.yearMonthDay}} = YYYY-MM-DD
{{now.monthDayYear}} = MM/DD/YYYY
{{now.monthDayYear2}} = MM/DD/YY
{{now.dayMonthYear}} = DD-MM-YYYY
Default variables
Default variables that are available for every iHub integration request are:
Variable | Description |
---|---|
{{issue}} | The issue that triggered the request. (or was in context of the scheduled job). Note: Scheduled iHub integrations will only have an issue if an issue context scope has been defined. |
{{now}} |
|
{{baseUrl}} |
Upper case on "U" in baseUrl |
{{#comments.all}} | Get all comments for the issue Usage:
|
{{comments.latest}} | Get the latest comment object for an issue. Usage:
|
{{customfield_id}} | Get custom field name. example;
|
{{currentUser}} | Returns the current user as a ApplicationUser object |
Defining custom variables from a response
You may define any number of variables from the response of the parent iHub integration that will be available for usage within the child's variable scope.
Define custom variables by defining them in the variables section of the child action.
Set the variable name followed by the JSONPath expression.
See JSONPath for tutorials examples on how to define your JSON path for your use case
Automatic response variables
By choosing "Auto populate response variables
" the child action will automatically parse the response JSON and add top-level variables to the variable scope.
Example JSON response from parent action:
{ "gender": "male", "name": { "title": "mr", "first": "sal", "last": "van ballegooij" }, "location": { "street": "1978 predikherenstraat", "city": "oldenzaal", "state": "groningen", "postcode": 32432, "coordinates": { "latitude": "46.8524", "longitude": "-179.9888" }, "timezone": { "offset": "+5:00", "description": "Ekaterinburg, Islamabad, Karachi, Tashkent" } } }
Will result in the following variables being available:
{{gender}} - The String "male" in this case
{{name}} - An object, use "." notation to drill down. Ie. {{name.title}} for "mr"
{{location}} - An object, use "." notation to drill down. Ie. {{location.coordinates.latitude}} for "46.8524"
Issue object
You may access the issue object by using the {{issue}}
variable notation followed by the getter that you would like to retrieve.
Variable | Description |
---|---|
{{issue.summary }} | returns the issue summary |
{{issue .key}} | returns the issue key |
{{issue .type }} | returns issue type |
{{issue .assignee }} | returns the assignee. Chain the notation with {{issue.assignee.name}} for the assignee name. |
{{issue .reporter }} | returns the reporter |
{{issue .watchers }} | returns a list of watchers such as: ["user1","user2"] |
{{issue .affectsversion }} | returns the affects version |
{{issue .fixversion }} | returns the fix version |
{{issue .components }} | returns the components |
{{issue .labels }} | returns the labels |
{{issue .resolution }} | returns the resolution |
{{issue .attachments }} | returns the attachment |
{{issue .comments }} | returns the comments. See working with collections on how to iterate this |
{{issue .worklog }} | returns the worklog |
{{issue .votes }} | returns the issue votes |
{{issue .due }} | returns the issue due date |
{{issue .description }} | returns issue description |
{{issue .priority }} | returns the priority of the issue |
{{issue .created }} | returns the created date of the issue |
{{issue .updated }} | returns the updated date of the issue |
{{issue .status }} | returns the status of the issue |
{{issue. customfield_xxxxx }} | returns the value of the custom field. example {{issue. customfield_10100 }} |
Parent object
{{parent.name}} | Name of the parent action |
{{parent.id}} | Id of the parent action |
{{parent.url}} | URL of the parent action |
{{parent.method}} | method of the parent action |
{{parent.description}} | description of the parent action |
Using variables
Use the variable in an URL
Template URL: https://my_jira_instance_url/rest/api/2/issue/{{issue.key}}/comment
If operated on an issue with the key "QWERY-123" this will be evaluated as
https://my_jira_instance_url/rest/api/2/issue/QWERTY-123/comment
More variables
Groovy variables enable more complex mapping of data. It could be that status or date needs to be mapped to other values.
Available scopes
The groovy script has the following objects / variables available
Variable name | Description | Note |
---|---|---|
issue | the current issue that the call is operating on | |
response | the parent response from the previous runned call as String | |
jsonSlurper | Does not work with Groovy 3.0.7 and OpenJDK 64bit 11.0.13+8 (https://issues.apache.org/jira/browse/GROOVY-9802 ) | |
jsonOutput | Does not work with Groovy 3.0.7 and OpenJDK 64bit 11.0.13+8 (https://issues.apache.org/jira/browse/GROOVY-9802 ) | |
scope | all previous defined variables or responses Example if call A get then call C and c wants to access name it can do so by using scope.name |
Common Error
Exception in your groovy code java.lang.RuntimeException: Unable to load FastStringService
Workaround
Workaround is to use ObjectMapper instead of JSON Slurper
Parse JSON
import com.fasterxml.jackson.databind.ObjectMapper ObjectMapper mapper = new ObjectMapper() //response is passed in from the parent action def myRespnse = mapper.readValue(response, HashMap.class)
Produce JSON
def myList = [] myList.add([email:issue.reporter.emailAddress]) return mapper.writeValueAsString(myList)
See examples
Static variables are used to remove repeated work and enable the reuse of values.
For instance, it is convenient to add a variable to the URL of a system to make fewer typing and changes.
It can also be used to store keys for systems that do not have support for any of our Credentials.