How to add a domain registrar module

How it works

1. A domain registrar module is set up
2. The module is integrated with a domain registrar 
3. A new tariff plan is set up 
4. Clients order and pay for services 
5. The system handles the service 
6. The service is activated/suspended/deleted, etc

You can install the module manually (if it is a list of files) or from the repository using the package manager. Once installed, you can choose this module when adding a Certification Authority in BILLmanager.

BILLmanager asks every module about supported features and required parameters. This operation is performed each time BILLmanager starts. It allows improving BILLmanager performance and excludes unsupported calls.

Module structure 

The registrar module contains two files:

• etc/xml/billmgr_mod_XXX.xml —  module XML description
• processing/XXX — the main script of the module

Where XXX is the name of your module in the Latin alphabet letters. If the name of the main module contains a file extension, it will be also included in the name. For example, if your script name is pmregistrar.php, the module name will be pmregistrar.php, rather than registrar or pmregistrar.

XML description

A file name can look like the following — billmgr_mod_XXX.xml, where XXX  is a module name. The file is copied into the etc/xml directory relative to the BILLmanager installation path. The file contains a description of the module (it is described as a plugin) and additional forms and messages.

Example of the module XML file:

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
  <plugin name="XXX">
    <group>processing_module</group>
    <params>
      <type name="domain"/>
    </params>
    <msg name="desc_short" lang="en">XXX module</msg>
    <msg name="desc_full" lang="en">XXX module</msg>
  </plugin>

  <metadata name="processing.edit.XXX" type="form">
    <form>
      <page name="connect">
        <field name="prop1">
          <input name="prop1" required="yes" type="text" />
        </field>
        <field name="prop2">
          <input name="prop2" required="yes" type="text" />
        </field>
      </page>
    </form>
  </metadata>

  <lang name="en">
    <messages name="label_processing_modules">
      <msg name="XXX">XXX module</msg>
      <msg name="module_XXX">XXX module</msg>
    </messages>

    <messages name="processing.edit.XXX">
      <msg name="prop1">Prop 1</msg>
      <msg name="hint_prop1">Hint for prop 1</msg>
      <msg name="prop2">Prop 2</msg>
      <msg name="hint_prop2">Hint for prop 2</msg>
    </messages>
  </lang>

  <lang name="ru">
     <messages name="label_processing_modules">
      <msg name="XXX">XXX модуль</msg>
      <msg name="module_XXX">XXX модуль</msg>
    </messages>

    <messages name="processing.edit.XXX">
      <msg name="prop1">Свойство 1</msg>
      <msg name="hint_prop1">Подсказка для свойства 1</msg>
      <msg name="prop2">Свойствоop 2</msg>
      <msg name="hint_prop2">Подсказка для свойства 2</msg>
    </messages>
  </lang>
</mgrdata>

The <plugin> section describes the module. The name property must match the name of your registrar module.

• The section may contain the group element with the processing_module value indicating that this module is used to handle services,
• several msg elements
• the params section with the <type name="domain"/> sub-node indicating that this handler is a domain registrar module, i.e. can process services with the domain internal name. 

The lang property of the msg element defines a language associated with the message, the name attribute may have the following values

• desc_short —  a brief description of the module. It is displayed in the BILLmanager payment form.
• desc_full — a full description of the module which is displayed in the list of installed modules in COREmanager.

The metadata section processing.edit.XXX handles additional fields of the module that are displayed when you add or configure the module. It is formed according to the standard description of XML forms. Take the note of the location of fields in the <page name="connect"></page> section for correct location of fields on BILLmanager forms.

The lang section contains translations of form fields according to the standard scheme of translation description. The <messages name="label_processing_modules"> section specifies the module name in a list of processing modules.

Main script 

The main script sends BILLmanager the information about the functions that the module supports and handles those functions. BILLmanager executes 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 — a command which defines an action that the module should perform. 
• item — service id for which the operation is performed 
• module — processing module id for which the operation is performed
• itemtype — product type internal name
• param — parameter name
• value — parameter value
• runningoperation — id of the current operation. This id is required for changing parameters of the current operation and creating tasks.
• tld — domain zone 
• searchstring — search string which is used during import 

The runningoperation parameter is passed if BILLmanager starts the module after creating the current operation. Once completed, perform one of BILLmanager functions (they are described below) to delete the current operation from the queue, or to perform one of the following operations:

• execute the runningoperation.edit function to save a text of the error into properties of the operation 
• execute the  runningoperation.setmanual function for manual set up of the current operation to avoid an automatic restart of the operation 
• execute the task.edit function to assign the task to a Support center department

The command parameter can have one of the following values: 

• features — request a list of features that the module supports. The following XML will be sent to stdout: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <itemtypes>
    <itemtype name="domain" />                   <!-- supported product type. domain for a domain registrar, additional types are also supported -->
  </itemtypes>
  <params>                                       <!-- list of module parameters -->
    <param name="param" />                       <!-- connect to the domain registrar. It should be specified in the list of supported features so that the panel can save and                   handle them  -->
    <param name="crypted_param" crypted="yes" /> <!-- encrypted parameters for integration with registrar. crypted="yes" indicates that encryption is required -->
  </params>
  <features>
    <feature name="check_connection" />          <!-- the module can verify parameters that were entered when adding the processing module  -->
    <feature name="tune_connection" />           <!-- the module can modify  the processing module add form -->
    <feature name="import" />                    <!-- the module can import services from registrar. For more details see our documentation -->
    <feature name="open" />                      <!-- the module can activate services, or register domains if the registrar module is used -->
    <feature name="suspend" />                   <!-- the module can suspend services -->
    <feature name="resume" />                    <!-- the module can enable services -->
    <feature name="close" />                     <!-- the module can delete services -->
    <feature name="setparam" />                  <!-- the module can change service and addon parameters -->
    <feature name="prolong" />                   <!-- the module can renew service with the the registrar -->
    <feature name="transfer" />                  <!-- the module can transfer services  -->
    <feature name="sync_item" />                 <!-- the module can get domain information from the registrar -->
    <feature name="tune_service" />              <!-- the module can  modify the service edit form -->
    <feature name="get_contact_type" />          <!-- the module can get domain contacts  required for a certain domain name -->
    <feature name="tune_service_profile" />      <!-- the module can изменения формы контакта доменов -->
    <feature name="validate_service_profile" />  <!-- the module can check properties of domain contacts -->
    <feature name="update_ns" />                 <!-- the module can change a list of name servers  -->
    <feature name="whois" />                     <!-- the module supports whois  -->
    <feature name="uploaddocs" />                <!-- the module can upload documents  -->
    <feature name="contactverify" />             <!-- the module can verify domain contacts (do not use it together with "domainverify") -->
    <feature name="domainverify" />              <!-- the module can verify a domain (do not use it together with "contactverify") -->
    <feature name="uploadext" />                 <!-- the module can return supported file formats for documents upload -->
  </features>
</doc>

Your module may not support some of the above functions. If a feature is not supported, it shouldn't be passed to the command stdout. 

• check_connection — send the XML with the registrar connection parameters. The output document looks like the following: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <param>value</param>
  ...
  <param>value</param>
</doc>

Regardless of module requirements, the parameters are not encrypted. 

Using these parameters your module will check if it is possible to use them to connect to the registrar and will return XML description of an error if any. If a success, it should return the following XML: 

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

• tune_connection — the XML containing parameters of the registrar connection form is sent to the module standard input. The XM document with the required parameters is sent to its standard output. 
• import — service import. Beside command, the following parameters will be sent to the processing module:
  • module — processing module id 
  • itemtype — product type internal name 
  • searchstring — service search string 

The import process is described below. 

• open — service activation command. The system sends the item and runningoperation parameters to the module  (when starting the task in BILLmanager). Once the service is activated, call the domain.open function to complete the operation and delete the task from the list of current operations.
• suspend — service suspension command. The system sends the item and runningoperation parameters to the module  (when starting the task in BILLmanager). Once the service is suspended, call the service.postsuspend function to mark the service as Suspended and delete the task from the list of current operations.  
• resume — service activation command. The system sends the item and runningoperation parameters to the module (when starting the task in BILLmanager). Once the service is activated, call the service.postresume function to change the service status to Active and delete the task from the list of current operations.
• close — service deletion command. The system sends the item and runningoperation parameters to the module (when starting the task in BILLmanager). Once the service is deleted, modify the  service.postclose function to change the service status to Deleted and delete the task from the list of current operations. 
• setparam — service parameters or tariff plan modification command. The system sends the item and runningoperation parameters to the module (when starting the task in BILLmanager). Once parameters are modified, call the service.postsetparam function to save the new tariff plan, update service price and delete the task from the list of current operations. 
• prolong — service renewal command. The system sends the item and runningoperation parameters to the module (when starting the task in BILLmanager).  Once the service is renewed, call the service.postprolong  function to delete the task from the list of current operations. 
• transfer — this function is processed the same ways as open, except for peculiarities of this operation. 
• sync_item —  get information about the service from the registrar. The system also sends the item parameter The below functions are used to save parameters. 
• tune_service — modify the domain edit form. The param parameter with the domain zone name is also sent to the module. The XML containing a description of the domain edit form is sent to the standard input. The modified XM document is sent to its standard output.  
• get_contact_type — get required contact types for registering a domain in a certain zone and additional information about support of that zone by the registrar.  The tld parameter with the domain zone name is sent to the module. The following XML is sent to its standard output:

<?xml version="1.0" encoding="UTF-8"?>
<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 contact_type nodes may contain one or multiple values, depending on registrar requirements for domain registration in a certain domain zone. The customer, owner, admin, bill, and tech types are built-in. You may return a custom type, however, the XML of this plug-in should contain a description for label_service_profile:

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

where contact_type_name — the name of your type.

The ns="require" attribute means that name servers must be specified for this domain zone. This is the mandatory attribute. The auth_code="require" attribute means that a domain password is required for the transfer of this domain zone. This is the mandatory attribute. The cancel_prolong_before="xxx" attribute — a period in days before the domain expiration date when you need to call the function to cancel automatic renewal. This is the mandatory attribute.

• tune_service_profile — modify parameters of the domain contact form. The param parameter with a domain zone name and the value parameter with a contact type name, are sent to the module. The XML of the domain contact form is sent to stdin, the modified XML is sent to the stdout 
• validate_service_profile — verify contact data. The param parameter with a domain zone name is sent to the module. The XML with parameters of the current user session is sent to stdin, and either the XML with data verification error description or an empty XML document is sent to stdout. 
• update_ns — modify the list of domain name servers. The module parameter with the processing module id and the item parameter with the service id are sent to the module. 
• cancel_prolong — cancel domain automatic renewal on the registrar-side. The item parameter with the service id is sent to the module. 
• whois — receive whois data from the processing module.

The registrar response must contain an XML with the whois node including domain whois information. E.g.: 

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

