How to add processing modules

From ISPWiki
Jump to: navigation, search

General information

Special processing modules can be used in BILLmanager in order to perform different operations with services in control panels. Besides, you can use special and additional modules to process any types of services. Such modules includes modules for manual setup and service reselling from one BILLmanager into another.

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 given according to standard API mechanisms

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, format adjusted

Purposes of processing modules

The main function of a processing module is to perform operations on services in a provider's control panel. Besides, a processing module can perform additional checks when service parameters are changed, inform BILLmanager about services configuration in a control panel or on a service provider's side, and modify settings of a 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 with BILLmanager's plug-in.

Module architecture

A standard module for BILLmanager consists of two files:

  • billmgr_mod_pmxxx.xml - xml description of the processing module. It is associated with a service type, module name, and decription of parameters specified during module creation in BILLmanager. An example of such a file is given below. The file should be located in the /usr/local/mgr5/etc/xml/ directory, and be named as billmgr_mod_pmxxx.xml. Where xxx id a unique name of a processing module.
  • pmxxx - executable file, which is called directly by BILLmanager or through a 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.

Other files can be also included if needed - cgi-scripts redirects users to control panel, additional executable files, BILLmanager plugin files, which can change BILLmanager interface and logic.

Structure of processing module XML file

<?xml version="1.0" encoding="UTF-8"?>
<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 in order to re-build XML cache and apply the changes.

Structure of the executable file

An executable file should be able to perform the following operations:

  • Get and analyse command line parameters, that were used to call a processing module
  • Select an internal function depending on the value for the --command parameter
  • Get input data, if needed
  • Perform operations in a control panel or via service provider's API
  • Change service status/parameters in BILLmanager, if needed
  • Send an XML to STDOUT

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

  • --command - operation type. Possible values:
    • features - request of XML description of supported features
    • open - background task to activate a service in a control panel or on a service provider's side
    • resume - background task to enable a service in a control panel or on a service provider's side
    • suspend - background task to disable a service in a control panel or on a service provider's side
    • start - background task to start a service on a client side (hourly billing type)
    • stop - background task to suspend a service on a client side (hourly billing type)
    • cancel_prolong - background task to cancel automatic service renewal in a control panel or on a service provider's side
    • close - background task to delete a service in a control panel or on a service provider's side
    • setparam - background task to change parameters in a control panel or on a service provider's side. Both service parameters in BILLmanager and its add-ons can be changed
    • get_suitable_module - request a list of available processing modules for a service with parameters passed in the input XML document
    • check_connection - check 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. An 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 a form with additional parameters of the processing module
    • usercreate - modify a new user registration form on a provider side. It can be used only if you distribute the processing module
    • tune_changepassword - modify a service password form
    • sync_pricelist - background task to synchronize a tariff plan in BILLmanager with templates in a control panel
    • get_server_config - background task to get configuration of templates in a control panel or on a service provider's side.
    • sync_server - background task to synchronize data in a control panel or on a service provider's side, and in BILLmanager
    • prolong - background task to renew a service in a control panel or on a service provider's side.
    • stat - background task to collect service consumption statistics
    • reboot - service reboot (VPS, dedicated server or any other service, which supports this functionality)
    • import_pricelist - request for parameters of a tariff plan, which will be created in BILLmanager. An XML with 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 withok 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 withok 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 an operation in cause 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 support 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:

No

Example:

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

Input parameters:

No

Output parameters:

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

<?xml version="1.0" encoding="UTF-8"?>
<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 соответствовать имени поля ввода формы настроек модуля обработки. The crypted attribute indicates that a parameter should be saved in encrypted format
  • The name attribute of customparam will be displayed in a list when 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:

No

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:

No

Once complete, 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 options is configured).

resume

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

Function:

No

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:

No

Once completed, call the service.postresumefunction with the following parameters:

  • elid - service id
  • sok= ok

suspend

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

Function:

No

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:

No

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:

No

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:

No

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

  • elid - service id
  • sok - ok

stop

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

Function support:

No

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:

No

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:

No

Example of call:

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

Input parameters:

  • --item - id of the service to handle к

Output parameters:

No

close

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

Function support:

No

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:

No

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:

No

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 change of the tariff plan

Output parameters:

no

Service parameters can be changed by performing two operations in BILLmanager

  • Change of tariff plan

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
  • Change of service parameters and add-ons

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 --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:

An XML document like

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <modules> <!-- service parameters -->
    <module id="id1"/>
    ...
    <module id="idN"/>
  </item>
</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:

  • An XML document with parameters like
<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <processingmodule> <!-- processing module parameters  -->
    <param1></param1>
    ...
    <paramN></paramN>
  </item>
</doc>

Output parameters:

Document XML like

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

В случае успеха, otherwise error XML description will be sent

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

Fucntion

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 already configured parameter
  • TableSet - the funcion 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 call:

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

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>
This feature is available starting from BILLmanager 5.84.0 

Functions:

tune_changepassword

Example of 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 call:

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

Input parameters:

  • --module - processing module id

Output parameters:

No

get_server_config

Form and save description of a processing module configuration

Function:

get_server_config

Example of call:

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

Input parameters:

  • --module - processing module id

Output parameters:

No

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:

No

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:

No

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:

no

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

  • item - service id
  • statdate - resouce 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
<?xml version="1.0" encoding="UTF-8"?>
<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
<?xml version="1.0" encoding="UTF-8"?>
<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
<?xml version="1.0" encoding="UTF-8"?>
<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
  • XML вида
<?xml version="1.0" encoding="UTF-8"?>
<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
<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <item> <!-- list of service parameters -->
    <param1>...</param1>
    ...
    <paramN>...</paramN>
  </item>
</doc>

Output parameters:

If 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:

no

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 new IP address to service

Function:

No

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:

no

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

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <ip.id>...</ip.id>
</doc>

Надо ip.id содержит новый код ip адреса в 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:

no

Example of call

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

Input parameters:

  • --ip - IP address id from the ip table

Output parameters:

no

delip

Delete service IP address

Function:

No

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:

no

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 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:

<?xml version="1.0" encoding="UTF-8"?>
<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 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

<?xml version="1.0" encoding="UTF-8"?>
<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 call:

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

Input parameters:

  • --item - service id

Output parameters:

No

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 call:

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

Входные параметры:

  • --item - new service id

Output parameters:

No

reboot

Service reboot

Function:

reboot

Example of call:

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

Input parameters:

  • --item - service id

Output parameters:

No

After service reboot, call the service.postreboot function with parameters:

  • elid - service id
  • sok = ok

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
<?xml version="1.0" encoding="UTF-8"?>
<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>

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:
<?xml version="1.0" encoding="UTF-8"?>
<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 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-standard-devel

Then you can find examples in the directory:

/usr/local/mgr5/src/examples

See also