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;
• 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.

For example:

{{TIME}.fmttime(format,time_shift)}
       {{ITEM.VALUE}.regsub(pattern, output)}
       {{$USERMACRO}.regsub(pattern, output)}
       {{#LLDMACRO}.regsub(pattern, output)}

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

A single function per macro is supported; multiple macro functions in chain are not supported.

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.35" from a received value of "24.3483523"
       {{ITEM.VALUE}.fmtnum(0)} - will return "24" from a received value of "24.3483523"

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);
• References to non-existent capture groups in the replacement string are replaced with an empty string.

Example:

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

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;
• References to non-existent capture groups in the replacement string are replaced with an empty string.

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);
• References to non-existent capture groups in the replacement string are replaced with an empty string.

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.

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.