Модули. Общие принципы

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

Модификации BILLmanager

 BILLmanager позволяет добавить следующие модификации:

• модули — крупные и самостоятельные компоненты системы, которые выполняют определённую функцию или набор функций. Например, расширяют функциональность за счёт интеграции со сторонней системой. Модули:
  • обычно имеют свои зависимости и могут включать в себя несколько плагинов;
  • не предназначены для динамического изменения поведения системы в реальном времени;
  • могут требовать изменений в основной архитектуре системы;
  • по функциональности разделяются на:
    • обработчики услуг;
    • методы оплаты;
    • шлюзы сообщений;
    • онлайн-кассы;
    • модули документооборота;
    • модули для координации со сторонними системами — LDAP, Omni, amoCRM и т. д.

• плагины — обычно более простые программные компоненты, которые добавляют определённую функциональность или изменяют поведение основной системы. Плагины позволяют:
  • интегрировать новые функции без изменения исходного кода;
  • перехватывать внутренние события;
  • добавлять новые элементы интерфейса;
  • выполнять фоновые задачи через триггеры на определённые события;
  • адаптировать систему под конкретные потребности.

Подробнее см. статью Плагины. Общие принципы.

Сравнение плагинов и модулей см. в статье Плагины и модули в BILLmanager.

Классы модулей

Модуль — внешний исполняемый файл, который BILLmanager вызывает с аргументом --command <команда> и набором параметров вида --<имя> <значение>. Для некоторых команд на стандартный ввод (stdin) может передаваться XML-документ, либо от модуля требуется вывод в stdout. Модуль не реагирует на события платформы, а реализует конкретный тип интеграции.

Все модули обязаны поддерживать команду --command features (для платёжных методов — config), которая возвращает XML-документ с описанием поддерживаемых возможностей (<features>, <params>, <itemtypes> и т. д.). Неподдерживаемые команды не должны упоминаться в ответе features, иначе BILLmanager будет пытаться их вызывать, что приведёт к ошибкам.

Ниже перечислено сравнение основных классов модулей, поддерживаемых BILLmanager.

Сравнительная таблица классов модулей

Общие замечания по разработке

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

• команда features (config у платёжных методов) должна быть реализована в любом модуле. Не включайте неподдерживаемые команды в XML-ответ;
• длительные операции (регистрация домена, выпуск сертификата) получают параметр --runningoperation. По завершении необходимо вызвать соответствующую функцию BILLmanager (например, domain.open, certificate.open, service.postclose и т. д.), иначе операция будет повторяться;
• параметры подключения, требующие защиты, должны иметь в XML-описании атрибут crypted="yes". BILLmanager будет хранить их в зашифрованном виде;
• рекомендуется размещать CGI-скрипты для платёжных методов и шлюзов в директории /usr/local/mgr5/cgi/;
• рекомендуется вести логирование в директории /usr/local/mgr5/var/. Для Python используйте billmgr.logger.

Общие замечания по XML

/usr/local/mgr5/sbin/mgrctl -m billmgr -R

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

• XML-документ без данных (<doc/>) означает успешное выполнение без дополнительных данных;
• ошибки передаются в виде:

<doc>
	<error type="<значение указанное после msg_error_ в сообщениях>" object="*" value="*"/>
</doc>

или для конкретного поля определено сообщение msg_error_value:

<doc>
	<error type="value" object="*" value="*"/>
</doc>

• используйте кодировку UTF-8 для всех XML-файлов;
• параметры с аттрибутом crypted="yes" в features BILLmanager передаёт в модуль незашифрованными только в команде check_connection. В остальных случаях они хранятся зашифрованными в БД и не передаются;
• сообщения можно переопределять на конкретных формах или глобально через XML-конфигурацию, указав их в нужном разделе. Это перезапишет существующее сообщение.

Принципы работы модулей

Модули BILLmanager запускаются с аргументами командной строки --command <команда> [--параметр значение] и могут обмениваться данными через стандартные потоки ввода-вывода. В этом разделе описан формат вызова модулей и принципы обмена данными.

