1 Macro functions

Overview

Macro functions offer the ability to customize macro values (for example, shorten or extract specific substrings), making them easier to work with.

The syntax of a macro function is:

{macro.func(params)}

where

• macro - the macro to customize, for example {ITEM.VALUE}, {$USERMACRO}, {#LLDMACRO};
• func - the function to apply (see supported functions);
• params - a comma-delimited list of function parameters, which must be double-quoted if:
  • start with a space or double quotes;
  • contain closing parentheses or a comma.

Macro functions are supported for:

• Built-in macros
• User macros
• Low-level discovery macros
• Expression macros

Macro functions can be used in all locations supporting the listed macros. This applies unless explicitly stated that only a macro is expected (for example, when configuring host macros or low-level discovery rule filters).

See also: known issues

Supported functions

The functions are listed without additional information. Click on the function to see the full details.

Function details

Optional function parameters are indicated by < >.

btoa

Encoding a macro value into Base64 encoding. Base64 encoding is a method for representing binary data as text, useful for storing and secure transmission of binary content over text-based protocols.

Example:

{{ITEM.VALUE}.btoa()} - will Base64-encode a value like "zabbix" into "emFiYml4"

fmtnum(digits)

Number formatting to control the number of digits printed after the decimal point.

Parameters:

• digits - the number of digits after decimal point. Valid range: 0-20. No trailing zeros will be produced.

Examples:

{{ITEM.VALUE}.fmtnum(2)} - will return "24.34" from a received value of "24.3413523"
       {{ITEM.VALUE}.fmtnum(0)} - will return "24" from a received value of "24.3413523"

fmttime(format,<time_shift>)

Time formatting.
Note that this function can be used with macros that resolve to a value in one of the following time formats:

• hh:mm:ss
• yyyy-mm-ddThh:mm:ss[tz] (ISO8601 standard)
• UNIX timestamp

Parameters:

• format - mandatory format string, compatible with strftime function formatting;
  
• time_shift (optional) - the time shift applied to the time before formatting; should start with -<N><time_unit> or +<N><time_unit>, where:
  
  • N - the number of time units to add or subtract;
  • time_unit - h (hour), d (day), w (week), M (month) or y (year).

Comments:

• The time_shift parameter supports multistep time operations and may include /<time_unit> for shifting to the beginning of the time unit (/d - midnight, /w - 1st day of the week (Monday), /M - 1st day of the month, etc.). Examples: -1w - exactly 7 days back; -1w/w - Monday of the previous week; -1w/w+1d - Tuesday of the previous week.
• Time operations are calculated from left to right without priorities. For example, -1M/d+1h/w will be parsed as ((-1M/d)+1h)/w.

Examples:

{{TIME}.fmttime(%B)} - will return "October" from a received value of "12:36:01"
       {{TIME}.fmttime(%d %B,-1M/M)} - will return "1 September" from a received value of "12:36:01"

htmldecode

Decoding a macro value from HTML encoding.

The following characters are supported:

Example:

{{ITEM.VALUE}.htmldecode()} - will HTML-decode a value like "&lt;" into "<"

htmlencode

Encoding a macro value into HTML encoding.

The following characters are supported:

Example:

{{ITEM.VALUE}.htmlencode()} - will HTML-encode a character like "<" into "&lt;"

iregsub(pattern,output)

Substring extraction by a regular expression match (case-insensitive).

Parameters:

• pattern - the regular expression to match;
• output - the output options. \1 - \9 placeholders are supported to capture groups. \0 returns the matched text.

Comments:

• If there is no match for the regular expression, the function returns nothing;
• If the function pattern is an incorrect regular expression, then the macro evaluates to 'UNKNOWN' (except for low-level discovery macros, in which case the function will be ignored, and the macro will remain unresolved).

Example:

{{ITEM.VALUE}.iregsub("fail|error|fault|problem","ERROR")} - will resolve to "ERROR" if "fail", "error", "fault", or "problem" substrings are received (case-insensitive)

lowercase

Transformation of all macro value characters into lowercase. Works with single-byte character sets (such as ASCII) and does not support UTF-8.

Example:

{{ITEM.VALUE}.lowercase()} - will transform a value like "Zabbix SERVER" into "zabbix server" (lowercase)

regrepl(pattern,replacement,<pattern2>,<replacement2>,...)

Replacement of character/substring in macro value. Note that this function is only supported with the libpcre2 library. If Zabbix server/proxy was compiled with libpcre, this function will return UNKNOWN.

Parameters:

• pattern - the regular expression to match;
• replacement - the replacement string. \1 - \9 placeholders are supported in replacement strings to capture groups.

Comments:

• The patterns and replacements are processed sequentially, with each subsequent pair being applied in accordance with the outcome of the previous replacement;
• Nothing is replaced if there is no match for the regular expression.

Examples:

{{ITEM.VALUE}.regrepl("oldParam", "newParam")} - will replace "oldParam" with "newParam"
       {{ITEM.VALUE}.regrepl("([^a-z])","\\\1")} - all non-letter characters will be escaped with a backslash
       {$THRESHOLD:"{{#FSNAME}.regrepl(\"\\$\",\"\")}"} - will remove a trailing backslash (for example, to replace "C:\" with "C:")
       {{ITEM.VALUE}.regrepl("_v1\.0", "_v2.0", "\(final\)", "")} - will replace multiple parts in item value

regsub(pattern,output)

Substring extraction by a regular expression match (case-sensitive).

Parameters:

• pattern - the regular expression to match;
• output - the output options. \1 - \9 placeholders are supported to capture groups. \0 returns the matched text.

Comments:

• If there is no match for the regular expression, the function returns nothing;
• If the function pattern is an incorrect regular expression, then the macro evaluates to 'UNKNOWN' (except for low-level discovery macros, in which case the function will be ignored, and the macro will remain unresolved).

Examples:

{{ITEM.VALUE}.regsub("^([0-9]+)", Problem ID: \1)} - will resolve to "Problem ID: 123" if a value like "123 Log line" is received
       {{ITEM.VALUE}.regsub("fail|error|fault|problem","ERROR")} - will resolve to "ERROR" if "fail", "error", "fault", or "problem" substrings are received (case-sensitive); nothing if there is no match

See more examples.

tr(characters,replacement)

Transliteration of macro value characters.

• characters - the set of characters to replace;
• replacement - the set of positionally corresponding replacement characters.

Comments:

• No transliteration if there is no match for the regular expression.

Examples:

{{ITEM.VALUE}.tr(abc, xyz)} - will replace all occurrences of "a" with "x", "b" with "y", "c" with "z"
       {{ITEM.VALUE}.tr(abc, xyzq)} - will replace all occurrences of "a" with "x", "b" with "y", "c" with "z" ("q" is ignored)
       {{ITEM.VALUE}.tr(abcde, xyz)} - will replace all occurrences of "a" with "x", "b" with "y", "c" with "z", "d" with "z", "e" with "z" (i.e. xyzzz)
       {{ITEM.VALUE}.tr("\\\'", "\/\"")} - will replace all occurrences of backslash with forward slash, single quotes with double quotes
       {{ITEM.VALUE}.tr(A-Z,a-z)} - will convert all letters to lowercase
       {{ITEM.VALUE}.tr(0-9a-z,*)} - will replace all numbers and lowercase letters with "*"
       {{ITEM.VALUE}.tr(0-9,ab)} - will replace all occurrences of 0 with "a", and replace all occurrences of 1, 2, 3, 4, 5, 6, 7, 8, and 9 with "b"
       {{ITEM.VALUE}.tr(0-9abcA-L,*)} - will replace all numbers, "abc" characters, and A-L range with "*"
       {{ITEM.VALUE}.tr("\n","*")} - will replace end-of-line occurrences with *
       {{ITEM.VALUE}.tr("e", "\n")} - will replace all "e" with end-of-line

To include literal characters:

backslash - must be escaped as \\
       single quote - must be escaped as \'
       double quote - must be escaped as \"

Supported escape sequences with backslash:

\\\\ => \\ - double backslash to single backslash
       \\a  => \a - alert
       \\b  => \b - backspace
       \\f  => \f - form feed
       \\n  => \n - newline
       \\r  => \r - return
       \\t  => \t - horizontal tab
       \\v  => \v - vertical tab

uppercase

Transformation of all macro value characters into uppercase. Works with single-byte character sets (such as ASCII) and does not support UTF-8.

Example:

{{ITEM.VALUE}.uppercase()} - will transform a value like "Zabbix Server" into "ZABBIX SERVER" (uppercase)

urldecode

Decoding a macro value from URL encoding.

Example:

{{ITEM.VALUE}.urldecode()} - will URL-decode a value like "%2F" into "/"

urlencode

Encoding a macro value into URL encoding.

Example:

{{ITEM.VALUE}.urlencode()} - will URL-encode a character like "/" into "%2F"

Additional examples

The table below shows more examples of using macro functions.

Seeing full item values

Long values of resolved {ITEM.VALUE} and {ITEM.LASTVALUE} macros for text/log items are truncated to 20 characters in some frontend locations. To see the full values of these macros you may use macro functions, e.g.:

{{ITEM.VALUE}.regsub("(.*)", \1)}
       {{ITEM.LASTVALUE}.regsub("(.*)", \1)}

See also: {ITEM.VALUE} and {ITEM.LASTVALUE} macro details.