Automation concepts – Variable Names and Shadows

[#1]

Estimated time to read: 5 minutes

TL; DR: Automation rules, like other code, can shadow variable names. For example, smart values appear to get "walked over". To avoid confusion and problems, please remember to use unique names for your own variables.

What is this about?

Let's start with...what is variable shadowing. When some piece of information has a declared name to reference it, and later in the code scope that same name is reused for something else, the second piece of information is likely used from that point onward. It overshadows the earlier one. A person reading the code may become confused...particularly with a longer code section that does not fit everything on a single screen page. Perhaps worse still, the code may not do what is intended. What has this got to do with automation rules?

What does it look like in a rule?

Here is an example rule to demonstrate the effect.

Here we have a simple rule, with a Scheduled trigger with JQL to get one work item. We write the Summary to the audit log, both fully specified as {{issue.summary}} and as {{summary}}, adding some text in front of each log write so we can tell them apart later. 

Then we use the Create Variable action to make a variable with the same name as the field, and we hard-code in a text value.

We follow that action with another write to the log for {{summary}}.

What happens when we run the rule? Here is the audit log:

Okay, what is happening here?

• The trigger gets our work item, supplying it to the rule, and referred to as {{issue}} (and {{triggerIssue}} )
• The first log write uses the fully specified {{issue.summary}} and has no problem resolving that to the correct thing
• The second log write uses only {{summary}} and apparently uses an implied prefix of issue to get at the same piece of information
• Our variable is created, effectively replacing what {{summary}} refers to
• Finally, our last log write now sees what the Create Variable added: Hello, world!

A related challenge around the behavior is smart values are case-sensitive. Even though you may have created a variable named "Summary" rather than "summary", and thought you were safe, a simple typo could result in problems later in the rule.

What, if anything, should we do about this?

This way of defining variables is a common enough behavior that I see it regularly in community questions, Atlassian documentation, and JAC backlog item workarounds. It makes sense, right: let's name a thing to what we need it to be.

Unfortunately, the rule engine processing cannot guess our intentions / meanings; it is following an algorithm to do what we asked within the guardrails provided by the rule definition.

One simple preventative measure is to always add a prefix to variable names, such as using:

• varSummary for a variable name
• tblCodeToAssignee for a created table name prefix
• etc.

Those are much less likely to collide with built-in (or future) smart value names, but as I always note: when in doubt, experiment to validate the rule works as expected.

Disclaimer time:

Yes...I understand this naming convention is a mitigation rather than a fix. Ideally, the rule editor would detect when we use a name which collides with all possible smart values, from all reachable products and spaces, preventing customers from saving a rule until the name is changed. I hypothesize that type of validation is unlikely to be added to the rule editor any time soon.

There are cases when you might want to reuse a variable name. One example is using a series of rule Create Variable actions to repeatedly add to something, such as sum values, concatenate text, etc., using the same variable name over and over again. Even in this case, I recommend using separate variables for each step to reduce mistakes. And, if you encounter rule limits (e.g., amount of variable storage) that may be solvable with other methods.

Thanks for reading, please let me know your feedback on the article, and as always...happy rule writing!

---

[Darryl Lee]

Great stuff as always @Bill Sheboy 

I learned this lesson the hard way when Atlassian decided to make {{baseurl}} into a reserved Smart Value in Confluence Automation.

My Automation that had been running just fine suddenly broke one day, all because I had inadvertently chosen a variable name that Atlassian later decided to use.

Support said they made the change "to increase parity with Jira Smart Values" but as I pointed out then, the base URL for Confluence sites should technically actually include /wiki.

(My {{baseurl}} did. Theirs does NOT.)

So yes, I think your prefixing idea is a good one. Hopefully Atlassian doesn't decide they need to start naming things varWhatever in the future.

[Josh]

This is a really valuable article, @Bill Sheboy !

You and @Darryl Lee are on my shortlist of must-read authors in the Community; regardless of topic. Would be great to say hi and thanks to you guys at Team in a couple days.

[Rick Westbrock]

This is a specific use case of the perennial programming adage: Names Matter. 

To Darryl's point one might use a prefix that is specific to their own company, for example if I worked for Acme Industries I would use acme_summary. As a Python programmer I would consider using snake_case for variable names (e.g. var_summary) since I have not seen Atlassian use snake case in the past but I can't recall off the top of my head whether underscore is a valid character for a variable name.