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}}".
| Table of Contents |
|---|
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.
| Info |
|---|
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
| Code Block |
|---|
{{issue.reporter.name}} |
In the advanced block section you would use
| Code Block |
|---|
{
"fields": {
"My User Custom Field": { "name": "{{issue.reporter.name}}"}
}
} |
What values can I use?
...
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}}
{{issue.status.name}}
{{issue.issuetype.name}}
{{issue.description}}
{{#issue.created}}format="dd/MM/yyyy"{{/}}
{{issue.Custom Field.value}}
{{#issue.components}}{{name}}{{/}}
...
{{#issue.comments}}{{body}}{{/}}
{{#issue.comments}}{{author}}{{/}}
{{#issue.comments}}{{created}}{{/}}
{{issue.comments.last.body}}
...
This refetches the latest state of the issue from JIRA.
| Info |
|---|
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.security.name}}
{{issue.security.id}}
...
{{triggerIssue.description}}
... all fields available to {{issue}} are available as well
...
{{reporter.displayName}}
{{reporter.emailAddress}}
{{reporter.key}}
{{reporter.timeZone}}
...
{{assignee.displayName}}
... (same as reporter)
...
{{initiator.displayName}}
... (same as reporter)
...
JIRA Triggers that contain a comment
E.g. Transition issue
...
{{comment.body}}
{{comment.author}}
{{comment.created}}
{{comment.internal}} (returns true or false for service desk comments)
...
{{comment.properties."sd.public.comment".internal}}
...
{{#changelog.summary}}{{toString}}{{/}}
{{#changelog.attachments}}{{fromString}}{{/}}
...
issue.fixVersions,
issue.versions
...
{{issue.fixVersions.first.releaseDate}}
{{issue.versions.first.name}}
Properties for versions include: name, description, archived, released, releaseDate
...
{{issue.components.first.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>:
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
{
"expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
"id": "10002",
"self": "http://www.example.com/jira/rest/api/2/issue/10002",
"key": "EX-1",
"names": {
"watcher": "watcher",
"attachment": "attachment",
"sub-tasks": "sub-tasks",
"description": "description",
"project": "project",
"comment": "comment",
"issuelinks": "issuelinks",
"worklog": "worklog",
"updated": "updated",
"timetracking": "timetracking"
},
"schema": {},
"fields": {
"summary": "Hello test issue!"
"watcher": {
"self": "http://www.example.com/jira/rest/api/2/issue/EX-1/watchers",
"isWatching": false,
"watchCount": 1,
"watchers": [
{
"self": "http://www.example.com/jira/rest/api/2/user?username=fred",
"name": "fred",
"displayName": "Fred F. User",
"active": false
}
]
},
"attachment": [
{
"self": "http://www.example.com/jira/rest/api/2.0/attachments/10000",
"filename": "picture.jpg",
"author": {
"self": "http://www.example.com/jira/rest/api/2/user?username=fred",
"key": "fred",
"accountId": "99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
"name": "fred",
"avatarUrls": {
"48x48": "http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred",
"24x24": "http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred",
"16x16": "http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred",
"32x32": "http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred"
},
"displayName": "Fred F. User",
"active": false
},
"created": "2017-01-20T00:36:28.642+0000",
"size": 23123,
"mimeType": "image/jpeg",
"content": "http://www.example.com/jira/attachments/10000",
"thumbnail": "http://www.example.com/jira/secure/thumbnail/10000"
}
],
"sub-tasks": [
{
"id": "10000",
"type": {
"id": "10000",
"name": "",
"inward": "Parent",
"outward": "Sub-task"
},
"outwardIssue": {
"id": "10003",
"key": "EX-2",
"self": "http://www.example.com/jira/rest/api/2/issue/EX-2",
"fields": {
"status": {
"iconUrl": "http://www.example.com/jira//images/icons/statuses/open.png",
"name": "Open"
}
}
}
}
],
"status": {
"self": "https://goonbag.atlassian.net/rest/api/2/status/10000",
"description": "",
"iconUrl": "https://goonbag.atlassian.net/images/icons/status_generic.gif",
"name": "To Do",
"id": "10000",
"statusCategory": {
"self": "https://goonbag.atlassian.net/rest/api/2/statuscategory/2",
"id": 2,
"key": "new",
"colorName": "blue-gray",
"name": "To Do"
}
},
"description": "example bug report",
"project": {
"self": "http://www.example.com/jira/rest/api/2/project/EX",
"id": "10000",
"key": "EX",
"name": "Example",
"avatarUrls": {
"48x48": "http://www.example.com/jira/secure/projectavatar?size=large&pid=10000",
"24x24": "http://www.example.com/jira/secure/projectavatar?size=small&pid=10000",
"16x16": "http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000",
"32x32": "http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000"
},
"projectCategory": {
"self": "http://www.example.com/jira/rest/api/2/projectCategory/10000",
"id": "10000",
"name": "FIRST",
"description": "First Project Category"
}
},
"comment": [
{
"self": "http://www.example.com/jira/rest/api/2/issue/10010/comment/10000",
"id": "10000",
"author": {
"self": "http://www.example.com/jira/rest/api/2/user?username=fred",
"name": "fred",
"displayName": "Fred F. User",
"active": false
},
"body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.",
"updateAuthor": {
"self": "http://www.example.com/jira/rest/api/2/user?username=fred",
"name": "fred",
"displayName": "Fred F. User",
"active": false
},
"created": "2017-01-20T00:36:28.593+0000",
"updated": "2017-01-20T00:36:28.593+0000",
"visibility": {
"type": "role",
"value": "Administrators"
}
}
],
"customfield_10700": "Hello sample field",
"issuelinks": [
{
"id": "10001",
"type": {
"id": "10000",
"name": "Dependent",
"inward": "depends on",
"outward": "is depended by"
},
"outwardIssue": {
"id": "10004L",
"key": "PRJ-2",
"self": "http://www.example.com/jira/rest/api/2/issue/PRJ-2",
"fields": {
"status": {
"iconUrl": "http://www.example.com/jira//images/icons/statuses/open.png",
"name": "Open"
}
}
}
},
{
"id": "10002",
"type": {
"id": "10000",
"name": "Dependent",
"inward": "depends on",
"outward": "is depended by"
},
"inwardIssue": {
"id": "10004",
"key": "PRJ-3",
"self": "http://www.example.com/jira/rest/api/2/issue/PRJ-3",
"fields": {
"status": {
"iconUrl": "http://www.example.com/jira//images/icons/statuses/open.png",
"name": "Open"
}
}
}
}
],
"worklog": [
{
"self": "http://www.example.com/jira/rest/api/2/issue/10010/worklog/10000",
"author": {
"self": "http://www.example.com/jira/rest/api/2/user?username=fred",
"name": "fred",
"displayName": "Fred F. User",
"active": false
},
"updateAuthor": {
"self": "http://www.example.com/jira/rest/api/2/user?username=fred",
"name": "fred",
"displayName": "Fred F. User",
"active": false
},
"comment": "I did some work here.",
"updated": "2017-01-20T00:36:28.801+0000",
"visibility": {
"type": "group",
"value": "jira-developers"
},
"started": "2017-01-20T00:36:28.792+0000",
"timeSpent": "3h 20m",
"timeSpentSeconds": 12000,
"id": "100028",
"issueId": "10002"
}
],
"updated": 1,
"timetracking": {
"originalEstimate": "10m",
"remainingEstimate": "3m",
"timeSpent": "6m",
"originalEstimateSeconds": 600,
"remainingEstimateSeconds": 200,
"timeSpentSeconds": 400
}
}
} |
...
JSON path
...
{{issue.key}}
...
| Code Block |
|---|
{
...
"key": "EX-1",
...
} |
...
Hello test issue!
| Code Block |
|---|
{
...
"key": "EX-1",
...
"fields": {
"summary": "Hello test issue!"
...
}
} |
...
To Do| Code Block |
|---|
{
...
"key": "EX-1",
...
"fields": {
...
"status": {
...
"name": "To Do",
...
"statusCategory": {
...
}
},
...
}
} |
...
{{#issue.attachments}}{{filename}},{{/}}
(the # syntax is used to iterate over collections - any value enclosed by [] in the JSON)
...
| Code Block |
|---|
{
...
"key": "EX-1",
...
"fields": {
...
"attachment": [
{
...
"filename": "picture.jpg",
"author": {...},
...
},
{
...
"filename": "log.txt",
"author": {...},
...
}
],
...
}
} |
...
{{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)
...
| Code Block |
|---|
{
...
"key": "EX-1",
...
"fields": {
...
"customfield_10700": "Hello sample field",
...
}
} |
...
{{#issue.fixVersions}}{{name}}, {{/}}
...
{{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
...
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
...
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?
...
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.
| Info | ||
|---|---|---|
| ||
| Info | ||
Our documentation has recently move to a new location! Please head on over to: http://docs.codebarrel.io/automation/#/smart-fields/smart-fields |