How to add a custom processing module

BILLmanager allows using processing modules to perform operations with services. Besides, you can use special and additional modules to process any type of services. They are the modules for manual setup and service reselling between two BILLmanager. This article walks you through the steps you need to perform to create a processing module for custom or built-in services.

All the functions in this article are called according to standard API mechanisms

The function result should be in XML or JSON format (a developer may choose any variant). If you use JSON, responses from BILLmanager will have the same structure as described in this article.

User modules can cause errors in the database and in the operation of the billing platform.

General information

The main function of a processing module is to perform operations with services in a provider's control panel. Besides, a processing module can perform additional checks when the service parameters are modified, inform BILLmanager about service configuration in a control panel or on the provider side, as well as modify settings of the module, service or service profile (for domains and SSL-certificates). Developers can add other actions that should be performed manually by a cron job or plug-in.

Module architecture

The standard module consists of two files:

billmgr_mod_pmxxx.xml — the XML description of the processing module. It is associated with the service type, module name, and description of parameters that were specified when creating the module in BILLmanager. The file example is given below. The file should be located in the /usr/local/mgr5/etc/xml/ directory. It's name — billmgr_mod_pmxxx.xml, where xxx is a unique name of a processing module.

pmxxx — the executable file, which is called directly by BILLmanager or through the background task when performing operations with services, or when required. The file should locate in the /usr/local/mgr5/processing/ directory and look like pmxxx. Make sure, that this file can be executed by root.

You can include other files, such as CGI-scripts that redirect users to the control panel, additional executable files, BILLmanager plugin files that modify the BILLmanager interface and logic.

Structure of processing module XML file

<mgrdata> <!-- XML root node -->
  <plugin name="pmxxx"> <!-- BILLmanager plugin description -->
    <group>processing_module</group> <!-- check box that indicates that this is a processing module -->
    <author>BILLmanager team</author> <!-- module author -->
    <params> <!-- processing module plugin parameters. At least one supported product type should be specified, other parameters are not required -->
      <priority lang="lang">1</priority> <!-- sorting order for a module  BILLmanager. It depends on a user's interface language specified in the attribute -->
      <type name="all"/> <!-- processing module supports all of the product types created in  BILLmanager -->
      <type name="itemtype"/> <!-- supported product type. It can be specified several times -->
      <notype name="itemtype"/> <!-- unsupported product type. It can be specified several times  -->
    </params>
  </plugin>

  <metadata name="processing.edit.pmxxx" type="form"> <!-- parameters of the module creation form in  BILLmanager. It is described according to standard rules -->
    <form title="name">
      <page name="connect">
        <field name="param1">
          <input type="text" name="param1"/>
        </field>
        <field name="param2">
          <input type="text" name="param2"/>
        </field>
        ...
        <field name="paramN">
          <input type="text" name="paramN"/>
        </field>
      </page>
    </form>
  </metadata>

  <lang name="ru"> <!-- localisation message  -->
    <messages name="plugin"> <!-- plugin name, which will be displayed in various lists and sections in BILLmanager -->
      <msg name="desc_short_pmxxx">XXX</msg>
      <msg name="desc_full_pmxxx">Integration with XXX</msg>
      <msg name="price_pmxxx">Feel</msg>
    </messages>
    <messages name="label_processing_modules"> <!-- module name, which will be displayed in various lists and sections in BILLmanager -->
      <msg name="pmxxx">XXX</msg>
      <msg name="module_pmxxx">XXX</msg>
    </messages>
    <messages name="processing.edit.pmxxx"> <!-- localisation of the module creation form in  BILLmanager -->
      <msg name="param1">First parameter</msg>
      <msg name="hint_param1">Hint to a parameter field</msg>
      <msg name="param2">Second parameter</msg>
      <msg name="hint_param2">Hint to a parameter field</msg>
      ...
      <msg name="paramN">N-parameter </msg>
      <msg name="hint_paramN">Hint to a parameter field</msg>
    </messages>
  </lang>
</mgrdata>

Restart BILLmanager to re-build the XML cache and apply the changes.

Structure of the executable file

An executable file must perform the following operations:

Receive and analyze the command line parameters that were used to call a processing module
Select the internal function depending on the value for the --command parameter
Receive the input data from the input thread, if needed
Perform operations in the control panel or through the API of the service provider
Change service status/parameters in BILLmanager, if needed
Send a result XML to STDOUT

The following values can be sent to the processing module as input parameters:

