You are viewing documentation for the development version, it may be incomplete.
Join our translation project and help translate Zabbix documentation into your native language.

User macro object

The following objects are directly related to the usermacro API.

Global macro

The global macro object has the following properties.

Property Type Description
globalmacroid ID ID of the global macro.

Property behavior:
- read-only
- required for update operations
description string Description of the macro.
macro string Macro string.

Property behavior:
- required for create operations
type integer Type of macro.

Possible values:
0 - (default) Text macro;
1 - Secret macro;
2 - Vault secret.
value string Value of the macro.

Property behavior:
- write-only if type is set to "Secret macro"
- required for create operations

Host macro

The host macro object defines a macro available on a host, host prototype or template. It has the following properties.

Property Type Description
hostmacroid ID ID of the macro.

Property behavior:
- read-only
- required for update operations
automatic integer Defines whether the macro is controlled by discovery rule.

Possible values:
0 - (default) Macro is managed by user;
1 - Macro is managed by discovery rule.

User is not allowed to create automatic macro.
To update automatic macro, it must be converted to manual.
config object/array Macro configuration responsible for how the macro is displayed in the Host Wizard.
description string Description of the macro.
hostid ID ID of the host, host prototype, or template that the macro belongs to.

Property behavior:
- constant
- required for create operations
macro string Macro string.

Property behavior:
- required for create operations
type integer Type of macro.

Possible values:
0 - (default) Text macro;
1 - Secret macro;
2 - Vault secret.
value string Value of the macro.

Property behavior:
- write-only if type is set to "Secret macro"
- required for create operations

Macro configuration

The macro configuration object defines how a macro is displayed in the Host Wizard.

Property Type Description
type integer Type of macro input field.

Possible values:
0 - Macro is not used in Host Wizard;
1 - Textbox;
2 - List;
3 - Checkbox.

Property behavior:
- required
label string Label for macro input field.

Property behavior:
- required if type is set to "Textbox", "List", or "Checkbox"
description text Help text displayed alongside macro input field. Supports Markdown formatting.
priority integer Macro input field position in the macro list.

If priority is not set, the macro is added at the end of the ungrouped macro list.
required integer Marks the macro as mandatory.

Possible values:
0 - Not mandatory;
1 - Mandatory.

Property behavior:
- supported if type is set to "Textbox" or "List"
regex string Regular expression to validate user input in a textbox field.

Property behavior:
- supported if type is set to "Textbox"
section_name string Label of the collapsible section where the macro is grouped.

If section_name is not set, the macro is ungrouped. Ungrouped macros are displayed first; grouped macros are displayed below, ordered by their priority within each collapsible section.
options text JSON string defining list items or checkbox values.

For lists: an array of objects with value and text properties.
Example: [{"value": "http", "text": "HTTP"}, {"value": "https", "text": "HTTPS"}]

For checkboxes: an object with checked and unchecked properties.
Example: {"checked": true, "unchecked": false}

Property behavior:
- required if type is set to "List" or "Checkbox"