Создание модулей обработки

В данной статье рассматривается вариант написания собственного модуля обработки либо для собственного типа услуг, либо для встроенного типа услуг.

Для выполнения любых операций с услугами в BILLmanager архитектурой платформы предусмотрено использование специализированных модулей обработки. В стандартной поставке предусмотрены как модули, отвечающие за выполнение операций над определенными типами услуг в конкретных панелях управления, так и специализированные и вспомогательные модули, способные обрабатывать любые типы услуг. К таким обработчикам относятся модуль ручной обработки услуги и модуль перепродажи услуг из BILLmanager в BILLmanager.

Все функции в статье вызываются согласно стандартным механизмам работы с API.

Вызов всех функций необходимо осуществлять с возвратом результата в XML или JSON. В случае использования JSON формата ответов от BILLmanager результат будет иметь туже структуру, что и описанная в статье, с поправкой на формат.

Назначение модулей обработчиков

Основной функцией модуля обработки является выполнение каких либо операций с услугами на стороне панели управления либо провайдера данных услуг. Дополнительно модуль может:

• выполнять проверки при изменении параметров услуг;
• сообщать BILLmanager доступные на стороне панели управления или провайдера конфигурации услуг;
• изменять формы настроек обработчика, услуги или профиля услуги (реализовано для доменных имён и сертификатов).

Разработчик может добавить выполнение других действий с ручным запуском, с запуском по расписанию, либо с запуском из плагина в BILLmanager.

Архитектура модуля

Стандартный модуль для BILLmanager состоит из двух файлов:

• billmgr_mod_pmxxx.xml — xml описание модуля обработки с привязкой к типу услуги, наименованием модуля и описанием параметров, указанных при добавлении обработчика в BILLmanager. Пример такого файла можно найти ниже в статье. Файл должен быть расположен в каталоге /usr/local/mgr5/etc/xml/ с именем вида billmgr_mod_pmxxx.xml. Здесь и далее xxx — уникальное имя модуля обработчика.
• pmxxx — исполняемый файл модуля, вызываемый BILLmanager напрямую или через фоновое задание при выполнении операций с услугами или по необходимости. Файл должен быть расположен в каталоге /usr/local/mgr5/processing/ с именем вида pmxxx. У файла должны стоять права на исполнение от имени root.

По необходимости в поставку модуля обработчика могут быть включены другие файлы:

• cgi скрипты, выполняющие переадресацию пользователей в панель управления;
• вспомогательные исполняемые файлы;
• файлы плагинов BILLmanager, вносящих изменения в интерфейс и логику BILLmanager.

Структура XML файла обработчика

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

<mgrdata> <!-- корневой узел XML -->
  <plugin name="pmxxx"> <!-- описание плагина к BILLmanager -->
    <group>processing_module</group> <!-- флаг принадлежности к модулям обработки -->
    <author>BILLmanager team</author> <!-- автор модуля -->
    <params> <!-- параметры плагина модуля обработчика. Обязательным является указание хотя бы одного поддерживаемого типа продуктов, другие параметры можно не указывать -->
      <priority lang="lang">1</priority> <!-- порядок сортировки на форме выбора модуля при добавлении подключения в BILLmanager. Зависит от указанного в атрибуте языка интерфейса пользователя -->
      <type name="all"/> <!-- указывает, если обработчик поддерживает все имеющиеся в BILLmanager типы продуктов -->
      <type name="itemtype"/> <!-- поддерживаемый тип продукта. Может указываться несколько раз -->
      <notype name="itemtype"/> <!-- не поддерживаемый тип продукта. Может указываться несколько раз -->
    </params>
  </plugin>

  <metadata name="processing.edit.pmxxx" type="form"> <!-- параметры формы добавления обработчика в BILLmanager. Описываются согласно стандартным правилам -->
    <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"> <!-- сообщения локализации -->
    <messages name="plugin"> <!-- наименование плагина для отображения в различных списках и разделах в BILLmanager -->
      <msg name="desc_short_pmxxx">XXX</msg>
      <msg name="desc_full_pmxxx">Интеграция с XXX</msg>
      <msg name="price_pmxxx">Бесплатно</msg>
    </messages>
    <messages name="label_processing_modules"> <!-- наименование обработчика для отображения в различных списках и разделах в BILLmanager -->
      <msg name="pmxxx">XXX</msg>
      <msg name="module_pmxxx">XXX</msg>
    </messages>
    <messages name="processing.edit.pmxxx"> <!-- локализация формы добавления обработчика в BILLmanager -->
      <msg name="param1">Первый параметр</msg>
      <msg name="hint_param1">Подсказка к полю параметра</msg>
      <msg name="param2">Второй параметр</msg>
      <msg name="hint_param2">Подсказка к полю параметра</msg>
      ...
      <msg name="paramN">N-ый параметр</msg>
      <msg name="hint_paramN">Подсказка к полю параметра</msg>
    </messages>
  </lang>
</mgrdata>

После внесения изменений в XML описание обработчика перезапустите BILLmanager для перестроения XML кеша.

Структура исполняемого файла обработчика

Исполняемый файл обработчика должен работать по следующему сценарию:

• получение и анализ параметров командной строки, с которыми вызван обработчик;
• выбор внутренней функции в зависимости от значения, полученного для параметра --command;
• получение входных данных из потока ввода;
• выполнение действий в панели управления или по API провайдера услуг;
• изменение статуса и параметров услуги в BILLmanager;
• вывод в стандартный поток результата в формате XML.

В качестве входных параметров модулю обработки передаются следующие значения:

• --command — тип операции, которую необходимо выполнить. Возможные значения:
  • features — запрос XML описания поддерживаемых возможностей;
  • open — фоновое задание открытия услуги на стороне платформы или провайдера услуг;
  • resume — фоновое задание включения услуги на стороне платформы или провайдера услуг;
  • suspend — фоновое задание выключения услуги на стороне платформы или провайдера услуг;
  • start — фоновое задание запуска услуги со стороны клиента при почасовой тарификации;
  • stop — фоновое задание остановки услуги со стороны клиента при почасовой тарификации;
  • cancel_prolong — фоновое задание отмены автоматического продления услуги на стороне платформы или провайдера услуг;
  • close — фоновое задание удаления услуги на стороне платформы или провайдера услуг;
  • setparam — фоновое задание на изменение параметров услуги в платформе или на стороне провайдера услуг. Измениться могут как параметры услуги в BILLmanager, так и дополнения к услуге;
  • get_suitable_module — запрос списка доступных модулей обработки для услуги с параметрами, переданными во входящем XML документе;
  • check_connection — проверка возможности подключения к платформе или провайдеру услуги с переданными во входящем XML документе параметрами;
  • tune_connection — изменение формы редактирования параметров подключения к платформе или провайдеру услуг. На вход подаётся XML исходной формы настройки параметров, на выход модуль должен передать изменённый XML документ, описывающий форму настройки параметров;
  • tuning_param — изменение формы настройки дополнительных параметров модуля обработки;
  • usercreate — изменение формы регистрации нового пользователя на стороне провайдера услуг. Может понадобиться только при условии дистрибьюции разрабатываемого модуля;
  • tune_changepassword — изменение формы смены пароля для услуги;
  • sync_pricelist — фоновое задание синхронизации тарифного плана в BILLmanager с пресетом в платформе;
  • get_server_config — фоновое задание получения конфигурации пресетов на стороне платформы или провайдера услуг;
  • sync_server — фоновое задание синхронизации данных в платформе или у провайдера услуг в BILLmanager;
  • prolong — фоновое задание продления срока действия услуги в платформе или у провайдера услуг;
  • stat — фоновое задание сбора статистики по использованию услугами ресурсов сервера или провайдера услуг;
  • reboot — перезагрузка услуги (выделенного или виртуального сервера, любой другой услуги, поддерживающей данный функционал);
  • import_pricelist — запрос данных тарифного плана для создания в BILLmanager. В ответ модуль должен вернуть XML с описанием параметров тарифа;
  • check_param — запуск проверки возможности изменения параметров услуги. На вход подается XML документ со старыми и новыми значениями параметров, в ответ либо возвращается XML документ с ok, либо XML описание ошибки;
  • check_addon — запуск проверки возможности изменения дополнений к услуге. На вход подается XML документ со старыми и новыми значениями параметров, в ответ либо возвращается XML документ с ok, либо XML описание ошибки;
  • changepassword — фоновое задание смены пароля для услуги в платформе или у провайдера услуг;
  • addip — фоновое задание добавления к услуге IP-адреса в платформе или у провайдера услуг;
  • editip — фоновое задание изменения IP-адреса услуги в платформе или у провайдера услуг;
  • delip — фоновое задание удаления IP-адреса в платформе или у провайдера услуг;
  • transition_controlpanel — запрос XML документа с описанием доступных для перехода панелей управления;
  • pingip — получение информации о занятости IP-адреса из платформы или от провайдера услуг;
  • cleanup — фоновое задание для выполнения дополнительных действий после пометки в BILLmanager услуги как удалённой;
  • cloneitem — фоновое задание для выполнения дополнительных действий после переноса услуги от клиента к клиенту;
  • в будущем могут добавиться другие значения. Если разрабатываемый модуль не способен обработать полученную команду, он должен завершиться с кодом 0 во избежание вывода непредвиденных ошибок и зависания текущих операций.
• --subcommand — параметр, уточняющий необходимое к выполнению действие. Передается при --command равном tuning_param и import_pricelist;
• --id — код тарифного плана на стороне платформы или провайдера услуг при выполнении import_pricelist;
• --item — код услуги, для которой требуется выполнение операции;
• --module — код модуля обработки, для которого требуется выполнение операции;
• --param — наименование дополнительного параметра;
• --value — значение дополнительного параметра;
• --runningoperation — код текущей операции, связанной с вызванной командой. Используется для регистрации задачи в случае ошибки обработки услуги;
• --level — уровень доступа, для которого вызвана команда модуля обработчика. Передаётся при выполнении transition_controlpanel;
• --password — новое значение пароля услуги. Передаётся при выполнении changepassword;
• --userid — код пользователя, из-под которого запущено выполнение операции. Передаётся при выполнении setparam;
• --panelkey — идентификатор платформы, переход в которую необходимо осуществить. Передаётся при выполнении transition_controlpanel;
• --ip — код IP-адреса, который необходимо обработать.

Разработчику модуля нет необходимости обрабатывать весь набор возможных команд и параметров, большая часть из них вызывается только при поддержке модулем необходимых возможностей. Далее приведено более полное описание вызываемых команд.

features

Запрос функций и параметров модуля обработки. Вызывается после запуска BILLmanager при первой необходимости.

Требуется поддержка функции:

нет

Пример вызова:

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

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

отсутствуют

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

