How to add a notification module

Message gateway modules integrate the BILLmanager platform with external services for sending notifications (SMS, email, messengers). The platform calls these modules directly or through notification modules.

The message gateway module is responsible for:

• a set of connection settings to the external service;
• the appearance of the gateway settings form in the platform interface;
• formatting and transmitting outgoing messages to the external system;
• receiving incoming messages from the external service.

General information

Installation directory: /usr/local/mgr5/gate/ or /usr/local/mgr5/addon/.
XML description: /usr/local/mgr5/etc/xml/billmgr_mod_gw<name>.xml.

Management: main module script (gwXXX).

The platform polls each module at startup to learn about supported features and required parameters. This speeds up operation: unsupported calls are excluded and form behavior is determined when configuring the gateway.

Module operation mechanism

Stages of working with the payment system module in BILLmanager:

1. Initial configuration:
   1. Module installation.
   2. Adding a gateway in the platform section.
2. Interaction with the external system:
   1. Configuring connection parameters and testing the connection. For more details, see articles in the section Notifications.
   2. Initiating message sending by the platform.
   3. Processing the external service response and updating the send task status.

Install the module:

• manually, if it is provided as a set of files;
• from the standard repository using a package manager.

After installation, the gateway becomes available for selection when creating a message gateway in BILLmanager.

Module structure

A message gateway module consists of an XML description and an executable script. If necessary, CGI scripts are added for receiving incoming messages.

The standard list of module files looks as follows:

Where XXX is the module name specified in Latin characters. If the name of the main module script contains a file extension, it is also included in the module name. For example, if your script is named gwsms.php, then the module name is sms.php, not sms.

XML description

The file name must be in the format billmgr_mod_gwXXX.xml, where XXX is the module name. The file is copied to the directory /etc/xml relative to the BILLmanager installation path. The file contains a description of the module itself (described as a plugin), as well as descriptions of additional forms and messages.

<mgrdata>
  <plugin name="XXX">
    <group>gateway</group>
    <msg name="desc_short" lang="ru">XXX gateway</msg>
    <msg name="desc_short" lang="en">XXX gateway</msg>
    <msg name="desc_full" lang="ru">Integration with XXX service for sending messages</msg>
    <msg name="desc_full" lang="en">Integration with XXX service for sending messages</msg>
  </plugin>

  <metadata name="gateway.XXX" type="form">
    <form>
      <page name="settings">
        <field name="api_url">
          <input name="api_url" type="text" check="url" required="yes"/>
        </field>
        <field name="api_key">
          <input name="api_key" type="text" private="yes" crypted="yes" required="yes"/>
        </field>
      </page>
    </form>
  </metadata>

  <lang name="ru">
    <messages name="gateway.XXX">
      <msg name="api_url">API URL</msg>
      <msg name="hint_api_url">Provider API endpoint address</msg>
      <msg name="api_key">API key</msg>
      <msg name="hint_api_key">Secret key for request authorization</msg>
    </messages>
    <messages name="gateway_include">
      <msg name="module_gwXXX">XXX gateway</msg>
      <msg name="gwXXX">XXX gateway</msg>
      <msg name="desc_gwXXX">Sending notifications via XXX service</msg>
    </messages>
    <messages name="msgerror">
      <msg name="msg_error_connection_failed">Failed to establish connection to gateway</msg>
      <msg name="msg_error_invalid_key">Invalid API key</msg>
    </messages>
  </lang>
</mgrdata>

Here the <plugin> element is responsible for describing the module itself. The name property matches the module name. Inside the element there can be one group element with the value gateway, which indicates that this module is used for message gateways, and several msg elements.

The metadata element with the name gateway.XXX is responsible for additional module fields when adding and configuring a gateway. Formed according to the standard XML form description. Place fields in the element <page name="settings"></page> for correct placement of fields on forms in BILLmanager. The crypted attribute indicates the need to store the parameter in encrypted form in the database. The private attribute hides the field value when displayed in the interface.

The lang element contains translations of field names on the form. The section <messages name="gateway_include"> is responsible for the module name label in the payment methods list. The section <messages name="msgerror"> contains error texts that the main script returns.

Main module script

The main gateway module script is responsible for passing information about supported functions to the platform and processing these functions. When working with the module, BILLmanager executes the script file with the following parameters:

gate/gwXXX --command cmd

Where cmd is the control command.

Required command:

• features — returns an XML file with <features> (list of supported features) and <notify_module> (specification of compatible notification module).

Main commands (called depending on declared <feature>):

• outgoing — sending an outgoing message;
• ingoing — receiving incoming messages;
• formtune — modifying the gateway settings form;
• check_connection — checking connection parameters to the external service.

Explanations for the XML file

features — output

In response to the features command, the module must return an XML document to standard output:

<doc>
  <features>
    <feature name="outgoing"/>
    <feature name="formtune"/>
    <feature name="check_connection"/>
  </features>
  <notify_module>ntsms</notify_module>
</doc>

The feature element contains a list of module capabilities. If a capability is not supported, it should not be present in the command execution result output.

outgoing — input (stdin)

The platform passes an XML document with data for sending to standard input:

<doc>
  <gateway>
    <login>user</login>
    <password>pass</password>
    <sender>BILLmanager</sender>
    <xmlparams>...</xmlparams>
  </gateway>
  <message>Your payment has been accepted</message>
  <user>
    <phone>+71234567890</phone>
    <email>client@example.com</email>
  </user>
  <project>
    <id>1</id>
    <name>MyProject</name>
  </project>
</doc>

The script must extract parameters from the <gateway> section, form a request to the external service API, using the text from <message> and contact details from <user>. On successful send, the script outputs <doc/>. On error, the script outputs XML with an error description.

check_connection — input and output

Input (stdin) — accepts connection parameters in plain text, even if the crypted="yes" attribute is specified in the XML description. This is necessary for performing a test request to the API.

<doc>
  <login>user</login>
  <password>pass</password>
  <url>https://sms.provider.com/api</url>
</doc>

Output: <doc/> on success or error XML on failure.