Actions for advanced and time-based enrichment

Actions are like conditions that are run sequentially on each event that matches the event selection criteria. 

Some actions help you define conditions to get a subset of matching events and other actions help you define conditions to further process or enrich matching events. For example, you can use the Lookup action to retrieve existing events that match the specific criteria. You can use the If-Then-Else action to process events in a specified way and the Enrich action to enrich event information. Based on your use case, you can combine various actions to build the refinement, advanced enrichment, and time-based enrichment policy workflows. The refinement policy is similar to the advanced enrichment policy.

Actions can be classified as: 

• Root action, which is the highest action in the workflow structure. This action has no parent. This action can have one or more child actions, but cannot have a sibling action or be repeated in the same workflow. You cannot add more than one root action in the same workflow. Lookup, Unless, Trigger-If, and Timeout are root actions.
• Non-root action, which can occur anywhere in the workflow structure and can be repeated multiple times in the same workflow. All actions other than the root actions are non-root actions.   

The following actions are supported for building a policy workflow. Some actions are common and some are specific to advanced enrichment and time-based enrichment policies.

Common actions

The following actions are common to refinement, advanced enrichment, and time-based enrichment policies.

Variable

Use variables to point to static text, event data (values of event slots), results of mathematical functions, and values of previously defined variables. Variables have the following types:

• Local variables: These variables can be used only within an enrichment policy and are prefixed with a dollar sign ($).
• Global variables: These variables can be used to share data across enrichment policies, which means they can be referred to in any other event policy. These variables are prefixed with $GV. Set attributes for these variables in enrichment policies by using the Set global variable check box as shown in the following example:
  
  
  Do not select the check box if you want to set only local variables. You can also specify global variables in the event selection criteria while creating event policies and in the notification settings while creating a notification policy.

Variables can be reused for building conditions for processing events, such as the If-Then-Else, and Enrich actions. You can specify the variable name as the value of these actions.

Variables are treated in the same way as slots. Therefore, while defining conditions for processing events, you can add variables in the same way as you add slots. For example, while defining conditions for actions such as If, Lookup, or Unless, you can select previously defined variables from the list of slots.

You can also specify variables in text strings. By default, variables are always considered as string values. For example, you can specify a variable as input for particular functions or you can add it as a text string value for the Enrich action and similarly, you can add it as a text string value for the Variable action. However, you can convert variable values from String to other data types based on your needs for managing variable values. You can do this by using the following converter functions in advanced enrichment policies:

• StringToInteger
• StringToReal
• Split (String to List of String)

You can also use variables to convert other data types to String. For more information, see Functions for advanced and time-based enrichment.

At the time of processing events, the variable name is replaced with the value of the variable.

In the policy workflow, under Variable Settings, you can set one of the following values:

• Text string: Assign a text string containing alphanumeric characters.

• Variable: Assign an existing variable’s value to this variable. 

• Function: Assign the function value as the variable value. To understand the supported functions, see Functions for advanced and time-based enrichment.
  The function parameters display slots based on the data type of the function parameter as shown: 

  Data type of parameters	Slots available
  String	Displays slots that have either the String, Number, or Boolean data types.
  List of string	Displays slots that have the List of String data type.
  Number	Displays slots that have the Number data type.

• Event Slot: Assign the slot value as the variable value.

If-Then-Else 

The If-Then-Else construct represents a conditional execution. If the condition specified in the If action is evaluated as true, the Then action is run. If the condition specified in the If action is evaluated as false, the Else action is run. The Else action is optional. 

In the policy workflow, under the If Settings, you can define a condition by specifying slots and existing variables. The process of constructing the If condition is very similar to constructing the event selection criteria for event policies. If you specify a condition that consists of an event class, manually specify the internal name of the class in the condition. To know the internal name of a class, export an event. For instructions on exporting an event, Exporting events.

The If-Then-Else construct allows you to create branches in the policy workflow. You can have multiple branches in the workflow. You can even define a branch under a branch. This feature can help you separate conditions and add more complex workflows to cater to your use case. 

Enrich

Use this action to enrich event data with meaningful user-specified data, data from other events, or results of functions and existing variables.

You can enrich event information by assigning a new value to the selected event slot. Events come with a set of out-of-the-box slots. However, if you want to change a piece of event information that is not already captured by the out-of-the-box slots, it is important that you have existing custom slots. While defining the enrichment conditions, you can select the custom slot to enrich.

 In the policy workflow, under Enrichment Settings, you can select a slot to enrich, and set one of the following values:

• Text string: Assign a text string containing alphanumeric characters as the slot value. You can specify slot values in multiple lines for the Message and Detailed Message event slots. For slots that have the String data type, you can add a line break to move content to a new line by using the <br> tag.

• Variable: Assign an existing variable’s value as the slot value.

  Important

  While creating a workflow, you can assign existing variables that are defined until then in the current workflow, as long as they are in the same branch of the workflow.

• Function: Assign the function value as the slot value. To understand the supported functions, see Functions for advanced and time-based enrichment.
  The functions list displays function based on the data type of the slot that you enrich as shown:
  

  Data type of slots	Return functions available
  String	Displays functions that return either a String, Number, or Boolean value.
  List of string	Displays functions that return a List of string value.
  Number	Displays functions that return a Number value.

  
  The function parameters display slots based on the data type of the function parameter as shown:
  

  Data type of parameters	Slots available
  String	Displays slots that have either the String, Number, or Boolean data types.
  List of string	Displays slots that have the List of String data type.
  Number	Displays slots that have the Number data type.

  
  
