Actions for advanced and time-based enrichment

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

Actions can be of the following types:

• Actions that help you define conditions to get a subset of matching events. For example, use the Lookup action to retrieve existing events that match the specific criteria.
• Actions that help you define conditions to further enrich matching events. For example, 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.

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 Lookup, Unless, Trigger-If, and Timeout are non-root actions.   

Common actions

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

• Variable
• if-Then-Else
• Enrich

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.
  

You can reuse variables for building conditions for processing events. You can specify the variable name as the value of these actions.

You can specify variables by selecting previously-defined variables from the list of slots. Alternatively, you can specify variables in text strings. For example, you can specify a variable as an input for specific functions, or you can add the variable as a text string value for the Enrich action. You can also add the variable as a text string value for the Variable action. 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 and global variables that have either the String, Number, or Boolean data types.
  List of string	Displays slots and global variables that have the List of String data type.
  Number	Displays slots and global variables that have the Number data type.

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

To learn how to use the variable action in the policy workflow, see the following topics:

• Example-Check-whether-there-is-a-time-delay-between-events
• Example-Enrich-events-according-to-the-event-hostname-and-event-message

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. If you specify multiple classes in the event selection criteria, refer to the following points:

• The event slots present in all the classes in the event selection criteria are displayed for selection in the following sections:
  • If action of an enrichment policy
  • Slot placeholder fields of an enrichment, correlation, and notification policy
• The event slots that are common to the multiple classes are suffixed with the name of the event class in the enrichment, correlation, and notification policy.
• An event slot is not suffixed with the name of the event class if the slot is not present in all the classes that you specify in the event selection criteria.

In a policy workflow, under If Settings, you can define a condition by specifying slots and existing variables. You can specify local variables on both the left and right sides of a condition. However, you can specify global variables on only the right side of a condition. 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, see Exporting-events.

With the If-Then-Else construct, you can separate conditions and add more complex workflows for your use case. To do this, you can use multiple branches in a workflow or define a branch within a branch. This feature can help you separate conditions and add more complex workflows to cater to your use case.

To learn how to use the if-then-else action in the policy workflow, see Example-Assign-open-events-to-specific-people-and-change-the-event-severity-and-status.

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. If you specify multiple classes in the event selection criteria, refer to the following points:

• The event slots present in all the classes in the event selection criteria are displayed for selection in the following sections:
  • Enrich and If action of an enrichment policy
    Enrich action: Event slots are displayed in Slot to enrich and on the Event Slot tab in the action value.
  • Slot placeholder fields of an enrichment, correlation, and notification policy
• The event slots that are common to the multiple classes are suffixed with the name of the event class in the enrichment, correlation, and notification policy.
• An event slot is not suffixed with the name of the event class if the slot is not present in all the classes that you specify in the event selection criteria.

For instructions on specifying multiple classes, see Creating-and-enabling-event-policies.

For example, the following slots are displayed if you specify the Anomaly and Alarm class in the event policy selection criteria:

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. 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 and global variables that have either the String, Number, or Boolean data types.
  List of string	Displays slots and global variables that have the List of String data type.
  Number	Displays slots and global variables that have the Number data type.

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

To learn how to use the enrich action in the policy workflow, see Example-Enrich-events-according-to-the-device-status.

Actions specific to advanced enrichment

The following actions are specific to the advanced enrichment policy:

• Function
• Lookup
• Unless
• Trigger-If

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.

To learn how to use the function action in the policy workflow, see Example-Generate-events-to-check-application-availability.

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.
  By default, this setting does not lookup events that are closed. If you want to lookup closed events, contact BMC Support.

  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.

To learn how to use the lookup action in the policy workflow, see Example-Drop-duplicate-events-and-update-the-existing-event-with-new-severity.

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. 

To learn how to use the unless action in the policy workflow, see Example-If-change-event-does-not-exist-drop-the-related-task-event.

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 the Trigger-If settings, you need to specify:

• The slot that needs to be monitored for changes. Slots that have the Enum, String (for example, Message), and Integer (for example, Repeated) data types are supported. Read-only and hidden slots are not listed but internal slots are listed.
• Conditions to monitor the value. You cannot specify a global variable or a slot name in an incoming event to replace the slot value.
  
  • The new slot value matches the given condition.
  • 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 slot value can change from:

• Any value to any value (The Trigger specific Criteria and If value was check boxes are not selected).
• Any value to a specific value (Only the Trigger specific Criteria check box is selected).
• A specific value to a specific value (Both The Trigger specific Criteria and If value was check boxes are selected).
  For incoming events, only the Trigger specific Criteria option is considered and the If value was option does not apply.
  The If value was option is considered only if the Apply for Existing events only option is selected.

The action is triggered each time the monitored slot's value changes.

To learn how to use the trigger-if action in the policy workflow, see Example-Close-events-when-the-event-priority-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 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 Timeout settings, you need to specify:

• The duration
  For the duration, you can specify a delay after which the policy is executed by using one of the following options:
  • Specify a static number in the duration field.
  • Click Select duration slot, and from the slot list, select an event slot or a global variable that has the integer data type.
    This option allows you to specify a dynamic delay based on the slot value of an incoming event.
    If you specify multiple classes in the event selection criteria of a policy, the duration field displays slots that are common to the multiple classes.

• Unit for the duration
  You can specify one of the following units:
  • Seconds
  • Minutes
  • Hours
  • Days

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.

To learn how to use the timeout action in the policy workflow, see Example-Set-a-timer-to-run-enrichment-actions.

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.