How to add a domain registrar module

The registrar module in BILLmanager is a software component that provides interaction between the billing system and external domain registrars. It allows you to automate domain registration, renewal, transfer, and management processes, as well as synchronize data between systems. This article describes the internal structure, life cycle, and operating principles of such a module, which are required for its development and integration.

Module operation mechanism

In general, the life cycle of a registrar module in BILLmanager looks like this:

Module installation.
Adding a registrar connection.
Configuring the tariff plan.
Ordering and paying for the service.
Processing the service opening.
Enabling, disabling, deleting the service, as well as performing additional operations.

The module is installed either manually, if it is provided as a set of files, or from the standard repository using the package manager. After installation, the module becomes available for selection when adding a registrar connection in BILLmanager.

BILLmanager queries each module for supported capabilities and the list of required parameters. This is done once per BILLmanager start, the first time the module is accessed. This is done to speed up BILLmanager by excluding unsupported calls.

Module structure

The registrar module consists of two files:

etc/xml/billmgr_mod_XXX.xml — XML description of the module. The file naming format is strictly regulated;
processing/XXX — the main script of the module. The file naming format is strictly regulated.

Where XXX is the name of your module in Latin characters. If the name of the module's main script includes a file extension, it is also included in the module name. For example, if your script is called pmregistrar.php, then the module name is pmregistrar.php, not registrar or pmregistrar.

XML description

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

Example XML file structure

The plugin section describes the module itself. The name property matches the registrar module name. The section can contain:
- one group element with the value processing_module, which indicates that this module is used for service handlers;
- several msg elements;
- and a params section with the subnode <type name="domain"/>, which indicates that the handler belongs to registrars, that is, it can process services with the type whose internal name is domain.
The lang property of the msg element indicates which language the message belongs to; the name attribute can have the following values:
- desc_short — short module description. Displayed when selecting a module in BILLmanager;
- desc_full — full module description. Displayed when building the list of installed modules in COREmanager.
The metadata section with the name processing.edit.XXX is responsible for additional module fields when adding and configuring the handler. It is formed according to the standard description of an XML forms, taking into account the need to place fields in the <page name="connect"></page> section for correct field placement in BILLmanager forms.
The lang section contains translations of field names in the form according to the standard translation scheme. The <messages name="label_processing_modules"> section is responsible for the module name label in the list of handlers.

Main module script

The main module script is responsible for passing information to BILLmanager about functions supported by the module, as well as for processing these functions. When working with the module, BILLmanager runs the script file with the following parameters:

processing/xxx --command command [--item item] [--module module] [--itemtype itemtype] [--param param --value value] 
[--runningoperation runningoperation] [--tld tld] [--searchstring searchstring]

Where:

command — control command. Specifies the action that the module must perform;
item — the service code for which the action is performed;
module — the handler code for which the action is performed;
itemtype — the internal name of the product type for which the action is performed;
param — parameter name;
value — parameter value;
runningoperation — code of the current operation for the action being performed. Required to change parameters of the current operation, as well as to create tasks;
tld — the name of the zone for which the action is performed;
searchstring — search string used during import.

The runningoperation parameter is passed if the module is launched by BILLmanager after a current operation has been created. In this case, when the module finishes, you must either call one of the BILLmanager functions (described later in the article), which will remove the current operation from the queue, or perform one or more of the following actions:

save the error text in the properties of the current operation using the runningoperation.edit function;
set the current operation to manual mode to prevent automatic restart of this operation using the runningoperation.setmanual function;
create a task for the responsible department using the task.edit function.

The command parameter can take one of the following values:

features — request for the list of supported capabilities. In response to this command, the module must return an XML document of the following form:

Example

