Configuring Insight automation rules
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
- Open your schema, and select Object schema > Configure.
- Switch to the Automation tab.
- Create a rule.
- Enter the rule's name and description.
- 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)
- Select the WHEN box.
- On the right, select Add events.
- Select the desired event, then select Add.
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 type | Description |
|---|---|
| User events | Most 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. |
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.
- Select the IF box.
- On the right, select Add condition.
- Enter an IQL statement and select Add.
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)
- Select the THEN box.
- On the right, select Add action.
- 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.
- Select Add.
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:
This action allows the rule to create a Jira issue.
Good to know
The issue type selected must be available for the chosen project, otherwise a Jira issue can't be created.
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 placeholders | Syntax example | Result example |
|---|---|---|
| Summary | Server ${label} stopped! | Server ${exchange.prod.main1} stopped! |
| Description | Server details - name: ${label}, key: ${Key}, id: ${objectId} | Server details - name: exchange.prod.main1, key: WS-5969, id: 17400 |
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 placeholders | Example syntax | Example result |
|---|---|---|
| Subject | Server: ${label} is stopped. | Server: exchange.prod.main1 is stopped. |
| Message | Server: ${label} (${Key}) has status: ${Status}. | Server: exchange.prod.main1 (WS-5969) has status: Stopped. |
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
| Parameter | Description | JAVA 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> |
This action allows a triggered rule to make an HTTP request. It supports the standard HTTP methods: GET / POST / PUT / DELETE.
| Fields that support placeholders | Syntax example | Result example |
|---|---|---|
| Url | http://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.
- Select the ELSE IF / THEN box.
- Add actions, and conditions if needed.
- 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.