7.2.3. Json Fields

Create the file /usr/share/opennac/api/application/models/Plugins/{plugin_name}/{plugin_name}.json

Inside this file, we will configure in JSON format what fields are shown in the form of the plugin. These fields are used in the execution of the file.

7.2.3.1. Fields to define a new field

1. Id of the field: The first field must be “0” and should be increased with each new field.

2. Name: Name of the plugin used by the system.

3. Label: Name of the plugin that will be shown in the Plugin’s FrontEnd. It will be displayed above the field.

4. Description: Text that will appear when hovering (positioning the mouse over the field). It must be an explanation of what the field does and how it is used.

5. Datatype: which type of data will be used to store the field. Check the available types of data: https://www.w3schools.com/php/php_datatypes.asp

6. Validator: Type of validation that will be done when the user edit the Plugin’s Form. Check https://framework.zend.com/manual/1.12/en/zend.filter.input.html for predefined validators. Also check /usr/share/opennac/api/library/Common/Validate/ for custom OpenNAC validations.

Note

If the user selects an invalid value that does not fulfill the validator, an error will be shown after editing the Plugin and clicking the Accept button:

7. Default: Predefined values of the field. This field is optional.

Example: The file openPorts.json contains the fields shown in the Plugin’s Form.

[root@principal ~]# ll /usr/share/opennac/api/application/models/Plugins/openPorts/
total 16
-rw-r--r-- 1 apache apache  2979 Jul 21 15:06 openPorts.json
-rw-r--r-- 1 apache apache 15592 Jul 21 15:06 openPorts.php

• Field portList inside openPorts.json

1. The id is “0” because it is the first field.

2. The name is portList because it is a list of ports.

3. The label displayed above the portList fields is “Port List”.

4. The description explains what this field does and which is the expected format. Also adds an example to clarify the explanation.

5. The data type used is string, which allows a set of characters (numbers and letters).

6. The PortRange validator checks that the user specifies a port or a port range. It also allows you to specify if the port is UDP or TCP. It is a custom validator that can be found in: /usr/share/opennac/api/library/Common/Validate/PortRange.php

7. The Default value is specified, so all users will initially have this value in the portList field.

"0": {
        "name":"portList",
        "label":"Port List",
        "description":"List of ports to be analyzed, separated by commas, in format 'portType:port' where portType is 'U' (UDP) or 'T' (TCP). Ex: U:53,T:20-22,T:80",
        "datatype": "string",
        "validator": "PortRange",
        "default":"U:53,T:21-23,T:80"
    },

• Field execTtl inside openPorts.json

1. The id is “1” because it is the second field.

2. The name is execTtl because it is the TTL of the execution.

3. The label displayed above the execTtl fields is “Execution TTL (m.)”.

4. The description explains what this field does and which is the expected format.

5. The data type used is integer which allows only a numeric value.

6. The validator has two different validations. The first one checks that only digits (numbers) are written. The second one checks that this value is greater than 0. It is a default validator.

7. The Default value is specified, so all users will initially have this value in the execTtl field.

"1": {
       "name":"execTtl",
       "label":"Execution TTL (m.)",
       "description":"During this period, indicated in minutes, no more executions are done over the same client.",
       "datatype": "integer",
       "validator": {
           "0": "digits",
           "1": {
               "0": "GreaterThan",
               "min": "0",
               "inclusive": false
           },
           "breakChainOnFailure": true
       },
       "default":5
   }

• Result of the Form

The new plugin will appear in the list of Plugins inside Configuration > Plugins as openPorts.

In the following image you can see the two previously configured fields Port List and Execution TTL:

7.2.3.2. Plugin’s description

As you could see in the image above, there is a description of the Plugin. This description is configured by adding a new line inside:

/usr/share/opennac/admonportal-html5/application/configs/i18n/configuration_en.ini (english) and
/usr/share/opennac/admonportal-html5/application/configs/i18n/configuration_es.ini (spanish).

The line must have the following format:

configuration.plugins.description.<pluginName> = "Plugin’s description"

Example:

configuration.plugins.description.openPorts = "The openPorts plugin provides the ability to scan and discover open ports on devices. This is done through requests on specified ports. This plugin could improve the profiling process detecting which UDP and TCP ports are open."