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 AdministrationGeneralModules) 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 that 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:

Problem Solution
Module did not appear in the list Make sure that the manifest.json file exists in modules/your-module/ folder of the Zabbix frontend. If it does that means the module does not suit the current Zabbix version. If manifest.json file does not exist, you have probably unpacked in the wrong directory.
Frontend crashed The module code is not compatible with the current Zabbix version or server configuration. Please delete module files and reload the frontend. You'll see a notice that some modules are absent. Go to Module administration and click Scan directory again to remove non-existent modules from the database.
Error message about identical namespace, ID or actions appears New module tried to register a namespace, ID or actions which are already registered by other enabled modules. Disable the conflicting module (mentioned in error message) prior to enabling the new one.
Technical error messages appear Report errors to the developer of the module.

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.

Item Naming rules Example
Module directory Lowercase [a-z], underscore and decimal digits example_v2
Action subdirectories Lowercase [a-z] and underscore character data_export
Action files CamelCase, ending with action type SomethingView.php
View and partial files Lowercase [a-z]
Words separated with dot
Prefixed by module. followed by module name
Ending with action type and .php file extension
module.example.something.view.php
Javascript files The same rules apply as for view and partial files, except the .js.php file extension. module.example.something.view.js.php

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:

Parameter Required Type Default Description
manifest_version Yes Double - Manifest version of the module. Currently supported version is 1.
id Yes String - Module ID. Only one module with given ID can be enabled at the same time.
name Yes String - Module name as displayed in the Administration section.
version Yes String - Module version as displayed in the Administration section.
namespace Yes String - PHP namespace for Module.php and action classes.
author No String "" Module author as displayed in the Administration section.
url No String "" Module URL as displayed in the Administration section.
description No String "" Module description as displayed in the Administration section.
actions No Object {} Actions to register with this module. See Actions.
config No Object {} Module configuration.

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:

Parameter Required Type Default Description
*key* Yes String - Action name, in lowercase [a-z], separating words with dot.
class Yes String - Action class name, including subdirectory path (if used) within the actions directory.
layout No String "layout.htmlpage" Action layout.
view No String null Action view.

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();