Documentation

#1 Macrofuncties

Overzicht

Macrofuncties bieden de mogelijkheid om macrowaarden aan te passen.

Soms kan een macro resulteren in een waarde die niet per se gemakkelijk te verwerken is. Het kan lang zijn of een specifieke interessante substring bevatten die je zou willen extraheren. Hier komen macrofuncties van pas.

De syntaxis van een macrofunctie is:

{<macro>.<func>(<params>)}

waarbij:

• <macro> - de macro om aan te passen (bijvoorbeeld {ITEM.VALUE} of {#LLDMACRO})
• <func> - de toe te passen functie
• <params> - een door komma's gescheiden lijst van functieparameters. Parameters moeten worden geciteerd als ze beginnen met '' '' (spatie), " of ), , bevatten.

Bijvoorbeeld:

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

btoa

Encoding a macro value into Base64 format. This function is supported since Zabbix 7.0.4.

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:

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:

htmldecode

Decoding a macro value from HTML encoding. This function is supported since Zabbix 7.0.4.

htmlencode

Encoding a macro value into HTML encoding. This function is supported since Zabbix 7.0.4.

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 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).

lowercase

Transformation of macro value characters into lowercase. This function is supported since Zabbix 7.0.4.

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

Replacement of character/substring in macro value. This function is supported since Zabbix 7.0.4.

Parameters:

• pattern - the regular expression to match;
• replacement - the replacement string.

Comments:

• The patterns and replacements are processed sequentially, with each subsequent pair being applied in accordance with the outcome of the previous replacement;
• This function also allows referencing captured groups in replacement strings using \1 to \9 placeholders.

Examples:

{{ITEM.VALUE}.regrepl("oldParam", "newParam")} - replace "oldParam" with "newParam"
       {{ITEM.VALUE}.regrepl("([^a-z])","\\\1")} - escape all non-letter characters with a backslash
       {{ITEM.VALUE}.regrepl("_v1\.0", "_v2.0", "\(final\)", "")} - 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 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:

tr(characters,replacement)

Transliteration of macro value characters. This function is supported since Zabbix 7.0.4.

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

Examples:

{{ITEM.VALUE}.tr(abc, xyz)} - replace all occurrences of a with x, b with y, c with z
       {{ITEM.VALUE}.tr(abc, xyzq)} - replace all occurrences of a with x, b with y, c with z (q is ignored)
       {{ITEM.VALUE}.tr(abcde, xyz)} - 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("\\\'", "\/\"")} - replace all occurrences of backslash with forward slash, ' with "
       {{ITEM.VALUE}.tr(A-Z,a-z)} - convert all letters to lowercase
       {{ITEM.VALUE}.tr(0-9a-z,*)} - replace all numbers and lowercase letters with "*"
       {{ITEM.VALUE}.tr(0-9,ab)} - 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,*)} - replace all numbers, abc characters, and A-L range with "*"
       {{ITEM.VALUE}.tr("\n","*")} - replace end-of-line occurencies with *
       {{ITEM.VALUE}.tr("e", "\n")} - replace all "e" to 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 macro value characters into uppercase. This function is supported since Zabbix 7.0.4.

urldecode

Decoding a macro value from URL encoding. This function is supported since Zabbix 7.0.4.

urlencode

Encoding a macro value into URL encoding. This function is supported since Zabbix 7.0.4.