--command — the operation type. Possible values:
- features — request the XML description of supported features
- open — the background task to activate a service in a control panel or on a service provider side
- resume — the background task to enable a service in a control panel or on a service provider side
- suspend — the background task to disable a service in a control panel or on a service provider side
- start — the background task to start a service on a client side (hourly billing type)
- stop — the background task to suspend a service on a client side (hourly billing type)
- cancel_prolong — the background task to cancel automatic service renewal in a control panel or on a service provider side
- close — the background task to delete a service in a control panel or on a service provider side
- setparam — the background task to change parameters in a control panel or on a service provider side. Service parameters in BILLmanager and its add-ons can be changed
- get_suitable_module — request a list of available processing modules for the service with parameters passed in the input XML document
- check_connection — check the connection to a control panel or service provider with parameters specified in the input XML document
- tune_connection — modify parameters that are used to connect to a control panel or service provider. The XML of the form with initial parameters is sent to STDIN, the system should return to STDOU a modified XML document describing parameters configuration form.
- tuning_param — modify the form with additional parameters of the processing module
- usercreate — modify the new user registration form on a provider side. It can be used only if you distribute the processing module
- tune_changepassword — modify the service password form
- sync_pricelist — the background task to synchronize a tariff plan in BILLmanager with templates in a control panel
- get_server_config — the background task to get templates configuration in a control panel or on a service provider side
- sync_server — the background task to synchronize data in a control panel or on a service provider side and in BILLmanager
- prolong — the background task to renew a service in a control panel or on a service provider side
- stat — the background task to collect service consumption statistics
- reboot — service reboot (VPS, dedicated server or any other service that supports this functionality)
- import_pricelist — request parameters of a tariff plan, which will be created in BILLmanager. An XML description of tariff parameters should be returned.
- check_param — check the possibility to change service settings. An XML document with old and new values is sent to STDIN, an XML with ok or error description is sent to STDOUT.
- check_addon — check the possibility to change service add-ons. An XML document with old and new values is sent to STDIN, an XML with ok or error description is sent to STDOUT.
- changepassword — background task to change a service password in a control panel or on a service provider's side.
- addip — background task to add an IP address to service in a control panel or on a service provider's side.
- editip — background task to change a service IP address in a control panel or on a service provider's side.
- delip — background task to delete an IP address in a control panel or on a service provider's side.
- transition_controlpanel — request an XML document with description of available control panels
- pingip — obtain information about IP address availability from a control panel or service provider.
- cleanup — background task to perform additional operations after a service has been marked deleted in BILLmanager
- cloneitem — background task to perform additional operations after a service has been imported from one client into another new values can be added in the future. If a processing module cannot handle a received command, it should end up with code 0 to avoid unexpected errors and hanging of running operations.
- --subcommand — parameter, which specifies an action that should be performed. It is passed if --command equals tuning_param and import_pricelist
- --id — tariff id in a control panel or on a service provider's side while executing import_pricelist
- --item — service id, for which this operation is performed.
- --module — id of the processing module for which this operation is performed
- --param — additional parameter name
- --value — additional parameter value
- --runningoperation — id of the running operation associated with the command you call. It is used to register operation in case of service processing failure
- --level — access level for which a processing module is called. It is passed when executing transition_controlpanel
- --password — a new service password. It is passed when executing changepassword
- --userid — id of the user who is running the operation. It is passed when executing setparam
- --panelkey — id of the control panel to go to. It is passed when executing transition_controlpanel
- --ip — id of IP address to handle.

A developer doesn't need to handle all of the commands and parameters. The most part of them is called only if a module supports certain functions. The following is a more detailed description of commands:

features

Request for functions and parameters of the processing module. It is called when needed after BILLmanager starts.

Function:

Example:

/usr/local/mgr5/processing/pmxxx --command features

Input parameters:

Output parameters:

The XML document containing a description of processing module parameters and supported functions in the following format

<doc>
  <itemtypes> <!-- list of supported product type -->
    <itemtype name="itemtype1"/>
    ...
    <itemtype name="itemtypeN"/>
  </itemtypes>
  <params> <!-- list of parameters of the processing module. Parameters that are not specified in this section won't be saved into the database -->
    <param name="param1"/> <!-- non-encrypted parameter -->
    ...
    <param name="paramN"/>
    <param name="cryptedparam1" crypted="yes"/> <!-- encrypted parameter -->
    ...
    <param name="cryptedparamN" crypted="yes"/>
    <param name="param1"/> <!-- non encrypted parameter --> <!-- additional parameter-->
    ...
    <customparam name="customparam1" unique="yes|no" defval=""/>
    ...
    <customparam name="customparamN"/>
  </params>
  <features> <!-- list of supported functions -->
    <feature name="feature1"/>
    ...
    <feature name="featureN"/>
  </features>
</doc>

Where:

