Skip to content

zProperties

zProperties are configuration properties that can be specified on any device class including the root /Devices class, and on any individual device. They are one part of a hierarchical configuration system.

Inheritance

The most-specific value for a zProperty within the hierarchy will be used for any given device. For instance, given a device linux1 in the /Server/Linux device class. The value for zSnmpMonitorIgnore will be checked first on the linux1 device. If it is not set locally on the device, the /Server/Linux device class will then be checked. If not set there, /Server will be checked. Finally the value at / (or /Devices) will be checked as a final resort. Since all zProperties must have a default values that is set at the root device class, there will always be a value for the zProperty. Even if it is an empty string.

Caveats

When changing modeler bindings using the zDeviceTemplates property, this will take effect on your ZenPack. Any previously defined bindings will be replaced. The same applies to the device level template bindings using the zCollectorPlugins property.

Beginning with ZenPackLib 2.0, this behavior has changed by default. zProperties will no longer be overwritten if a target device class already exists (that is, during an upgrade or if the YAML affects a preexisting class such as /Devices/Server). Instead, a warning will be displayed to the user during installation, and the target zProperty will be left alone.

Setting reset: true for a specific device class in the YAML will override this behavior, causing the zProperties to be replaced with the YAML-defined values.

Fields

The following fields are valid for a zProperty entry.

name (required, string, default = implied from key in zProperties map)
Name (e.g. zWidgeterEnable). Must be begin with a lowercase `z``.
category (optional, string, default = "" (empty string))
Category name. (e.g. ACME Widgeter). Used to group related zProperties in the UI.
label (optional, string, default = "" (empty string))
Brief description of zProperty.
description (optional, string, default = "" (empty string))
Notes regarding the purpose and function of this zProperty.
type (optional, string, default = string)
Type of property. Valid types are boolean, float, int, lines, long, password, and string.
default (optional)
Default value for property. Default value depends on the type: - boolean: false - lines: [] - password: "" (empty string) - string: "" (empty string) - all others: null (None)

Examples

To add a zProperty to your ZenPack you must include a zProperties section in your YAML file. The following example shows an example of adding two zProperties.

zenpack.yaml
zProperties:
  zWidgeterEnable:
    category: ACME Widgeter
    type: boolean
    default: true

  zWidgeterInterval:
    category: ACME Widgeter
    type: string
    default: 300

Each of these zProperty entries specifies a category, type and default. These are the only valid fields of the a zProperty entry. However, each of these fields has a default value that will be used if the field isn’t explicitly specified. For example, the default value for type is string. So the above example could be shortened slightly by omitting the explicit type on zWidgeterInterval.

zenpack.yaml
zProperties:
  zWidgeterEnable:
    category: ACME Widgeter
    type: boolean
    default: true

  zWidgeterInterval:
    category: ACME Widgeter
    default: 300

There is a special zProperty entry named DEFAULTS that can be used to further shorten definitions in cases where you’re adding many zProperties. The following example shows how DEFAULTS can be used to replace the duplicated category property.

zenpack.yaml
zProperties:
  DEFAULTS:
    category: ACME Widgeter

  zWidgeterEnable:
    type: boolean
    default: true

  zWidgeterInterval:
    default: 300

Since a zProperty is a YAML “mapping”, the minmal specification of a zProperty (name only) would look like:

zenpack.yaml
zProperties:
  zWidgeterMinimal: {}

Each zProperty listed in zProperties will be created when the ZenPack is installed, and removed when the ZenPack is removed.

When changing the default or category for a zProperty in the YAML file, it changes in the system. Removing a zProperty from the YAML file will not remove it from the system. To remove it completely, you must write a migration script.