XML документ, содержащий описание параметров модуля обработки и поддерживаемых функций, следующего формата:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <itemtypes> <!-- список поддерживаемых типов продуктов -->
    <itemtype name="itemtype1"/>
    ...
    <itemtype name="itemtypeN"/>
  </itemtypes>
  <params> <!-- список параметров модуля обработки. Не указанные в этом разделе параметры не будут сохранены в базе данных -->
    <param name="param1"/> <!-- не шифруемый параметр -->
    ...
    <param name="paramN"/>
    <param name="cryptedparam1" crypted="yes"/> <!-- шифруемый параметр -->
    ...
    <param name="cryptedparamN" crypted="yes"/>
    <param name="param1"/> <!-- не шифруемый параметр --> <!-- дополнительный параметр-->
    ...
    <customparam name="customparam1" unique="yes|no" defval=""/>
    ...
    <customparam name="customparamN"/>
  </params>
  <features> <!-- список поддерживаемых функций -->
    <feature name="feature1"/>
    ...
    <feature name="featureN"/>
  </features>
</doc>

Здесь:

• атрибут name у ноды itemtype указывается по внутреннему имени типа продукта/услуги;
• атрибут name у ноды param должен соответствовать имени поля ввода формы настроек модуля обработки. Атрибут crypted сигнализирует о необходимости хранения параметра в базе данных в зашифрованном виде;
• атрибут name у customparam будет отображён в списке выбора при добавлении дополнительного параметра. Атрибут unique со значением yes указывает на то, что параметр с указанным внутренним именем может быть только один. Атрибут defval не обязателен и определяет значение параметра по умолчанию;
• атрибут name у ноды feature указывает на поддерживаемую функцию модуля обработки. Доступные значения:
  • changepassword — модуль поддерживает смену пароля для услуги. В интерфейсе BILLmanager для услуг будет доступна соответствующая кнопка в списках;
  • tune_changepassword — модуль поддерживает изменение формы смены пароля;
  • check_addon — модуль поддерживает проверку возможности изменения дополнения к услуге;
  • check_connection — модуль поддерживает проверку корректности введённых на форме настройки обработчика параметров;
  • check_param — модуль поддерживает проверку параметров услуги при их изменении;
  • cleanup — модуль поддерживает обработку дополнительной очистки после завершения удаления услуги;
  • cloneitem — модуль поддерживает обработку переноса услуги от клиента к клиенту;
  • tune_connection — модуль поддерживает изменение формы настройки обработчика в BILLmanager;
  • datacenter — модуль поддерживает распределение услуг по дата-центрам. Обязательно, если вы используете типы продуктов, созданные вручную;
  • get_server_config — модуль поддерживает получение конфигурации;
  • get_suitable_module — модуль поддерживает самостоятельное определение списка доступных для открытия услуг обработчиков;
  • ipmgr — модуль поддерживает работу с IPmanager. Добавляет выбор IPmanager на форму настроек обработчика;
  • need_ipmgr — делает выбор IPmanager обязательным;
  • licserver — модуль поддерживает работу с внешними BILLmanager в качестве серверов лицензий. Добавляет выбор BILLmanager на форму настроек обработчика;
  • pingip — модуль поддерживает проверку недоступности IP-адреса перед удалением;
  • prolong — модуль поддерживает продление услуг на стороне платформы или провайдера услуг;
  • reboot — модуль поддерживает выполнение перезагрузки услуги;
  • stat — модуль поддерживает сбор статистики по услугам;
  • stop_by_panelid — модуль поддерживает остановку услуги по идентификатору в платформе;
  • sync_pricelist — модуль поддерживает синхронизацию тарифного плана в BILLmanager с соответствующей сущностью в платформе или у провайдера услуг;
  • sync_server — модуль поддерживает синхронизацию параметров услуг в BILLmanager или у провайдера услуг;
  • transition_controlpanel — модуль поддерживает переход в панель управления;
  • tuning_param — модуль поддерживает дополнительные параметры модуля обработки.

open

Обработка открытия (создания) услуги на стороне панели управления или у провайдера услуг.

Требуется поддержка функции:

нет

Пример вызова:

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

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

• --item — код услуги, для которой выполняется обработка;
• --runningoperation — код текущей операции на открытие услуги. Передается при наличии.

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

отсутствуют

По завершению обработки открытия услуги вызовите функцию itemtype.open, где itemtype — внутреннее имя типа услуги, с параметрами:

• elid — код услуги;
• все параметры, указанные при открытии услуги (перечислены в настройках параметров типа продукта):
• sok=ok — подтверждение операции.

После чего услуга перейдёт в активное состояние, а клиенту, в случае наличия настройки, уйдёт уведомление об обработке услуги.

resume

Обработка включения услуги на стороне платформы или у провайдера услуг.

Требуется поддержка функции:

нет

Пример вызова:

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

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

• --item — код услуги, для которой выполняется обработка;
• --runningoperation — код текущей операции на включение услуги. Передается при наличии.

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

отсутствуют

По завершению обработки включения услуги вызовите функцию service.postresume с параметрами:

• elid — код услуги;
• sok=ok — подтверждение операции.

suspend

Обработка выключения услуги на стороне платформы или у провайдера услуг.

Требуется поддержка функции:

нет

Пример вызова:

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

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

• --item — код услуги, для которой выполняется обработка;
• --runningoperation — код текущей операции на включение услуги. Передается при наличии.

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

отсутствуют

По завершению обработки включения услуги вызовите функцию service.postsuspend с параметрами:

• elid — код услуги;
• sok=ok — подтверждение операции.

start

Обработка запуска услуги на стороне платформы или у провайдера услуг.

Требуется поддержка функции:

нет

Пример вызова:

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

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

• --item — код услуги, для которой выполняется обработка;
• --runningoperation — код текущей операции на включение услуги. Передается при наличии.

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

отсутствуют

По завершению обработки включения услуги вызовите функцию service.poststart с параметрами:

• elid — код услуги;
• sok=ok — подтверждение операции.

stop

Обработка остановки услуги на стороне платформы или у провайдера услуг.