• Event Slot: Assign another slot's value as the slot value.

Actions specific to advanced enrichment

The following actions are specific to the advanced enrichment policy.

Function

These functions are void functions that do not return a value. Therefore, these functions are different from the functions that can be added as the value for Variable and Enrich actions.

For more information, see Functions for advanced and time-based enrichment.

Lookup

Use this action to retrieve information from the event repository of existing events. The resulting events can be used for further processing. This action is a root action and therefore, must always be specified at the top of the workflow before other actions. 

In the policy workflow, under Lookup Settings, you can:

Specify whether you want to lookup one of the following:

• Duplicate events that are associated to custom classes. To do this, select a custom class. 
  By default, duplicate events associated to out-of-the-box classes are dropped. Therefore, you cannot lookup such events even if you select an out-of-the-box class under the Lookup events containing Class list.

  Important

  Suppose you selected the criteria of With duplicate events and in the subsequent action if you selected Update old events followed by another action, for example Enrich action.

  In this scenario, if the events matching the criteria have missing dedup values, all the matching events are updated.

  If you select the criteria of With duplicate events, duplicate events that are not closed are looked up and retrieved based on:

  • <dedup_slots> for event classes containing dedup slots
  • ID for event classes not containing dedup slots

  If you use the Enrich action to enrich slots in the existing event after you select Update old events, the repeat count for the event is auto-incremented.

• Events matching a custom criteria associated to all the classes irrespective of whether it is out-of-the-box or custom.
  For custom criteria, you must specify a condition. This is similar to constructing the event selection criteria.

  Important

  We recommend that you avoid specifying a generic condition to lookup events. For example, a generic lookup condition in which you lookup events of only a specific class.
  If you still want to specify a generic condition, make sure that you configure the lookup to fetch only the latest events (Last occured option) to avoid enrichment policy performance issues.

The event class value defaults to the class specified under the event selection criteria. If no class is specified, the base EVENT class is considered for the event selection criteria, and therefore, the value defaults to the base class value.

Under the settings, if you:

• Do not change the value: The same class is used to lookup existing events and incoming events. 
• Do change the value: The new class value is used to lookup existing (or old) events and the class specified in the event selection criteria is used to lookup incoming (or new) events. 
  While building the condition, you can specify slots prefixed with $OLD and $NEW. Slots prefixed with ‘$OLD’ refer to slots of existing events and slots prefixed with ‘$NEW’ refer to slots of incoming events. This feature allows you to add conditions to compare old and new slot values.

Additionally, you can define whether you want to consider all events or only the latest events matching the Lookup condition. You can also define the duration for the lookup in seconds. If the duration is not specified, the duration is assumed to be active as long as the policy is active. The lookup will continue, until the policy is disabled or deleted.

After configuring the Lookup conditions, you can configure actions to update new events (or incoming events) and old events (existing events). This action allows you to create a logical branch in the policy workflow. Under each branch, you can add subsequent actions for enrichment or further processing. You can even configure actions to update only new or only old events. 

Unless

This action applies the subsequent action(s) only if the specified query condition does not find a match. The Unless action is similar to Lookup, but the logic is reversed.

This is a root action and therefore, must always be specified at the top of the workflow before other actions. 

Similar to the Lookup action, in the policy workflow, under Unless Settings, you can:

• Specify an event class to query events belonging to that class 
• Specify a condition to query events matching the condition. This is similar to constructing the event selection criteria.

The event class value defaults to the class specified under the event selection criteria. If no class is specified, the base EVENT class is considered for the event selection criteria, and therefore, the value defaults to the base class value.

Under the settings, if you:

• Do not change the value: The same class is used to query existing events and incoming events. 
• Do change the value: The new class value is used to query existing (or old) events and the class specified in the event selection criteria is used to query incoming (or new) events. 
  While building the Where condition, you can specify slots prefixed with $OLD and $NEW. Slots prefixed with ‘$OLD’ refer to slots of existing events and slots prefixed with ‘$NEW’ refer to slots of incoming events. This feature allows you to add conditions to compare old and new slot values.

If the condition specified is not satisfied, subsequent action(s) are run. 

Trigger-If

This action triggers the policy workflow of an incoming event or if a specified slot of an existing event is modified. This is a root action and therefore, must always be specified at the top of the workflow before other actions. Unless an event matches the conditions specified in this action, the advanced enrichment process cannot begin. 

In the policy workflow, under Trigger-If settings, you need to specify:

• The slot that needs to be monitored for changes. Only Enum type slots are supported.  
• Conditions to monitor the value:
  
  • If the new slot value matches the given condition.
  • If the previous slot value matches the given condition.

This feature allows you to monitor precisely when the slot value changes from or to a particular value. The action is triggered each time the monitored slot's value changes.

Actions specific to time-based enrichment

The following action is specific to the time-based enrichment policy.

Timeout

Use this action to set a timer after which actions are run on incoming events. This is a root action and therefore, must always be specified at the top of the workflow before other actions.

In the policy workflow, under Timeout settings, you need to specify:

• The duration

  Important

  We recommend that you specify a minimum duration of 30 seconds to avoid enrichment policy performance issues.

• Unit for the duration

The specified duration is calculated from the time the event arrived (_arrival_time slot).

You can add subsequent actions for enrichment or further processing. After the specified duration lapses, the subsequent actions are run.

Where to go from here

Now that you understand actions, see Building a policy workflow for advanced and time-based enrichment. You can also see workflow examples that show you how to combine various actions to achieve different use cases.