Creating a Rule Based on an External Event

An Event object lets you create rules using internal, and external event conditions. It enables you to respond to events based on defined rules, that have been specifically 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.

This page includes the following:

What Will You Learn?

How to create an Event Definition
How to create an Event Rule based on an Event Definition
How to use a script to launch an Event

Prerequisites

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

Use Case Objective

To trigger an example event based on an external script launch

Objects in this Example

Name	Object Type
Event Rule	Connection
IA Object	Executable VARA

Create the Event Definition

On the Process Assembly page, select Add Object from the menu. From the Add Object window, select the VARA menu and then the EVENT_DEFINITION variable. In the following example, the event name is PS.TEST.EVENT.

Open the Event definition sheet. Define the Attributes, describe them (optional) and assign a Type to each of them.
- Attribute Key: Key Value Pair (example: application message, status event, acknowledgment, and so on).
- Description: Optional
- Type: You can either select String, Number, or Boolean in relation to your Attribute Key.
In the test example three Attributes have been created, Count, Name, and Status. These Attributes can be associated with the rules in the Rule Object.
Save the Event.

Create the Rule Object

Create a Rule Object, that under certain conditions, is triggered by an external event.

An EVENT_DEFINITION variable has previously been created, it holds the Attributes and returns the defined Types. These Attributes have to be associated with a Rule.

Select Add Object from the menu, and create a SIMPLE_RULE Event.

Note: The event is named PS.EVENT.TRIGGER.EXAMPLE for simplicity.
Open the Rule Event Object and in the Event Definition box, enter the Event Definition name (or use the combo list) to link the Event Rule to the previously created Event Definition. In the example, it has to be link to PS.TEST.EVENT.

Using the Add Row button create a row. Define the Event Rule Conditions by setting the following:
- Link the Attribute in the condition with an Attribute defined in the Event definition. Use the Attribute Count defined in Event definition, and create an Attribute in the Rule Object called Count
- Assign a relevant operator, in the example make the event to be greater than > something.
- Finally, designate a Value. If the Count is greater (>) than 3 do something (i.e. execute a script, send a message, and so on).
In the Action section, set out the steps taken when the condition is met. From the Execute box, select an event to execute specific to the event.
Select the Attributes tab in the Rule Event object and select an IA Agent to execute the Rule on then click Save.
Finally Click Execute to run the Rule. The Rule will now be displayed as Active in Executions.

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

The following PowerShell script sends events to the Event Engine to trigger the rule created:

!get client specific api key
:SET &KEY# = GET_VAR(VARA.API_KEY)
:P &KEY#
<#
.SYNOPSIS
    Can be used to send events to the CA AutomicEvent Engine
.DESCRIPTION
    Use this cmdlet to send events to the CA AutomicEvent 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

To summarize, the script does the following:

Uses a cmdlet to send events to the 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:Analytics REST API Key Management
Sends an event to the API REST point http://localhost:8090/analytics/api/v1/events

Whenever the script is executed the Rule event increases because the data.count is set to four. The condition in the event definition states that anything greater than three should create an event.