Требуется поддержка функции:

нет

Пример вызова:

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

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

• --item — код услуги, для которой выполняется обработка;
• --runningoperation — код текущей операции на включение услуги. Передается при наличии.

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

отсутствуют

По завершению обработки включения услуги вызовите функцию service.poststop с параметрами:

• elid — код услуги;
• sok=ok — подтверждение операции.

cancel_prolong

Обработка отмены автоматического продления услуги на стороне платформы или провайдера услуг.

Требуется поддержка функции:

нет

Пример вызова:

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

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

• --item — код услуги, для которой выполняется обработка.

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

отсутствуют

close

Обработка удаления услуги на стороне платформы или у провайдера услуг.

Требуется поддержка функции:

нет

Пример вызова:

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

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

• --item — код услуги, для которой выполняется обработка;
• --runningoperation — код текущей операции на включение услуги. Передается при наличии.

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

отсутствуют

По завершению обработки включения услуги вызовите функцию service.postclose с параметрами:

• elid — код услуги;
• sok=ok — подтверждение операции.

setparam

Обработка изменения параметров услуги на стороне платформы или у провайдера услуг

Требуется поддержка функции:

нет

Пример вызова:

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

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

• --item — код услуги, для которой выполняется обработка;
• --runningoperation — код текущей операции на включение услуги. Передается при наличии;
• --userid — код пользователя инициировавшего смену тарифного плана. Передается при наличии.

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

отсутствуют

Изменение параметров услуги может быть вызвано двумя действиями в BILLmanager:

• смена тарифного плана;
• изменение параметров и дополнений к услуге.

В этом случае в таблице item для услуги сохраняется ссылка lastpricelist на предыдущий тарифный план. В случае возникновения ошибки смены тарифного плана на стороне платформы или у провайдера услуги вызовите функцию service.changepricelist.rollback с параметрами:

• elid — код услуги;
• userid — код пользователя;
• sok=ok — подтверждение операции.

В этом случае дополнительных действий выполнять не требуется.

По завершению обработки изменения параметров услуги вызовите функцию service.postsetparam с параметрами:

• elid — код услуги;
• sok=ok — подтверждение операции.

get_suitable_module

Получение списка модулей обработки, доступных для обработки открытия услуги с переданными параметрами.

Требуется поддержка функции:

get_suitable_module

Пример вызова:

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

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

• --item — код услуги, для которой выполняется обработка. Не передается при построении списка тарифных планов;
• XML документ с параметрами услуги вида:

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <item> <!-- параметры услуги -->
    <pricelist>PR_ID</pricelist> <!-- PR_ID — это код заказываемого тарифа -->
    <param1></param1>
    ...
    <paramN></paramN>
  </item>
  <skip_modules></skip_modules>  <!-- Id обработчиков, которые не нужно учитывать при подборе подходящего модуля обработки. Обычно указываются модули обработки, на которых уже производилась попытка открытия указанной услуги -->
</doc>

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

XML документ вида

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <modules> <!-- параметры услуги -->
    <module id="id1"/>
    ...
    <module id="idN"/>
  </modules>
</doc>

где атрибут id у ноды module — код обработчика, подходящего для обработки услуги.

check_connection

Проверка возможности доступа к платформе или провайдеру услуг.

Требуется поддержка функции:

check_connection

Пример вызова:

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

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

XML документ с параметрами обработчика вида:

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <processingmodule> <!-- параметры обработчика -->
    <param1></param1>
    ...
    <paramN></paramN>
  </item>
</doc>

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

XML документ:

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

Либо XML описание ошибки.

tune_connection

Изменения формы настроек параметров обработчика. Может быть использован для заполнения списков, удаления/добавления атрибутов к полям и других действий по изменению формы.

Требуется поддержка функции:

tune_connection

Пример вызова:

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

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

XML документ текущего описания формы.

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

Исходный или изменённый XML документ.

tuning_param

Поддержка функции настройки дополнительных параметров, а так же изменение формы/списка настройки дополнительных параметров.

Требуется поддержка функции:

tuning_param

Пример вызова:

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

где action может принимать следующие значения:

• TableFormTune — функция вызвана при построении формы настройки параметра;
• TableGet — функция вызвана при получении данных уже настроенного параметра;
• TableSet — функция вызвана при сохранении параметра;
• List — функция вызвана при построении списка параметров.

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

XML документ текущего описания формы или списка с дополнительной нодой session_params, содержащей параметры сессии.

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

Исходный или изменённый XML документ, либо XML описание ошибки.

usercreate

Изменение формы создания нового пользователя на стороне провайдера услуги. Обычно служит для формирования ссылки на регистрацию в системе провайдера услуг.

Требуется поддержка функции:

usercreate

Пример вызова:

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

В XML-файле обработчика должна быть описана форма регистрации пользователя под именем processing.edit.module_name.createuser.

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

XML документ текущего описания формы.

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

Исходный или изменённый XML документ.

tune_changepassword

Изменение формы смены пароля для услуги.

Для добавления новых полей на форму смены пароля. Например, для описания формата ввода пароля нужно добавить метадату в XML модуля обработки в следующем формате:

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

Требуется поддержка функции:

tune_changepassword

Пример вызова:

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

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

• --module - код модуля обработчика, к которому привязана услуги, для которой производится смена пароля;
• XML документ текущего описания формы.

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

Исходный или изменённый XML документ.

sync_pricelist

Синхронизация тарифного плана в BILLmanager с соответствующей сущностью в платформе или у провайдера услуг. Может использоваться для создания пресета на стороне платформы, выставления лимитов дополнений в BILLmanager по данным от платформы или провайдера услуг и т.д. Вызывается при создании или изменении внутреннего имени тарифного плана, а также при подключении тарифов к обработчику.