the name attribute of the itemtype nodes is specified based on the product/service internal name.
the name attribute of the param node must match the field name of the input form of a processing module to match the name of the input field of the processing module settings form. The crypted attribute indicates that a parameter should be saved in an encrypted format
The name attribute of customparam will be displayed in a list when the additional parameter is added. The unique attribute set to yes indicates that there can be only one parameter with that internal name. The defval attribute is optional and defines a default value
The name attribute of the feature node indicates the supported feature of a processing module/ Possible values:
- changepassword — the module supports service password change. The corresponding button will be available in BILLmanager interface
- tune_changepassword — the module supports password form change
- check_addon — the module enables to check the possibility to change service add-on
- check_connection — the module supports check of input data in a processing module edit form
- check_param — the module supports service parameters check when they are modified
- cleanup — the module supports additional cleaning after server deletion
- cloneitem — the module supports service import between clients
- tune_connection — the module supports modification of a processing module form in BILLmanager
- datacenter — the module supports service distribution among data-centers
- get_server_config — the module enables to get configuration
- get_suitable_module — the module enables to define a list of processing modules that can be used for service processing
- ipmgr — the module supports integration with IPmanager. It enables to choose IPmanager in the processing module form
- need_ipmgr — IPmanager is required for further operations
- licserver — the module supports integration with external BILLmanager as a license server. It enables to choose BILLmanager in the processing module form
- pingip — the module supports check of IP availability before deletion
- prolong — the module supports service renewal in a control panel or service provider side
- reboot — the module supports service restart
- stat — the module supports service statics collection
- stop_by_panelid — the module supports service suspension by id in a control panel
- sync_pricelist — the module supports synchronization of a tariff plan in BILLmanager with a corresponding item in a control panel or service provider
- sync_server — the module supports synchronization of service parameters in BILLmanager and a control panel or service provider
- transition_controlpanel — the module supports switching to a control panel
- tuning_param - the module supports additional parameters of the processing module

open

Service creation (activation) in a control panel or on the service provider's side.

Function:

Example:

/usr/local/mgr5/processing/pmxxx --command open --item id --runningoperation id
/usr/local/mgr5/processing/pmxxx --command open --item id

Input parameters:

--item — service id
--runningoperation — id of service activation operation (if any)

Output parameters:

Once completed, you should call the itemtype.open function, where itemtype is an internal name of a service type with parameters:

elid — service id
All parameters that are specified during service activation (they are shown in the product type parameters)
sok = ok

The service will get activated, and a client will receive a corresponding notification (if this option is configured).

resume

Service activation in a control panel or on the service provider's side

Function:

Example:

/usr/local/mgr5/processing/pmxxx --command resume --item id --runningoperation id
/usr/local/mgr5/processing/pmxxx --command resume --item id

Input parameters:

--item — id of the service to handle
--runningoperation — id of the running operation.

Output parameters:

Once completed, call the service.postresume function with the following parameters:

elid — service id
sok = ok

suspend

Service suspension in a control panel or on a service provider's side

Function:

Example of call:

/usr/local/mgr5/processing/pmxxx --command suspend --item id --runningoperation id
/usr/local/mgr5/processing/pmxxx --command suspend --item id

Input parameters:

--item — id of the service to handle
--runningoperation — id of the running operation to suspend a service

Output parameters:

Once completed, call the service.postsuspend function with the following parameters:

elid — service id
sok = ok

start

Service start in a control panel or on a service provider's side

Function:

Example of call:

/usr/local/mgr5/processing/pmxxx --command start --item id --runningoperation id
/usr/local/mgr5/processing/pmxxx --command start --item id

Input parameters:

--item — id of the service to handle
--runningoperation — id of the running operation to start a service.

Output parameters:

Once completed, call the service.poststart function with parameters:

elid — service id
sok = ok

stop

Stop a service in a control panel or on a service provider's side

Function support:

Example of call:

/usr/local/mgr5/processing/pmxxx --command stop --item id --runningoperation id
/usr/local/mgr5/processing/pmxxx --command stop --item id

Input parameters:

--item — id of the service to handle
--runningoperation — id of the running operation to stop a service

Output parameters:

Once completed, call the service.poststop function with the following parameters:

elid — service id
sok = ok

cancel_prolong

Cancel automatic service renewal in a control panel or on a service provider's side

Function support:

Example of call:

/usr/local/mgr5/processing/pmxxx --command cancel_prolong --item id

Input parameters:

--item — id of the service to handle

Output parameters:

close

Service deletion in a control panel or on a service provider's side

Function support:

Example of call:

/usr/local/mgr5/processing/pmxxx --command close --item id --runningoperation id
/usr/local/mgr5/processing/pmxxx --command close --item id

Input parameters:

--item — id of the service to handle
--runningoperation — id of the running operation to enable the service

Output paremeters:

Once completed, execute the service.postclose function with the following parameters:

elid — service id
sok = ok

setparam

