Getting started with rules

To understand automations, we need to first take a look at some of the basic concepts associated with them, the foremost of which is the rule.

In this section, we will examine the following concepts:

• The definition of a rule
• Rule scopes
• Owners and actors
• Audit log

These will give us a foundation on which to build in the following chapters, so without further ado, let's get started.

What is a rule?

A rule, in its basic form, is a list of steps required to be executed in a specific order to achieve a desired outcome that is both repeatable and auditable.

By this, we mean that a rule should have the exact same outcome each and every time it is executed, and we should be able to examine the actions applied by the rule chronologically.

Specifically, a rule in Jira allows you to perform actions against issues based on criteria that you set.

Every rule is comprised of three basic components:

• Triggers: The entry point for a rule.
• Conditions: These refine the criteria of the rule.
• Actions: These perform the actual tasks.

In addition to these, a rule also contains some other basic information:

• The rule name
• The rule description
• The rule scope
• The rule owner and actor
• Options to notify the rule owner in the case of rule failures
• Options to allow other rules to trigger this rule
• The rule audit log

Together, these form the building blocks of automation rules. By combining these basic components, you are able to create rules that can be used to automate many time-consuming and repetitive tasks.

The following screenshot shows an outline of the basic components of a rule in Jira:

Figure 1.1 – Visualizing the basic components of a rule

We will cover each of these components in more detail in this and the following chapter.

Understanding scopes

Rules in Jira have can be applied in one of four scopes:

• Global rules
• Multi-project rules
• Project type-specific rules
• Project-specific rules

The following table shows how these rule scopes are defined and which Jira permission is required in order to create and manage a rule that is applied in that scope:


Figure 1.2 – Rule scope permissions

As we can see, most of the rule scopes require you to have Jira Global admin permissions in order to manage them, and this is expected, as these rules span multiple projects and cannot therefore rely on project-specific permissions.

Project rules, on the other hand, can be created and managed by project administrators in addition to Jira global administrators.

Having this distinction allows Jira administrators to delegate the project-specific automations and gives project administrators more flexibility in managing their own project rules, whilst Jira Global admins can focus on automation rules that can be applied across a much wider audience.

Rules can also be moved between the global and project scopes by Jira administrators. If, for example, it is determined that a project-specific rule could be reused across multiple projects, a Jira administrator can adjust the scope of the rule. The reverse is also true. If a particular global rule is only ever utilized by a single project, a Jira administrator can adjust the scope to that specific project and by doing so, transfer administration of the rule to the project administrators.

Owners and actors

Every rule requires both an owner and an actor.

The owner of the rule is generally the user who created the rule and is responsible for maintaining the rule. The rule owner will also receive email notifications from Jira if the rule fails while executing.

The rule actor is the user the rule will execute as. This user must have the correct permissions in the project for both the trigger and any actions the rule will perform. For example, if you create a rule that needs to add a comment to an issue, the rule actor will need to have the Add Comments permission in the project.

Important note

In Jira Cloud, the default rule actor is always the Automation app user and will belong to the atlassian-addons-project-access project role. This project role is assigned every permission in a project and can be changed in the Project settings | Permissions section. Removing permissions from this role could potentially cause add-ons not to work correctly, so it is generally advised not to change these permissions.

Audit log

Every rule has its own audit log, which tracks the execution of a rule chronologically and allows you to examine the outcome as well as the actions applied to the affected items for each execution.

This functionality is not only necessary to be able to track the outcomes of a rule execution; it also gives us the ability to be able to debug rules when things don't go as planned.

We will examine the role of the audit log in debugging rules in more detail in Chapter 10, Troubleshooting Tips and Techniques, when we will explore techniques for debugging rules and solving common issues.