Automation concepts -- Smart Values and Scope of Information

[#1]

Estimated time to read: 6 minutes

TL;DR: Several community questions ask about where in a rule a smart value has certain information, and misunderstandings may lead to rules with odd symptoms / defects when the rules execute. Understanding the scope of smart values in rules helps our learning to prevent such challenges.

{{triggerIssue}} versus {{issue}}

The {{triggerIssue}} smart value (when it applies) has a constant value* throughout a rule. But the {{issue}} smart value is based on context. Please consider this example rule below:

Rule	Smart value content
trigger: work item created	At this point, {{triggerIssue}} and {{issue}} refer to the same work item.
action: re-fetch work item data	Still the same, although the data has been updated from the Cloud storage.
action: some action	Still the same.
branch: some branch to other work items	Still the same.
action: some action inside the branch	Inside the branch, they are different, where {{issue}} now refers to the branched-to work item(s).
action: some action after the branch	After the branch, they are once again the same work item.

Here we see the value of {{issue}} changes once inside of a branch, allowing us to act upon it as a work item. This would not apply when using a branch over data only, such as an Advanced Branch where there are no "work items" provided.

* Noting the asterisk from earlier, the value of {{triggerIssue}} and {{issue}} can be changed when the Re-fetch Work Item Data action is used, refreshing the rule's data from the Cloud storage.

Also please note {{triggerIssue}} does not always have an work item, as there are several rule triggers which do not supply work items to a rule:

• Scheduled trigger (with no JQL)
• Sprint-related, such as Sprint Started (This one often surprises people, and they forget to add a branch to the work items assigned to the sprint.)
• etc.

When it doubt, check the documentation or use a Log action immediately after the trigger to write the value of {{triggerIssue.key}}.

What about work item edits?

When a rule updates a field in a work item, that change is made in the Cloud storage, and not in the information in {{triggerIssue}} or {{issue}}.  Regardless of opinions about that design choice, that may confuse rule writers.  For example, when they edit a field and then try to use it later in the rule, it seems wrong to them!  Once again, our solution is to add the Re-fetch Work Item Data action after the edit when the rule needs the updated information.

Inside of iterators, what can we see?

Short answer: long-format iterators cannot "see" outside data and inline iterators can.

For long-format iterators, such as {{#someListField}} … {{/}}, we can only see the data from {{someListField}} and lower in scope. An example of this is with {{lookupIssues}} iteration to filter / list the work items to send in an email. This is a current limitation of such iterators and there are open suggestions to improve this behavior.

Inline iterators, such as {{someList.match(someRegularExpression)}}, can use data from other rule scopes. Thus, this helps to create a workaround for the long-format iterator. To learn more about this advanced technique, please see this article: Automation concepts -- Dynamic Searches within a List. 

Dynamic, just-in-time smart value data loading

Based on my experience and experimentation, it appears some smart values do not immediately load their data. Instead, they get it just-in-time. Examples of this are {{issue.subtasks}} and {{issue.issuelinks}}. The consequence of this is some latency in lengthier smart value expression processing.

For a practical example, consider building a dynamic JSON expression to update a field with the Edit Work Item action, such as to add values to a multiple-selection option field. If there is a delay in looking up the data, the JSON expression may be considered invalid when the rule runs because it is partially completed, leading to a rule error.

The workaround for this is to first build the dynamic JSON expression and store it with the Create Variable action, and then use that variable in place of the JSON for the Edit Work Item action. This will force full evaluation of the smart values before they are needed later.

Digging a bit deeper on the just-in-time smart values, please consider things like {{issue.subtasks}} do not contain all of the fields for those subtasks; they only have a subset of the fields. If they did have all of them, one could imagine a situation where a subtask leads to issuelinks, which leads to other links, and so pulls in more and more work item data! When one wants all of the fields for the subtasks of a work item in a rule, try using the Lookup Issues action with JQL as that will get everything supported by rules. When in doubt, use a write to the audit log with the Log action to confirm the presence of a field...or use this how-to article to Find all available smart values for a Jira Issue.

I hope this article helps you better understand the what / where / when for smart value data. Please let me know your feedback and experiences tracking down smart value scope in rules.

Happy rule writing!

[John Funk]

Excellent article @Bill Sheboy  - this should be VERY helpful for newcomers as well as those who have been using Automation for a while!

[Kelly Arrey]

Thanks @Bill Sheboy ! Bookmarked this one!

[Hana Kučerová]

Great article @Bill Sheboy !