Формат вызова

BILLmanager запускает модуль командой:

/путь/к/модулю --command <команда> [--параметр1 значение1] [--параметр2 значение2] ...

Где:

• каждый параметр передаётся в виде --имя значение;
• обязательным является аргумент --command, который задаёт вызываемую функцию модуля (например, open, close, features, process);
• остальные аргументы — именованные параметры (например, --item 42, --cash_register 1).

Передача данных через стандартный ввод (stdin)

Некоторые команды требуют передачи структурированных данных, которые неудобно или невозможно передать через аргументы командной строки. Например, сложные XML-формы или многострочные значения. В таких случаях BILLmanager подаёт XML на stdin модуля.

Команды, которые обычно используют stdin:

• check_connection — получает параметры подключения в открытом виде;
• tune_connection, form_tune, *tune (pmtune, crtune, rftune и т. д.) — получают текущий XML-шаблон формы;
• *validate (pmvalidate, crvalidate и т. д.) — получают введённые пользователем данные;
• *set (rfset, tfset и т. д.) — получают дополнительные данные операции.

<doc>
<api_url>https://api.provider.com</api_url>
<api_key>test_key</api_key>
<extra_param>value</extra_param>
</doc>

Модуль использует XML-код из stdin, обрабатывает и выдаёт результат в stdout.

Вывод результатов в стандартный поток (stdout)

Результат выполнения команды модуль выводит в stdout. Формат вывода — всегда XML-файл (кроме случаев, когда модуль сам выполняет внешние действия без возврата данных, но даже тогда рекомендуется выводить пустой XML).

Типы выходных данных:

• успешное выполнение без дополнительных данных — пустой XML-файл: <doc/>;
• успешное выполнение с данными — XML-файл, структура которого зависит от команды. Например:
  • features — возвращает описание возможностей модуля;
  • WHOIS — возвращает WHOIS-строку в узле <WHOIS>;
  • approver — возвращает список email-адресов.
  Пример для approver:

  <doc>
  <email>admin@example.com</email>
  <email>hostmaster@example.com</email>
  </doc>

• выполнение с ошибкой — XML-файл с узлом <error>:

  <doc>
  <error type="connection" value="*" object="*"/>
  </doc>

Обязательная команда features (или config для платёжных методов)

Все модули должны поддерживать команду --command features (для платёжных методов — --command config). Эта команда не получает входных данных (stdin не используется) и выводит XML-файл, который описывает:

• какие типы элементов обслуживает модуль (<itemtypes>);
• какие параметры нужны для его настройки (<params>);
• какие команды (функции) он поддерживает (<features>);
• дополнительную информацию. Например, <templates> для SSL-сертификата, <contact_type> для уведомлений;
• config должен содержать элемент <features> .

<doc>
<itemtypes><itemtype name="domain"/></itemtypes>
<params>
<param name="api_url"/>
<param name="api_key" crypted="yes"/>
</params>
<features>
<feature name="open"/>
<feature name="close"/>
<feature name="check_connection"/>
</features>
</doc>

BILLmanager не будет вызывать команды, которые не перечислены в ответе features . Если модуль поддерживает команду, но администратор не указал её в features, она останется невостребованной.

Длительные операции и параметр --runningoperation

Некоторые операции (регистрация домена, выпуск сертификата, создание VPS) могут занимать продолжительное время. Для таких команд BILLmanager передаёт дополнительный параметр --runningoperation <id>.

Модуль обязан после реального завершения операции уведомить BILLmanager о результате (успех или ошибка) через вызов mgrctl .

/usr/local/mgr5/sbin/mgrctl -m billmgr service.postclose --elid 456

Если модуль не вызовет соответствующую функцию, BILLmanager будет периодически перезапускать команду, считая, что операция ещё не завершилась.

Шифрование параметров

В XML-метаданных модуля параметры могут быть помечены атрибутом crypted="yes". Это означает, что BILLmanager будет хранить их в базе данных в зашифрованном виде.

