Functions for advanced and time-based enrichment
Functions are mathematical operations that can be performed to modify slot values and to retrieve information related to slot values. BMC Helix Operations Management offers event and return functions.
Event functions
Event functions are also known as void functions and do not return a value.
DropNewEvent
This function drops incoming events as they occur. After execution, the dropped events are not saved and are not available on the UI.
GenerateNewEvent
This function generates events for a specific event class. The following table lists the parameters and slots for the selected class that are displayed as inputs for the function. After execution, the generated event is displayed on the Events page.
Input
Input | Type | Description | |
|---|---|---|---|
1 | Event Class | ENUM | Out-of-the-box or custom class for which you want to generate the event. Default: Event Note: The Anomaly event class is not supported. |
2 | Event Severity | ENUM | Severity for the generated event. Default: Minor |
3 | Event Priority | ENUM | Priority for the generated event. Default: Moderate |
4 | Source Hostname | String | Host name of the event provider. We recommend a character limit of 256 characters. |
5 | Message | String | Message that you want to include in the generated event. Use the % character to include slot placeholders. When the policy is applied, the placeholders are replaced with values from the incoming event. We recommend a character limit of 1024 characters. |
6 | Source Identifier | String | Unique event source identifier which can be used for associating the event with the Entity/CI. We recommend a character limit of 256 characters. |
7 | Mandatory and dedup slots | Depends on the class you select | Mandatory and dedup slots for the selected class. Dedup slots may or may not be mandatory. If you do not mention a value in dedup slots, a blank value is considered for enrichment. For more information on mandatory and dedup slots, see Slot-facets. For example: If you select the Alarm class, Alarm ID is displayed as a dedup slot which is a mandatory slot. If you haven’t set a default value for a slot in the event class definition, the function considers the slot value that you enter. |
8 | Non-mandatory slots | Depends on the class you select | Choose additional slots to add in the generated event for the selected class by using the If you haven’t set a default value for a slot in the event class definition, the function considers the slot value that you enter. If you have set a default value for a slot in the event class definition, but you haven’t added the slot in the function. In this case, the default value for the slot is considered the slot value. Use the delete icon to delete the added slot. Once you add and save a slot from the list, the slot is disabled for selection. To enable the slot, delete and add it again. Supported data types for slots:
The date data type is not supported for slots. |
option. This option does not list the read-only or internal slots.To understand a use case for this function, see Example-Generate-events-to-check-application-availability.
AddOperation
This function adds a note in an incoming or existing event when an event is assigned, acknowledged, unacknowledged, closed, owned, declined, or prioritized. A note is a list of strings that contains information such as the timestamp, owner, and note content. The following table lists the parameters that are displayed as inputs for the function. After execution, the note is displayed on the Event Details page.
Input
Input | Type | Description | |
|---|---|---|---|
1 | Operation name | ENUM | Indicates the following event operations:
|
2 | Note | String | Inserts a note that you want to include in the event. We recommend a character limit of 256 characters. You can specify slot placeholders for this input; for example, %msg%,%severity%. You can manually specify variables for this input; for example, $dbname, $tablespace. When the policy is applied, the variable names are replaced with the variable values that you have configured in the policy workflow. |
To understand a use case for this function, see Example-Add-operation-note-for-event-assignment.
AddNote
This function adds a note in an incoming or existing event. The following table lists the parameters that are displayed as inputs for the function. The owner of the note is set to the event policy name. After execution, the note is displayed on the Event Details page.
Input
Input | Type | Description | |
|---|---|---|---|
1 | Note | String | Inserts a note that you want to include in the event. We recommend a character limit of 256 characters. You can specify slot placeholders for this input; for example, %msg%,%severity%. You can manually specify variables for this input; for example, $dbname, $tablespace. When the policy is applied, the variable names are replaced with the variable values that you have configured in the policy workflow. |
To understand a use case for this function, see Example-Add-notes-to-incoming-events-to-indicate-event-generation.
SetNote
This function modifies the note content for a specific note from a list of notes in an incoming or existing event. After execution, the modified note is displayed on the Event Details page.
Input
Input | Type | Description | |
|---|---|---|---|
1 | Position | Integer | The sequence number of the note that you want to modify. Notes are numbered, starting from 1 for the oldest note. To modify the most recent note, specify the position as 0. If you specify an incorrect position, an exception message is displayed in the _errors slot for the event. |
2 | Note | String | The new text of the note that you want to set in the existing note of the event. We recommend a character limit of 256 characters. You can specify slot placeholders for this input; for example, %msg%,%severity%. You can manually specify variables for this input; for example, $dbname, $tablespace. When the policy is applied, the variable names are replaced with the variable values that you have configured in the policy workflow. |
To understand a use case for this function, see Example-Retrieve-and-modify-notes-in-incoming-events.
LookupNodeDetails
This function fetches node details, such as node IP address, source, location, and so on, from BMC Discovery according to the Node ID (_node_id)slot and the topology lookup slots for an event class present in the incoming event. The fetched node details can further be used to enrich events. This function returns String or List of String node attribute values.
Input
Input | Type | Description | |
|---|---|---|---|
1 | Node Attributes to fetch | List | Comma-separated list of node attributes that you want to fetch from BMC Discovery. To refer to node attributes in BMC Discovery, run the GET/data/nodes/{node_id} endpoint by using the _node_id value present in an existing event. For more information, see Endpoints in the REST API. The state attribute returned in the API response contains the node attribute details that you could specify for this input. The attributes can be specified by using standard JSON path conventions. For example, the following attribute list can be used to retrieve node attributes: ["kernel", "os", "model", "kind", "__all_ip_addrs[0]"] After the attributes are fetched, you can use these attributes as local variables in the function input by using the $NODE prefix to further enrich events. For example, $NODE. kernel and $NODE.os. |
To understand a use case for this function, see Example-Enrich-events-with-node-details.
Return functions
Return functions are also known as non-void functions and return a value. Return functions are further classified into the following categories:
- String functions
- List functions
- Number functions
For an Enrich action, 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. |
For an Enrich or Variable action, 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. |
String functions
These functions are used for string manipulation operations such as concatenating strings, replacing strings, and so on. These functions use slots or variables with a string value.
Concat
Concatenates two text strings to return a new string.
Input
Expected output
Example
Input 1= Hello World
Input 2=[tagName1,tagName2,tagName3]
Output=Hello World[tagName1,tagName2,tagName3]
ConcatList
Concatenates a list of comma-separated strings using the given separator and returns a new string.
Input
Expected output
Example
Input 1= [tagName1,tagName2,tagName3]
Input 2= -
Output=tagName1-tagName2-tagName3
Contains
Detects whether a text string contains a substring.
Input
Expected output
Example
Input 1=v1v4v5v6
Input 2=v4
Output=true
CurrentFormattedTimeStamp
Returns the current timestamp with the date in the specified date format and the time zone in UTC. Use this function to enrich slots that have the string data type.
Input
Expected output
Example
Input =EEE, MMM d, “yy
Output=Wed, Dec 29, '21
To understand a use case for this function, see Example-Retrieve-the-timestamp-as-a-date-format.
GetPosition
Returns the position of the first character of the first occurred substring, reading left to right.
Input
Expected output
Example
Input 1=GetPosition v3 cool
Input 2=cool
Output=16
GetPositionOnOccurrences
If the substring occurred for the given number of times, this function returns the position of the first character of the final substring based on the number of occurrences specified, reading left to right.
Input
Expected output
Example
Input 1=city reno is called reno
Input 2=reno
Input 3=2
Output=21
MatchRegex
Matches a text string with a simple regular expression.
Input
Expected output
Example
Input 1=aaabbb
Input 2=a*b*
Output=true
Replace
Replaces part of a text string with another string.
Input
Expected output
Example
Input 1= Hello World
Input 2=World
Input 3=User
Output=Hello User
Split
Splits a text string into a list of substrings based on the separator occurring in the string.
Input
Expected output
Example
Input 1= Hello World
Input 2=" "
Output=[Hello, World]
StringLength
Returns the number of characters in a text string.
Input
Expected output
Example
Input 1=HELLO WORLD
Output= 11
StringMatch
Matches character patterns in a text string and extracts fields from it. The pattern can contain literal text and substitutes.
Input
Expected output
Example
Input 1=Hello World 2021
Input 2=Hello %s %d
Output=[World,2021]
StringToInteger
Converts a text string that represents a number to an integer value.
Input
Expected output
Example
Input 1=20
Output=20
StringToReal
Converts a text string that represents a real number to a real number.
Input
Expected output
Example
Input 1=10.2
Output=10.2
Strip
Removes leading and trailing blank spaces from a text string.
Input
Expected output
Example
Input 1=" space " (provided without the double quotes)
Output=space
Substring
Returns part of a text string based on the given starting position and length.
Input
Expected output
Example
Input 1=HELLO WORLD
Input 2=1
Input 3=5
Output=HELLO
SubstringOnPositions
Returns part of a text string between the start and end positions.
Input
Expected output
Example
Input 1= Hello World
Input 2=3
Input 3=6
Output=llo (includes the space character at the end)
SubstringOnStartPosition
Returns part of a text string starting from the given start position to the end of the string.
Input
Expected output
Example
Input 1= Hello World
Input 2=3
Output=llo World
ToLowerCase
Converts all letters in a text string to lower case.
Input
Expected output
Example
Input 1= Hello User
Output=hello user
ToUpperCase
Converts all letters in a text string to upper case.
Input
Expected output
Example
Input 1= Hello User
Output=HELLO USER
List functions
These functions are used for list manipulation operations such as determining the list length, retrieving an element from the list, and so on. These functions use slots or variables with string values.
You can specify a list by using one of the following formats:
- [listValue1,listValue2,listValue3]
- ["listValue1","listValue2","listValue3"]
ConcatListToList
Concatenates two lists of comma-separated strings to return a new list.
Input
Expected output
Example
Input 1=[abc,def,ghi]
Input 2=[123,456,789]
Output=[abc,def,ghi,123,456,789]
GetNote
Returns a note present in the given position in a list of notes in the incoming event. A note is a list of strings that contain information like the timestamp, owner, and the note content.
Input
Expected output
Example
An incoming event has the following list of notes:
[0x17cbca212fd,admin,BASIC_ENRICHMENT,0x17cbca212fd,admin,ADVANCED_ENRICHMENT,0x17cbca212fd,admin,NOTIFICATION]
Input= 2
Output= [0x17cbca212fd,admin,ADVANCED_ENRICHMENT]
To understand a use case for this function, see Example-Retrieve-and-modify-notes-in-incoming-events.
IsDisjoint
Compares elements of two lists to verify that no common elements exist between them.
Input
Expected output
Example
Example 1:
- Input 1=[123,111Input1,def,ghi]
- Input 2=[456,789,abc]
- Output=true (because no common elements are present in the two lists)
Example 2:
- Input 1=[123,111,456]
- Input 2=[456,789]
- Output=true (because common elements are present in the two lists)
ListContains
Detects whether a list contains an element.
Input
Expected output
Example
Input 1=[v1,v2,v3,v4,v5,v6,v3,v2]
Input 2=v1
Output=true
ListGetElement
Returns the element present in the given position in a list, reading left to right.
Input
Expected output
Example
Input 1=[oxford,cambridge,london]
Input 2=2
Output=cambridge
ListIntersect
Compares two lists to return the common elements between them.
Input
Expected output
Example
Input 1=[html,css,javascript]
Input 2=css
Output=css
ListLength
Returns the number of elements in a list.
Input
Expected output
Example
Input 1=[html,css,javascript]
Output=3
ListUnion
Returns a union of all unique values between the two lists.
Duplicate values between the two lists are repeated only once. Duplicate values within a single list are retained.
Input
Expected output
Example
Input 1=[bmc,ade]
Input 2=[bmc,helix]
Output=[bmc,ade,helix]
RemoveDuplicateElements
Removes duplicate elements from a list.
Input
Expected output
Example
Input 1=[v1,v2,v3,v4,v5,v6,v3,v2]
Output=[v1,v2,v3,v4,v5,v6]
RemoveElement
Removes all occurrences of an element from a list.
Input
Expected output
Example
Input 1=[abc,def,ghi,jkl,mnp]
Input 2=def
Output=[abc,ghi,jkl,mnp]
RemoveElementList
Removes a list of elements from a list.
Input
Expected output
Example
Input 1=[v1,v2,v3,v4,v5,v6]
Input 2=[v2,v3]
Output=[v1,v4,v5,v6]
Number functions
These functions are used for integer manipulation operations such as integer addition, subtraction, and so on.
CurrentTimeStamp
Returns the current timestamp in epoch (milliseconds). This function does not require any input parameter. Use this function to enrich slots having the number data type.
Expected output
For example, if the current data and time is Wednesday, December 29, 2021 12:03:42 PM GMT+05:30, then the function returns the timestamp as 1640759622000 milliseconds.
To understand a use case for this function, see Example-Check-whether-there-is-a-time-delay-between-events.
Math
Performs basic mathematical operations on two numbers and returns the result.
Input
Expected output
Example
Input 1=+
Input 2=5
Input 3=7
Output=12