Change service parameters in a control panel or on a service provider's side

Function support:

Example of call:

/usr/local/mgr5/processing/pmxxx --command setparam --item id --runningoperation id --userid id
/usr/local/mgr5/processing/pmxxx --command setparam --item id

Input parameters:

--item — id of the service to handle
--runningoperation — id of the running operation
--userid — id of the user who initiated a change of the tariff plan

Output parameters:

Service parameters can be changed by performing two operations in BILLmanager

Change of tariff plan
Change of service parameters and add-ons

In this case, in the item table, the link lastpricelist to a previous tariff plan is saved for the service. If the tariff plan cannot be changed in a control panel or on a service provider's side, you should call the service.changepricelist.rollback function with the following parameters:

elid — service id
userid — user id
sok = ok

In this case additional actions are not required

Once completed, call the service.postsetparam function with the following parameters:

elid — service id
sok = ok

get_suitable_module

Get a list of processing modules to activate a service with sent parameters

Function support:

get_suitable_module

Example of call:

/usr/local/mgr5/processing/pmxxx --command get_suitable_module
/usr/local/mgr5/processing/pmxxx --command get_suitable_module --item id

Input parameters:

--item — id of the service to handle. If this a tariff selection step, the --item parameter won't be used.
An XML document with service parameters such as

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <item> <!-- service parameters -->
   <pricelist>PR_ID</pricelist> <!-- PR_ID - tariff id -->
    <param1></param1>
    ...
    <paramN></paramN>
  </item>
  <skip_modules></skip_modules>  <!-- Id of processing modules that can be ignored when choosing an appropriate processing module. Usually, processing modules that were already used to activate a service, are selected -->
</doc>

Output parameters:

The XML document like

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <modules> <!-- service parameters -->
    <module id="id1"/>
    ...
    <module id="idN"/>
  </modules>
</doc>

where the id attribute of the module node is an id of the processing module that will handle a service

check_connection

Check the possibility to connect to a control panel or service provider

Function:

check_connection

Example of call:

/usr/local/mgr5/processing/pmxxx --command check_connection

Input parameters:

The XML document with parameters

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <processingmodule> <!-- processing module parameters -->
    <param1></param1>
    ...
    <paramN></paramN>
  </item>
</doc>

Output parameters:

The XML document:

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <ok/>
</doc>

Or the error XML description will be returned.

tune_connection

Change the configuration form of a processing module. It can be used to fill out lists, delete /add attributes to fields, and perform other operations in order to modify a form

Function:

tune_connection

Example of call

/usr/local/mgr5/processing/pmxxx --command tune_connection

Input parameters:

An XML document describing a form

Output parameters:

Source or modified XML document

tuning_param

Configuration of additional parameters, modification of a form/list of additional parameters' settings

Function

tuning_param

Example of call:

/usr/local/mgr5/processing/pmxxx --command tuning_param --subcommand action

where action can have the following values:

TableFormTune — the function is called to create a parameter configuration form
TableGet — the function is called to obtain data of the already configured parameter
TableSet — the function is called while saving parameter
List — the function is called to create a list of parameters

Input parameters:

An XML document describing a form or list with the additional node session_params with session parameters

Output parameters:

Source or modified XML document, or XML description of an error

usercreate

Modification of a user creation form on a service provider's side. It is normally used for generating a registration link in a provider's system Function:

usercreate

Example of a call:

/usr/local/mgr5/processing/pmxxx --command usercreate

The XML handler file should describe the user registration form named processing.edit.module_name.createuser

Input parameters:

An XML document describing a form

Output parameters:

Source or modified XML document

tune_changepassword

Modification of a service password form

To add new fields into the password change form, for example, description of how to enter a password, you need to add metadata into the module XML:

<metadata name="modulename.changepassword" type="form">
  <form title="name">
    ...
  </form>
</metadata>

Functions:

tune_changepassword

Example of a call:

/usr/local/mgr5/processing/pmxxx --command tune_changepassword --module id

Input parameters:

--module — id of the processing module associated with the service, which password will be changed
An XML document with form description

Input parameters:

Source or modified XML document

sync_pricelist

Synchronization of a tariff plan in BILLmanager with the corresponding item in a control panel or on a service provider's side. It can be used to create a template in a control panel, set additional limits for add-ons in BILLmanaer based on data from a control panel or service provider. This function is called when creating or modifying a tariff plan, and connecting a tariff plan to a processing module.

sync_pricelist

Example of a call:

/usr/local/mgr5/processing/pmxxx --command sync_pricelist --module id

Input parameters:

--module — processing module id

Output parameters:

get_server_config

Form and save the description of a processing module configuration

Function:

get_server_config

Example of a call:

/usr/local/mgr5/processing/pmxxx --command get_server_config --module id