Важное исключение: при вызове команды check_connection (а также pmvalidate, crvalidate и других валидирующих команд) BILLmanager передаёт эти параметры в открытом виде на stdin модуля. Это необходимо, чтобы модуль мог проверить их корректность. Например, выполнить тестовое подключение к API.

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

Требования к кодировке

Чтобы избежать ошибок парсинга и обеспечить корректную обработку данных системой, соблюдайте следующие требования:

• входные (stdin) и выходные (stdout) XML  должны быть в кодировке UTF-8;
• BILLmanager ожидает именно UTF-8; использование других кодировок может привести к ошибкам парсинга.

Пример полного цикла вызова

Рассмотрим вызов команды check_connection для модуля обработки услуг:

1. BILLmanager формирует XML-файл с параметрами подключения. Шифрование не используется.
2. BILLmanager запускает модуль:

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

3. BILLmanager передаёт XML на stdin модуля.
4. Модуль принимает stdin и выполняет проверку. Например, вызывает API провайдера.
5. В зависимости от результата выводит в stdout:
   • при успехе: <doc/>
   • при ошибке: <doc><error type="msg_error_*" .../></doc>
6. BILLmanager читает stdout, парсит XML-код и определяет, успешна ли проверка.

Если команда не использует stdin (например, features), модуль игнорирует stdin.

XML-описание (файл billmgr_mod_<имя>.xml)

Файл метаданных описывает модуль для BILLmanager: его тип, форму настроек, локализованные названия и сообщения об ошибках. Формат файла зависит от типа модуля и может включать несколько разделов <metadata> для разных целей (основные настройки, создание пользователя, профиль услуги и т. д.).

Подробнее о работе с XML-формами, поиске тегов и атрибутов к ним см. документацию COREmanager.

Общие правила

• корневой элемент — <mgrdata>;
• родировка — UTF-8;
• расположение — /usr/local/mgr5/etc/xml/;
• имя файла формируется по формату:
  • модуль обработки услуг: billmgr_mod_pm<имя>.xml;
  • платёжный метод: billmgr_mod_pm<имя>.xml;
  • онлайн-касса: billmgr_mod_cr<имя>.xml;
  • модуль уведомлений: billmgr_mod_nt<имя>.xml;
  • шлюз сообщений: billmgr_mod_gw<имя>.xml;
• после изменения XML-файла перезагрузите BILLmanager:

  /usr/local/mgr5/sbin/mgrctl -m billmgr exit

Элемент <plugin>

Элемент <plugin> используется для модулей, которые являются самостоятельными плагинами:

• модули обработки услуг (group=processing_module);
• платёжные методы (group=payment_method);
• онлайн-кассы (group=payment_cash_register);
• шлюзы сообщений (group=gateway);
• плагины (group=plugin).

Атрибуты:

• name — внутреннее имя модуля (совпадает с именем исполняемого файла и частью имени XML-файла).

Дочерние элементы:

<plugin name="pmnic">
	<group>processing_module</group>
	<author>BILLmanager team</author>
	<params>
		<type name="domain"/>
		<priority lang="ru">1800</priority>
		<priority lang="en">700</priority>
	</params>
</plugin>

<plugin name="pmnowpayments">
	<group>payment_method</group>
	<author>BILLmanager team</author>
	<params>
		<priority lang="en">3810</priority>
		<priority lang="ru">1800</priority>
	</params>
</plugin>

Элемент <metadata>

Может быть несколько блоков <metadata> в одном файле. Каждый описывает определённую форму: настройки модуля, форму создания пользователя, профиль услуги и т. д.

Общие атрибуты:

• name — идентификатор формы. Формат зависит от назначения. Подробнее см. таблицу;
• type="form" — обязательно для форм.

Внутренняя структура: <metadata> содержит <form>, который может включать несколько страниц (<page>) и полей (<field>). Поддерживаются также <link> (ссылки) и <include> для переиспользования частей форм.

