Automation - Basic Tips and Tricks

[#1]

These tips, tricks, and pitfall avoidance techniques can help you get the most out the time you spend on your Automation Rules.  

Cloud vs Server/Data Center

Jira Cloud has Automation built-in. The Server and Data Center (Server/DC) hosting types require you to install either the full (paid) or lite (free) version (differences) from the Atlassian Marketplace.

Note also that Jira Cloud Automation contains a lot more features than Server/DC (differences). 

Your Knowledge Base

This tip is simple: make a browser folder of bookmarks to Automation resources. Start with the main documentation page for either Cloud or Server/Data Center. Take a minute to make bookmarks specifically to the pages about Smart Values, Triggers, Actions, and Branches/Conditions.

I also recommend having links for JQL, the Automation template library, the Automation blog (for Server/DC only), and this Automation group in the Atlassian Community. 

Besides looking up details on syntax, features, and limitations, these resources can help you see what others have done. The Atlassian University also has this one hour free Skillbuilder course on Automation. 

Be aware that generic web searches might show results specific to Cloud or Server/DC. Inspect the URL and the breadcrumbs at the top of each Atlassian documentation page to check the Jira hosting type. Results from non-Atlassian sites, and older answers in the Atlassian Community, may be outdated.

Tip: If you are totally new to Automation in Jira, start with this Automation Basics guide.

Know Your Triggers

Every rule starts with a Trigger. Take a few minutes to briefly review all the Triggers available for Jira Cloud or Server/DC. This will help you start learning the scope of what Automation Rules can and cannot do.

When you use a new Trigger, read about all the options to configure the Trigger. That will help you configure it correctly for your use case, and you’ll learn how flexible the Trigger can be.

Tip: When developing a new rule, I like to use the Scheduled Trigger (Cloud, Server/DC) and select “Use cron expression” with “0 0 0 1 1 ? 2000” which will never trigger. But the “Run rule” button will work, allowing you to quickly execute the Rule, review the results, and continue working on the Rule.

 

For a rule that will eventually be triggering on a changed or newly created issue, use the Manual Trigger (Cloud, Server/DC) during development of the rule instead. Go to a specific issue in Jira and in the Detail pane (Cloud) or Actions menu (Server/DC) select the automation rule to execute it. When you're ready to go live with the rule, just change the Trigger back and configure it as needed. More here.

Pitfall: If your Rule is disabled, even the “Run rule” button won’t work (and no warning or error is shown). Simply enable the Rule to run it.

Use the Log Action

The Log Action tends to be overlooked, but is extremely valuable! It can give you insight into what’s going on as an Automation Rule executes. It can also help you diagnose why a Rule isn’t working. It will help you debug your rules.

I will often use Log Action right after an issue-based Trigger, to confirm the conditions at the start of the Rule. For example, the following will show the issue and user that triggered the rule:

The link to access the Audit Log is on the page where you edit Automation Rules, right under “Rule Details”. Here’s what the above Log Action added to the Audit Log for that rule when it executed:

Log Actions can be helpful in and around conditionals. Often I will use a lot of Log Actions as I’m developing a new Rule. Once the Rule is working, I’ll remove most of them.

Smart Values

Much of the power of Automation comes from using Smart Values. The Log Action configuration example above used three Smart Values:

• initiator.displayName
• issue.issueType.name
• issue.key

Spend some time understanding the syntax and available data that can be accessed vis Smart Values. Note that Jira Cloud has many more Smart Values than Jira Server/DC.

Beware Branches

Looping and Branching in Automation is optimized using multi-threading. What does this mean? Here’s an example.

Consider a branch (loop) that will process issues A, B, C and D. It might be that Automation will process issue C first, then A, then D, then B. They’ll each get their turn in the loop, but you can’t be certain of the order. Also, turns can happen simultaneously - actions taken on issues B and D could happen at the same time.

Pitfall: You cannot have a branch within another branch. However, you can use Smart Value list processing within a branch, perhaps combined with conditional logic.

Common use cases that frustrate Automation users include trying to loop through a set of issues to count how many issues meet some criteria, or totaling up some values. It seems like an Automation variable could accumulate that count or total, but it simply doesn’t work.

Tip: To sum up a set of values, like issue Story Points or Estimates, use the sum() function with the Lookup action — no variables necessary!

Pitfall: Variables, and some Smart Value functions, are not available in Server/DC.

Also note that within a Branch, the {{issue}} Smart Value will change based on the type of branch or related issues you have selected. For example, If your rule is triggered on a Story, and you Branch to iterate through the Subtasks of that Story, then outside the Branch {{issue}} will reference the Story, and inside the Branch {{issue}} will reference each Subtask in turn. You can also use {{triggerIssue}} inside the branch to reference the Story.

Issue Hierarchy

The basic Jira issue hierarchy is: Epic - Story - Subtask. So if you have a Subtask, use the smart value {{issue.parent}} to access the parent Story of that Subtask.

Pitfall: You cannot access the Epic of a Story using {{issue.parent}}

If you have a Story, use the smart value {{issue.epic}} to access the parent Epic of that Story.

Tip: Use a Condition to verify the issue type before trying to navigate the hierarchy.

IDs versus Names

Pitfall: Some smart values return numeric IDs, which you might not expect. An example is {{issue.status}} which might return 10004, for example.

Tip: Use {{issue.status.name}} to get the actual status name, such as “Done”. Consult the Smart Value documentation to be sure, or use the Log Action to see what you're getting.

Pitfall: Names can change, whereas numeric IDs do not. For example, a Jira Admin could rename the "Done" Status name to "Finished", which could break a rule looking for "Done". Ask your Jira Admins to keep you in-the-loop for such global changes in your Jira instance.

Automation Limitations

Depending on your Jira product type and plan, there are limits to Automation. These limitations include whether you can configure a rule to work with more than one project, and how many multi-project rules can be executed in a month. Rules that are configured for a single project have fewer limitations than rules which are Global or configured for multiple projects.

Other limits do not depend on your plan, like how many components can be in a single Rule, how long one Rule can take to execute, and how many issues can be processed or created/edited in one Rule execution.

• For Jira Cloud see the “Automation” section here.
• For Server/DC see here.

Tip: Some limits on Server/DC can be configured (more here under "Increasing service limits").

Monitor Usage

Admins should periodically take a look at the Automation Usage, especially if you have multiple people authoring Rules. One Rule behaving badly can exceed a limit that affects all Rules. Here's how to check automation usage on Jira Cloud.

Pitfall: Rules configured for multiple projects (which includes rules with Global project scope) have more limitations than rules configured for a single project.

Watch for Rules which execute excessively often; they may need to be optimized, refactored, or even combined with other Rules. In a pinch, a global or multi-project Rule can sometimes be replicated and each rule configured for a single project in order to avoid some execution limits.

Things Change

The information and links here were accurate as of the date of this article. However, Atlassian is constantly improving their products, and sometimes adjusting their documentation.

Further Reading

• Automation Knowledge Base for Jira Server/DC.
• 79 Questions and Answers (somewhat dated information circa Apr 2020, but broad coverage)
• Other Automation gurus may have good comments below!

[Wagner Filho]

Very nice article @Mykenna Cepek !! 

[Ilenice]

This is great, @Mykenna Cepek thanks for the article! :D