<doc>
  <itemtypes>
    <itemtype name="domain" />                   <!-- supported product type. For a registrar module, at least domain, but additional types may also be included -->
  </itemtypes>
  <params>                                       <!-- list of module parameters -->
    <param name="param" />                       <!-- registrar connection parameter. It must be included in the list of supported capabilities for correct saving and processing by the panel -->
    <param name="crypted_param" crypted="yes" /> <!-- encrypted registrar connection parameter. The need for encryption is indicated by crypted="yes" -->
  </params>
  <features>
    <feature name="check_connection" />          <!-- support for checking the entered parameters when adding a service handler -->
    <feature name="tune_connection" />           <!-- support for changing the service handler add form -->
    <feature name="import" />                    <!-- support for importing services from the registrar. More details on the import mechanism are described later in the documentation -->
    <feature name="open" />                      <!-- support for processing service opening; in the case of a registrar, domain registration -->
    <feature name="suspend" />                   <!-- support for processing service suspension -->
    <feature name="resume" />                    <!-- support for processing service enabling -->
    <feature name="close" />                     <!-- support for processing service deletion -->
    <feature name="setparam" />                  <!-- support for changing service parameters and additions -->
    <feature name="prolong" />                   <!-- support for renewing services on the registrar side -->
    <feature name="transfer" />                  <!-- support for service transfer -->
    <feature name="sync_item" />                 <!-- support for retrieving domain information from the registrar -->
    <feature name="tune_service" />              <!-- support for changing the service edit form -->
    <feature name="get_contact_type" />          <!-- support for retrieving the list of contact types required to register a domain in a specific zone -->
    <feature name="tune_service_profile" />      <!-- support for changing the domain contact form -->
    <feature name="validate_service_profile" />  <!-- support for validating domain contact properties -->
    <feature name="update_ns" />                 <!-- support for changing the list of name servers -->
    <feature name="whois" />                     <!-- support for implementing the whois command by the registrar module -->
    <feature name="uploaddocs" />                <!-- support for uploading documents -->
    <feature name="contactverify" />             <!-- support for domain contact verification (cannot be used together with "domainverify") -->
    <feature name="domainverify" />              <!-- support for domain verification (cannot be used together with "contactverify") -->
    <feature name="uploadext" />                 <!-- support for returning the list of supported file formats for uploading domain documents -->
  </features>
</doc>

Your module may not support some of the functions described. In this case, do not report unsupported functions when processing the features command; otherwise, service processing errors may occur.

check_connection — the module receives XML with registrar connection parameters as input. The input document format is as follows:

<doc>
  <param>value</param>
  ...
  <param>value</param>
</doc>

Regardless of the module's requirements, the parameters are provided in unencrypted form.

Using these parameters, the module must check whether they can be used to connect to the registrar and, if there is an error, return its XML description. If successful, you must return an XML document of the following form:

<doc/>

tune_connection — the handler receives an XML document with the current registrar connection form description as input, and an XML document with the required changes must be returned as output;
import — service import processing. In addition to the command parameter, the following parameters are passed to the handler in this case:
- module — service handler code;
- itemtype — internal name of the service type;
- searchstring — service search string.

Detailed description of service import is provided later in the article.

open — service opening command. The module also receives the item and runningoperation parameters (when a BILLmanager task starts). After service opening is complete, call the domain.open function to finish processing the service and remove the task from current operations;
suspend — service suspension command. The module also receives the item and runningoperation parameters (when a BILLmanager task starts). After service suspension is complete, call the service.postsuspend function to change the service status to Stopped and remove the task from current operations;
resume — service enabling command. The module also receives the item and runningoperation parameters (when a BILLmanager task starts). After service enabling is complete, call the service.postresume function to change the service status to Active and remove the task from current operations;
close — service deletion command. The module also receives the item and runningoperation parameters (when a BILLmanager task starts). After service deletion is complete, call the service.postclose function to change the service status to Deleted and remove the task from current operations;
setparam — command for changing service parameters or tariff. The module also receives the item and runningoperation parameters (when a BILLmanager task starts). After changing service parameters, call the service.postsetparam function to save the new tariff plan, update the service cost for display in the list, and remove the task from current operations;
prolong — command for extending the service term. The module also receives the item and runningoperation parameters (when a BILLmanager task starts). After the service extension is complete, call the service.postprolong function to remove the task from current operations;
transfer — processed similarly to open, except for the specifics of the operation;
sync_item — command for retrieving service information from the registrar. The module also receives the item parameter. Saving of parameters is performed using the functions described below;
tune_service — command for changing the domain edit form. The module also receives the param parameter, which contains the domain zone name. The module receives the current XML description of the domain edit form as input and must return the modified form as output;
get_contact_type — command for retrieving the list of contact types required for registering a domain in a specific zone, as well as additional information about support for this zone by the registrar. The module also receives the tld parameter, which contains the domain zone name. In general, the module returns an XML document of the following form:

Example response

<doc ns="require" auth_code="require">
  <contact_type>customer</contact_type>
  <contact_type>owner</contact_type>
  <contact_type>admin</contact_type>
  <contact_type>bill</contact_type>
  <contact_type>tech</contact_type>
</doc>