Требуется поддержка функции:

sync_pricelist

Пример вызова:

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

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

• --module — код обработчика.

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

отсутствуют

get_server_config

Формирование и сохранение в BILLmanager описания конфига обработчика.

Требуется поддержка функции:

get_server_config

Пример вызова:

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

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

• --module — код обработчика.

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

отсутствуют

Конфиг модуля представляет собой XML документ следующего формата:

<?xml version='1.0' encoding='UTF-8'?>
<doc>
  <ostemplate> <!-- список шаблонов ОС, установленных в платформе -->
    <elem>
      <id>id1</id>
    </elem>
    ...
    <elem>
      <id>idN</id>
    </elem>
  </ostemplate>
  <presets> <!-- список пресетов, настроенных на стороне платформы или провайдера услуг. Используется в качестве внутренних имён для тарифных планов в BILLmanager -->
    <preset name="name1"/>
    ...
    <preset name="nameN"/>
  </presets>
</doc>

В конфиг можно сохранить дополнительную информацию для дальнейшего использования модулем.

Сохранение конфига в BILLmanager выполняется вызовом функции processing.setconfig с параметрами:

• elid — код обработчика;
• config — XML описание конфига.

Сохранение в BILLmanager шаблонов ОС (и других вариантов параметров типов продукта) выполняется функцией itemtype.param.value.edit с параметрами:

• intname — внутреннее наименование шаблона (идентификатор);
• name (name_xx) — наименование, в том числе локализованные;
• plid — код параметра типа продукта с внутренним именем ostempl для шаблонов ОС, либо соответствующие нужному параметру типа продукта;
• elid — код значения параметра, если требуется его изменение. Пустое значение при добавлении значения параметра;
• module — код модуля обработки, если требуется одновременное подключение к обработчику услуг;
• sok=ok — подтверждение операции.

sync_server

Синхронизация данных по услугам между BILLmananager и панелью управления или провайдером услуг.

Требуется поддержка функции:

sync_server

Пример вызова:

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

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

• --module — код обработчика.

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

отсутствуют

Может использоваться для:

• выставления узла кластера, на котором была создана услуга;
• шаблона ОС для виртуальных и выделенных серверов;
• любых других действий, обеспечивающих актуальность информации, отображаемой в BILLmanager.

prolong

Продление срока действия услуги в платформе или у провайдера услуг.

Требуется поддержка функции:

prolong

Пример вызова:

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

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

• --item — код услуги;
• --runningoperation — код текущей операции.

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

отсутствуют

По завершению продления услуги вызовите функцию service.postprolong с параметрами:

• elid — код услуги;
• sok=ok — подтверждение операции.

stat

Сбор статистики использования ресурсов услугами в платформе или у провайдера услуг.

Требуется поддержка функции:

stat

Пример вызова:

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

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

• --module — код обработчика.

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

нет

Собранную статистику необходимо сохранить в базу данных BILLmanager в таблицу itemstat, поля таблицы:

• item — код услуги;
• statdate — дата потребления ресурса;
• param — внутреннее имя параметра, по которому сохраняется статистика. Это либо внутреннее имя типа продукта дополнения к тарифному плану услуги, либо произвольное наименование параметра, которое указывается в настройках дополнения к тарифному плану;
• value — целочисленное значение потреблённого ресурса;
• measure — код единицы измерения.

По завершению сохранения информации о собранной статистике в базе данных BILLmanager вызовите функцию service.poststat, с параметрами:

• elid — код обработчика;
• date — дата за которую была собрана статистика.

Дата последнего сбора статистики сохраняется в поле laststatdate таблицы processingmodule, где id — код обработчика.

import_pricelist

Получение данных тарифного плана из панели управления или от провайдера услуг для сохранения в BILLmanager

Требуется поддержка функции:

import_pricelist

Пример вызова:

/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

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

• --module — код обработчика;
• --subcommand — тип получаемой информации. Возможные значения:
  • available — запрос списка доступных для импорта тарифных планов;
  • pricelist — запрос детальной информации по тарифному плану для импорта. Параметр --id — идентификатор тарифа в панели управления или у провайдера услуг;
  • images — запрос списка образов диска тарифного плана (при наличии). Параметр --id — идентификатор тарифа в панели управления или у провайдера услуг;
  • periods — запрос списка доступных периодов заказа тарифного плана. Параметр --id — идентификатор тарифа в панели управления или у провайдера услуг;
  • details — запрос списка доступных дополнений к тарифному плану. Параметр --id — идентификатор тарифа в панели управления или у провайдера услуг.

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

XML документ, формат которого зависит от полученного --subcommand:

• available

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <elem>
    <id>...</id> <!-- код тарифа в панели управления или на стороне провайдера услуг -->
    <name>...</name> <!-- наименование тарифа в панели управления или на стороне провайдера услуг -->
    <name_ru>...</name_ru> <!-- наименование тарифа в локализации ru в панели управления или на стороне провайдера услуг -->
    ...
    <name_xx>...</name_xx> <!-- наименование тарифа в локализации xx в панели управления или на стороне провайдера услуг -->
    <itemtype>...</itemtype> <!-- внутреннее имя типа продукта тарифа-->
  </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> <!-- код тарифа в панели управления или на стороне провайдера услуг -->
    <name>...</name> <!-- наименование тарифа в панели управления или на стороне провайдера услуг -->
    <name_ru>...</name_ru> <!-- наименование тарифа в локализации ru в панели управления или на стороне провайдера услуг -->
    ...
    <name_xx>...</name_xx> <!-- наименование тарифа в локализации xx в панели управления или на стороне провайдера услуг -->
    <itemtype>...</itemtype> <!-- внутреннее имя типа продукта тарифа -->
    <real_billtype>4</real_billtype> <!-- фиксированное значение -->
    <internalname>...</internalname> <!-- имя пресета тарифного плана -->
    <billdaily>...</billdaily> <!-- значение on для ежедневного списания, off в противном случае -->
    <billprorata>...</billprorata> <!-- значение on для календарного списания, off в противном случае -->
    <prorataday>...</prorataday> <!-- переходный день для календарного списания -->
    <minperiodtype>...</minperiodtype> <!-- тип минимального периода заказа: 0 - без минимального периода заказа, 1 - месяцы, 2 - дни -->
    <minperiodlen>...</minperiodlen> <!-- длина минимального периода заказа -->
  </elem>
