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 functions that have arguments of the String type, in the argument value, you can add a line break to move content to a new line by using the <br> tag. You can also use the <br> tag as a separator to separate text strings.
For an Enrich action, the functions list displays functions based on the data type of the slot that you enrich, as shown in the following table:
Data type of slots | Return functions available |
|---|---|
String | Displays functions that return either a String, Number, or Boolean value. |
List of strings | Displays functions that return a List of string values. |
Number | Displays functions that return a Number value. |
For an Enrich or Variable action, the function parameters display slots and global variables 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 strings | Displays slots and global variables that have the List of Strings data type. |
Number | Displays slots and global variables 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. The following string functions are available:
- Concat
- ConcatList
- Contains
- CurrentFormattedTimeStamp
- GetPosition
- GetPositionOnOccurrences
- IsActiveTimeFrame
- MatchRegex
- GetRegexMatches
- Replace
- Split
- StringLength
- StringMatch
- StringToInteger
- StringToReal
- Strip
- Substring
- SubstringOnPositions
- SubstringOnStartPosition
- ToBase64
- ToFormattedTimeStamp
- ToLowerCase
- ToUpperCase
Concat
Concatenates two text strings to return a new string.
Input
Input | Type | Description |
|---|---|---|
Text String 1 | String | A single text string, slot (with a string value) or variable (with a string value) that you want to join. Enclose values that contain blank spaces or other special characters in double quotation marks. The maximum limit is 1024 characters. |
Text String 2 | String | A single text string, slot (with a string value) or variable (with a string value) that you want to join to the earlier string value. Enclose values that contain blank spaces or other special characters in double quotation marks. The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
Result of concatenating the specified strings | String |
Example
- Input 1= CPU utilization
- Input 2=[CPU utilization,CPU utilization for the host is rapidly increasing,CPU utilization is growing]
- Output=CPU utilization[CPU utilization,CPU utilization for the host is rapidly increasing,CPU utilization is growing]
ConcatList
Concatenates a list of comma-separated strings using the given separator and returns a new string.
Input
Input | Type | Description |
|---|---|---|
Text String | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values), that you want to join. You can specify a combination of text strings, slots with string values, and variables with string values. Enclose the list in square brackets and enclose values that contain blank spaces or other special characters in double quotes. The maximum limit is 1024 characters. |
Separator | String | Alphanumeric or special character(s) by which you want to separate the new string. Providing the separator is optional. Important: Use two backslashes (\\) as the separator instead of a single backslash (\) because it might cause a policy failure. |
Output
Expected output | Type |
|---|---|
Concatenated string by combining the specified comma-separated list of strings | String |
Example
- Input 1= [tagName1,tagName2,tagName3]
- Input 2= -
- Output=tagName1-tagName2-tagName3
Contains
Detects whether a text string contains a substring.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value)in which you want to search. Search is case insensitive. The maximum limit is 1024 characters. |
Find Substring | String | Substring that you want to find in the text string. Returns true if the substring is found, otherwise returns false. |
Output
Expected output | Type |
|---|---|
Indicates whether the substring is present in the specified string. | Boolean |
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
Input | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Date Format | String | Specify a date format as a string in which you want to retrieve the current timestamp. This function supports the standard date formats. Refer to the following table for a few date format examples:
|
Output
Expected output | Type |
|---|---|
Timestamp in the specified date format and the UTC time zone | String |
Example
- Input =EEE, MMM d, “yy
- Output=Wed, Dec 29, '21
To read 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 substring that occurred first, reading left to right.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value)in which you want to find the substring. The maximum limit is 1024 characters. |
Find Substring | String | Substring that you want to find in the text string. Returns 0 if the substring is not found. |
Output
Expected output | Type |
|---|---|
Position of the specified substring | Integer |
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
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value) in which you want to find the substring. The maximum limit is 1024 characters. |
Find Substring | String | Substring that you want to find in the text string. Returns 0 if the substring is not found. |
Number of Occurrences | Integer | Number of occurrences of the substring that you want to find. Returns 0 if the specified number is not found. |
Output
Expected output | Type |
|---|---|
Position of the specified substring based on occurrences | Integer |
Example
- Input 1=city reno is called reno
- Input 2=reno
- Input 3=2
- Output=21
IsActiveTimeFrame
Returns the state of the time frame based on whether it is currently active. You can perform conditional event enrichment based on the state of the time frame.
You can enter a maximum of 20 values as an input for the function.
Input
Input | Type | Description |
|---|---|---|
Time Frame Name | String | Specify single or multiple time frames in a tenant to check whether the time frame is active. If you specify multiple time frames and if any one of the time frames is active, the time frame status is returned as true. The function can resolve the time frame from the time frame ID also. |
| Event slot | String | If the time frame is configured with an event slot, the function resolves the time frame name from the event slot and returns the time frame status. |
| Local variable | String | If the time frame is configured with a local variable, the function resolves the variable value and returns the time frame status. |
| Global variable | String | If the time frame is configured with a global variable, the function resolves the variable value and returns the time frame status. |
Output
Expected output | Type |
|---|---|
Status of the time frame | Boolean |
To read a use case for this function, see Example: Assign event owner according to the time frame status.
MatchRegex
Matches a text string with a simple regular expression.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string. Can be a slot or a variable that matches the pattern. The maximum limit is 1024 characters. |
Regex Pattern | String | Regular expression pattern that matches the text string. |
Output
Expected output | Type |
|---|---|
Indicates whether the string matches the regular expression | Boolean |
Example
- Input 1=aaabbb
- Input 2=a*b*
- Output=true
GetRegexMatches
Extracts and returns a list of strings from the input text that matches the specified regular expression pattern.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string. Can be a slot or a variable that matches the pattern. |
Regex Pattern | String | Regular expression pattern that matches the text string. |
Output
Expected output | Type |
|---|---|
| Returns a list of matching tokens | List of strings |
Example
- Input 1=CPU-utilization is high. Reduce CPU-utilization.
- Input 2=\b(CPU-)?(utilization)\b
- Output=[CPU-utilization,CPU-,utilization,CPU-utilization,CPU-,utilization]
Replace
Replaces part of a text string with another string.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value)in which you want to replace a substring. The maximum limit is 1024 characters. |
Existing Substring | String | Existing substring that you want to replace in the text string. |
New Substring | String | New substring with which you want to replace the existing substring. |
Output
Expected output | Type |
|---|---|
New string created as a result of the replacement | String |
Example
- Input 1= CPU Utilization
- Input 2=CPU
- Input 3=Memory
- Output=Memory Utilization
Split
Splits a text string into a list of substrings based on the separator occurring in the string.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value) that you want to split. The maximum limit is 1024 characters. |
Separator | String | Separator character(s) in the text string at which you want to split the string. The separator character(s) are not included in the resulting value. Important: To use [, ^, or \, prefix them with a backslash (\) as the separator; otherwise, it might cause a policy failure. Example of multiple characters or strings as a separator: original-string = "hnadfbstcjak" separator = "abc" resulting-list = ["hn","df","st","j","k"] |
Output
Expected output | Type |
|---|---|
List of substrings divided by the specified separator | String |
Example
Input 1= CPU Utilization
Input 2=" "
Output=[CPU, Utilization]
StringLength
Returns the number of characters in a text string.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value) whose length you want to find. The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
String length (in characters) | Integer |
Example
- Input 1=CPU Utilization
- Output= 15
StringMatch
Matches character patterns in a text string and extracts fields from it. The pattern can contain literal text and substitutes.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string. Can be a slot or a variable for matching the pattern. The maximum limit is 1024 characters. |
Match Pattern | String | Pattern that matches the entire string and not just a portion of it. The pattern can contain literal text and substitutes. Literal text is matched literally. A substitute is preceded by a % sign, followed by a type indicator. The values corresponding to the substitutes are extracted as fields. Valid values for substitutes:
Tips:
|
Output
Expected output | Type |
|---|---|
Retrieved fields | List of strings |
Example
Input 1=CPU Utilization is 80
Input 2=CPU Utilization %s %d
Output=[is,80]
StringToInteger
Converts a text string that represents a number to an integer value.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value) that you want to convert. The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
Conversion result, returned as an integer | Integer |
Example
- Input 1=20
- Output=20
StringToReal
Converts a text string that represents a real number to a real number.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string or reference to a slot or variable (with a real number value) that you want to convert. The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
Conversion result, returned as a real value | Real |
Example
- Input 1=10.2
- Output=10.2
Strip
Removes leading and trailing blank spaces from a text string.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value)from which you want spaces removed. The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
Resulting string after the blank spaces are removed | String |
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
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value)from which you want to extract the substring. The maximum limit is 1024 characters. |
Start Position | Integer | Position of the character from where you want to begin extraction. The first character in the text string starts at 1. |
Length | Integer | Number of characters that you want to extract. |
Output
Expected output | Type |
|---|---|
Retrieved string | String |
Example
- Input 1=CPU Utilization is increasing
- Input 2=1
- Input 3=15
- Output=CPU Utilization
SubstringOnPositions
Returns part of a text string between the start and end positions.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value)from which you want to extract the substring. The maximum limit is 1024 characters. |
Start Position | Integer | Position of the character from where you want to begin extraction. The first character in the text string starts at 1. |
End Position | Integer | Position of the character where you want to end the extraction. The first character in the text string starts at 1. |
Output
Expected output | Type |
|---|---|
Retrieved string | String |
Example
- Input 1= CPU Utilization is increasing
- Input 2=5
- Input 3=16
- Output=Utilization (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
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value)from which you want to extract the substring. The maximum limit is 1024 characters. |
Start Position | Integer | Position of the character from where you want to begin extraction. The first character in the text string starts at 1. |
Output
Expected output | Type |
|---|---|
Retrieved string | String |
Example
- Input 1= CPU Utilization
- Input 2=5
- Output=Utilization
ToBase64
Converts a text string to a Base64 value.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value), or variable (with a string value) that you want to convert to a Base64 value. |
Output
Expected output | Type |
|---|---|
Converted Base64 value | String |
To read a use case for this function, see Example: Enrich event details with the encoded event ID.
ToFormattedTimeStamp
Converts the timestamp from an epoch value to a string value in the specified date format.
Input
Input | Type | Description |
|---|---|---|
Date Format | String | Date format to which you want to convert the timestamp. The following date formats that are available on the User Preferences page are supported:
|
Epoch Value | Epoch (milliseconds) | Text string, slot (with a string value), or variable (with a string value) that you want to convert to a timestamp value. |
Time Zone | String | Time zone in which you want to view the timestamp. The time zones that are available on the User Preferences page are supported. |
Output
Expected output | Type |
|---|---|
Formatted timestamp value. Important: | String |
Example
- Input 1= yyyy-MM-dd h:mm a
- Input 2= Occurred (Timestamp in milliseconds: 1681816440000)
- Input 3= (GMT+05:30)Chennai, Kolkata, Mumbai, New Delhi
- Output= 2023-04-18 4:44 PM
ToLowerCase
Converts all letters in a text string to lower case.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value) that you want to convert. Characters that are not letters are not changed. The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
Lower case version of the specified string. | String |
Example
- Input 1=CPU Utilization
- Output=cpu utilization
ToUpperCase
Converts all letters in a text string to upper case.
Input
Input | Type | Description |
|---|---|---|
Text String | String | Text string, slot (with a string value) or variable (with a string value) that you want to convert. Characters that are not letters are not changed. The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
Upper case version of the specified string | String |
Example
- Input 1=CPU Utilization
- Output=CPU UTILIZATION
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"]
The following list functions are available:
- ConcatListToList
- GetNote
- IsDisjoint
- ListContains
- ListGetElement
- ListIntersect
- ListLength
- ListUnion
- RemoveDuplicateElements
- RemoveElement
- RemoveElementList
ConcatListToList
Concatenates two lists of comma-separated strings to return a new list.
Input
Input | Type | Description |
|---|---|---|
List 1 | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values), that you want to join. The maximum limit is 1024 characters. |
List 2 | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values), that you want to join to the earlier list. You can append a string slot value to the list by specifying the list in the following format: [$NEW.internalSlotName] The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
Result of concatenating the specified lists | List of strings |
Example 1
- Input 1=[abc,def,ghi]
- Input 2=[123,456,789]
- Output=[abc,def,ghi,123,456,789]
Example 2
Input 1=[CPU utilization is increasing,CPU utilization is growing,CPU utilization is rising]
- Input 2=[$NEW.location]
- Output=[CPU utilization is increasing,CPU utilization is growing,CPU utilization is rising,Houston] (Assuming that the location slot is the event has the value "Houston")
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
Input | Type | Description |
|---|---|---|
Position | Integer | The sequence number of the note that you want to retrieve. The position starts from 1 for the oldest note. To retrieve 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.. |
Output
Expected output | Type |
|---|---|
The retrieved note | List of string |
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 read 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
Input | Type | Description |
|---|---|---|
List 1 | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values) that you want to compare. The maximum limit is 1024 characters. |
List 2 | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values) that you want to compare with the earlier list. The maximum limit is 1024 characters. Returns true is no common elements exist, otherwise returns false. |
Output
Expected output | Type |
|---|---|
Indicates that no common elements exist in the specified lists, | Boolean |
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
Input | Type | Description |
|---|---|---|
List | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values) in which you want to search. Search is case insensitive. The maximum limit is 1024 characters. |
Find Element | String | Element that you want to find in the list. Returns true if the element is found, otherwise returns false. |
Output
Expected output | Type |
|---|---|
Indicates whether the element is present in the specified list. | Boolean |
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
Input | Type | Description |
|---|---|---|
List | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values) in which you want to find the element. The maximum limit is 1024 characters. |
Position | Integer | Position of the element, reading left to right. The first element in the list starts at 1. |
Output
Expected output | Type |
|---|---|
Element present at the specified position in the list. | String |
Example
- Input 1=[oxford,cambridge,london]
- Input 2=2
- Output=cambridge
ListIntersect
Compares two lists to return the common elements between them.
Input
Input | Type | Description |
|---|---|---|
List | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values) that you want to compare. The maximum limit is 1024 characters. |
List | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values) that you want to compare with the earlier list. The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
Common elements present in the two lists | List of strings |
Example
- Input 1=[html,css,javascript]
- Input 2=css
- Output=css
ListLength
Returns the number of elements in a list.
Input
Input | Type | Description |
|---|---|---|
List | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values), whole length you want to find. The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
List length (in characters) | Integer |
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
Input | Type | Description |
|---|---|---|
List 1 | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values), that you want to combine. The maximum limit is 1024 characters. |
List 2 | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values), that you want to combine with the earlier list. The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
Union of the specified lists | List of strings |
Example
- Input 1=[bmc,ade]
- Input 2=[bmc,helix]
- Output=[bmc,ade,helix]
RemoveDuplicateElements
Removes duplicate elements from a list.
Input
Input | Type | Description |
|---|---|---|
List | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values) containing duplicate elements. The maximum limit is 1024 characters. |
Output
Expected output | Type |
|---|---|
Resulting list after the duplicate elements are removed. | List of strings |
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
Input | Type | Description |
|---|---|---|
List | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values), from which you want to remove an element. The maximum limit is 1024 characters. |
Remove Element | String | Element that you want to remove from the list. |
Output
Expected output | Type |
|---|---|
Resulting list after the specified element is removed. | List of strings |
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
Input | Type | Description |
|---|---|---|
List | List of strings | Comma-separated list of only text strings, only slots (with string values), or only variables (with string values), from which you want to remove elements. The maximum limit is 1024 characters. |
Remove Element List | List of strings | Comma-separated list of elements occurring in the list that you want to remove. |
Output
Expected output | Type |
|---|---|
Resulting list after the specified list is removed. | List of strings |
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.
The following number functions are available:
- Char
- CurrentTimeStamp
- Math
Char
Returns a character equivalent for a specific ASCII number value. This function helps you to manage characters in the event data. Use the output of this function to replace, remove, or append ASCII characters in the event data with other characters and enrich the event with more meaningful information.
Input
Input | Type | Description |
|---|---|---|
Number | Number | Specify the ASCII number value that you want to convert into a character. You can also specify event slots and variables of the number data type. The number must be between 0 and 127. |
Output
Expected output | Type |
|---|---|
A character equivalent for a specific ASCII number value. | String |
Example 1
- Input = 30
- Output = RS (Nonprintable ASCII character)
Example 2
- Input = 32
- Output = space (Printable ASCII character)
To understand a use case for this function, see Example: Manage ASCII characters in the event data.
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.
Output
Expected output | Type |
|---|---|
Timestamp value in milliseconds | Number |
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 read 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
Input | Type | Description |
|---|---|---|
Operator | String | Arithmetic operator to use for the calculation. Valid values are: +,-,*, / |
Number 1 | Integer | First number to use for the calculation. |
Number 2 | Integer | Second number to use for the calculation. |
Output
Expected output | Type |
|---|---|
Resulting value of the mathematical operation performed. | Integer |
Example
- Input 1=+
- Input 2=5
- Input 3=7
- Output=12