The set of contact_type nodes can be complete or contain only one or several values. It all depends on the registrar's requirements for domain registration in a specific zone.

To make the module return normalized contacts, add type="normalized" to the contact type XML description:

Example response for normalized contacts

<doc ns="require" auth_code="require">
  <contact_type type="normalized">customer</contact_type>
</doc>

The customer, owner, admin, bill, and tech types are built in. To make the module return another contact type name, add a messages section for label_service_profile to the plugin XML description:

Example section

<messages name="label_service_profile">
  <msg name="contact_type_name">Contact type name</msg>
</messages>

Where:

- contact_type_name — the name of your contact type;
- The ns="require" attribute means that for the given domain zone the registrar requires name servers to be specified. This attribute may be absent;
- The auth_code="require" attribute means that for the given domain zone the registrar requires the domain password to be specified during transfer. This attribute may be absent;
- The cancel_prolong_before="xxx" attribute specifies how many days before the domain expires the automatic renewal cancellation function must be called. This attribute may be absent.

tune_service_profile — command for changing the domain contact parameter form. The module also receives the param parameter, which contains the domain zone name, and value, which contains the contact type name. The module receives the XML contact form as input and must return the modified XML as output;
validate_service_profile — command for validating the data specified in contact properties. The module also receives the param parameter, which contains the domain zone name. The module receives an XML document containing all parameters of the current user session as input. As output, the module must either return an XML description of the validation error or an empty XML document;
update_ns — command for changing the list of domain name servers. The module also receives the module parameter, which contains the handler code, and item, which contains the service code;
cancel_prolong — command for canceling automatic domain renewal on the registrar side. The module also receives the item parameter, which contains the service code;
whois — retrieve whois data from the handler module.

The handler response must consist of XML with a whois node containing whois information for the domain:

Example response

<doc>
   <whois>NOT FOUND </whois>
</doc>

contactverify, domainverify — verification commands. In the case of contactverify, all services belonging to the domain contact are verified (the domain contact is created on the registrar side and has an external ID), and domainverify verifies only the domain (usually for such registrars, contact data for the domain is transmitted together with the domain data itself, and the contact does not have an external ID). XML with the external identifier of the domain contact (if any) and all service parameters is passed as input. As output, in case of an error, the module must return either an empty XML or XML in the following format:

Example response

<doc>
  <response>
    <file id="file ID from BILLmanager">ok</file> <!-- ok - in case of successful file upload, err - in case of error -->
    ...
  </response>
</doc>

uploadext — calling this command returns the list of file formats supported by the handler in the following format:

Example response

<doc>
  <ext>jpg</ext>
  <ext>png</ext>
  ...
</doc>

checkdomaindoc — this command checks the verification status of domains/domain contacts; the response must be returned in the following format:

Example response

<doc>
  <response>
    <item id="service ID from BILLmanager">ok</item> <!-- ok - in case of successful check, err - in case of error -->
    ...
  </response>
</doc>

An example implementation of the script can be found at the end of the article.

Related tables structure

table item — contains the main information about services:
- field id — service code;
- field processingmodule — handler code.
table processingmodule — contains the main information about the service handler:
- field id — handler code.
table processingparam — contains handler module parameters:
- field processingmodule — handler code;
- field intname — parameter name;
- field value — value.
table processingcryptedparam — contains encrypted handler module parameters:
- field processingmodule — handler code;
- field intname — parameter name;
- field value — encrypted value.
table service_profile — contains the main information about domain contacts:
- field id — domain contact code.
table service_profileparam — contains domain contact parameters:
- field service_profile — domain contact code;
- field intname — parameter name;
- field value — parameter value.
table service_profile2item — contains mappings between domains and contacts:
- field item — service code;
- field service_profile — domain contact code;
- field type — contact type.
table service_profile2processingmodule — contains mappings between contacts and handlers:
- field service_profile — domain contact code;
- field processingmodule — handler code;
- field type — contact type;
- field externalid — contact code on the registrar side;
- field externalpassword — contact password on the registrar side.

Service import

Service import in BILLmanager is performed in two stages:

retrieving a list of services from the registrar based on the passed condition;
assigning services to clients.

To retrieve the list of services, the control command import is passed to the module. When it is executed, the module must:

use the API to get a list of domains from the registrar that match the condition;
get contact information for the domains and group it by ID at the registrar;
register contacts in BILLmanager using the processing.import.profile function (for different contact types, you can use one created contact, but register its binding to the handler using the service_profile2processingmodule.edit function);
register domains in BILLmanager using the processing.import.service function;
bind contacts to domains using the service_profile2item.edit function.