</doc>

• images

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <elem>
    <name>...</name> <!-- наименование шаблона диска -->
    <name_ru>...</name_ru> <!-- наименование шаблона диска в локализации ru -->
    ...
    <name_xx>...</name_xx> <!-- наименование шаблона диска в локализации xx -->
    <intname>...</intname> <!-- внутреннее имя шаблона диска -->
  </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 код валюты, в которой указана стоимость -->
      <period name="monthly">...</period> <!-- стоимость месяца заказа, опционально -->
      <period name="quarterly">...</period> <!-- стоимость трёх месяцев заказа, опционально -->
      <period name="semiannual">...</period> <!-- стоимость полугода заказа, опционально -->
      <period name="annually">...</period> <!-- стоимость года заказа, опционально -->
      <period name="biennial">...</period> <!-- стоимость двух лет заказа, опционально -->
      <period name="triennial">...</period> <!-- стоимость трех лет заказа, опционально -->
      <period name="quadrennial">...</period> <!-- стоимость четырех лет заказа, опционально -->
      <period name="quinquennial">...</period> <!-- стоимость пяти лет заказа, опционально -->
      <period name="setup">0.0000</period> <!-- стоимость установки, опционально -->
    </elem>
  </currencies>
</doc>

• details

<doc>
  <elem>
    <id>...</id> <!-- код дополнения на стороне панели управления или провайдера услуг -->
    <intname>...</intname> <!-- внутреннее имя типа дополнения -->
    <billtype>...</billtype> <!-- тип учета дополнения: 1 — не учитывать, 2 — по заказанным значениям, 3 — по статистике -->
    <addontype>...</addontype> <!-- тип дополнения: 1 — логическое, 2 — целое число, 3 — перечисление -->
    <manualname>...</manualname> <!-- признак собственного наименования: on — будет использовано значение name, off — будет использовано наименование типа продукта -->
    <active>...</active> <!-- признак активности дополнения: on — включено, off — выключено -->
    <name>...</name> <!-- наименование типа продукта дополнения -->
    <name_ru>...</name_ru>
    ...
    <name_xx>...</name_xx>
    <addonname>...</addonname> <!-- наименование дополнения при manualname=on -->
    <addonname_ru>...</addonname_ru>
    ...
    <addonname_xx>...</addonname_xx>
    <rlimit>...</rlimit> <!-- включённое в тариф значение для целочисленного дополнения -->
    <addonenumval>...</addonenumval> <!-- включённое в тариф значение для дополнения задаваемого перечислением -->
    <measure>unit</measure> <!-- внутреннее имя единицы измерения -->
    <addonenum>...</addonenum> <!-- код перечисления в панели управления или у провайдера услуг для дополнения задаваемого перечислением -->
    <addonstep>...</addonstep> <!-- шаг заказа дополнения для целочисленного дополнения -->
    <addonmax>...</addonmax> <!-- максимальное значение дополнения для целочисленного дополнения -->
    <minperiodtype>...</minperiodtype> <!-- тип минимального периода заказа, как у тарифа -->
    <minperiodlen>...</minperiodlen> <!-- длина минимального периода заказа, как у тарифа -->
    <addonstattype>...</addonstattype> <!-- тип учёта дополнения по статистике: 1 — превышение считается за месяц, 2 — превышение считается за день -->
    <addonstatcomparison>...</addonstatcomparison> <!-- тип учета нескольких параметров дополнения по статистике: 1 — значения параметров суммируются, 2 — учитывается максимальный параметр -->
    <addonstatcalculation>...</addonstatcalculation> <!-- способ указания стоимости дополнения по статистике: 1 — стоимость указана за каждую единицу, 2 — стоимость указана за единицы в месяц -->
    <internalname>...</internalname> <!-- внутреннее имя параметра для учёта по статистике -->
    <restrictclientchange>...</restrictclientchange> <!-- возможность изменения клиентом после заказа: on — изменение разрешено, off — изменение запрещено -->
  </elem>
  ...
  <enum id="..." name="..." intname="..." name_ru="..."> <!-- описание перечисления, используемого в тарифном плане: id — код во внешней системе, name — наименование перечисления, intname — внутреннее наименование перечисления -->
    <enumitem id="..." name="..." intname="..." disabled="..." name_ru="..."/> <!-- элемент перечисления: id — код во внешней системе, name — наименование элемента перечисления, intname — внутреннее наименование элемента перечисления -->
    ...
  </enum>
  ...
  <addon_prices> <!-- цены на дополнения -->
    <elem>
      <id>...</id> <!-- код дополнения, для которого указаны цены -->
      <currency_code>...</currency_code> <!-- ISO код валюты, в которой указана стоимость -->
      <period name="monthly">...</period> <!-- стоимость месяца заказа, опционально -->
      <period name="quarterly">...</period> <!-- стоимость трёх месяцев заказа, опционально -->
      <period name="semiannual">...</period> <!-- стоимость полугода заказа, опционально -->
      <period name="annually">...</period> <!-- стоимость года заказа, опционально -->
      <period name="biennial">...</period> <!-- стоимость двух лет заказа, опционально -->
      <period name="triennial">...</period> <!-- стоимость трёх лет заказа, опционально -->
      <period name="quadrennial">...</period> <!-- стоимость четырёх лет заказа, опционально -->
      <period name="quinquennial">...</period> <!-- стоимость пяти лет заказа, опционально -->
      <period name="setup">...</period> <!-- стоимость установки, опционально -->
      <period name="stat">...</period> <!-- стоимость учета по статистике, опционально -->
    </elem>
    ...
  </addon_prices>
  <enumitem_prices>
    <elem>
      <id>...</id> <!-- код дополнения, для которого указаны цены -->
      <enumitem>...</enumitem> <!-- код элемента перечисления, для которого указаны цены -->
      <currency_code>...</currency_code> <!-- ISO код валюты, в которой указана стоимость -->
      <period name="monthly">...</period> <!-- стоимость месяца заказа, опционально -->
      <period name="quarterly">...</period> <!-- стоимость трёх месяцев заказа, опционально -->
      <period name="semiannual">...</period> <!-- стоимость полугода заказа, опционально -->
      <period name="annually">...</period> <!-- стоимость года заказа, опционально -->
      <period name="biennial">...</period> <!-- стоимость двух лет заказа, опционально -->
      <period name="triennial">...</period> <!-- стоимость трёх лет заказа, опционально -->
      <period name="quadrennial">...</period> <!-- стоимость четырёх лет заказа, опционально -->
      <period name="quinquennial">...</period> <!-- стоимость пяти лет заказа, опционально -->
      <period name="setup">0.0000</period> <!-- стоимость установки, опционально -->
    </elem>
    ...
  </enumitem_prices>