Input parameters:

--module — processing module id

Output parameters:

Module configuration is an XML document in the following format:

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <ostemplate> <!-- list of OS templates installed in a control panel -->
    <elem>
      <id>id1</id>
    </elem>
    ...
    <elem>
      <id>idN</id>
    </elem>
  </ostemplate>
  <presets> <!-- list of templates created in a control panel or on a service provider's side. It is used as internal names for tariff plans in BILLmanager -->
    <preset name="name1"/>
    ...
    <preset name="nameN"/>
  </presets>
</doc>

It can also contain additional information for further use

Call the processing.setconfig function with the following parameters

elid — processing module id
config — XML description of the configuration parameters

sync_server

Synchronize service data between BILLmananager and a control panel or service provider

Function:

sync_server

Example of call:

/usr/local/mgr5/processing/pmxxx --command sync_server --module id

Input parameters:

--module — processing module id

Output parameters:

It can be used to set a cluster node where a service was created, OS template for VPS and dedicated servers, or for any other operations that provide up-to-date information in BILLmanager.

prolong

Service renewal in a control panel or on a service provider's side

Function:

prolong

Example of call:

/usr/local/mgr5/processing/pmxxx --command prolong --item id --runningoperation id
/usr/local/mgr5/processing/pmxxx --command prolong --item id

Input parameters:

--item — service id
--runningoperation — id of the running operation

Output parameters:

Once completed, call the service.postprolong function with the following parameters:

elid — service id
sok = ok

stat

Collect resource usage statistics by services in a control panel or on a service provider's side

Function:

stat

Example of call:

/usr/local/mgr5/processing/pmxxx --command stat --module id

Input parameters:

--module — processing module id

Output parameters:

Collected statistics should be saved into BILLmanager database -- the itemstat table, table fields:

item — service id
statdate — resource consumption date
param — internal name of the parameters to save statistics. It can be either an internal name of add-on's service type or any name of a parameter that is specified in the add-on's configuration form.
value — resource consumption (integer)
measure — unit of measure

Once statistical information is saved into the BILLmanager database, call the service.poststat function with the following parameters:

elid — processing module id
date — date when statistics was collected

A date when statistics was collected is saved into the laststatdate field of the processingmodule table, where id is handler id

import_pricelist

Get information about an SSL-certificate from a control panel or service provider. This information will be saved in BILLmanager

Function:

import_pricelist

Example of call:

/usr/local/mgr5/processing/pmxxx --command import_pricelist --module id --subcommand action
/usr/local/mgr5/processing/pmxxx --command import_pricelist --module id --subcommand action --id id

Input parameters:

--module — processing module id
--subcommand — information type. Possible values:
- available — request a list of tariff plans available for import
- pricelist — request detailed information about a tariff for import. The --id parameter is the id of a tariff panel in a control panel or on service provider's side
- images — request a list of disk images (if any). The --id parameter is the id of a tariff panel in a control panel or on service provider's side
- periods — request a list of tariff order periods. The --id parameter is the id of a tariff panel in a control panel or on service provider's side
- details — request a list of tariff add-ons. The --id parameter is the id of a tariff panel in a control panel or on service provider's side

Output parameters:

An XML document, which format depends on --subcommand that you receive:

available

<doc>
  <elem>
    <id>...</id> <!-- tariff id in a control panel or on a service provider's side -->
    <name>...</name> <!-- tariff name in a control panel or on a service provider's side -->
    <name_ru>...</name_ru> <!-- tariff name in ''ru'' localisation in a control panel or on a service provider's side -->
    ...
    <name_xx>...</name_xx> <!-- tariff name in ''xx'' localisation in a control panel or on a service provider's side -->
    <itemtype>...</itemtype> <!-- internal name of a tariff product type-->
  </elem>
  ...
  <elem>
    <id>...</id>
    <name>...</name>
    <name_ru>...</name_ru>
    ...
    <name_xx>...</name_xx>
    <itemtype>...</itemtype>
  </elem>
</doc>

pricelist

<doc>
  <elem>
    <id>...</id> <!-- tariff id in a control panel or on a service provider's side -->
    <name>...</name> <!-- tariff name in a control panel or on a service provider's side -->
    <name_ru>...</name_ru> <!-- tariff name in ''ru'' localisation in a control panel or on a service provider's side -->
    ...
    <name_xx>...</name_xx> <!-- tariff name in ''xx'' localisation in a control panel or on a service provider's side -->
    <itemtype>...</itemtype> <!-- internal name of a tariff product type -->
    <real_billtype>4</real_billtype> <!-- fixed amount -->
    <internalname>...</internalname> <!-- tariff template name-->
    <billdaily>...</billdaily> <!-- ''on'' for daily charges, otherwise - ''off'' -->
    <billprorata>...</billprorata> <!-- ''on'' for calendar-based charges, otherwise - ''off'' -->
    <prorataday>...</prorataday> <!-- pro-rata day for calendar billing  -->
    <minperiodtype>...</minperiodtype> <!-- type of a minimal order period: 0 - without minimal order period, 1 - months, 2 - days-->
    <minperiodlen>...</minperiodlen> <!-- minimal order period length -->
  </elem>