Основная форма настроек модуля

Используется для ввода параметров подключения (API-ключи, URL, логины, пароли и т. д.).

Ниже примеры основной формы для различных типов модулей.

<metadata name="processing.edit.pmnic" type="form">
<form title="name">
<page name="connect">
<field name="contract_num">
<input type="text" name="contract_num" required="yes" check="int"/>
</field>
<field name="password">
<input type="password" name="password" required="yes"/>
</field>
<field name="msg_lang">
<select name="msg_lang"/>
</field>
<field name="partner_domain">
<input type="text" name="partner_domain" check="domain"/>
</field>
</page>
</form>
</metadata>

<metadata name="paymethod.edit.2checkout" type="form">
<form>
<page name="methodprops">
<field name="apiurl">
<input type="text" name="apiurl" check="url" private="yes" required="yes"/>
</field>
<field name="sid">
<input type="text" name="sid" required="yes"/>
</field>
<field name="secret_word">
<input type="text" name="secret_word" private="yes" required="yes"/>
</field>
<field name="pay_method">
<select name="pay_method" private="yes"/>
</field>
<field name="pending">
<input type="checkbox" name="pending" private="yes"/>
</field>
</page>
</form>
</metadata>

<metadata name="payment_cash_register.edit.crcustom" type="form">
<form>
<page name="page_settings">
<field name="url">
<input name="url" type="text" check="url"/>
</field>
<field name="username">
<input name="username" type="text" required="yes"/>
</field>
<field name="password">
<input name="password" type="password" required="yes"/>
</field>
</page>
</form>
</metadata>

<metadata name="gateway.gwcustom">
<form>
<field name="custom_param_url">
<input type="text" check="url" name="custom_param_url" required="yes" identifier="yes"/>
</field>
<field name="custom_param_api_key">
<input type="text" name="custom_param_api_key" required="yes"/>
</field>
</form>
</metadata>

Форма создания пользователя (опционально)

Некоторые модули (например, платёжные методы и регистраторы) требуют отдельной формы для создания аккаунта во внешней системе. Имя такой формы обычно содержит суффикс .createuser.

<metadata name="paymethod.edit.pm2checkout.createuser" type="form">
<form>
<page name="createuser">
<field name="link">
<link name="outerlink" target="_blank"/>
</field>
</page>
</form>
</metadata>

<metadata name="processing.edit.pmnic.createuser" type="form">
<form>
<page name="createuser">
<field name="link">
<link name="outerlink" target="_blank"/>
</field>
</page>
</form>
</metadata>

Форма профиля услуги (service_profile)

Для модулей обработки услуг (например, регистраторов доменов) может потребоваться форма для заполнения контактных данных, специфичных для доменной зоны. Имя такой формы: service_profile.<имя_модуля>[.<зона>].

<metadata name="service_profile.pmnic">
<form>
<page name="company_info">
<field name="company">
<input type="text" name="company" check="latin" required="yes"/>
</field>
</page>
</form>
</metadata>

<metadata name="service_profile.pmnic.ru" type="form">
<form>
<page name="base_info">
<field name="profiletype">
<select name="profiletype" readonly="yes"/>
</field>
</page>
<page name="registration_info" insert_after="contact_info">
<field name="registration_postcode">
<input type="text" name="registration_postcode" required="yes" maxlength="255"/>
</field>
</page>
</form>
</metadata>

<metadata name="service_profile.pmnic.xn--p1ai" type="form">
<include name="service_profile.pmnic.ru"/>
</metadata>

Модуль уведомлений: добавление поля в профиль пользователя

Модули уведомлений не имеют собственной формы настроек. Вместо этого они добавляют поле в профиль пользователя (user_include).

<metadata name="user_include" type="form">
<form title="name">
<page name="user">
<field name="jabber" after="phone">
<input type="text" name="jabber" check="email"/>
</field>
</page>
</form>
</metadata>

Атрибуты <input> и других элементов