Working with current operations

Before passing most requests, BILLmanager creates an operation that will be restarted if the previous attempt failed and automatic restart is enabled. The operation code is passed to the module in the runningoperation parameter and may be absent.

If the module receives the code of the current operation, then in case of a command processing error you can save information about it in the current operation parameters for display in BILLmanager using the runningoperation.edit function, and also switch its run mode to manual using the runningoperation.setmanual function.

If you also want to create a task based on the current operation for a BILLmanager administrator to resolve it, you need to:

Get the task type using the task.gettype function, passing the command received by the module in the operation parameter.
Register the task using the task.edit function.

After that, the task will appear in the list for employees belonging to the department selected as responsible in the handler settings.

Additional fields for domains and contacts

If necessary, additional fields can be added for a specific registrar module. These fields will be added to the contact properties when registering a domain through this registrar or in the selected domain zone. Such fields can also be added to domain properties.

In the first case, you need to add one or more metadata sections and the corresponding message descriptions in messages to the plugin XML description. Depending on what the additional parameters are added for, the section can look like this:

service_profile.tld — affects contacts when using any registration module;
service_profile.type — affects contacts when using any registration module;
service_profile.type.tld — affects contacts when using any registration module;
service_profile.xxx;
service_profile.xxx.tld;
service_profile.xxx.type;
service_profile.xxx.type.tld.

Where:

xxx — module name;
tld — domain zone name;
type — contact type name.

For example, to add the age field for the domain owner (owner) when registering in the .teen zone (an abstract example), add the following XML to the existing plugin description:

Example XML

For the same purposes, and also to fill choice lists, you can use the tune_service_profile handler.

BILLmanager functions

paramlist — does not require parameters. Returns a list of panel configuration parameters.
processing.import.profile — saves an imported domain contact in BILLmanager. Parameters:
- module — handler code;
- type — contact type;
- sok=ok — save parameters flag;
- externalid — contact code on the registrar side;
- list of standard domain contact parameters;
- any additional parameters that need to be saved in the domain contact properties.

Returns profile_id — the code of the created contact.

processing.import.service — saves an imported domain in BILLmanager. Parameters:
- module — handler code;
- import_pricelist_intname — domain zone code from BILLmanager;
- import_service_name — domain name;
- status — service status;
- expiredate — domain expiration date;
- domain — full domain name;
- service_status — additional service status. Possible values are listed below in the documentation;
- period — order period in months;
- sok=ok — save parameters flag;
- any additional parameters that need to be saved in domain properties.

Returns service_id — the code of the created domain.

service_profile2item.edit — binds contacts to a domain name by type:
- service_profile — contact code in BILLmanager;
- item — domain code in BILLmanager;
- type — contact type (it is recommended to use the standard types customer, owner, admin, tech, bill).
runningoperation.delete — deletes the current operation:
- elid — current operation code.
runningoperation.edit — changes current operation parameters:
- elid — current operation code;
- sok=ok — save parameters flag;
- errorxml — XML of the occurred error.
runningoperation.setmanual — switches the current operation to manual start mode:
- elid — current operation code.
service.postclose — service deletion completion operation. Changes the service status and removes the deletion operation:
- elid — service code;
- sok=ok — save parameters flag.
service.postopen — service opening completion operation. Only removes the service opening operation:
- elid — service code;
- sok=ok — save parameters flag.
service.postprolong — service renewal completion operation. Only removes the service renewal operation:
- elid — service code;
- sok=ok — save parameters flag.
service.postresume — service enabling completion operation. Changes the service status and removes the enabling operation:
- elid — service code;
- sok=ok — save parameters flag.
service.postsetparam — service parameter change completion operation. Resets the link to the previous tariff, removes the current operation, and updates the service cost for display in the list:
- elid — service code;
- sok=ok — save parameters flag.
service.postsuspend — service suspension completion operation. Changes the service status and removes the suspension operation:
- elid — service code;
- sok=ok — save parameters flag.
service.saveparam — saves an arbitrary service parameter:
- elid — service code;
- name — internal parameter name;
- value — parameter value.
service.setexpiredate — changes the service expiration date:
- elid — service code;
- expiredate — new service expiration date.
service.setstatus — changes the additional service status:
- elid — service code;
- service_status — new service status.
service_profile2processingmodule.edit — saves the binding parameters of a domain contact to the registrar:
- service_profile — domain contact code;
- sok=ok — save parameters flag;
- processingmodule — handler code;
- type — contact type;
- externalid — contact code on the registrar side;
- externalpassword — contact password on the registrar side (optional).

