This documentation is for Insight for Jira Cloud only.



Summary

Learn how to use the Automation feature in Insight Cloud.

In this article

What does Automation do?

Insight Automation enables an administrator to create Rules that can automatically perform Actions on object/s or groups of objects based on Events. Examples of few events could be: object created, updated or deleted, while an example of an action could be changing the attribute value on the object/s.

Configuring rules requires at least Insight Schema Manager permissionInsight Administrators and the global permission Jira Administrators can always access Insight Automation too.















Set up a new rule

To set up a new rule, follow the steps below:

  1. Click on InsightObject Schemas from the left panel (this will change if you have switched to the new nagivation menu )on your Jira cloud instance and select Configure on the schema that you want to set the automation rule/s for. You can also reach the configuration through Object Schema → Configure.
  2. Then, select tab: Automation.






  3. You can either create the first rule when you click on "Be the first to create one" or click on "Create New Rule" if previous rules already exist.











Configure Rules

When you click on either of the options as mentioned above, you will reach the configuration screen for automation. This defines the overview of the automation rules that you want to set up. On this screen, execute the following steps to define an automation rule:

  1. Enter the name of the rule. This MUST BE provided.
  2. Enter the Description of the rule which is a guide to explain the rule.
  3. Enter the "Triggered rule will run as" field at the right side. This user MUST BE either an Insight Manager on the schema OR  Insight Administrator.
    1. Configure the trigger (WHEN):  Select an appropriate event. At least one trigger MUST BE defined. 
    2. Configure the conditions (IF): Select objects for this rule.
    3. Configure the actions (THEN): Select actions to be taken for this rule. At least one action MUST BE defined.
    4. Each box contains an "info icon"    that will display explanatory information when you hover your mouse over it.
  4. You can save the rule by clicking on the Save button at the right. You can also click Cancel and exit if you want to define this rule later.



Rules can be modified in case you need to change the event, conditions or actions. Examples of a rule:

  • Trigger - WHEN an object type "Licence" gets updated
  • Condition - IF "expiry date" on "License"  is greater than due date
  • Action - THEN the status for License must be set to "INACTIVE" 






Configure WHEN (Triggers) 

A trigger is the event on which the automation rule is executed. It can be defined by the WHEN block as highlighted below.

  1. Click on Add a Trigger which opens a dialog "EDIT WHEN" at the right side.



  2. Click on Add Event on the dialog and that will bring up the options to select the event. The events could either be initiated by a user or through a cron schedule.




  3. Once you select the event you want to define, click on the Add button. You may Cancel in case you want to define this later.



























A maximum of 5 events can be configured.




Types of Events

Events could either be triggered by a user or cron schedule.

The following events get triggered on a user action:

  • Object created
  • Object updated
  • Object deleted
  • Comment added
  • Comment edited
  • Comment deleted
  • Attachment added
  • Attachment deleted

The following event gets triggered by a cron schedule that you provide when you configure the rule.

  • Scheduled event - As the name suggests, these are events that are scheduled by setting up a Cron Expression and a Condition as shown in the screenshot below.


The two required parameters are:

  • Condition: This is a IQL expression and when the scheduled rule is run, all Insight objects that are matched by this Condition, will be considered for Configure IF and Configure THEN parts of the rule. This is required field since the Configure IF piece of an automation rule can be occasionally empty. This will ensure that there is an initial list of filtered objects against which the Configure IF and Configure THEN work.
  • Cron Expression: This determines when and how frequently the provided Condition will try to match Insight objects.
    By default, the expression is set to " 0 0 1 * *", that is: at 00:00 on day-of-month 1. This can of course be changed the way you want to schedule the event. 

How to set up cron expressions

A cron expression is a string of 5 or 6 fields separated by spaces. The following table displays the fields of a cron expression, in the order that they must be specified (from left to right):

Possible values0-590-590-231-311-12 OR JAN-DEC1-7 OR SAT-SUN
  • Insight does not support Year as an option in cron expressions.
  • The cron expressions support standard GMT timezone, which means you must specify cron expressions from this timezone reference.
  • If your cron expression has just 5 characters, it will mean that the Seconds field is not considered. E.g. if the cron expression is: 10 * 1 JAN *, it means the job will run: At minute 10 on day-of-month 1 in January

You can use certain special characters in cron expressions. These have been described in the table below.

*This indicates any value. E.g. the cron expression * * * * * means At every minute.
/This denotes the step values. E.g. the cron expression */5 * * * * means: At every 5th minute.
-This indicates a range of values. E.g. the cron expression */10 * 1 JAN MON-TUE means: At every 10th minute on day-of-month 1 and on every day-of-week from Monday through Tuesday in January.
,This is used for value separator. E.g. the cron expression */10 * 1 JAN MON,TUE means: At every 10th minute on day-of-month 1 and on Monday and Tuesday in January.





Configure IF (Conditions) 

A condition is specified to select objects which should be affected by the automation rule. It is specified with the help of IF block as highlighted below.

  1. Click on Any Object which opens a dialog "EDIT IF" at the right side.





  2. Click on Add Condition on the dialog and this will bring up the options to define the condition. The condition is defined using IQL. All objects resulting out of the IQL are selected for this rule.

    In case a condition is not defined, this rule will be applied to all objects on the schema. Hence, you may want to define the condition.

  3. After you have defined the condition, click on Add to save the changes. Click Cancel in case you want to define this later. You can configure up to 3 conditions. To do this, click on ADD ELSE/THEN block.