Часто используемые атрибуты <input>:

Элемент <select>

<field name="pay_method">
	<select name="pay_method" private="yes"/>
</field>

Варианты выбора определяются в локализации (см. документацию COREmanager).

Элемент <link>

<field name="link">
	<link name="outerlink" target="_blank"/>
</field>

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

Элемент <if> внутри <select>

Позволяет скрывать поля в зависимости от выбранного значения.

Элемент <lang> и блоки сообщений

Атрибут name используется для локализации строк. с помощью указания языка (ru, en, es и т. д.). Внутри — блоки <messages name="...">, каждый из которых содержит <msg name="..." value="..."/> (или текст между тегами).

Основные блоки сообщений (по типам модулей):

<lang name="ru">
	<messages name="gateway.gwcustom">
		<msg name="custom_param_url">API URL</msg>
		<msg name="custom_param_api_key">API Key</msg>
		</messages>
		<messages name="gateway_include">
		<msg name="module_gwcustom">gwcustom</msg>
		<msg name="gwcustom">gwcustom</msg>
		<msg name="desc_gwcustom">СМС-шлюз</msg>
	</messages>
</lang>

<lang name="ru">
<messages name="label_paymethod">
<msg name="pm2checkout">2CheckOut</msg>
<msg name="module_pm2checkout">2CheckOut</msg>
</messages>
<messages name="paymethod.edit.2checkout">
<msg name="sid">2CO Account #</msg>
<msg name="pay_method">Способ оплаты</msg>
<msg name="cc">Платёжные карты</msg>
<msg name="ppi">PayPal</msg>
</messages>
</lang>

<lang name="ru">
<messages name="processing.edit.pmnic">
<msg name="contract_num">Номер договора</msg>
<msg name="msg_lang">Язык</msg>
<msg name="partner_domain">Домен</msg>
</messages>
</lang>

Названия модуля может не быть в отдельном блоке, оно берётся из plugin, а processing.edit.pmnic используется для подписей полей.

Сообщения об ошибках (секция msgerror)

Модуль может возвращать ошибки в формате XML (см. раздел Вывод результатов в стандартный поток (stdout)). BILLmanager локализует их, используя сообщения из секции msgerror. Поиск сообщения происходит следующим образом:

1. msg_error_<тип>
2. msg_error_unknown

Пример определения в pmnowpayments:

<messages name="msgerror">
<msg name="msg_error_invalid_api_key">Неверный API-ключ</msg>
<msg name="msg_error_api_down">Шлюз недоступен</msg>
<msg name="msg_error_wrong_email_form">Неверный формат электронной почты</msg>
</messages>

Сводная таблица: типы модулей и идентификаторы <metadata>

Важные замечания

• Модули уведомлений не содержат <plugin> . Они только добавляют поле в профиль пользователя (user_include) и определяют новый тип уведомления в include.notify. Фактическую отправку сообщений выполняет соответствующий шлюз (gw*);
• Имена полей в <field name="..."> должны в точности совпадать с именами параметров, указанных в ответе команды features (или config для платёжных методов);
• Атрибут private="yes" скрывает поле в интерфейсе, но значение может быть показано в журналах при отладке. Для паролей и ключей рекомендуется использовать оба атрибута: private="yes" crypted="yes";
• Блоки messages name="..." не имеют жёсткого стандарта — они должны соответствовать имени соответствующего <metadata> (для подписей полей) или общепринятым именам (plugin, label_paymethod, gateway_include, payment_cash_register.include). Название модуля в интерфейсе чаще всего определяется в блоке ..._include или label_..., но может быть и в plugin (для модулей обработки услуг название часто берётся из desc_short_<имя>);
• Приоритет сортировки (<priority lang="ru">число</priority>) влияет на порядок отображения модуля в списке выбора. Меньшее число — выше в списке;
• Чтобы добавить несколько локализаций для плагина, добавляйте блоки <lang name="..."> для каждого поддерживаемого языка. Например, en, ru, es, de.