Configuring Insight automation rules

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

You can create automation rules that automatically perform actions (for example, notify users) based on specific events (for example, object updated) for all objects, or only a group of objects in a schema.

Before you begin

Make sure you have the right permissions:

  • To configure automation rules, you need to have at least the Insight manager role for the schema.
  • To run and execute automation rules, the user (either the logged-in user or the user that you select for running scheduled events) needs to have at least the Insight users role for the schema. If this user has a different role for the object types affected by the rule (object type's permissions take precedence over schema's permissions), then also grant them the Insight users role for these object types. This is only needed if a rule affects such object types, otherwise permissions are inherited from the schema.

For more info about permissions, see Configuring roles and permissions.

Create a rule

  1. Open your schema, and select Object schema > Configure.
  2. Switch to the Automation tab.
  3. Create a rule.
  4. Enter the rule's name and description.
  5. Select each of the boxes (WHEN, IF, THEN). A panel will appear on the right allowing you to add an event, condition, and action. You can read more about them below.

Any changes to your rule will only be saved after you select Save. If you've deleted something by mistake, you can select Cancel to revert these changes.

Configure your rule

Configure your rule by specifying events (WHEN), conditions (IF), and actions (THEN).

1. Add events (WHEN)

  1. Select the WHEN box.
  2. On the right, select Add events.
  3. Select the desired event, then select Add.
tip/resting Created with Sketch.

Good to know

  • You can add up to five events for a single rule.
  • Instead of creating two or more rules with the same actions (for example, email notification), add two or more events to the same rule. It will be easier to maintain later.

Event types

Event typeDescription
User eventsMost events, except the Scheduled event are triggered when a logged-in user performs an action on an object (object updated, attachment added, etc.) These events don't require any additional configuration.
Scheduled events

Scheduled events aren't triggered by an action performed by a user. They run according to the specified cron expression (e.g. once a day, once an hour) and conditions. 

Required parameters for scheduled events...

Here are the required parameters for scheduled events:

  1. Condition: This is an IQL (Insight Query Language) expression. When the scheduled rule is activated, all objects that match the condition will trigger individual actions.
  2. Cron expression: This determines when and how often the provided condition will try to match insight objects. By default, the expression is set to " 0 0 12 1/1 * ? *", that is: once a day at noon. Learn more about cron expressions
  3. Triggered rule will run as: You need to select a specific user here because scheduled events can’t be triggered by a logged-in user. You can select the user on the top-right of the page.

2. Add conditions (IF)

You can add a condition if you don't want the configured action to apply to all objects in your schema, but rather a specific set of objects. 

  1. Select the IF box.
  2. On the right, select Add condition.
  3. Enter an IQL statement and select Add.
tip/resting Created with Sketch.

Good to know

  • A condition (IF) always needs a THEN box. When you add another condition, you'll be able to edit its actions.
  • You can configure up to three IF/THEN pairs.

Example

  • A rule is triggered by an object updated event.
  • The rule has a condition: "name = Windows server".
  • The rule has an email notification action.

The rule configuration in this example means that if a user updates an object whose exact name is “Windows server”, an email notification is automatically sent

3. Add actions (THEN)

  1. Select the THEN box.
  2. On the right, select Add action.
  3. Select your action and fill in the details. Every action requires different information. For example, details needed for Create a Jira issue will differ from those needed to Execute a Groovy script.
  4. Select Add.
tip/resting Created with Sketch.

Good to know

  • You can have up to five actions for every THEN box.

Available actions

Here's a list of actions that you can select:

Attribute value

This action allows the rule to change the value of an object's attribute.

Set an attribute value of the Insight object affected by the event. Multiple values are separated by a comma (,).

FieldSingle value exampleMultiple values example
Attribute nameStatusServer
ValueStoppedServer 1,Server2
Create Jira issue

This action allows the rule to create a Jira issue.

tip/resting Created with Sketch.

Good to know

  • (warning) The issue type selected must be available for the chosen project, otherwise a Jira issue can't be created.
  • (info) If the custom field is populated, the chosen project must be configured to handle this object type, otherwise this field won't have any effect.


Fields that support placeholdersSyntax exampleResult example
SummaryServer ${label} stopped! Server ${exchange.prod.main1} stopped!
DescriptionServer details - name: ${label}, key: ${Key}, id: ${objectId} Server details - name: exchange.prod.main1, key: WS-5969, id: 17400 
Email notification

This action allows the rule to send email notifications related to the event that was triggered.

Example: For the object updated event, an email will be sent showing the changes related to this object.

Note that for the Recipients by attribute option you need to select the object type in the rule's condition with attributes of the email, user, or group type.

Fields that support placeholdersExample syntaxExample result
SubjectServer: ${label} is stopped.Server: exchange.prod.main1 is stopped.
MessageServer: ${label} (${Key}) has status: ${Status}.Server: exchange.prod.main1 (WS-5969) has status: Stopped.
Execute Groovy script

Groovy scripts need adequate permissions and must be whitelisted to be executed. Learn how to add Groovy scripts to the Whitelist

This action allows a triggered rule to execute a Groovy script.

Data available to the Groovy script by our rule engine

ParameterDescriptionJAVA class
object

The object that was directly involved in a user action (like updating an Insight object) or matched by a scheduled rule through IQL, with an "Execute Groovy Script" as an action

object that was directly involved in a user action (for example, updating an object) or matched by a scheduled rule through IQL, with an "Execute Groovy Script" action.

com.riadalabs.Jira.plugins.insight.services.model.ObjectBean
currentUser

The user who triggered the rule or a specific user chosen to run the rule.

com.atlassian.Jira.user.ApplicationUser
log

An instance of the Apache Log interface, for convenient logging in a script.

org.apache.commons.logging.Log
objectUpdateList

A list of object attributes that are affected in an object update event that includes an affected attribute in an object, as well as values added or removed for it.

List<com.riadalabs.jira.plugins.insight.services.model.ObjectUpdateBean>
Http request

This action allows a triggered rule to make an HTTP request. It supports the standard HTTP methods: GET / POST / PUT / DELETE.

Fields that support placeholdersSyntax exampleResult example
Urlhttp://company/service?id=${objectId}&name=${label}http://company/service?id=1405&name=exchange.prod.main1
Post Data (POST / PUT){ "name":"${label}","key":"${Key}","id":"${objectId}" }{ name:exchange.prod.main1,key:WS-76100,id:76100 }

4. Add more conditions and actions

A rule can only consist of one event (WHEN), but it can have up to three pairs of conditions and actions (IF/THEN). This allows you to add more conditions and actions, if the first ones aren't matched.

  1. Select the ELSE IF / THEN box.
  2. Add actions, and conditions if needed.
  3. Select Save.

More automation

Automation rules are related to a specific object scheme, but there's way more automation that you can add. Your Jira admin can add conditions and validators, as well as post-functions, to Jira workflows that will make issues affect objects while they're being transitioned through workflows. For more info, see Adding Insight functions to Jira workflows.

Last modified on Feb 3, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.