Configure THEN (Actions)

An action is a task that is carried out on the objects selected in the condition. E.g., Changing an attribute value for the object/s. You can do this with the help of the THEN block as highlighted below.

  1. Click on Add an Action and this will open a dialog "EDIT THEN" at the right side.




  2. Click on Add action on the dialog that will bring up the actions that can be defined for the rule.

  3. After you have defined the action, click on "Add" to save your changes. Click on "Cancel" if you want to do this later.












An action is always paired up with a condition. So, multiple IF/THEN blocks can be configured.





Types of Actions

Attribute Value

  • This allows you to change the value of an attribute of object/s selected out of the condition defined earlier. To do that, fill in the following fields:
  • Attribute Name - the attribute that you want to change.
  • Value - the new value that you want to set to the attribute.
  • You can also use placeholders in the Value field for e.g, ${label} etc. to set new values. The fields are shown in the screenshot below.

Http Request

  • This action allows you to make an HTTP request to a specified URL. All the fields for this action are shown in the screenshots below.
  • You can either do a GET, POST, PUT or DELETE request.
  • When you select any request from the Http method field you have to provide a mandatory request URL
  • You also need to enter the credentials User name and Password which you need to access the URL.
  • The Password field has an Update button adjacent to it and both of them work as follows:
    • While creating a new rule, the Password field is disabled by default. You have to click on the Update button next to the field so that you can enter a value for it.
    • While editing an existing rule, the Password field is displayed as masked irrespective of whether a value for it was entered or not when you created the rule. If you want to change it, you need to click the Update button. The field will be cleared and you can enter a new one. In case you click the Update button accidentally, then you need to click on the Cancel button and start editing again.
  • In case of the POST and PUT request, an additional field of Post Data is mandatory to be filled in. This field contains the request body data.
  • The URL and Post Data fields both allow use of placeholders. E.g, ${label} etc.
  • When you get a response from the Http request, you can extract fields from this response and use it to update the objects in your schema. To make this work, you need to specify following two fields on the form:
    • Attribute Name: The attribute to be updated in your object on the schema.
    • Value: The key of the field from the JSON response whose value will be used to update your object.





Example Scenario for Http Request action

Suppose, you have an Employee Onboarding schema for your new employees under which you have an Employee object. You want to update the attribute "Tax Return Number" on this object. The value for this field can only be determined by making an HTTP request to an external service.

So, you make a call to this service and get the following JSON response:

{
    "person": {
        "ssn": 1234567890,
        "first-name": "Foo",
        "last-name": "Bar",
        "address": "ABC, 123",
        "tax_return_status": "VERIFIED",
        "tax_return_number": 12345
    }
}

Now, you want to extract the tax return number from this JSON response. In order to make this work, you will specify the following in the Http Request action form:

Attribute Name: "Tax Return Number" (This is the name of the attribute in your Employee object of Employee Onboarding schema).

Value: person.tax_return_number (This is the key of the field from the JSON response shown above whose value will be used to update the Employee object). So when this automation rule runs, the value "12345" will be updated to the "Tax Return Number" attribute of your Employee object.

You need to have the response in JSON format to be able to extract field values.

You have to specify a key from the JSON response starting from the root element. In the example above, "person" is the root element of the JSON and hence the key you must provide is "person.tax_return_number". No other filters or operators to query the keys are supported as of now.

Additionally, the one other key that you can use in Value is "response.status-code". This will extract the status code of the HTTP response object(e.g, 200) that you may want to use to update any of your object attributes, if needed.

Create a Jira issue

  • This action allows you to create a Jira issue in your project.
  • You have to select the project in which the issue needs to be created by the Project field.
  • You have to also select the mandatory Issue Type and Priority fields. If the selected Issue Type is unavailable for the selected project, the issue will not be created. 
  • You can select a particular Assignee or let it be automatically assigned as per your project settings.
  • Enter a Summary and Description for the issue. You can use placeholders here. E.g, ${label}, ${Key} etc.

All of the fields described are shown in the screenshots below.


Email Notification

  • This action allows you to send email notifications.
  • Recipients who will be notified, can be specified by either of the fields below. At least one of them must be specified. 
    • Jira Recipients - Select users that have an account in Jira.
    • External Recipients - Provide any external user's email. For multiple recipients, insert a comma separated string of email addresses.
    • Recipients by Attribute - Select the user by the Email/User/Group attribute type of any object type in the schema. E.g, You have object type  "Computers"  in your schema which has an attribute type "User". So this "User" option will be available in Recipients by Attribute dropdown field. If you select it, an email will be sent to the email address present in that User object. 
  • You must fill in the content for the email using Subject and the Message fields. You can use placeholders here. E.g, ${label}, ${Key} etc.

All of the fields described are shown in the screenshots below.

Please note that the email address specified in any of the recipients' fields will be notified if and only if the respective user has unhidden their email address from public under his/her profile settings.