</doc>

images

<doc>
  <elem>
    <name>...</name> <!-- disk template name -->
    <name_ru>...</name_ru> <!-- disk template name in ''ru'' localisation -->
    ...
    <name_xx>...</name_xx> <!-- disk template name in ''xx'' localisation -->
    <intname>...</intname> <!-- disk template internal name -->
  </elem>
  ...
  <elem>
    <name>...</name>
    <name_ru>...</name_ru>
    ...
    <name_xx>...</name_xx>
    <intname>...</intname>
  </elem>
</doc>

periods

<doc>
  <currencies>
    <elem>
      <currency_code>...</currency_code> <!-- ISO code of the price currency -->
      <period name="monthly">...</period> <!-- monthly price, optionally -->
      <period name="quarterly">...</period> <!-- price for 3 months, optionally -->
      <period name="semiannual">...</period> <!-- price for half a year, optionally -->
      <period name="annually">...</period> <!-- yearly price, optionally  -->
      <period name="biennial">...</period> <!-- price for 2 years, optionally -->
      <period name="triennial">...</period> <!-- price for 3 years, optionally -->
      <period name="quadrennial">...</period> <!-- price for 4 years, optionally -->
      <period name="quinquennial">...</period> <!-- price for 5 years, optionally -->
      <period name="setup">0.0000</period> <!-- setup fee, optionally -->
    </elem>
  </currencies>
</doc>

details

<doc>
    <elem>
    <id>...</id> <!-- add-on id in a control panel or on a service provider's side -->
    <intname>...</intname> <!-- add-on type internal name -->
    <billtype>...</billtype> <!-- add-on billing type: 1 - do not count, 2 - based on order, 3 - based on statistics -->
    <addontype>...</addontype> <!-- add-on type: 1 - logical, 2 - integer, 3 - enumeration -->
    <manualname>...</manualname> <!-- custom name: on - ''name'' will be used, off - product type name will be used  -->
    <active>...</active> <!-- add-on state: on - enabled, off - disabled-->
    <name>...</name> <!-- add-on's product type name -->
    <name_ru>...</name_ru>
    ...
    <name_xx>...</name_xx>
    <addonname>...</addonname> <!-- add-on name in case of manualname=on -->
    <addonname_ru>...</addonname_ru>
    ...
    <addonname_xx>...</addonname_xx>
    <rlimit>...</rlimit> <!-- value included into tariff plan for integer add-on -->
    <addonenumval>...</addonenumval> <!-- value included into tariff plan for add-on based on enumeration -->
    <measure>unit</measure> <!-- internal name of unit of measure -->
    <addonenum>...</addonenum> <!-- enumeration id in a control panel or on a service provider's side for add-on based on enumeration -->
    <addonstep>...</addonstep> <!-- order step for integer add-on -->
    <addonmax>...</addonmax> <!-- maximum value for integer add-on -->
    <minperiodtype>...</minperiodtype> <!-- minimum order period type, like for tariff plan -->
    <minperiodlen>...</minperiodlen> <!-- minimum order period length, like for tariff plan -->
    <addonstattype>...</addonstattype> <!-- billing type for add-ons based on statistics:  1 - overage price is calculated over one month, 2 - overage price is calculated over one day-->
    <addonstatcomparison>...</addonstatcomparison> <!-- billing type for several add-on parameters based on statistics: 1 - sum up parameters' values, 2 - the maximum parameter is taken -->
    <addonstatcalculation>...</addonstatcalculation> <!-- price selection method for a statistics-based add-on: 1 - per item, 2 - per item per month -->
    <internalname>...</internalname> <!-- internal name of a statistics-based parameter -->
    <restrictclientchange>...</restrictclientchange> <!-- client can edit service after order: on - can edit, off - cannot edit -->
  </elem>
  ...
  <enum id="..." name="..." intname="..." name_ru="..."> <!-- description of tariff enumeration: id - id in the external system, name - enumeration name, intname - enumeration internal name -->
    <enumitem id="..." name="..." intname="..." disabled="..." name_ru="..."/> <!-- enumeration element: id - id in the external system, name - enumeration element name, intname - element internal name -->
    ...
  </enum>
  ...
  <addon_prices> <!-- add-on prices -->
    <elem>
      <id>...</id> <!-- id of the corresponding add-on -->
      <currency_code>...</currency_code> <!-- ISO code of the price currency -->
      <period name="monthly">...</period> <!-- monthly price, optionally -->
      <period name="quarterly">...</period> <!-- price for 2 months, optionally -->
      <period name="semiannual">...</period> <!-- price for half a year, optionally -->
      <period name="annually">...</period> <!-- yearly price, optionally -->
      <period name="biennial">...</period> <!-- price for 2 years, optionally -->
      <period name="triennial">...</period> <!-- price for 3 years, optionally -->
      <period name="quadrennial">...</period> <!-- price for 4 years, optionally -->
      <period name="quinquennial">...</period> <!-- price for 5 years, optionally -->
      <period name="setup">...</period> <!-- setup fee, optionally -->
      <period name="stat">...</period> <!-- statistics-based price, optionally -->
    </elem>
    ...
  </addon_prices>
  <enumitem_prices>
    <elem>
      <id>...</id> <!-- id of the corresponding add-on -->
      <enumitem>...</enumitem> <!-- enumeration element id -->
      <currency_code>...</currency_code> <!-- ISO code of the price currency -->
      <period name="monthly">...</period> <!-- monthly price, optionally -->
      <period name="quarterly">...</period> <!-- price for 3 months, optionally -->
      <period name="semiannual">...</period> <!-- price for half a year, optionally -->
      <period name="annually">...</period> <!-- price for 1 year, optionally -->
      <period name="biennial">...</period> <!-- price for 2 years, optionally -->
      <period name="triennial">...</period> <!-- price for 3 years, optionally -->
      <period name="quadrennial">...</period> <!-- price for 4 years, optionally -->
      <period name="quinquennial">...</period> <!-- price for 5 years, optionally -->
      <period name="setup">0.0000</period> <!-- setup fee, optionally -->
    </elem>
    ...
  </enumitem_prices>
