Creating a rule based on an external event

An Event object lets you to create rules based on internal and external events conditions. It enables you to respond to events based on defined rules that have been specially tailored for an Event.

The Event Engine feature can be used to react to internal and external events. The following use case is based on an external event that is launched by a powershell.

What will you Learn

How to create and define an Event Definition

How to create and define an Event Rule based on an Event Definition

How to launch an event via a script

Prerequisites

• Good knowledge of how to create AE Objects (Events)
• Good understanding how to create rules
• Knowledge of a powershell

Objective

• To trigger an example event based on an external script launch.

Objects used in this use case

Name	Object Type
Event Rule	Connection
IA Object	Executable VARA

Creating the Event Definition

1. Using the Add Object option, create an EVENT_DEFINITION variable. In the following example we have called itPS.TEST.EVENT.


2. Open the Event definition sheet. We now need to define our Key Attributes, describe them (optional) and assign a Type to them.

   • Attribute Key: Key Value Pair (for example application message, status event, acknowledgment and so on).
   • Description: Optional but advisable.

   • Type: You can either select String, Number or Boolean in relation to your Attribute Key.

   In our test example we have created 3 Key Attributes Count, Name and Statuswhich can be associated with our rules in the Rule Object.

   

3. Save the event.

Create the Rule Object

1. We want to create a Rule Object that under certain conditions, is triggered by our external event.

   We have already created an EVENT_DEFINITION variable that holds our Key Attributes and returns our defined Types. Now we have to associate them by creating a Rule.

   Using the Add Object option, create a SIMPLE_RULE Event.

   We have named ours PS.EVENT.TRIGGER.EXAMPLE for simplicity.

   

2. Open the Rule Event Object and in the Event Definition box, enter (or use the combo list) to link the Event Rule to the previously created Even Definition. In our example we need to link to PS.TEST.EVENT.


