This documentation is for Insight for Server/Data Center only.


Insight Automation enables an administrator to create Rules that can automatically perform Actions (e.g. Notify users) based on specific Events (e.g. Object updated) for all objects, or groups of objects, in a schema. Configuring rules require at least Insight Schema Manager. Insight Administrators and the global permission Jira Administrators can always access Insight Automation.

Set up a new rule

  1. In your Object schema, choose menu: Object Schema > Configure, and choose tab: Automation
  2. Select Be the first to create one (or Create New Rule if previous rules already exists)
     


  3. Start configuring the new rule.

Configure Rule

  1. Edit the rule name and description (optional)
  2. Configure the WHEN (Events), IF (condition), THEN (Action) boxes by clicking them. A configuration panel will show to the right, where the appropriate information can be added.
    A name, at least one Event (trigger) and one Action is the minimum required information. 
  3. Each box contains an "info icon"    that will display explanatory information when hovering over it.
  4. If the rule needs to be executed with a specific user (i.e. other then the currently logged in user) when triggered, choose a specific user in the "Triggered rule will run as" menu.

     

  5. Save the rule by clicking the "Save" button.
     

    A rule can be modified any number of times (Event added, Action removed etc.) but it's ONLY when the "Save" button is clicked, that the rule will be stored.

    (thumbs up) To undo a change (deleted something by mistake?) on a previously saved rule, just click cancel and then start editing the rule again.

    All these steps will be explained in more detail further down the page.
      

Configure Events (WHEN box)

  1. Click the "Add a trigger" to bring up the "Edit WHEN" dialog to the right.
  2. Click the "Add Event", to start configuring an event.

  3. Choose the desired event and click the "Add" button to add the event to the new rule.



  4. If more then one event (triggers) are desired repeat the process until you are done.


(info) A maximum of 5 events are allowed for a rule.

(thumbs up) Instead of defining two or more rules with the same Actions (i.e. Email Notification), add two or more events and your rule configuration will be easier to maintain.

Event types

User events

Most events (except the: Scheduled event) are triggered when a logged in user performs that specific Action on a Insight object (e.g. Object updated, Attachment added etc.). These events do not require any additional configuration, simply choose the desired event and your done.

Scheduled events

As the name implies, these are scheduled events and are not triggered by a user action.
Instead, when the Cron Expression (i.e. once an hour, once a day) dictates that the rule should run and the Condition holds true for one or more Insight objects.

The two required parameters are:

  1. Condition: This is a IQL expression and when the scheduled rule is activated, all Insight objects that are matched by the Condition, will trigger an individual Action. 
    For more details, please refer to: IQL - Insight Query Language
  2. Cron Expression: This determines when and how often the provided Condition will try to match Insight objects, in order to perform the Actions configured for this rule.
    By default, the expression is set to " 0 0 12 1/1 * ? *", that is: once a day at noon (Thursday, April 28, 2016 12:00 PM, ...) but can of course be changed to the desired need.
    FreeFormatter is a formatting tool to help you generate Cron expressions that are suitable for use in Insight.

(warning) Scheduled events MUST have a specific user as "Run as". This due to the fact that they are not triggered by an action from a logged in user.

Configure a Condition (IF box)

A Condition can be seen as an "Insight object Action filter", that we configure when we don't want the configured Action(s) to apply to all our Insight objects in the schema but rather a specific set of Insight objects that should be included when a rule have triggered. 

  1. Click the "Any objects" to bring up the "Edit IF" dialog to the right.
  2. Click the "Add Condition", to start configuring a Condition.


     
  3. Enter the IQL statement and click the "Add" button to add the Condition to the new rule. 

    (info) A Condition always comes in pair with a THEN box.

    (info) One Condition is allowed for each IF box.

    (info) A maximum of three IF / THEN pairs can be configured.

Example

  • A rule has an Event: "Object Updated"
  • A rule has a Condition: "Name = Windows server"
  • A rule has an Action: "Notification Email"

This rule will ONLY send a Notification email IF the Insight object that was changed by a user has the exact name: "Windows server". This is just a fictive example of course, normally we don't want to configure such strict Conditions, but it clearly highlights how Conditions can and should be used.

Configure Actions (THEN box)

  1. Click the "Add an action" to bring up the "Edit THEN" dialog to the right.

  2. Click the "Add Action", to start configuring an Action.

  3. Choose the desired Action.




  4. Each Action will require configuration that is specific for each Action (i.e. the information needed in order to "Create a Jira Issue" is of course different from "Executing a Groovy Script")
    (thumbs up) Each Action and its parameters will be explained in a separate table below.
  5. If more then one Action are desired repeat the process until you are done.   

    (info) A maximum of 5 Actions are allowed for each "THEN" box.

Actions

The Action(s) that have been configured for a specific Event (and Conditions if specified) will be executed in a asynchronous manner. A note related to the asynchronous nature of Actions is the fact that the client will not be able to present a message related to the result of the executed action. In the case that the result of the action needs to be validated, besides the expected result (like actually receiving an Email notification), please refer to the Logging on troubleshooting section in the end of this page.

(info) All actions except Excecute Groovy Script have fields that support placeholders. For the specific details related to the semantics and syntax for placeholders, please refer to Insight with Placeholders

Attribute Value

This Action allows the Rule to change an attribute value.

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

Fields

Example syntax single valueExample syntax multi value (comma separated)

Attribute Name

StatusServer

Value

StoppedServer 1, Server 2