</doc>

check_param

Check the possibility to change service parameters

Function:

check_param

Example of call:

/usr/local/mgr5/processing/pmxxx --command check_param --item id --param id --value id --level id

Input parameters:

--item — service id
--param — parameter internal name
--value — new value
--level — access level of the user who changed parameters
the XML

<doc>
  <item> <!-- list of old parameters of a service-->
    <param1>...</param1>
    ...
    <paramN>...</paramN>
  </item>
  <newitem> <!-- list of new parameters of a service -->
    <param1>...</param1>
    ...
    <paramN>...</paramN>
  </newitem>
</doc>

Output parameters:

If a parameter can be changed, the following XML will be generated

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <ok/>
</doc>

Otherwise, an error message will be displayed.

check_addon

Check the possibility to change service add-on

Function:

check_addon

Example of call:

/usr/local/mgr5/processing/pmxxx --command check_addon --item id --param id --value id --level id
/usr/local/mgr5/processing/pmxxx --command check_addon --item id --param id --value id

Input parameters:

--item — service id
--param — add-on internal name
--value — new value
--level — user access level, who modified the add-on
XML

<doc>
  <item> <!-- service parameters -->
    <param1>...</param1>
    ...
    <paramN>...</paramN>
  </item>
</doc>

Output parameters:

If the parameter can be changed, the following XML will be generated

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <ok/>
</doc>

Otherwise, an error message will be displayed

changepassword

Service password change in a control panel or on a service provider's side

Function:

changepassword

Example of call:

/usr/local/mgr5/processing/pmxxx --command changepassword --item id --password pwd

Input parameters:

--item — service id
--password — new value

Output parameters:

Once the password has been changed, save it in BILLmanager by executing the service.saveparam command with the following parameters

item — service id
password — new password
sok = ok

Call the service.postchangepassword function with the following parameters:

item — service id
sok = ok

addip

Assign a new IP address to service

Function:

Example of call:

/usr/local/mgr5/processing/pmxxx --command addip --item id --ip id

Input parameters:

--item — service id
--ip — IP address id from the ip table

Output parameters:

An IP address is saved in BILLmanager with the service.ip.add fucntion with parameters:

elid — IP address id
ip — IP address value
domain — PTR
ipmgr — URL to IPmanager, if any
sok = ok

The following XML will be returned

<doc>
  <ip.id>...</ip.id>
</doc>

ip.id contains a new id of the IP address in BILLmanager (the id is changed if a service is assigned an IP address that has been already saved in BILLmanager)

For the received ip id, call the activation function service.ip.add.commit with the following parameters:

elid — IP address id
sok= ok

editip

Changer service IP address. It is called when editing the domain name associated with that IP in BILLmanager

Function:

Example of call

/usr/local/mgr5/processing/pmxxx --command editip --ip id

Input parameters:

--ip — IP address id from the ip table

Output parameters:

delip

