Fabrice Gabolde


Zabbix2::API::CRUDE -- Base abstract class for most Zabbix2::API::* objects


  package Zabbix2::API::Unicorn;

  use Moo;
  extends 'Zabbix2::API::CRUDE';

  # now override some virtual methods so that it works for the specific case of
  # unicorns

  sub id { ... }
  sub _prefix { ... }
  sub _extension { ... }


This module handles most aspects of pushing, pulling and deleting the various types of Zabbix objects. You do not want to use this directly; a few abstract methods need to be implemented by a subclass.


Note that subclasses may define their own attributes in addition to the ones in this base class.


(read-only hashref of object properties, defaults to {})

This is where the object properties obtained from the server are stored. To update the object on the server, modify the contents of the hashref and call the update method. Similarly, to create a brand new object on the server, create a Perl object with the desired properties in the data attribute, and call the create method.


(read-only required Zabbix2::API instance)

Reference to the current Zabbix connection object.


_readonly_properties (optional abstract method)

  (not intended for public consumption)

This method, if implemented in a subclass, must return a hashref whose keys are property names. Those properties will be filtered out when the create and update methods are called. This is sometimes necessary because Zabbix complains that read-only properties must not be updated, even when their values have not changed.


  my $unicorn = Zabbix2::API::Unicorn->new(...);

This method calls the corresponding API CLASS.create method, which returns the ID of the new object. This ID is then set in the object.

If pull_after_push_mode is true in the Zabbix2::API object, the API CLASS.get method is then called to fetch the values of all server-generated properties.



This method calls the corresponding API CLASS.delete method. The object itself is not modified; you should probably stop using it afterwards as it will no longer exist on the server.

An exception is thrown if the object does not have an ID.


  $unicorn->exists or say 'deleted';

This method checks that the ID still exists on the server. This is usually a good way to determine if the object has been deleted on the server, since Zabbix object IDs are not usually reused.

An exception is thrown if the object does not have an ID.

_extension (required abstract method)

  (not intended for public consumption)

This method's return value will be added to the API method call parameters when trying to fetch an object from the server. It should return valid CLASS.get parameters as a hash (not a hashref, mind). E.g., Zabbix2::API::Item's implementation is as follows:

  sub _extension {
      return (output => 'extend');

id (required abstract method)

  # accessor
  say 'the id is '. $unicorn->id;
  # mutator

This method must implement a mutator for the object's ID. This is generally a wrapper around the "unicornid" key in the data attribute.

name (optional abstract method)

  say 'this thing is ' . $unicorn->name;

This method should return a human-readable name for the object; e.g. the implementation in the Zabbix2::API::Item class returns the parent host's name and the item's key, separated by a slash. No guarantees are made on the unicity or even usefulness of any implementation of this method, nor are any required.

Currently, not all subclasses implement this method, since it is optional. If you have a good implementation for a missing name method, please send a patch!


  say 'the unicorn lives on node ' . $unicorn->node_id;

This method returns the object's node's ID, or false if it does not live on a decentralized setup. Note that node-based setups are being deprecated in the 2.x series.

An exception is thrown if the object does not have an ID.

_prefix (required abstract method)

  (not intended for public consumption)

This method is where most class differentiation is done. It receives a single argument, usually a method name (prepended by a dot), and it should return the derivation appropriate for the class.

Most implementations just return a constant string prepended to the argument, e.g. Item's implementation returns "item$suffix": "item.create", etc. However, some implementations are more complicated; the Macro class, for instance, needs to check the instance to determine if it is used as a host macro or a global macro.



The pull method fetches an object's properties from the server and sets the data attribute with them.

An exception is thrown if the object does not have an ID.

Note that this method is not aware if you previously retrieved the object with an "output" parameter to limit the columns retrieved, so it will pull all columns from the server every time.


  # this is a Unicorn
  say 'this is a ' . $unicorn->short_class;

This method returns a shortened class name. The "Zabbix2::API::" prefix is removed.


  $unicorn->data->{some_property} = 'some_value';

This is the opposite of pull.


Some subclasses do not actually need to be a full implementation to be useful; e.g. the Zabbix2::API::HostInterface class is only ever manipulated through Zabbix2::API::Host instances. Calling fetch with the intent of creating objects of these classes will throw an exception.


Zabbix2::API and the Zabbix API documentation at http://www.zabbix.com/documentation/start.


Fabrice Gabolde <fga@cpan.org>


Copyright (C) 2011, 2014 SFR

This library is free software; you can redistribute it and/or modify it under the terms of the GPLv3.