Not all fields are born equal - some are born with extra abilities.
When a rule is run, you want to be able to customize your rule and components depending on what triggered the rule and what components have run previously. To do this we use Smart Fields - fields that can substitute in values at rule execution time. For example, to send an email to the reporter of the issue just created or substitute the initiator's user key into a comment action. e.g. "This issue was updated by {{initiator.displayName}}".
What is the format?
We use the mustache library to do our smart substitutions. We used this for security reasons as it wont allow for arbitrary code execution. The downside is that the syntax can sometimes be a little awkward. To make a substitution you need to wrap the value in "double curly braces". E.g. {{somevalue}}
To reference child elements you simply use a dot. E.g. {{issue.key}}
To iterate over a list you have use {{#issue.versions}}{{name}}{{/}}
For a more in depth guide to mustache refer the mustache user manual.
Working with dates
We have power functions to manipulate and format dates - date formatting, manipulation and timezones.
Working with strings
We have also added some extra functionality for string manipulation.
Math and working with numbers
We have the ability to perform math functions - Math functions
What fields are smart?
Most actions/conditions have at least one field that is smart and we label them in the interface (most of the time). For a complete list of Smart Fields - please refer to the Component Library Documentation.
How do I escape values?
Be default values are not encoded, but don't worry, this doesn't allow for any evil doing. I.e. If an issue has a status of "Waiting for R&D" and I render it in a smart value - {{issue.status.name}}, it will appear as "Waiting for R&D".
If you do need to encode values there is a built-in function - "htmlEncode". I.e. {{#htmlEncode}}{{issue.status.name}}{{/}} will render as "Waiting for R&D"
How do I access issue custom fields?
Traditionally to access custom fields you would need to use the following syntax - {{issue.customfield_10001}}
We have added some sugar for accessing custom field values on issues to make it easier. Simply use the name - {{issue.My custom Field}}
If the field is an object, you will need reference the value with in it. E.g. if it is a User custom field you will need to do - {{issue.My user field.displayName}}
The values are case insensitive and you can replace spaces with underscores. If there are multiple custom fields with same name or the same name as a system field, you will need to use the longer syntax.
Field names are translated using your rule actor's language setting. If you are using smart-value field names for translated custom fields in your smart-values, then please use the language set for your rule actor user!
If you want to access time tracking fields or work with more advanced issue edits, see the page on advanced fields.
How do I set user fields using smart values?
User fields accept the "name" (username) property of a user. To access this is available on user values via the .name property. So for example if you wanted to copy the reporter to another user field you would use
{{issue.reporter.name}}
In the advanced block section you would use
{
"fields": {
"My User Custom Field": { "name": "{{issue.reporter.name}}"}
}
}
What values can I use?
| Value | What adds it | What is it | Example |
|---|---|---|---|
| issue | Most JIRA Triggers | The active issue. e.g. the issue created/edited. These have the shape defined by JIRA's REST interface (see the JSON example). You can access fields like issue type, status and cutomfields through the dot notation. | {{issue.key}} |
| issues | Triggers that run a JQL search (e.g. Scheduled or Webhook) or otherwise gather multiple issues | The list of issues returned by trigger, each in the same form as single issues. See below for how to work with lists. | {{#issues}}{{.}}{{/}} |
| issue.comments | This is added any time an issue is added | The list of comments for the issue. | {{#issue.comments}}{{body}}{{/}} |
| issue.parent | This is added any time an issue is added | If this issue is a sub-task, then parent refers to the parent issue. You can access all fields of the parent. | {{issue.parent.key}} {{issue.parent.priority.name}} {{issue.parent.Epic Link}} {{issue.parent.epic.summary}} |
| issue.properties | This is added any time an issue is added | Here you can access any issue property. Properties are frequently used by add-ons and integrations to store values. | {{issue.properties.some.value}} |
| issue.epic | This is added any time an issue is added | If this issue is in an Epic, then epic refers to the Epic issue. You can access all fields of the Epic. | {{issue.epic.key}} {{issue.epic.status.name}} {{issue.epic.My Custom Field}} |
| issue.latest | This is added any time an issue is added | This refetches the latest state of the issue from JIRA. In generally this should not be used since it requires an expensive reload of issue data. The only situation where this is necessary, is where subsequent actions need to have visibility of the latest state of the issue (e.g. 2 edit issue actions that need to 'add' to the value of a field instead of overwriting it). | {{issue.latest.description}} |
| issue.security.name | This is added any time an issue is added | The text of the security level | {{issue.security.name}} {{issue.security.id}} |
| triggerIssue | The Related Issues Action | The refers to the original issue when you branch the chain. | {{triggerIssue.description}} ... all fields available to {{issue}} are available as well |
| reporter | Most JIRA Triggers | The reporter of the active issue | {{reporter.displayName}} |
| assignee | Most JIRA Triggers | The assignee of the active issue | {{assignee.displayName}} ... (same as reporter) |
| initiator | Most Triggers | The user who performed the action that triggered the rule | {{initiator.displayName}} ... (same as reporter) |
| comment | JIRA Triggers that contain a comment E.g. Transition issue | The comment associated with an trigger | {{comment.body}} |
| comment.properties | Accessible for all comments | Here you can access any comment property. Properties are frequently used by add-ons and integrations to store values. | {{comment.properties."sd.public.comment".internal}} |
| changelog | JIRA Triggers that edit an issue | All the fields that where changed. Each field is a list of changes. | {{#changelog.summary}}{{toString}}{{/}} |
| webhookData | Webhook Trigger | The body of the Webhook request | {{webhookData.someValue.childValue}} |
| createdIssues | Clone Issue Action, Create Issue Action, Create Sub-tasks Action | A list of issues that have been created in the rule | {{#createdIssues}}{{key}}{{/}} |
| createdIssue | Same as createdIssues | The previous issue created in this rule | {{createdIssue.some field}} |
| eventType | The type of event that triggered the rule | e.g.: jira:issue_updated:issue_commented | {{eventType}} |
issue.fixVersions, | This is added any time an issue is added | Fix / affects versions of an issue as a list. See below for how to work with lists | {{issue.fixVersions.first.releaseDate}} Properties for versions include: name, description, archived, released, releaseDate |
| issue.components | This is added any time an issue is added | Components of an issue as a list. See below for how to work with lists | {{issue.components.first.name}} |
| issue.project | This is added any time an issue is added | Project that the issue belongs to | {{issue.project.key}} {{issue.project.name}} |
How to extract issue data?
With the {{issue...}} value you access all of JIRA's field data, based on the issue representation JIRA's REST api returns. The syntax for this can be a little bit complicated so here's a few examples.
Assuming your issue has the following JSON representation obtained by visiting https://<YOUR-INSTANCE>.atlassian.net/rest/api/2/issue/<YOUR-ISSUE-KEY>:
| Field | Smart-value | Value | JSON path |
|---|---|---|---|
| Issue Key | {{issue.key}} | EX-1 | {
...
"key": "EX-1",
...
}
|
| Summary | {{issue.summary}} | Hello test issue! | {
...
"key": "EX-1",
...
"fields": {
"summary": "Hello test issue!"
...
}
}
|
| Status name | {{issue.status.name}} | To Do | {
...
"key": "EX-1",
...
"fields": {
...
"status": {
...
"name": "To Do",
...
"statusCategory": {
...
}
},
...
}
}
|
| All attachment file names | {{#issue.attachments}}{{filename}},{{/}} (the # syntax is used to iterate over collections - any value enclosed by [] in the JSON) | picture.jpg,log.txt | {
...
"key": "EX-1",
...
"fields": {
...
"attachment": [
{
...
"filename": "picture.jpg",
"author": {...},
...
},
{
...
"filename": "log.txt",
"author": {...},
...
}
],
...
}
}
|
| "Sample text" custom field (text custom field) | {{issue.customfield_10700}} OR {{issue.Sample text}} (we do some convenience mapping of the field name to its ID so you don't have to lookup custom field IDs for smart-values) | Hello sample field | {
...
"key": "EX-1",
...
"fields": {
...
"customfield_10700": "Hello sample field",
...
}
}
|
How do I work with lists?
| Smart value | Description | Example |
|---|---|---|
| {{#list}}{{.}}{{/}} | Iterates over a list and prints it. You can also reference further methods and properties. | {{#issue.fixVersions}}{{name}}, {{/}} |
| {{list.get(index)}} | The element at the specified index, where 0 denotes the first element in the array | {{issue.comments.get(1).body}} |
| {{list.getFromEnd(index)}} | The element at the specified index from the end, where 0 denotes the last element in the array | {{issue.comments.getFromEnd(1).body}} |
{{list.first}} | The first element of a list | {{issue.comments.first.body}} |
| {{list.last}} | The last element of a list | {{issue.comments.last.author}} |
| {{list.size}} | The size of the list | {{issue.comments.size}} |
| {{#list}}{{#first}}..{{/}}{{/}} | Iterates over the list and only enters the "first" block on the first element. Can also use _first if the element has a method or property called first. | {{#issue.comments}}{{#first}}First:{{author.key}}{{/}}{{body}}{{/}} // Prints all comment bodies and places "First:<author>" in front of the first comment |
| {{#list}}{{#last}}..{{/}}{{/}} | Iterates over the list and only enters the "last" block on the last element. Can also use _last if the element has a method or property called last. | {{#issue.comments}}{{body}}{{^last}}, {{/}}{{/}} // Prints all comment bodies and places a comma and new line after each except the last comment |
| {{#list}}{{index}}{{/}} | Prints the index of the current item. Can also use _index if the element has a method or property called index. | {{#issue.comments}}{{index}}. {{body}}{{^last}}, {{/}}{{/}} // The same as above but prints the index of the comment in front |
What other functions are available?
| Function | Description | Notes |
|---|---|---|
| {{now}} | Prints out the current time | You can perform manipulations and formatting on this. |
| {{#increment}}value{{/}} | Increments the value by 1 | When setting field values in the advanced section, this can only be used with text fields, not number fields. |
How do I match a field to multiple values?
Sometimes you want to add a condition so that a field matches multiple values. You can use the "Contains regular expression" option and then use the (value1|value2|...) syntax to match multiple values like the example below.
Can't find what you're looking for here?
Please contact us via support or ask in the Atlassian community and we'll try to help you out!