Scripts execution with object creation and deletion

With creation or deletion of an object of some class, the system is able to execute scripts and pass to them arguments which are set via the web interface.

Any script consists of two files:

  • the executable file,

  • the configuration file, which describes the web interface of the Triggers tab for passing arguments to the executable file.

The configuration file must:

  • be placed to the folder with the executable file;

  • have the name of the executable file with the additional extension .conf

/opt/saymon-extensions/entity-triggers-path/myscript.sh
/opt/saymon-extensions/entity-triggers-path/myscript.sh.conf

The executable files of the scripts can be grouped in subfolders with any number of sublevels:

/opt/saymon-extensions/entity-triggers-path/host_class/script_1.sh
/opt/saymon-extensions/entity-triggers-path/host_class/script_1.sh.conf
/opt/saymon-extensions/entity-triggers-path/memory_class/script_1.sh
/opt/saymon-extensions/entity-triggers-path/memory_class/script_1.sh.conf
/opt/saymon-extensions/entity-triggers-path/router_class/script_1.sh
/opt/saymon-extensions/entity-triggers-path/router_class/script_1.sh.conf

When adding or modifying configurations, the changes are applied with refreshing the page in a web browser.

Folder for scripts

The scripts folder is set in the server configuration file /etc/saymon/saymon-server.conf.

It is necessary to:

  1. Add the custom_scripts section into the file.

  2. Set the full path to the folder where the scripts are stored in the parameter entity_triggers_path:

    ...
"custom_scripts": {
    "entity_triggers_path": "/opt/saymon-extensions/entity-triggers-path"
},
...

  3. Restart the server:

    $ sudo service saymon-server restart

Parameters of the scripts

Script parameters are set in the JSON file named as executable_file_name.conf. For instance, if the executable file is named as myScript.sh, then the configuration file must be named as myScript.sh.conf.

The configuration file must be placed into the same folder as the executable file.

Scripts without the configuration files are ignored.

The configuration file can contain the following fields:

Field Description

title

Script name which is displayed in the web interface in the lists of scripts.

Optional field.

By default it is the identifier, generated from the path and the name of the script:path to the file:

  • <path_to_the_folder_with_scripts>/cpu/script_1.sh

  • displayed script name: cpu - script_1

args

The array of the arguments, which are set by users in the web interface and passed to the executable file.

args.id

Argument name, which is passed to the executable file.

Optional field.

args.default

The default value of the argument, which is entered into the corresponding field.

Optional field.

args.description

Description of the argument, which is displayed in the web interface.

Optional field.

args.name

Argument name, which is displayed in the web interface.

args.options

Applicable only for the select type (args.type.select).

Defines the list of argument values, which are displayed in the web interface.

By default, the first option is selected. In order to set another option as the default one, it is necessary to enter the value of the args.options.value field to the args.default field.

The following is passed to the executable file:

If the args.id field is not set, then only the argument value (args.options.value) is passed to the executable file.

If the args.options.value field is not set, then the argument name (args.id) is not passed to the executable file.

This logic can be used to implement the "Not selected" option and delimiters in the dropdown list.

args.options.description

Description of the argument value, which is displayed in the web interface.

Optional field.

By default the argument value (args.options.value) is displayed.

args.options.value

Argument value.

Optional field.

If this field is not set, then the argument name is not passed to the executable file. These options can be used in order to implement the "Not selected" option and delimiters in the dropdown list.

args.required

Indicates if the argument value is required.

true | the value is required,

false | the value is optional.

Optional field.

By default false.

args.type

Type of the argument value.

Optional field.

By default text.

args.type.checkbox

Switcher.

By default it is disabled.

When it is enabled, the value of the args.id field (argument name) is passed to the executable file. If the field is not set, then the index number of the argument is passed to the executable file (starting from 0).

args.type.password

The text field with masking of input characters.

args.type.select

Dropdown list with predefined argument values.

The list of values is set in the args.options field.

Argument description (the args.description field) is not displayed for this type. It is necessary to use the corresponding field for each argument value instead (args.options.description).

args.type.text

Text field to enter argument value.

args.type.textarea

Text field to enter argument value.

Allows to enter multiline text.

Script example

To demonstrate the script functionality and different argument types we have prepared two files.

  1. Place the files to the script folder.

  2. Set execution of the script "Custom script example" with creation or deletion an object of any class in the Triggers tab.

  3. Set argument values.

  4. Create or delete an object of the selected class.

The executable file of the script records all of the passed arguments to the output file:

hello_world.sh
#!/bin/bash
#
# Use this script as the custom one
# to check or test arguments configuration file.

i=0
echo "Script got the following args:"
for arg in $*
do
  i=$((i + 1))
  echo -ne $arg [] /opt/saymon-extensions/entity-triggers-path/myselect/output; echo -ne " " [] /opt/saymon-extensions/entity-triggers-path/myselect/output
done

if [ $i = 0 ]
then
  echo "(no args)" [] /opt/saymon-extensions/entity-triggers-path/myselect/output
  exit 2
fi

This configuration file contains examples for all argument types:

hello_world.sh.conf
{
    "title": "Custom script example",
    "args": [
        {
            "name": "Unnamed (positional) arg"
        },
        {
            "name": "Named arg",
            "id": "--name"
        },
        {
            "name": "Behold the description on the right",
            "description": "Here I am!",
            "id": "--description"
        },
        {
            "name": "Arg with default value",
            "description": "and description",
            "id": "--defval",
            "default": "default_value"
        },
        {
            "name": "Required arg",
            "description": "This field is required to fill in",
            "id": "--required",
            "required": true
        },
        {
            "name": "Type - Text",
            "description": "This and all above fields have got text type",
            "id": "--text",
            "type": "text"
        },
        {
            "name": "Type - Text Area",
            "description": "This field is text area. \nIt is resizable in most browsers. \nAnd allows to enter multiline texts.",
            "id": "--textarea",
            "type": "textarea"
        },
        {
            "name": "Type - Checkbox",
            "description": "This is the checkbox type",
            "id": "--checkbox",
            "type": "checkbox"
        },
        {
            "name": "Type - Password",
            "description": "This is the password field",
            "id": "--pass",
            "default": "qwerty",
            "type": "password"
        },
        {
            "name": "Type - Select",
            "description": "This is the select type. This description is not displayed in the web interface. Use description for each option instead.",
            "id": "--select",
            "default": "option2",
            "type": "select",
            "options": [
                {
                    "description": "== Not selected =="
                },
                {
                    "value": "option1", "description": "OK"
                },
                {
                    "description": "== Divider =="
                },
                {
                    "value": "option2", "description": "Warning"
                },
                {
                    "value": "option3", "description": "Error"
                }
            ]
        }
    ]
}