• contactverify, domainverify — verification commands. contactverify will verify all the services that belong to a domain contact (the domain contact is created on the registrar-side and has the external ID).  domainverify verifies only a domain (usually, such registrars pass contact data along with domain information and the domain contact doesn't contain external ID). The system will receive the XML to stdin with the domain contact external id (if any), and all service parameters. The module outputs an empty XML or an XML in the following format:

<doc>
  <response>
    <file id="file id from BILLmanager">ok</file> <!-- ok - file has been sent successfully, err - failure-->
    ...
  </response>
</doc>

• uploadext — calling this function will return a list of file formats that the processing module supports:

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

• checkdomaindoc — this command checks domain/domain contact verification status. The system must return the following response:

<doc>
  <response>
    <item id="service id from BILLmananger">ok</item> <!-- ok - verification has completed successfully, err - failure -->
    ...
  </response>
</doc>

You can find an example at the end of this article.

Linked table structure

• the item table — contains information about services
  • the id field — service id, 
  • the processingmodule field — processing module id. 
• the processingmodule table — contains information about the processing module, 
  • the id field — processing module id
• the processingparam table — содержит параметры модуля обработчика,
  • the processingmodule field — processing module id,
  • the intname field — parameter id,
  • the value field — value
• the processingcryptedparam table — contains parameters of the processing module, 
  • the processingmodule field — processing module id,
  • the intname field — parameter name,
  • the value — encrypted value
• the service_profile table — contains domain contacts, 
  • the id field  — domain contact id
• the service_profileparam table — contains domain contact parameters, 
  • the service_profile field — domain contact id, 
  • the intname field — parameter name, 
  • the value field — parameter value, 
• the service_profile2item table  — contains information about domains and associated contacts
  • the item field — service id, 
  • the service_profile field — domain contact type,
  • the type field  — contact type 
• the service_profile2processingmodule table —domain contacts and the associated processing modules
  • the service_profile field — domain  contact id,
  • the processingmodule field — processing module id,
  • the type field — contact type,
  • the externalid field — contact id on the registrar-side,
  • the externalpassword field — contact password on the registrar-side 

Service import 

Service import in BILLmanager involves 2 steps:

• the system gets a list of services from a domain registrar
• allocates services to clients 

To get a list of services, the system passes the import command to the module. The module completes the following steps:

• obtains a list of domains from the registrar via API 
• gets the domain contacts and group them by id on the registrar-side
• registers contacts in  BILLmanager using the processing.import.profile function (a single contact can be used for different types of contacts, however, use the service_profile2processingmodule.edit function to assign it to the processing module)
• registers domains in  BILLmanager using the processing.import.service function 
• ties contacts to domains with the service_profile2item.edit function 

Current operations 

Before sending most of the requests, BILLmanager creates an operation that will be restarted if the previous operation fails and automatic restart is enabled. The operation id is passed to the module with the runningoperation parameter (you may not pass it). 

When the module gets the id of the current operation, if the command fails, the information about the operation can be kept in parameters of the current operation to be displayed in BILLmanager with the runningoperation.edit function, and activate manual setup with the runningoperation.setmanual function. 

To create a task based on the current operation, complete the following steps:

1. Define a task type using the task.gettype function. Use the operation parameter to pass the command that the module has received
2. Execute the task.edit function to register the task 

Once completed, the task will be assigned to a  department that can handle it (it is already selected in the processing module configuration form).

Additional fields for domains and contacts

You may add additional fields to your registrar module. The fields will be added into the domain contact form that opens when registering a domain name with a selected registrar or in a certain domain zone. You can add additional fields to domain properties.

In the plug-in XML description add one or multiple metadata sections and corresponding description into messages. The section may look like the following:

• service_profile.tld — modifies the contacts when using any registration module
• service_profile.type — modifies the contacts when using any registration module
• service_profile.type.tld — modifies the 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 

E.g.: to add the age and owner fields into the .teen domain registration form, add the following XML to your plugin description

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
  <metadata name="service_profile.xxx.owner.teen" type="form">
    <form title="name">
      <field name="age">
        <input name="age" required="yes" type="text" check="int" checkargs="1,"/>
      </field>
    </form>
  </metadata>
  <lang name="en">
    <messages name="service_profile.xxx.owner.teen">
      <msg name="age">Age</msg>
      <msg name="hint_age">Age of owner</msg>
    </messages>
  </lang>
 </mgrdata>

You can also use tune_service_profile to complete this task. 

BILLmanager functions

• paramlist — does not require parameters. The function passes a list of panel configuration parameters.
• processing.import.profile — save the imported domain contact into BILLmanager. Parameters:
  • module — processing module id
  • type — contact type 
  • sok=ok — indicates that parameters are saved
  • externalid — contact id on the registrar-side
  • domain contact standard parameters
  • any additional parameters to be saved in the domain contact configuration form.

The system returns profile_id — id of the newly created contact 

• processing.import.service — save the imported domain into BILLmanager. Parameters:
  • module — processing module id
  • import_pricelist_intname — domain zone id from BILLmanager
  • import_service_name — domain name
  • status — service status 
  • expiredate — domain expiration date 
  • domain — domain name 
  • service_status — the additional status of the service. Possible statuses are described below
  • period — order period in months
  • sok=ok — indicates that parameters are saved
  • any additional parameters to be saved in the domain configuration form.

The system returns service_id — id of the newly created domain 

• service_profile2item.edit — tie the contacts to the domain name by type 
  • service_profile — contact id in BILLmanager
  • item — domain id in BILLmanager
  • type — contact type (we recommend that you use standard types customer, owner, admin, tech, bill)
• runningoperation.delete — delete the current operation
  • elid — current operation id
• runningoperation.edit — edit properties of the current operation
  • elid — current operation id
  • sok=ok — indicates that parameters are saved
  • errorxml — error XML
• runningoperation.setmanual — manual setup of the current operation
  • elid — current operation id
• service.postclose — complete service deletion. This operation will change the service status and delete the deletion operation
  • elid — service id
  • sok=ok — indicates that parameters are saved
• service.postopen —  complete service setup. This operation will delete the setup operation
  • elid — service id
  • sok=ok — indicates that parameters are saved
• service.postprolong — complete service renewal. This operation will delete the renewal operation
  • elid — service id
  • sok=ok — indicates that parameters are saved
• service.postresume — complete service activation. This operation will change the service status and delete the activation operation
  • elid — service id
  • sok=ok — indicates that parameters are saved
• service.postsetparam — complete service modification. This operation will change the service status, delete the link to the previous tariff plan, and update the service price
  • elid — service id
  • sok=ok — indicates that parameters are saved
• service.postsuspend — complete service suspension. This operation will change the service status and delete the suspension operation
  • elid — service id
  • sok=ok — indicates that parameters are saved
• service.saveparam — saves a service parameter
  • elid — service id
  • name — parameter internal name
  • value — parameter value
• service.setexpiredate — changes the service validity period
  • elid — service id
  • expiredate —new expiration date 
• service.setstatus — changes the additional status of the service
  • elid — service id
  • service_status — new status
• service_profile2processingmodule.edit — save information about domain contact and corresponding registrar
  • service_profile — domain contact id
  • sok=ok — indicates that parameters are saved
  • processingmodule — processing module id
  • type — contact type
  • externalid — contact id on the registrar-side
  • externalpassword — contact password on the registrar-side (optional)

Service statuses

The service may have one of the following statuses:

• 1 — domain is  not paid 
• 2 — domain is registered and delegated 
• 3 —  domain is registered, but not delegated 
• 4 — domain deleted 
• 5 — domain registration in progress 
• 6 — registrar change in progress 
• 7 — domain renewal in progress 
• 8 — domain has been delegated 

Standard parameters of domain contacts

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

• profiletype — contact legal status
  • 1 — individual,
  • 2 — company,
  • 3 — individual proprietor 
• firstname_locale — first name of the contact person in the national alphabet letters
• middlename_locale — middle name of the contact person in the national alphabet letters
• lastname_locale — last name of the contact person in the national alphabet letters
• firstname — first name in the Latin alphabet letters
• middlename — middle name in the Latin alphabet letters
• lastname — last name in the Latin alphabet letters
• email — email 
• phone — phone number 
• mobile — cell phone 
• fax — fax
• passport —  password number
• passport_org — an organization that issued the passport
• passport_date — password issue date YYY—MM—DD
• birthdate — date of birthday YYY—MM—DD
• location_country — country id in BILLmanager
• location_state — state, region
• location_postcode — Zip code
• location_city — city 
• location_address — address (street, building, apartment, office)
• postal_country — country id (in (BILLmanager) of the contact's postal address
• postal_state — state, region
• postal_postcode — Zip code
• postal_city — city 
• postal_address —  address (street, building, apartment, office)
• postal_addressee — addressee full name 
• company_locale — company name in the national alphabet letters
• company — company name in the Latin alphabet letters
• inn — INN number
• kpp — KPP number 
• ogrn — Primary State Registration Number

Example

C++ (using BILLmanager libraries)

Starting from version 5.58.0 you can use BILLmanager header files to develop custom processing modules. Beside this simplified example, you study the examples in the  BILLmanager developer package billmanager-[BILLmanager version]-devel:

yum install billmanager-devel

You can find the examples in the  '/usr/local/mgr5/src/examples' directory

/usr/local/mgr5/src/examples

If make failed 

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

or 

make debian-prepare

PHP

The module consists of three files:

• etc/xml/billmgr_mod_pmregistrar.php.xml — XML description 
• processing/pmregistrar.php — main script 
• dist/pmregistrar.php/domains.sql — test database dump 

Besides, it contains the additional file with the functions:

• include/php/bill_util.php

You can find the example at https://github.com/ISPsystemLLC/billmanager/

The bill_util.php function

!!! Before adding the bill_util.php filed you need to define the  __MODULE__ macro to generate a log file name:

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 delivers the following functions:

• Debug($str) — outputs $str into the log as additional information
• Error($str) — outputs $str as an error message
• LocalQuery($function, $param, $auth = NULL) — executes $function in BILLmanager and sends parameters from the $param array, and the session id from $auth to this function.
• HttpQuery($url, $param, $requesttype = "POST", $username = "", $password = "", $header = array("Accept: application/xml")) — sends a request to $url with parameters from $param. The file uses $requesttype as a request type and authentication data from $username and $password. Additional headings can be also sent to $header
• CgiInput($skip_auth = false) — receives an array of script parameters in the request or data POST. $skip_auth receives the auth parameter from cookie, if it is not present in the data received.
• ClientIp() — gets the IP address from which the script was called
• class Error — error class imitating behavior similar to COREmanager errors.

save information about domain contact and corresponding registrar