Service statuses

The additional service status can take the following values:

1 — domain is unpaid;
2 — domain is registered and delegated;
3 — domain is registered but not delegated;
4 — domain is deleted;
5 — domain is being registered;
6 — domain is being transferred to another registrar;
7 — domain is being renewed;
8 — domain delegation has ended.

Standard parameters of domain contacts

By default, in BILLmanager a domain contact can have the following properties:

profiletype — legal status of the contact:
- 1 — individual;
- 2 — legal entity;
- 3 — sole proprietor.
firstname_locale — first name of the contact person in the native alphabet;
middlename_locale — middle name of the contact person in the native alphabet;
lastname_locale — last name of the contact person in the native alphabet;
firstname — first name in Latin characters;
middlename — middle name in Latin characters;
lastname — last name in Latin characters;
email — email address;
phone — phone number;
mobile — mobile phone number;
fax — fax number;
passport — passport number with series;
passport_org — organization that issued the passport;
passport_date — passport issue date in YYYY-MM-DD format;
birthdate — date of birth in YYYY-MM-DD format;
location_country — country code of the contact location from the BILLmanager country reference list;
location_state — state, region, etc. of the contact location;
location_postcode — postal code of the contact location;
location_city — city of the contact location;
location_address — address (street, house, apartment/office, etc.) of the contact location;
postal_country — country code of the contact postal address from the BILLmanager country reference list;
postal_state — state, region, etc. of the contact postal address;
postal_postcode — postal code of the contact postal address;
postal_city — city of the contact postal address;
postal_address — address (street, house, apartment/office, etc.) of the contact postal address;
postal_addressee — full name of the mail recipient;
company_locale — organization name in the native alphabet;
company — organization name in Latin characters;
inn — tax registration number of the organization;
kpp — organization registration code;
ogrn — state registration number of the organization.

Module example

C++ (using BILLmanager libraries)

Using BILLmanager header files to develop your own handler modules is available starting from BILLmanager 5.58.0. In addition to the simplified example provided, you can study examples included in the BILLmanager developer package — billmanager-[BILLmanager edition]-devel, for example:

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

Notes

After that, examples can be found in the directory:

/usr/local/mgr5/src/examples

If you encounter an error when trying to make:

Building for <your operating system>
Compiling pmregru.cpp
pmregru.cpp:12:23: fatal error: json/json.h: No such file or directory
#include <json/json.h>
                      ^
compilation terminated.
make: *** [.build/.obj/pmregru.o] Error 1

Install the package:

make centos-prepare

make debian-prepare

PHP

The example illustrates how to implement the sale of third-level domains based on an existing domain. In practice, the example only stores a minimal set of data in a separate database and manipulates it.

The module consists of three main files:

etc/xml/billmgr_mod_pmregistrar.php.xml — XML description;
processing/pmregistrar.php — main module script;
dist/pmregistrar.php/domains.sql — dump of the test database.

And a helper file with useful functions:

include/php/bill_util.php.

The example can be viewed online — https://github.com/ISPsystemLLC/billmanager/.

bill_util.php functions

Before including the bill_util.php file in your script, you need to define the __MODULE__ macro to form the log file name. It looks roughly like this:

set_include_path(get_include_path() . PATH_SEPARATOR . "/usr/local/mgr5/include/php"); 
define('__MODULE__', "pmXXX"); 
require_once 'bill_util.php';

The bill_util.php file provides the following functions:

Debug($str) — outputs $str as additional information to the log;
Error($str) — outputs $str as an error message to the log;
LocalQuery($function, $param, $auth = NULL) — executes the $function function in BILLmanager, passing parameters from the $param array and the session code from $auth;
HttpQuery($url, $param, $requesttype = "POST", $username = "", $password = "", $header = array("Accept: application/xml")) — sends a request to $url with parameters from $param, using the request type $requesttype and authorization data from $username and $password. You can also pass additional headers in $header;
CgiInput($skip_auth = false) — gets an array of parameters received from scripts in the query string or POST data. $skip_auth is responsible for getting the auth parameter from the cookie if it is missing in the received data;
ClientIp() — gets the IP address from which the script was called;
class Error — an error class that mimics behavior similar to errors in COREmanager.