</doc>

check_param

Проверка возможности изменения параметра услуги.

Требуется поддержка функции:

check_param

Пример вызова:

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

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

• --item — код услуги;
• --param — внутреннее наименование параметра;
• --value — новое значение параметра;
• --level — уровень доступа пользователя, изменившего параметры;
• XML вида:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <item> <!-- список старых значений параметров услуги -->
    <param1>...</param1>
    ...
    <paramN>...</paramN>
  </item>
  <newitem> <!-- список новых значений параметров услуги -->
    <param1>...</param1>
    ...
    <paramN>...</paramN>
  </newitem>
</doc>

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

В случае допустимости изменения параметра:

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

В противном случае сообщение об ошибке.

check_addon

Проверка возможности изменения дополнения к услуге.

Требуется поддержка функции:

check_addon

Пример вызова:

/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

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

• --item — код услуги;
• --param — внутреннее наименование типа дополнения;
• --value — новое значение дополнения;
• --level — уровень доступа пользователя, изменившего дополнение;
• XML вида:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <item> <!-- список параметров услуги -->
    <param1>...</param1>
    ...
    <paramN>...</paramN>
  </item>
</doc>

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

В случае допустимости изменения параметра:

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

В противном случае сообщение об ошибке.

changepassword

Изменение пароля для услуги на стороне панели управления или провайдера услуг.

Требуется поддержка функции:

changepassword

Пример вызова:

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

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

• --item — код услуги;
• --password — новое значение пароля, зашифрованное алгоритмом RSA и секретным ключом /usr/local/mgr5/etc/billmgr.pem.

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

отсутствуют

По завершению смены пароля у услуги необходимо сохранить его в BILLmanager командой service.saveparam с параметрами:

• item — код услуги;
• password — новый пароль услуги;
• sok=ok — подтверждение операции.

И вызвать функцию service.postchangepassword с параметрами:

• item — код услуги;
• sok=ok — подтверждение операции.

addip

Добавление у услуге нового IP-адреса.

Требуется поддержка функции:

нет

Пример вызова:

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

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

• --item — код услуги;
• --ip — код IP-адреса из таблицы ip.

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

отсутствуют

IP-адрес сохраняется в BILLmanager функцией service.ip.add с параметрами:

• elid — код IP-адреса;
• ip — значение IP-адреса;
• domain — ptr запись IP-адреса;
• ipmgr — ссылка на IPmanager, если используется;
• sok=ok — подтверждение операции.

В ответ функция вернет XML вида:

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

Нода ip.id содержит новый код IP-адреса в BILLmanager (код меняется в случае, если услуге выделяется IP-адрес, ранее уже сохранённый в BILLmanager).

Для полученного кода IP-адреса нужно вызвать функцию активации service.ip.add.commit с параметрами:

• elid — код ip адреса;
• sok=ok — подтверждение операции.

editip

Изменение существующего IP-адреса услуги. Вызывается при редактировании доменного имени у IP-адреса в BILLmanager.

Требуется поддержка функции:

нет

Пример вызова:

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

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

• --ip — код ip адреса из таблицы ip.

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

отсутствуют

delip

Удаление IP-адреса у услуги.

Требуется поддержка функции:

нет

Пример вызова:

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

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

• --item — код услуги;
• --ip — код ip адреса из таблицы ip.

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

отсутствуют

IP-адрес помечается в BILLmanager удалённым функцией service.ip.del с параметрами:

• elid — код IP-адреса;
• sok=ok — подтверждение операции.

transition_controlpanel

Переход на сервер под учётной записью клиента или сотрудника.

Требуется поддержка функции:

transition_controlpanel

Пример вызова:

/usr/local/mgr5/processing/pmxxx --command transition_controlpanel --item id --level level - получения списка доступных для перехода панелей
/usr/local/mgr5/processing/pmxxx --command transition_controlpanel --item id --panelkey panelkey - получение ссылки на переход в выбранную панель
/usr/local/mgr5/processing/pmxxx --command transition_controlpanel --panelkey panelkey - переход на сервер из раздела обработчиков

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

• --item — код услуги;
• --level — уровень доступа пользователя, выполняющего переход;
• --panelkey — код обработчика при переходе из списка обработчиков или идентификатор панели, ссылку на переход в которую необходимо вывести.

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

XML документ со списком панелей или ссылкой на переход в панель управления:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <url></url> <!-- ссылка для перехода, выводится только при непосредственном переходе, либо при наличии только одного варианта -->
  <panelcount>...</panelcount> <!-- количество доступных для перехода панелей управления. При непосредственном переходе, либо при наличии только одного варианта передается значение '''1''' либо отсутствует -->
  <panelname keyname="keyname">...</panelname> <!-- описание варианта выбора панели управления для перехода. Значение keyname будет в последствии передано как panelkey -->
  ...
</doc>

pingip

Проверка доступности IP-адреса. Выполняется перед удалением.

Требуется поддержка функции:

pingip

Пример вызова:

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

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

• --item — код услуги;
• --ip — код IP-адреса.

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

XML документ с результатом проверки доступности IP-адреса:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <ping_result>...</ping_result> <!-- результат проверки: OK, если IP-адрес пингуется -->
</doc>

cleanup

Выполнение дополнительных действий по завершению удаления услуги (после перевода услуги в статус "удалён").

Требуется поддержка функции:

cleanup

Пример вызова:

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

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

• --item — код услуги.

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

отсутствуют

cloneitem

Перенос услуги от клиента к клиенту в BILLmanager. Может быть полезна, если разные услуги одного клиента создаются в рамках одной учётной записи в панели управления или на стороне провайдера услуг.

Требуется поддержка функции:

cloneitem

Пример вызова:

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

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

• --item — новый код услуги.

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

отсутствуют

reboot

Перезагрузка услуги.

Требуется поддержка функции:

reboot

Пример вызова:

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

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

• --item — код услуги.

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

отсутствуют

По завершению перезагрузки услуги вызовите функцию service.postreboot с параметрами:

• elid — код услуги;
• sok=ok — подтверждение операции.

Обработка ошибок

Если при вызове функции модуля был передан Id текущей операции и при обработке команды произошла какая-либо ошибка, целесообразно отобразить информацию об этом в BILLmanager. Для этого существует набор функций:

• runningoperation.edit — изменение текущей операции. Принимает параметры:
  • elid — код текущей операции;
  • errorxml — XML документ с набором XML описаний произошедших ошибок, вида:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <error date="2000-01-01 00:00:00" type="type" object="object" value="value"> <!-- описание ошибки в стандартном формате с добавлением атрибута date — время возникновения ошибки -->
    ...
    <backtrace>...</backtrace> <!-- отладочная информация для диагностики ошибки. Отображается при просмотре ошибки в разделе текущих операций -->
    <log>...</log> <!-- лог выполнения операции. Отображается при просмотре ошибки в разделе текущих операций -->
  </error>
  <processingmodule date="2000-01-01 00:00:00" id="id" name="name"/> <!-- информация об обработчике, на котором произошла ошибка -->
  <custommessage>...</custommessage>  <!-- произвольная дополнительная информация. Отображается при просмотре ошибки в разделе текущих операций -->
</doc>

Error: Type: 'rpc' Object: 'query' Value: 'query: Failed writing received data to disk/application'
]]></log></error></doc>
</errorxml><out>xml</out><func>runningoperation.edit</func></tparams></doc>

libmgr ERROR Error: Type: 'client' Object: 'bad_response' Value: ''

Error: Type: 'db' Object: 'query' Value: ''

При наличии кода услуги и необходимости прекращения повторных попыток выполнения операции (в таблице runningoperation поле trycount отражает количество попыток выполнения операции) можно создать задачу на отдел, ответственный за модуль обработки.

Для этого выполните два шага:

1. Вызвать функцию task.gettype, в которую параметром operation передаётся текущее значение параметра --command командной строки. В ответ будет получен XML документ вида:
   

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

   где task_type — тип задачи, которую необходимо создать. Если нода отсутствует или пуста, создание задачи невозможно.

2. Зарегистрировать задачу функцией task.edit, с параметрами:
   • item — код услуги;
   • runningoperation — код текущей операции;
   • type — значение task_type;
   • sok=ok — подтверждение операции.

Примеры модулей

Исполняемый файл модуля обработчика может быть реализован на любом скриптовом или компилируемом языке программирования, поддерживающим работу с параметрами командной строки, а так же потоками ввода вывода. Выбор языка программирования зависит от разработчика, но для ускорения разработки и своевременного реагирования на добавления новых функций, рекомендуется использовать C++ и заголовочные файлы из пакета разработчика BILLmanager.

C++ (с использованием библиотек BILLmanager)

Использование заголовочных файлов BILLmanager для разработки собственных модулей обработчиков доступно с версии BILLmanager 5.58.0. Кроме приведённого упрощённого примера, можно изучить примеры, представленные в пакете разработчика BILLmanager — billmanager-[Редакция BILLmanager]-devel:

yum install billmanager-devel
или
yum install billmanager-corporate-devel

После этого примеры можно найти в директории:

/usr/local/mgr5/src/examples
<?xml version='1.0' encoding='UTF-8'?><doc>  <modules> <!-- параметры услуги -->    <module id="id1"/>    ...    <module id="idN"/>  </modules></doc>