3. Using the Add Row button create a new row. We now need to define the Event Rule Conditions by setting the following:

   • We are going to link our Attribute in the condition with a Key Attributedefined in the Event definition. We will use in the Key Attribute Count defined in Event definition and create a new Attribute in the Rule Object called event.Count
   • Then we will assign a relevant operator, in our example we would like the event to be greater than ">" something.
   • Finally we designate a Value. Our condition is if the event.Count is greater (>) than 3 do something (i.e. execute a script, send a message and so on.

   

4. In the Action section, we set out the steps to be taken when the condition is met. From the Execute box we select an event to execute specific to our event.

   

5. Select the Attributes tab in the Rule Event object and select an IA Agent to execute the Rule on then click Save.

   

6. Finally Click Execute to run the Rule. Our Rule will now be displayed as Active in Executions.

   

   In the Details window of Execution we can also see that no rule has been triggered and therefore the Event count value remains 0.

   

7. To trigger our rule we've created a powershell script that sends events to the Event Engine.

   !get client specific api key
   :SET &KEY# = GET_VAR(VARA.API_KEY)
   :P &KEY#
   <#
   .SYNOPSIS
       Can be used to send events to the Automic Event Engine
   .DESCRIPTION
       Use this cmdlet to send events to the Automic Event Engine.
       It's making use of the Invoke-RestMethod commandlet and preconfigures everything.
       Creates the timestamp for the event automatically (current utc timestamp).
   .PARAMETER Uri
       The Uri to the endpoint for the events
   .PARAMETER Token
       The pre-shared key used for authentication with the Uri
   .PARAMETER Type
       The type of the Event, must match the Event Definition in the AE
   .PARAMETER Attributes
       The attributes of the event
   .PARAMETER Timestamp
       The timestampe (Event time) of the event, if empty current time in utc is used, timestamp will be converted to utc.
   .PARAMETER DisableKeepAlive
       Indicates that the cmdlet sets the KeepAlive value in the HTTP header to False. By default, KeepAlive is True. KeepAlive establishes a persistent connection to the server to facilitate subsequent requests.
   .PARAMETER Proxy
       Specifies that the cmdlet uses a proxy server for the request, rather than connecting directly to the Internet resource. Enter the URI of a network proxy server.
   .PARAMETER ProxyCredential
       Specifies a user account that has permission to use the proxy server that is specified by the Proxy parameter. The default is the current user.
       Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.
       This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.
   .PARAMETER ProxyUseDefaultCredentials
       Indicates that the cmdlet uses the credentials of the current user to access the proxy server that is specified by the Proxy parameter.
       This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.
   .EXAMPLE
       $data = @{
           Name="Tobi"
           Status="New"
           Count=3
       }
       C:\PS>send-event "http://path_to_ia/" "your-pre-shared-key" "IA.TEST" $data
       This will send the $data to the Event "IA.TEST" ($data is converted to json)
   
   .NOTES
       Author: Tobias Stanzel
       Date:   June 17, 2017
   #>
   function Send-Event {
       [CmdletBinding()]
       param (
           [parameter(Mandatory=$true,Position=0)]
           [Uri]$Uri,
   
           [parameter(Mandatory=$true,Position=1)]
           [string]$Token,
   
           [parameter(Mandatory=$true,Position=2)]
           [alias("t")]
           [string]$Type,
   
           [parameter(Mandatory=$true,Position=3)]
           [alias("a")]
           [hashtable]$Attributes,
   
           [parameter(Mandatory=$false)]
           [DateTime]$Timestamp,
   
           #Invoke-RestMethod Options
           [parameter(Mandatory=$false)]
           [Int32]$TimeoutSec,
   
           [parameter(Mandatory=$false)]
           [switch]$DisableKeepAlive,
   
           [parameter(Mandatory=$false)]
           [Uri]$Proxy,
   
           [parameter(Mandatory=$false)]
           [PSCredential]$ProxyCredential,
   
           [parameter(Mandatory=$false)]
           [switch]$ProxyUseDefaultCredentials
       )
       PROCESS {
           if(!$Timestamp){
               $Timestamp = Get-Date;
           }
           $utcString = $Timestamp.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ");
           Write-Verbose "Event time set to: $utcString"
   
           $Body = @{
               type = $type
               timestamp = $utcString
               values = $attributes
           }
           $BodyString = ConvertTo-Json($Body)
   
           $headers = @{ "Content-Type"="application/json";Authorization=$Token}
           $params = @{
               Method = "Post"
               Headers = $headers
               Uri = $Uri
               Body = $BodyString
           }
           if($VerbosePreference) {
               $params.Verbose = $true
           }
           if($DebugPreference) {
               $params.Debug = $true
           }
           if($DisableKeepAlive) {
               $params.DisableKeepAlive = $true
           }
           if($TimeoutSec) {
               $params.TimeoutSec = $TimeoutSec
           }
           if($Proxy) {
               $params.Proxy = $Proxy
               if($ProxyCredential) {
                   $params.ProxyCredential = $ProxyCredential
               }
               if($ProxyUseDefaultCredentials) {
                   $params.ProxyUseDefaultCredentials = $true
               }
           }
           Write-Verbose "Headers: $(ConvertTo-Json($headers))"
           Write-Verbose "Body: $BodyString"
           try {
               Invoke-RestMethod @params
               Write-Host "Event $type send successfull"
           } catch {
               # Dig into the exception to get the Response details.
               # Note that value__ is not a typo.
               Write-Host "StatusCode:" $_.Exception.Response.StatusCode.value__
               Write-Host "StatusDescription:" $_.Exception.Response.StatusDescription
               Throw $_.Exception
           }
       }
   }
   echo "Sending hardcoded event now via powershell cmdlet to Event Engine now..."
   $data = @{
     Name="Test Event"
     Status="New"
     Count=3
   }
   send-event "http://localhost:8090/analytics/api/v1/events" "&KEY#" "PS.TEST.EVENT" $data -v
   echo "Sending event again, with different count"
   $data.count = 4
   send-event "http://localhost:8090/analytics/api/v1/events" "&KEY#" "PS.TEST.EVENT" $data -v

   As a summary the script does the following:

   • Uses a cmdlet to send events to the Automic Event Engine.
   • Specifies that the user uses a proxy to make the request, ensuring security and network integrity.
   • Gets API keys from the Event Engine (needed to make requests). See:API Key Management

   • Sends an event to the API REST point "http://localhost:8090/analytics/api/v1/events"

     

8. Whenever the script is executed the Rule event increases because our data.count is set to 4. Our condition in the event definition states that anything greater than 3 should create an event.

   

   

Useful Links