Dynamic event enrichment actions

Actions are like conditions that are run sequentially on a selected event. 

Unlike an advanced or time-based enrichment policy, the policy workflow or the sequence of actions for a dynamic enrichment policy is predefined and fixed. In the policy workflow, click an action to view and configure the settings. 

According to the predefined sequence, you first import an external enrichment source file; then you define slots for which you need to match values in the external file; and lastly you define the slots for which you need to enrich values using the external file.

Each incoming event that matches the event selection criteria must go through this fixed set of conditions sequentially. 

The following image illustrates the dynamic enrichment process at a high level:

The following sections describe the settings that you need to specify for each of these actions while you are creating a dynamic enrichment policy. Note that the dynamic enrichment policy is an extension of the advanced enrichment policy.

Import

Use the Import action to import an external CSV source file with appropriate data.

In the policy workflow, under Import Settings, you can download the sample source file, make changes, and then attach the file. This data in the source file must correspond to the match and enrichment slots that you want to define in the policy. For more information, see Defining an external source file for dynamically enriching events.

Until you import a source file that matches the supported format, you cannot go to the next step of defining match slots. 

Match

Use the Match action to define match slots to be used for matching data in the imported external file.

A dynamic enrichment policy helps you define a bulk of If-Then scenarios, such as:

• If Slot A=<value1>, then update Slot B with <value2> 
• If Slot A=<value1> and Slot B=<value2>, then update Slot C with <value3>
• If Slot A=<value1> and Slot B=<value2>, then update Slot C with <value3>, and update Slot D with <value4>.

In the policy workflow, under Match Settings, select the slots that correspond to the match fields in your source file. These match slots represents the If condition.

For example, suppose your external source file contains the following information (severity and message details):

For this scenario, in the policy, under the Match Settings, you need to provide the following inputs:

• Select the Severity slot to match the first value in the source file. Because there are only two values per row, the message can be considered as an enrichment field.
  At run time, the first value in the first row (MAJOR) is matched with the Severity slot of an incoming event. If the severity value in the source file matches with the severity of the incoming event, the policy proceeds forward to the enrichment step. Otherwise, the process carries on until a match is found.
• You can also set the following matching preferences:
  • First Match: Searches each row of the source file sequentially, starting at the top, until it finds the first match.
  • Best Match: Searches each row of the source file sequentially, starting at the top, until it finds the best match according to the following order of matching preference:
    1. exact match

    2. starts with

    3. ends with

    4. contains

    5. regular expressions

    6. any

It is important that the source file contains the same number of match and enrichment values and in the same order as the source file.

Suppose, you want to enrich the Message slot based on the severity and status values.

You want to enrich event data based on the following If-Then condition:

• If: Severity and status of an incoming event equals the values given in the source file.
• Then: Update the Message slot based on the corresponding value given in the source file.

In this scenario, it is important that the source file provides information in the following order and the same order is applied while selecting the match and enrichment slots in the policy:

1. Match value 1 (severity information)
2. Match value 2 (status information)
3. Enrich value 1 (message information)

Also, in the matching values, you can specify an asterisk (*) as the wildcard character and regular expressions. You can also specify slot names as placeholders (%slotname%) in the values for enriching. In the external CSV source file, you can specify placeholders only for slots that have the String data type (for example, message, location, and so on).

The following examples can help you understand how to specify wildcards, regular expressions, slot placeholders, and how matching is conducted.

Example: Source file for specifying wildcard characters and slot placeholders

In the following table, each column corresponds to a type of slot value:

• Column A corresponds to the Severity match slot.
• Column B corresponds to the Location match slot.
• Column C corresponds to the Owner (or the assigned user) match slot.
• Column D corresponds to the Message enrichment slot.

In the values to be used for matching, you can specify asterisk as the wildcard character. In the values to be used for enriching, you can specify slot placeholders. When the policy is applied, the slot names are replaced with appropriate slot values from the incoming event.

In the preceding table, you can see how a leading asterisk, a trailing asterisk, and an asterisk all by itself is specified in the values to be used for matching. You can also see the placeholder slots (%slotname%) specified for the values to be used for enriching.

At the time of matching, if the matching preference is set to Best Match, then the following order of preference is applied:

1. exact match (for example, CRITICAL)
2. starts with (for example, CRIT*)
3. ends with (for example, *RITICAL)
4. contains (for example, *RITIC*)
5. any (for example, *)

Column E in the following table indicates how the values would be processed based on the Best Match and First Match preference:

Example: Source file for specifying regular expressions

In the following tables, each column corresponds to a type of slot value:

• Column A corresponds to the match slot, Location.
• Column B corresponds to the match slot, Status.
• Column C corresponds to the enrichment slot, Owner (or the assigned user).

Source file 1

Source file 2

Source file 3

In the values to be used for matching, you can specify regular expressions.

In the preceding table, you can see a few examples of regular expressions (.*, [a-z], ab*c, [^a], a+, a?) that you can specify in the values to be used for matching.

At the time of matching, if the matching preference is set to Best Match, then the following order of preference is applied:

1. exact match 
2. starts with
3. ends with
4. contains
5. regular expressions
6. any

Refer the following table to understand how the values in the example source files would be processed based on the Best Match and First Match preference:

• Column A corresponds to values in the incoming event
• Column B corresponds to the example source file number
• Column C corresponds to the best match (row number in the example source file) 
• Column D corresponds to the first match (row number in the example source file) 

Enrich 

Use the Enrich action to define the enrichment slots to be used for updating the event data by using appropriate values from the source file.

This step is the last step in the dynamic enrichment process. 

In the policy workflow, under Enrich Settings, select the slots that correspond to the enrichment fields in your source file. These enrichment slots represent the Then condition.

The total number of match and enrichment slots must be equal to the number of values specified in the source file and in the same order. 

If the match condition is satisfied, the policy picks up the value in the appropriate position in the source file and then uses that value to update the specified enrichment slots in the incoming event.