Delete service IP address

Function:

Example of call:

/usr/local/mgr5/processing/pmxxx --command delip --item id --ip id

Input parameters:

--item — service id
--ip — IP address id from the ip table

Output parameters:

An IP address is marked deleted in BILLmanager with the service.ip.del function with the following parameters:

elid — IP address id
sok = ok

transition_controlpanel

Drill down to server as user

Function:

transition_controlpanel

Example of a call:

/usr/local/mgr5/processing/pmxxx --command transition_controlpanel --item id --level level - get a list of available control panels
/usr/local/mgr5/processing/pmxxx --command transition_controlpanel --item id --panelkey panelkey - get a URL to the selected control panel
/usr/local/mgr5/processing/pmxxx --command transition_controlpanel --panelkey panelkey - navigate to server from the processing modules section

Input parameters:

--item — service id
--level — user role
--panelkey — processing module id. When you go from the list of processing, or panel id, which URL will be displayed

Output parameters:

The XML document with a list of control panels and their URL:

<doc>
  <url></url> <!-- URL, it is shown when you navigate to the panel, or when only one variant is available -->
  <panelcount>...</panelcount> - number of control panels that can be open. When you navigate to a certain panel, or when only one variant is available,  '''1''' will be passed, or the value will be missing 
  <panelname keyname="keyname">...</panelname> <!-- description of a control panel to drill down. The ''keyname'' value will be passed as ''panelkey'' -->
  ...
</doc>

pingip

Check IP address availability. This check is performed before deletion

Function:

pingip

Example of a call:

/usr/local/mgr5/processing/pmxxx --command pingip --item id --ip id

Input parameters:

--item — service id
--ip — IP address id

Output parameters:

The XML document indicating availability if that IP address

<doc>
  <ping_result>...</ping_result> <!-- check result: OK if that IP address is pinged -->
</doc>

cleanup

Additional actions are performed after service deletion (after the service gets the "deleted" status)

Function:

cleanup

Example of a call:

/usr/local/mgr5/processing/pmxxx --command cleanup --item id

Input parameters:

--item — service id

Output parameters:

cloneitem

Service import between clients in BILLmanager. It can be used if different services are created within one account in a control panel or in a service provider's side.

Function:

cloneitem

Example of a call:

/usr/local/mgr5/processing/pmxxx --command cloneitem --item id

Input parameters:

--item — new service id

Output parameters:

reboot

Service reboot

Function:

reboot

Example of a call:

/usr/local/mgr5/processing/pmxxx --command reboot --item id

Errors

If Id of a running operation was passed when calling the module function, and an error occurred while processing the command, the corresponding information should be displayed in BILLmanager. You can use a number of functions:

runningoperation.edit — edit the running operation. Possible values:

elid — id of the running operation
errorxml — XML document with XML description of errors, like

<doc>
  <error date="2000-01-01 00:00:00" type="type" object="object" value="value"> <!-- error description in a standard format with the ''date'' format - time when the error occurred -->
    ...
    <backtrace>...</backtrace> <!-- debugging information to diagnose the error. It is shown when in the Current operations module -->
    <log>...</log> <!-- error log. It is shown when in the Current operations module -->
  </error>
  <processingmodule date="2000-01-01 00:00:00" id="id" name="name"/> <!-- processing module where the error occurred -->
  <custommessage>...</custommessage>  <!-- comments. It is shown when in the Current operations module -->
</doc>

Details

If you have a service id and don't want this operation to be performed again and again (in the runningoperation table the trycount field shows the number of attempts to run the operation), you can create a task to a responsible department. Complete the following steps:

Call the task.gettype function, and in the operation parameter pass the current value of the --command parameter. The following XML will be returned:

<doc>
  <task_type>...</task_type>
</doc>

where task_type is a type of the operation you need to create. If the node doesn't exist or empty, the operation cannot be created.

Register a task with the task.edit function. Parameters:
- item — service id
- runningoperation — id of the running operation
- type — the task_type value

Examples of modules

An executable file of the processing module can be written in any script or compiled programming language, which supports parameters of the command line and input/output threads. You may choose any language, however, we recommend using C++ in order to facilitate the development process and catch up with new functions.

C++ (using BILLmanager libraries)

Starting from version 5.58 you can use BILLmanager header files to create custom processing modules. Beside that simplified example, you can look into examples in BILLmanager developer package - billmanager-[BILLmanager release version]-devel, e.g:

yum install billmanager-devel
or
yum install billmanager-corporate-devel

Comments

Then you can find examples in the directory:

/usr/local/mgr5/src/examples
<?xml version='1.0' encoding='UTF-8'?><doc>  <modules> <!-- service parameters -->    <module id="id1"/>    ...    <module id="idN"/>  </modules></doc>