Create Jira Issue

This Action allows the Rule to create a Jira Issue.   

(warning) The Issue type selected must be available for the chosen project, otherwise a Jira issue cant be created.

(info) If the custom field is populated, the chosen project must be configured to handle this object type, otherwise this field will not have any effect.


Fields supporting placeholders

Example syntaxExample result

Summary

Server ${label} stopped! 

Server ${exchange.prod.main1} stopped!

Description

Server details - name: ${label}, key: ${Key}, id: ${id} 

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, a mail will be sent showing the changes related to the object that was modified.

(info) At least one of the two email related fields (Jira Recipients, External Recipients) must contain valid values.


Fields supporting placeholders

Example syntaxExample 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.

Execute Groovy Script

This Action allows a triggered Rule to execute a Groovy Script.

(warning) Ensure that the Groovy Script located by the specified "File path" has the adequate permissions so it can be executed by Insight Automation. 

 Data available to the Groovy script by the Insight Automation Rule Engine

Parameter nameDescriptionJAVA Class
objectThe 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 Action.

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

currentUser

The user that triggered the Rule or a specific user (Actor) configured 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


Read about groovy examples here

Http request

This Action allows a triggered Rule to make a Http request.

Supports the standard Http methods: GET / POST / PUT / DELETE

 (info) For POST and PUT, a message body field will be available, where the data (like JSON)


Fields supporting placeholders

Example syntaxExample result

Url

http://company/service?id=${id}&name=${label}

http://company/service?id=1405&name=exchange.prod.main1

Post Data (POST / PUT)

{ "name":"${label}","key":"${Key}","id":"${id}" }

{ name:exchange.prod.main1,key:WS-5969,id:76100 }

Adding more Conditions and Actions (ELSE IF / THEN)

A rule can only consist of one WHEN box (with one or several events), but several sets of IF / THEN pairs (up to three).

This allows us to execute one type of Action if our first Condition finds any Insight objects that matches the first Condition, otherwise the next IF Condition is evaluated and so on.

  1. Click the "Add IF / THEN" box and a new pair of ELSE IF / THEN boxes will appear.
  2. Add Actions (and a Condition if desired).
  3. Click "Save" to store the changes.

(info) A new ELSE IF / THEN pair can only be added IF the "last configured Condition" is different from "Any objects". As seen in the picture above, the last (the ELSE IF box) Condition will always match, and we can't therefore add any new IF / THEN configuration. If we add a Condition to the ELSE IF box, then a new IF / THEN configuration can once again be added.


Remove an ELSE IF / THEN configuration

  1. Click the trash can that is present in the bottom right corner for any ELSE IF box. That will remove the ELSE IF / THEN configuration from the rule.
  2. Click "Save" to store the changes.

Change "Triggered rule will run as"

Sometimes its desired to use a user different from the one that "triggered the rule". One example is when a Email Notification Action is executed and when we want a specific user to act as "the sender". 

  1. When editing a rule, select the drop down for "Triggered rule will run as"
  2. Select the radio button 
  3. Select a user and click "Change"

     
  4. Click "Save" to store the changes.

Show & Administer Rules

After creating your first rule, the starting page will show the list of rules configured.


ColumnMandatoryDescription
Name(tick)The name of the rule.
Description(error)The description of the rule.
Run as(tick)The user that will be used when executing the Actions for the rule. Default is "Logged in user" but can be set to a specific user.
Status(tick)Enabled or Disabled.
Last action(tick)Shows how long time ago the rule was last triggered.
Created(tick)Shows how long time ago the rule was created.
Updated(tick)Shows how long time ago the rule was updated.

Administrative operations

A number of administrative operations can be performed on each rule in the list.

They are accessed by clicking the "Wheel" on the right side for each rule.


OperationDescription
EditTo edit the specific rule.
CloneClones the specific rule. Convenient when a new rule will be similar to an already existing one.
DeleteDeletes the rule.
A confirmation dialog will be shown to prevent any undesired mistakes.
Disable / EnableAn enabled rule (default) can be disabled and thereby preventing the rule from triggering. A disabled rule can at any point of time be enabled again.
A confirmation dialog will be shown to prevent any undesired mistakes.
RunA Rule with Scheduled events, can be made to run instantly if so desired. Useful if Rule must be executed but its undesirable to change the current Cron Expression that dictates when and how often a rule is executed.
A confirmation dialog will be shown to prevent any undesired mistakes.
ResetAn Action can be configured with an "Idle interval" that prevents the Action to be executed a certain amount of time after the last execution. "Reset" will remove this "idle time" allowing an "Idle" Action to be ready for execution again.
A confirmation dialog will be shown to prevent any undesired mistakes.


Edit an existing Rule

To edit an existing rule, in the rules list, click: "Wheel" > Edit

Edit an existing Event, Condition or Action

  1. Just click on the box (WHEN, IF, THEN) that represents the specific item that should be reconfigured.

  2. That will once again bring up the "Edit" dialog

  3. Click "Edit", make the desired changes.

  4. Click the "Change" button to keep the changes.

  5. Click "Save" to store the changes.

Remove an existing Event, Condition or Action

  1. Follow the same steps as described in section above: "Configure existing Event, Condition or Action" but instead of clicking "Edit", click the trash can. 
  2. Click "Save" to store the changes.

Logging on troubleshooting

Add log level "DEBUG" on package "com.riadalabs.Jira.plugins.insight.services.automation" if you want to get more information when throubleshooting.