Working with triggers

The starting point for every rule is a trigger. A trigger defines how the rule will activate and will generally listen for events in Jira, such as when an issue is created or when values in fields within an issue change.

In this section, we will begin by looking at Jira events as this will help you to understand when and why rules are triggered, after which we'll explore the available rule triggers, what each of them are, and how they can be used.

Understanding Jira events

To better understand how triggers work, it is worth taking a brief look at how events in Jira work as these are the driving force behind most of the triggers available in the automation rules.

Jira, like many applications, incorporates an event-driven architecture. In essence, this means that every time an action is performed within Jira, an event is fired that allows interested components to listen to and perform additional actions based on those events.

There are two main types of events that affect issues in Jira. The first of these are workflow events. These events are fired when an issue is created and any time an issue is transitioned to a new status in its underlying workflow, and are responsible for causing the Issue created and Issue transitioned triggers in an automation rule to fire.

The second type of event is issue events and these are responsible for the majority of the remainder of the issue triggers and are fired whenever a user (or app) makes a non-workflow-related change to an issue, such as updating a field or linking two issues together.

Rule triggers

Jira automation provides us with a number of triggers that we can use to kick off the execution of our rules.

These triggers are grouped into categories to make it easier to identify which type of trigger you will need when creating your rule, and these categories are as follows:

• Issue triggers
• DevOps triggers
• Scheduled triggers
• Integration triggers

We will take a look at each category in turn and the available triggers in each.

Issue triggers

As we mentioned in the Understanding Jira events section, the majority of triggers relate to events occurring on issues, such as when an issue is created or edited.

Most of the triggers are self-explanatory and single purpose. However, there are some that can be further configured to make the trigger more specific without needing to use additional conditions.

Let's take a look at the issue triggers available at the time of writing and what each one does:

• Field value changed: This rule will run when the value of a field changes. You configure this trigger by selecting the fields you want to monitor or by using a regular expression that matches the field names you want to monitor. You can also optionally narrow which issue operations will trigger the rule.
• Issue assigned: This rule will run when the assignee of the issue changes.
• Issue commented: This rule will run every time a new comment is added to an issue. Note though that this does not include when comments are edited or deleted.
• Issue created: This rule will execute every time an issue is created. This trigger listens for the issue-created event that is always fired as the first step in a workflow.
• Issue deleted: This rule will run when an issue is deleted.
• Issue link deleted: This rule will run when an issue is unlinked from another issue. You can optionally configure this trigger to only execute for specific link types.
• Issue linked: This rule will execute when an issue is linked to another issue. Like the issue link deleted trigger, you can optionally configure which issue link type the trigger will execute for.
• Issue moved: This rule will execute when an issue is moved from one project to another. You can optionally specify that the trigger only executes if an issue is moved from a specific project.
• Issue transitioned: This rule will execute every time an issue transitions through the workflow from one status to another. You can optionally configure this trigger to listen for a specific transition or multiple transitions to or from a specific status.
• Issue updated: This will trigger the rule when details on an issue are updated, except when changes are made by linking, assigning, or logging work on an issue.
• SLA threshold breached: This rule will get triggered for issues in a Service Management project when the SLA threshold has breached or is about to breach. You can configure which SLA to monitor as well as the time before or after it has breached.
• Work logged: This rule will run when a worklog is created, updated, or deleted.

There are a few specialized issue triggers worth taking note of and these are the following:

• Manual trigger: This trigger is not dependent on any underlying events. Instead, triggers of this type are presented to the user in the Issue view and require the user to manually activate them.
• Multiple issue events: This trigger allows you to listen to more than one event for an issue. For example, this is useful when you need to perform the same automation when a ticket is both created and updated, rather than having to create a separate rule for each event.
• Sprint and Version triggers: These triggers are not directly associated with underlying issues, and instead they allow you to perform actions against the related issues when something happens to the containing Sprint or when the versions pertaining to a project are created or changed.
• Service limit breached: This is a specialized trigger that allows you to monitor and manage your automation rules themselves.

DevOps triggers

DevOps triggers are specific to Jira Cloud and allow you to create rules that are linked to events in your connected development tools, such as Bitbucket and GitHub.

Let's take a quick look at these triggers and what they do:

• Branch created: This rule will run when a branch in a connected source repository is created.
• Build failed: This rule will be executed when a build in a connected build tool fails. You can optionally configure this to trigger on specific build names, branches, or tags.
• Build status changed: This rule will be run when the build status in a connected build tool changes, for example, from failed to success, or vice versa. This can optionally also be configured to trigger on specific build names, branches, or tags.
• Build successful: Similar to the previous triggers, this will cause the rule to execute when a build in a connected build tool is successful. This can also optionally be configured to listen for specific build names, branches, or tags.
• Commit created: This rule will run when a commit is created in a connected source repository.
• Deployment failed: This rule will execute when a deployment against a specified environment fails.
• Deployment status changed: This rule will run when the deployment against a specified environment changes status from failed to success, or vice versa.
• Deployment successful: This rule will run when the deployment against a specified environment is successful.
• Pull request created: This rule will execute when a pull request in a connected source repository is created.
• Pull request declined: This rule will execute when a pull request in a connected source repository is declined.
• Pull request merged: This rule will execute when a pull request in a connected source repository is merged.

  Important note

  DevOps triggers are not available in Jira Server, although these triggers can be emulated using the Incoming webhook integration trigger.

We will explore these triggers in more detail in Chapter 8, Integrating with DevOps tools.

Scheduled triggers

Scheduled triggers allow you to configure rules that run at defined intervals. These can be simple fixed-rate intervals or more complex schedules.

Scheduled triggers are perfect for automating clean-up processes or to create recurring tasks that need to be actioned and we'll look at these in more detail in Chapter 2, Automating Jira Issues.

Integration triggers

The final type of trigger is the incoming webhook. This trigger provides a way for third-party applications to trigger automation rules.

An incoming webhook trigger can specify the exact issues to act on or even provide real-time data that you can use to update issues.

Chapter 5, Working with External Systems, is dedicated to exploring the ways in which we can integrate our automation rules with external systems.