[comment]: # attributes: notoc [comment]: # (terms: fmtnum, fmttime, iregsub, regsub) [comment]: # ({09129833-0458cee0}) # 1 Macro functions #### Overview Macro functions offer the ability to customize [macro](/manual/config/macros) values (for example, shorten or extract specific substrings), making them easier to work with. The syntax of a macro function is: ```default {macro.func(params)} ``` where - **macro** - the macro to customize; - **func** - the function to apply (see [supported functions](#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: ```default {{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](/manual/appendix/macros/supported_by_location) - [User macros](/manual/appendix/macros/supported_by_location#other-macro-types) - [Low-level discovery macros](/manual/appendix/macros/supported_by_location#other-macro-types) - [Expression macros](/manual/appendix/macros/supported_by_location#other-macro-types) 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](/manual/config/hosts/host#configuration) or low-level discovery rule [filters](/manual/discovery/low_level_discovery#filter)). A single function per macro is supported; multiple macro functions in chain are not supported. :::noteclassic Please see [escaping examples](/manual/appendix/escaping) for cases when macro functions are used inside other contexts (function, item key, another macro, etc). ::: [comment]: # ({/09129833-0458cee0}) [comment]: # ({7283f95a-b8563887}) #### Supported functions The functions are listed without additional information. Click the function to see the full details. |Function|Description| |--|--------| |[btoa](#btoa)|Encoding macro value into Base64 encoding.| |[fmtnum](#fmtnum)|Number formatting to control the number of digits printed after the decimal point.| |[fmttime](#fmttime)|Time formatting.| |[htmldecode](#htmldecode)|Decoding macro value from HTML encoding.| |[htmlencode](#htmlencode)|Encoding macro value into HTML encoding.| |[iregsub](#iregsub)|Substring extraction by a regular expression match (case-insensitive).| |[lowercase](#lowercase)|Transformation of macro value characters into lowercase.| |[regrepl](#regrepl)|Replacement of character/substring in macro value.| |[regsub](#regsub)|Substring extraction by a regular expression match (case-sensitive).| |[tr](#tr)|Transliteration of macro value characters.| |[uppercase](#uppercase)|Transformation of macro value characters into uppercase.| |[urldecode](#urldecode)|Decoding macro value from URL encoding.| |[urlencode](#urlencode)|Encoding macro value into URL encoding.| [comment]: # ({/7283f95a-b8563887}) [comment]: # ({91058888-c1632a9e}) #### Function details Optional function parameters are indicated by < >. [comment]: # ({/91058888-c1632a9e}) [comment]: # ({d8d5fafe-6e2e93df}) ##### btoa {#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: ```default {{ITEM.VALUE}.btoa()} - will Base64-encode a value like "zabbix" into "emFiYml4" ``` [comment]: # ({/d8d5fafe-6e2e93df}) [comment]: # ({31245134-4df3fd19}) ##### fmtnum(digits) {#fmtnum} 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: ```default {{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" ``` [comment]: # ({/31245134-4df3fd19}) [comment]: # ({a8d94ee5-3caa4dc7}) ##### fmttime(format,) {#fmttime} 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 `-` or `+`, 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 `/` 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: ```default {{TIMESTAMP}.fmttime(%B)} - will return "October" from a received value of "1633098961" {{TIMESTAMP}.fmttime(%d %B,-1M/M)} - will return "1 September" from a received value of "1633098961" ``` [comment]: # ({/a8d94ee5-3caa4dc7}) [comment]: # ({d224cb43-e5cb24ab}) ##### htmldecode {#htmldecode} Decoding a macro value from HTML encoding. The following characters are supported: |Value|Decoded value| |----|------| |`&`|`&`| |`<`|`<`| |`>`|`>`| |`"`|`"`| |`'`|`'`| |`'`|`'`| Example: ```default {{ITEM.VALUE}.htmldecode()} - will HTML-decode a value like "<" into "<" ``` [comment]: # ({/d224cb43-e5cb24ab}) [comment]: # ({f78164e5-b0e6d63f}) ##### htmlencode {#htmlencode} Encoding a macro value into HTML encoding. The following characters are supported: |Value|Encoded value| |----|------| |`&`|`&`| |`<`|`<`| |`>`|`>`| |`"`|`"`| |`'`|`'`| Example: ```default {{ITEM.VALUE}.htmlencode()} - will HTML-encode a character like "<" into "<" ``` [comment]: # ({/f78164e5-b0e6d63f}) [comment]: # ({edaa6df7-e78b5abd}) ##### iregsub(pattern,output) {#iregsub} 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 an empty string. - 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: ```default {{ITEM.VALUE}.iregsub("fail|error|fault|problem","ERROR")} - will resolve to "ERROR" if "fail", "error", "fault", or "problem" substrings are received (case-insensitive); will return an empty string if there is no match ``` [comment]: # ({/edaa6df7-e78b5abd}) [comment]: # ({9186768b-b7de9b23}) ##### lowercase {#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: ```default {{ITEM.VALUE}.lowercase()} - will transform a value like "Zabbix SERVER" into "zabbix server" (lowercase) ``` [comment]: # ({/9186768b-b7de9b23}) [comment]: # ({2064b2f8-2d4d3410}) ##### regrepl(pattern,replacement,,,...) {#regrepl} Replacement of character/substring in macro value. 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: ```default {{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 ``` [comment]: # ({/2064b2f8-2d4d3410}) [comment]: # ({825c2e80-a8dcf3b5}) ##### regsub(pattern,output) {#regsub} 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 an empty string. - 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: ```default {{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); will return an empty string if there is no match ``` See [more examples](#additional-examples). [comment]: # ({/825c2e80-a8dcf3b5}) [comment]: # ({40e84cc5-d7660986}) ##### tr(characters,replacement) {#tr} Transliteration of macro value characters. - **characters** - the set of characters to replace; - **replacement** - the set of positionally corresponding replacement characters. Examples: ```default {{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: ```default backslash - must be escaped as \\ single quote - must be escaped as \' double quote - must be escaped as \" ``` Supported escape sequences with backslash: ```default \\\\ => \\ - 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 ``` [comment]: # ({/40e84cc5-d7660986}) [comment]: # ({57ab4e3a-8315e479}) ##### uppercase {#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: ```default {{ITEM.VALUE}.uppercase()} - will transform a value like "Zabbix Server" into "ZABBIX SERVER" (uppercase) ``` [comment]: # ({/57ab4e3a-8315e479}) [comment]: # ({9f54b4cb-15465392}) ##### urldecode {#urldecode} Decoding a macro value from URL encoding. Example: ```default {{ITEM.VALUE}.urldecode()} - will URL-decode a value like "%2F" into "/" ``` [comment]: # ({/9f54b4cb-15465392}) [comment]: # ({725aedc6-362f6ccf}) ##### urlencode {#urlencode} Encoding a macro value into URL encoding. Example: ```default {{ITEM.VALUE}.urlencode()} - will URL-encode a character like "/" into "%2F" ``` [comment]: # ({/725aedc6-362f6ccf}) [comment]: # ({a95b22c2-148bfc16}) #### Additional examples The table below shows more examples of using macro functions. :::noteinfo `{#IFALIAS}` is an [LLD macros](/manual/config/macros/lld_macros) and is only defined in low-level discovery contexts (discovery rules, prototypes and the items/triggers created from them). Using it outside LLD will leave the token unexpanded. ::: |Macro function|Received value|Output| |-------------|----|-------------| |`{{ITEM.VALUE}.regsub(^[0-9]+, Problem)}`|`123Log line`|`Problem`| |`{{ITEM.VALUE}.regsub("^([0-9]+)", "Problem")}`|`123 Log line`|`Problem`| |`{{ITEM.VALUE}.regsub(".*", "Problem ID: \1")}`|`Log line`|`Problem ID: `| |`{{ITEM.VALUE}.regsub("^(\w+).*?([0-9]+)", " Problem ID: \1_\2 ")}`|`MySQL crashed errno 123`|` Problem ID: MySQL_123 `| |`{{ITEM.VALUE}.regsub("([1-9]+", "Problem ID: \1")}`|`123 Log line`|`*UNKNOWN*` (invalid regular expression)| |`{{#IFALIAS}.regsub("(.*)_([0-9]+)", \1)}`|`customername_1`|`customername`| |`{{#IFALIAS}.regsub("(.*)_([0-9]+)", \2)}`|`customername_1`|`1`| |`{{#IFALIAS}.regsub("(.*)_([0-9]+", \1)}`|`customername_1`|`{{#IFALIAS}.regsub("(.*)_([0-9]+", \1)}` (invalid regular expression)| |`{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+)\", \1)}"}`|`customername_1`|`{$MACRO:"customername"}`| |`{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+)\", \2)}"}`|`customername_1`|`{$MACRO:"1"}`| |`{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+\", \1)}"}`|`customername_1`|`{$MACRO:"{{#IFALIAS}.regsub(\"(.*)_([0-9]+\", \1)}"}` (invalid regular expression)| |`"{$MACRO:"\{{#IFALIAS}.regsub("(.*)_([0-9]+)", \1)}\"}"`|`customername_1`|`"{$MACRO:"\customername\"}"`| |`"{$MACRO:"\{{#IFALIAS}.regsub("(.*)_([0-9]+)", \2)}\"}"`|`customername_1`|`"{$MACRO:"\1\"}"`| |`"{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+\\", \1)}\"}"`|`customername_1`|`"{$MACRO:\"{{#IFALIAS}.regsub(\\"(.*)_([0-9]+\\", \1)}\"}"` (invalid regular expression)| ##### 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.: ```default {{ITEM.VALUE}.regsub("(.*)", \1)} {{ITEM.LASTVALUE}.regsub("(.*)", \1)} ``` See also: {ITEM.VALUE} and {ITEM.LASTVALUE} [macro details](/manual/appendix/macros/supported_by_location). [comment]: # ({/a95b22c2-148bfc16})