20. Modules

Overview

It is possible to enhance Zabbix frontend functionality by adding 3rd party modules or by developing your own modules without the need to change the source code of Zabbix.

Note that the module code will run with the same privileges as Zabbix source code. This means:

• 3rd party modules can be harmful. You must trust the modules you are installing;

• Errors in a 3rd party module code may crash the frontend. If this happens, just remove the module code from the frontend. As soon as you reload Zabbix frontend, you’ll see a note saying that some modules are absent. Go to Module administration (in Administration → General → Modules) and click Scan directory again to remove non-existent modules from the database.

Installation

Please always read the installation manual for a particular module. It is recommended to install new modules one by one to catch failures easily.

Just before you install a module:

• Make sure you have downloaded the module from a trusted source. Installation of harmful code may lead to consequences, such as data loss

• Different versions of the same module (same ID) can be installed in parallel, but only a single version can be enabled at once

Steps to install a module:

• Unpack your module within its own folder in the modules folder of the Zabbix frontend

• Ensure the your module folder contains at least the manifest.json file

• Navigate to Module administration and click the Scan directory button

• New module will appear in the list along with its version, author, description and status

• Enable module by clicking on its status

Troubleshooting:

Developing modules

Modules are written in PHP language. Model-view-controller (MVC) software pattern design is preferred, as it is also used in Zabbix frontend and will ease the development. PHP strict typing is also welcome but not mandatory.

Please note that with modules you can easily add new menu items and respective views and actions to Zabbix frontend. Currently it is not possible to register new API or create new database tables through modules.

Module structure

Each module is a directory (placed within the modules directory) with sub-directories containing controllers, views and any other code:

example_module_directory/           (required)
    manifest.json                   (required)  Metadata and action definition.
    Module.php                                  Module initialization and event handling.
    actions/                                    Action controller files.
        SomethingView.php
        SomethingCreate.php
        SomethingDelete.php
        data_export/                                 
            ExportAsXml.php
            ExportAsExcel.php
    views/                                      View files.
        example.something.view.php
        example.something.delete.php
        js/                                     JavaScript files used in views.
            example.something.view.js.php
    partials/                                   View partial files.
        example.something.reusable.php
        js/                                     JavaScript files used in partials.
            example.something.reusable.js.php

As you can see, the only mandatory file within the custom module directory is manifest.json. The module will not register without this file. Module.php is responsible for registering menu items and processing events such as ‘onBeforeAction’ and ‘onTerminate’. The actions, views and partials directories contain PHP and JavaScript code needed for module actions.

Naming convention

Before you create a module, it is important to agree on the naming convention for different module items such as directories and files so that we could keep things well organized. You can also find examples above, in the Module structure section.

Note that the ‘module’ prefix and name inclusion is mandatory for view and partial file names, unless you need to override Zabbix core views or partials. This rule, however, does not apply to action file names.

Manifest preparation

Each module is expected to have a manifest.json file with the following fields in JSON format:

For reference, please see an example of manifest.json in the Reference section.

Actions

The module will have control over frontend actions defined within the actions object in the manifest.json file. This way new actions are defined. In the same way you may redefine existing actions. Each key of actions should represent the action name and the corresponding value should contain class and optionally layout and view keys.

One action is defined by four counterparts: name, controller, view and layout. Data validation and preparation is typically done in the controller, output formatting is done in the view or partials, and the layout is responsible for decorating the page with elements such as menu, header, footer and others.

Module actions must be defined in the manifest.json file as actions object:

There are several predefined layouts, like layout.json or layout.xml. These are intended for actions which produce different result than an HTML. You may explore predefined layouts in the app/views/ directory or even create your own.

Sometimes it is necessary to only redefine the view part of some action leaving the controller intact. In such case just place the necessary view and/or partial files inside the views directory of the module.

For reference, please see an example action controller file in the Reference section. Please do not hesitate to explore current actions of Zabbix source code, located in the app/ directory.

Module.php

This optional PHP file is responsible for module initialization as well as event handling. Class ‘Module’ is expected to be defined in this file, extending base class \Core\CModule. The Module class must be defined within the namespace specified in the manifest.json file.

<?php
namespace Modules\Example;
use Core\CModule as BaseModule;
class Module extends BaseModule {
    ...
}

For reference, please see an example of Module.php in the Reference section.

Reference

