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

Для выполнения всех операций с услугами в 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 вида

<?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 вида

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

Пояснения

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

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

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

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

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

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

Исполняемый файл модуля обработчика может быть реализован на любом скриптовом или компилируемом языке программирования, поддерживающем работу с параметрами командной строки, а так же потоками ввода вывода. Выбор языка программирования зависит от разработчика, но для ускорения разработки, а так же своевременного реагирования на добавления новых функций, рекомендуется использовать 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>