Background plugins

Background plugins are supported for products of COREmanager version 5.377 and higher. To check the version of COREmanager, run:

Description

In all ISPsystem software products based on COREmanager it is possible to perform certain actions when events occur. For example, a Telegram notification can be sent to the user upon successful authorization.

Unlike the system of Events, which runs synchronously with the occurrence of events and can affect the behavior of the system, the mechanism described in this article runs asynchronously with the event and does not affect the behavior of the system.

To process dashboard events, you need to:

Write an event handler script.
Register your handler script, linking it to the events to be processed.

Format of communication

The following information is transmitted to the handler script:

in the form of environment variables (env):
- o query parameters with the prefix PARAM_;
- o query headers;
- o miscellaneous;
input stdin with the results of event processing in xml format, if the event is registered with the sessiondata attribute. Without specifying sessiondata, only environment variables will be transmitted.

Example

Below is an example of a simple task — sending information to an employee in Telegram about crediting a payment of more than 5000 units.

Creating the handler script

Create a file in the /usr/local/mgr5/addon/ directory called send_notify.sh with the following contents:

#!/usr/bin/sh

#env >> var/send_notify.sh.log

PAYMENT=$(sbin/mysql-billmgr <<< "SELECT id FROM payment WHERE id = '${PARAM_elid}' AND paymethodamount > 5000" | tail -1)

if [ -n "${PAYMENT}" ]; then
        BOT_TOKEN="{TOKEN}" # Replace {TOKEN} with your bot token
        CHAT_ID="{CHAT_ID}" # Replace {CHAT_ID} with your channel id

        curl "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage?chat_id=${CHAT_ID}&text=Payment №${PARAM_elid} is above 5000"
fi

Set the script's running permissions:

chmod +x /usr/local/mgr5/addon/send_notify.sh

Registering the handler script

To register the handler script, create the file /usr/local/mgr5/etc/xml/billmgr_mod_send_notification.xml with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
        <handler name="send_notify.sh" type="xml">
              <task name="payment.setpaid"  get="yes" setvalues="yes" submit="yes" sessiondata="yes"/>
        </handler>
</mgrdata>

Comments to the plugin

Block responsible for registering the handler script:

<handler name="send_notify.sh" type="xml">
	<task name="payment.setpaid"  get="yes" setvalues="yes" submit="yes" sessiondata="yes"/>
</handler>

The name property of the handler node specifies the file that performs the event processing. Place this file in the directory /usr/local/mgr5/addon/, the file name must be exactly the same as the one specified in the name property.

The task node specializes the event to be tracked and has the following attributes:

name — the event to be tracked. Events are requests to the system via http/https or CLI (/usr/local/mgr5/sbin/mgrctl). To see a list of all events, run:
```
/usr/local/mgr5/sbin/mgrctl -m billmgr actionlist
```
get — track an event without sv_field={param} and sok=ok parameters in the query;
setvalues — track events with the sv_field={param} parameter in the query;
submit — track events with the sok=ok parameter in the query;
sessiondata — the result of event processing will be transmitted to the script in xml format.