This section contains basic versions of different module elements introduced in the previous sections.

manifest.json

{
    "manifest_version": 1.0,
    "id": "example_module",
    "name": "Example module",
    "version": "1.0",
    "namespace": "Example",
    "author": "John Smith",
    "url": "http://module.example.com",
    "description": "Short description of the module.",
    "actions": {
        "example.something.view": {
            "class": "SomethingView",
            "view": "module.example.something.view"
        },
        "example.something.create": {
            "class": "SomethingCreate",
            "layout": null
        },
        "example.something.delete": {
            "class": "SomethingDelete",
            "layout": null
        },
        "example.something.export.xml": {
            "class": "data_export/ExportAsXml",
            "layout": null
        },
        "example.something.export.excel": {
            "class": "data_export/ExportAsExcel",
            "layout": null
        }
    },
    "config": {
        "username": "john_smith"
    }
}

Module.php

<?php declare(strict_types = 1);
namespace Modules\Example;
use APP;
use CController as CAction;
/**
 * Please see Core\CModule class for additional reference.
 */
class Module extends \Core\CModule {
    /**
     * Initialize module.
     */
    public function init(): void {
        // Initialize main menu (CMenu class instance).
        APP::Component()->get('menu.main')
            ->findOrAdd(_('Reports'))
                ->getSubmenu()
                    ->add((new \CMenuItem(_('Example wide report')))
                        ->setAction('example.report.wide.php')
                    )
                    ->add((new \CMenuItem(_('Example narrow report')))
                        ->setAction('example.report.narrow.php')
                    );
    }
    /**
     * Event handler, triggered before executing the action.
     *
     * @param CAction $action  Action instance responsible for current request.
     */
    public function onBeforeAction(CAction $action): void {
    }
    /**
     * Event handler, triggered on application exit.
     *
     * @param CAction $action  Action instance responsible for current request.
     */
    public function onTerminate(CAction $action): void {
    }
}

Action controller

<?php declare(strict_types = 1);
namespace Modules\Example\Actions;
use CControllerResponseData;
use CControllerResponseFatal;
use CController as CAction;
/**
 * Example module action.
 */
class SomethingView extends CAction {
    /**
     * Initialize action. Method called by Zabbix core.
     *
     * @return void
     */
    public function init(): void {
        /**
         * Disable SID (Sessoin ID) validation. Session ID validation should only be used for actions which involde data
         * modification, such as update or delete actions. In such case Session ID must be presented in the URL, so that
         * the URL would expire as soon as the session expired.
         */
        $this->disableSIDvalidation();
    }
    /**
     * Check and sanitize user input parameters. Method called by Zabbix core. Execution stops if false is returned.
     *
     * @return bool true on success, false on error.
     */
    protected function checkInput(): bool {
        $fields = [
            'name'  => 'required|string',
            'email' => 'required|string',
            'phone' => 'string'
        ];
        // Only validated data will further be available using $this->hasInput() and $this->getInput().
        $ret = $this->validateInput($fields);
        if (!$ret) {
            $this->setResponse(new CControllerResponseFatal());
        }
        return $ret;
    }
    /**
     * Check if the user has permission to execute this action. Method called by Zabbix core.
     * Execution stops if false is returned.
     *
     * @return bool
     */
    protected function checkPermissions(): bool {
        $permit_user_types = [USER_TYPE_ZABBIX_ADMIN, USER_TYPE_SUPER_ADMIN];
        return in_array($this->getUserType(), $permit_user_types);
    }
    /**
     * Prepare the response object for the view. Method called by Zabbix core.
     *
     * @return void
     */
    protected function doAction(): void {
        $contacts = $this->getInput('email');
        if ($this->hasInput('phone')) {
            $contacts .= ', '.$this->getInput('phone');
        }
        $data = [
            'name' => $this->getInput('name'),
            'contacts' => $contacts
        ];
        $response = new CControllerResponseData($data);
        $this->setResponse($response);
    }
}

Action view

<?php declare(strict_types = 1);
/**
 * @var CView $this
 */
$this->includeJsFile('example.something.view.js.php');
(new CWidget())
    ->setTitle(_('Something view'))
    ->addItem(new CDiv($data['name']))
    ->addItem(new CPartial('module.example.something.reusable', [
        'contacts' => $data['contacts']
    ])
    ->show();