Registrar module

From ISPWiki
Jump to: navigation, search

General information

Module at work

  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. A client orders and pays for a service
  5. His service is set up
  6. The service is activated/suspended/deleted, etc.

The module can be installed either manually (if it is a list of files), or from repository using the package manager. Once installed, you can choose this module when configuring a new domain registrar in BILLmanager.

Each module sends requests to BILLmanager for supported features and required parameters. This operation is performed each time BILLmanager starts, and the call is sent to the payment module, which allows to improve BILLmanager performance, exclude unsupported calls.

Module structure

The registrar module contains two files:

  • etc/xml/billmgr_mod_XXX.xml - XML description of the module. Be sure to provide a standard filename format.
  • processing/XXX - the main script of the module. Be sure to provide a standard filename format

Where XXX is the name of your module in Latin characters. If the name of the main module contains file extension, it will be included into the name. For example, if your script name is pmregistrar, the module name will be pmregistrar.php, rather than pmregistrar.

XML description

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

Example of the 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="ru">XXX module</msg>
    <msg name="desc_short" lang="en">XXX module</msg>
    <msg name="desc_full" lang="ru">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 module </msg>
      <msg name="module_XXX">XXX module</msg>
    </messages>

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

The <plugin> section describes the module. The name property must match the name of your domain registrar's module. The section may contain;

  • one 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 registrar, i.e. it can handle 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 - brief description of the module, which is displayed in BILLmanager payment form.
  • desc_full - full description of the module, which is displayed in the list of installed modules in COREmanager.

The metadata section named processing.edit.XXX handles additional fields of the module that are displayed when you add or configure a domain registrar. It is formed according to standard description of XML forms. Take the note of the location of fields in the <page name="connect"></page> section to ensure 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_paymethod"> section is used to specify the module name.

Main script

The main script passes information about functions supported by the module to BILLmanager, and handles these 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 - control command. Defines an action to be performed by the module
  • item - service id
  • module - id of the module performing the action
  • itemtype - internal name of the product type
  • 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 - name of the domain zone
  • searchstring - search field that is used for domain import

The runningoperation parameter is passed if the module is run by BILLmanager after creating the current operation. Once completed, perform one of BILLmanager operations (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 automatic restart of the operation
  • Add and assign a task to an appropriate Support department by executing the task.edit function

The command parameter may have one of the following values:

  • features - request features supported by the module. 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>                                       <!-- module parameters -->
    <param name="param" />                       <!-- connect to registrar. It should be specified in the list of supported features so that the panel can save and handle them correctly -->
    <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" />          <!-- verify parameters that were entered when adding the processing module -->
    <feature name="tune_connection" />           <!-- modify  the processing module add form -->
    <feature name="import" />                    <!-- import services from registrar. For more details see our documentation -->
    <feature name="open" />                      <!-- activate services, or register domains, if the registrar module is used -->
    <feature name="suspend" />                   <!-- suspend services -->
    <feature name="resume" />                    <!-- activate services -->
    <feature name="close" />                     <!-- delete services -->
    <feature name="setparam" />                  <!-- change service and addon parameters -->
    <feature name="prolong" />                   <!-- renew service with the registrar -->
    <feature name="transfer" />                  <!-- service transfer  -->
    <feature name="sync_item" />                 <!-- get domain information from registrar  -->
    <feature name="tune_service" />              <!-- modify the service edit form  -->
    <feature name="get_contact_type" />          <!-- get domain contacts  required for a certain domain name -->
    <feature name="tune_service_profile" />      <!-- modify the domain contact form  -->
    <feature name="validate_service_profile" />  <!-- check domain contacts -->
    <feature name="update_ns" />                 <!-- modify the list of name servers  -->
    <feature name="whois" />                     <!-- whois support by registrar module (under development) -->
    <feature name="uploaddocs" />                <!-- upload documents -->
    <feature name="contactverify" />             <!-- verification of domain contacts (it cannot be used together with "domainverify") -->
    <feature name="domainverify" />              <!-- domain verification (it cannot be used with "contactverify") -->
    <feature name="uploadext" />                 <!-- 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 sent to the command stdout.

  • check_connection - send the XML with CA connection paramaters. The imput document looks like the following:
<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <param>value</param>
  ...
  <param>value</param>
</doc>

Note: parameters are not encrypted.

Using these parameters your module will check if it is possible to use them to connect to a domain 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 description of the registrar connection form is sent to the module's standard input. The XM document with 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 - service type internal name
    • searchstring - search field

A detailed description of the service import can be found below

  • open - service setup command. The item and runningoperation parameters are also sent to the module (when starting the BILLmanager task). 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 item and runningoperation parameters are also sent to the module (when starting the task in BILLmanager). Once the service is suspended, call the service.postsuspend function to mark the service Suspended and and delete the task from the list of current operations.
  • resume - service activation command. The item and runningoperation parameters are also sent 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. Theitem and runningoperation parameters are also sent 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 - modify service parameters or tariff plans. The item and runningoperation parameters are also sent 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 item and runningoperation parameters are also sent 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 command is handled in the same way open, however take the note of specific features of the operation.
  • sync_item - get information about the service from registrar. The item parameter is also sent. 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. The XML containing 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 node may contain one or multiple values, depending on a registrar's requirements to domain registration in a certain domain zone. The customer, owner, admin, bill, and tech types are built-in. You may return a custom type, if required, however the XML of this plug-in should contain 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 custom 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 if required for transfer of this domain zone. This is the mandatory attribute.


  • tune_service_profile - modify parameters of domain contact. The param parameter with the domain zone name and the value parameter with the 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 the 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, the empty XML document is sent to stdout.
  • update_ns - modify the list of domain's name servers. The module parameter with the processing module id, and the item parameter with the service id are sent to the module.
  • whois - receiving whois data from the processing module.

The response should contain an XML with the whois node including whois information. Example:

<doc>
   <whois>NOT FOUND </whois>
</doc>
  • contactverify, domainverify - verification commands. contactverify will verify all services that belong to domain contact (domain contact is created on the registrar side and has the external ID), and domainverify verifies only domain (usually, such registrars pass contact data along with domain information, and domain contact doesn't contain external ID). The system will receive the XML to STDin with external identifier of domain contact (if any), all service parameters. The module outputs an empty XML or an XML in the following format:
<doc>
  <response>
    <file id="file identifier from BILLmanager">ok</file> <!-- ok - if file was sent successfully, err - in case of error -->
    ...
  </response>
</doc>
  • uploadext - calling this function will return a list of file formats supported by the handler:
<doc>
  <ext>jpg</ext>
  <ext>png</ext>
  ...
</doc>
  • checkdomaindoc - this command checks domain/domain contact verification status. A response should be returned in the following format:
 <doc>
   <response>
     <item id="service identifier from BILLmananger">ok</item> <!-- ok - in case of successful verification, err - in case of error-->
     ...
   </response>
 </doc>

A script example can be found below.

Structure of linked tables

  • 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,
    • id - processing module id
  • theprocessingparam table - contains parameters of the processing module,
    • processingmodule - processing module id,
    • intname - parameters name,
    • value - value
  • the processingcryptedparam table - contains encrypted parameters of the processing module
    • processingmodule - processing module id,
    • intname - parameter name,
    • value - encrypted value
  • the service_profile table - contains domain contacts,
    • id - domain contact id
  • the service_profileparam table - contains parameters of domain contacts,
    • service_profile - domain contact id,
    • intname - parameter name,
    • value - parameter value
  • the service_profile2item table - contains information about domains and contacts associated with them,
    • item - service id,
    • service_profile - domain contact id,
    • type - contact type
  • theservice_profile2processingmodule table - contains information about processing modules and contacts associated with them
    • service_profile - domain contact id,
    • processingmodule - processing module id,
    • type - contact type,
    • externalid - contact id on the registrar side,
    • externalpassword - contact password on the registrar side.

Service import

Service import in BILLmanager includes 2 steps:

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

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

  • obtains a list of domains from the registrar via API the
  • gets 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

Operations

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

When the module gets the id of current operation, if the command fails, the information about this 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 that will be assigned to BILLmanager staff, complete the following steps: н

  1. With the operation parameter, pass the command received from the module to the task.gettype function, and run that function to get a task type.
  2. Run the task.edit function to register the task with

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

Additional fields for domain and contacts

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

Add one or multiple metadata sections and corresponding description in messages to XML description of the plug-in. The section may look like the following:

  • service_profile.xxx
  • service_profile.xxx.tld
  • service_profile.xxx.type
  • service_profile.xxx.type.tld

where

  • xxx - module name
  • tld - domain zone
  • type - contact name


E.g.: to add the age and owner fields into the .teen domain registration form, add the following XML to your plugin's 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>
  <lang name="ru">
    <messages name="service_profile.xxx.owner.teen">
      <msg name="age">Age</msg>
      <msg name="hint_age">Owner age</msg>
    </messages>
  </lang>
</mgrdata>


You may also use tune_service_profile for this purpose

BILLmanager functions

  • otparamlist - 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 - id contact on the registrar side
    • standard parameters of domain contacts
    • any additional parameters to be saved in the domain contact configuration form.

profile_id will be returned - id of the newly created contact

  • processing.import.service - save the imported domain into BILLmanager. Parameters:
    • module - processing module id
    • import_pricelist_intname - zone id from BILLmanager
    • import_service_name - domain name
    • status - service status
    • expiredate - domain validity period
    • domain - full domain name
    • service_status - additional status of the service. Possible statuses are described below
    • period - order period in months
    • sok=ok - indicates that parameters are saved
    • parameters such as type=id, where type - contact type, id - id passed by the previous function
    • any additional parameters to be saved in the domain configuration form.

It returns service_id - id of the newly created domain

  • runningoperation.delete - delete the current operation
    • elid - id of the current operation
  • runningoperation.edit - edit properties of the current operation
    • elid - id of the current operation
    • sok=ok - indicates that parameters are saved
    • errorxml - error XML
  • runningoperation.setmanual - manual setup of the current operation
    • elid - id of the current operation
  • 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 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 - save a service parameter
    • elid - service id
    • name - parameter internal name
    • value - parameter value
  • service.setexpiredate - change validity period
    • elid - service id
    • expiredate - new validity period
  • service.setstatus - change 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 also get 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 is deleted
  • 5 - domain is being registered
  • 6 - registrar is being changed for domain
  • 7 - domain is being renewed
  • 8 - domain delegated successfully

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 - sole proprietor
  • firstname_locale - first name of the contact person in national alphabet letters
  • middlename_locale - middle name of the contact person in national alphabet letters
  • lastname_locale - last name of the contact person in national alphabet letters
  • firstname - first name in Latin alphabet letters
  • middlename - middle name in Latin alphabet letters
  • lastname - last name in Latin alphabet letters
  • email - email address
  • phone - phone number
  • mobile - cell phone number
  • fax - fax
  • passport - password number
  • passport_org - 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
  • postal_postcode - Zip code
  • postal_city - city
  • postal_address - address (street, building, apartment, office)
  • postal_addressee - addressee full name
  • company_locale - company name in national alphabet letters
  • company - comany name in Latin alphabet letters
  • inn - inn number
  • kpp - kpp number
  • ogrn -Primary State Registration Number

Module example

C++ (with the use of BILLmanager libraries)

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

 yum install billmanager-standard-devel

Then you can find examples in the directory:

/usr/local/mgr5/src/examples

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 contain the additional file with functions:

  • include/php/bill_util.php

The example can be found at https://github.com/ISPsystemLLC/billmanager/

The bill_util.php function

Note: Before adding the bill_util.php file into your script, be sure to define the __MODULE__ macro to form a log file name.

It looks like the following:

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() - get the IP address from which the script was called
  • class Error - error class imitating behavior similar to COREmanager errors.