Агент мониторинга¶
Описание¶
Основной задачей агента мониторинга является управление информационными потоками между ПроАТМ и системой мониторинга. Агент мониторинга обеспечивает надежный транспортный уровень для передачи информации о событиях из ПроАТМ в систему мониторинга банка. Основными особенностями функционирования агента мониторинга являются:
Предоставление ПроАТМ унифицированного интерфейса для взаимодействия с внешними системами мониторинга.
Обеспечение надежной доставки сообщений до системы мониторинга.
Работа агента мониторинга разбивается на следующие операции:
предоставление унифицированного интерфейса к внешним системам;
инкапсуляция логики взаимодействия с внешними системами;
управление коммуникационными и другими параметрами, связанными с внешними системами;
мониторинг доставки сообщений во внешние системы.
Компонент, входящий в состав ПроАТМ и взаимодействующий с агентом мониторинга, подписывается на все события, происходящие в ПроАТМ, при помощи т.н. «общей шины». Таким образом, обеспечивается максимальная полнота информации, передаваемой в систему мониторинга. Отдельно выделенный компонент «Агент мониторинга» реализует интерфейс взаимодействия с ПроАТМ и внешними системами мониторинга.
Решаемые задачи:
Получение событий мониторинга от ПроАТМ.
Реализация очереди на отправку событий в систему мониторинга.
Гарантированная доставка событий в систему мониторинга.
Фильтрация событий по определенным правилам.
Пересылка команд от системы мониторинга в ПроАТМ.
Использование подсистемы не накладывает дополнительных требований на состав базового ПО УС кроме тех, что предусмотрены ПроАТМ. Настройки агента мониторинга находятся в разделе реестра [HKEY_LOCAL_MACHINE\SOFTWARE\FS365\MonitoringAgent]. Стандартный механизм RedLabel предназначен для логирования агента мониторинга. Все предупреждения о работе агента записываются с уровнем логирования 65, информационные сообщения – с уровнем 66.
Особенности реализации¶
Агент мониторинга является Windows-приложением. После запуска его иконка появляется в области уведомлений. С помощью этой иконки можно завершить работу агента мониторинга или приостановить его работу.
Транспортом для взаимодействия ПроАТМ и агента мониторинга является сетевой протокол TCP/IP, посредством которого передаются сообщения. Сообщение состоит из заголовка и тела. Заголовок включает в себя сигнатуру системы мониторинга (4 байта) и размер тела сообщения (2 байта). Тело сообщения представляет собой строку в формате xml и в кодировке UTF-8.
Для начала работы с агентом мониторинга необходимо в настройках агента мониторинга установить в параметре RemoteMonitoringUrl URL системы мониторинга, по которому необходимо отправлять сообщения о событиях. Для отправки команды ПроАТМ достаточно послать агенту мониторинга на порт 3333 сообщение следующего вида:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring>
<command id='1' name='GO_IN_SERVICE'/>
</monitoring>
Атрибут «id» является уникальным числом, однозначно идентифицирующий команду на данном временном и пространственном отрезке. Он используется, в основном, для наблюдения за судьбой команды. Атрибут «name» задает имя команды. Поддерживаются следующие команды:
REBOOT – перезагрузка терминала;
GO_IN_SERVICE – перевод терминала в состояние обслуживания клиента;
GO_OUT_OF_SERVICE – перевод терминала в состояние «не обслуживает»;
GET_STATUS – получение статуса устройства;
RESET – сброс состояния устройства;
GET_CASH_UNIT_INFO – получение информации о состоянии кассет;
GET_CIM_NOTETYPES – получение информации о типах принимаемых банкнот;
GET_DEVICE_INFO – получение сведений о версиях ПО и оборудовании УС.
На каждую команду агент мониторинга вернет результат выполнения команды. Для правильной отработки команд GO_OUT_OF_SERVICE и GO_IN_SERVICE необходимо, чтобы в настройках ПроАТМ в разделе [HKEY_LOCAL_MACHINE\SOFTWARE\FS365\MajorBusinessModules] параметр GoInServiceMajors содержал строку «Monitoring» (если параметр содержит несколько значений, то они должны разделяться запятой). Пока подтверждение не будет получено, сообщение считается не доставленным и будет отсылаться вновь и вновь.
Функционирование¶
Получение событий мониторинга от ПроАТМ¶
Для получения событий агент мониторинга открывает порт, номер которого задается в настройках агента мониторинга или, по умолчанию, порт номер 3333. На этот порт ПроАТМ посылает сообщение о событии в виде xml-строки вида:
<?xml version='1.0' encoding='UTF-8'?>
<event severity="normal" device="12" message="Запущено терминальное ПО ProATM" agent="ProATM" service_id="Ogre.exe" atm="00000040" eventtime="1290606064"/>
XML-код, описывающий событие, содержит единственный тег <event> c набором атрибутов. Атрибуты severity и device являются обязательными. Остальные атрибуты являются опциональными, то есть могут отсутствовать. Набор атрибутов варьируется в зависимости от события. На каждое успешно полученное сообщение о событии агент мониторинга отправляет ПроАТМ подтверждение о получении. Затем соединение завершается.
Реализация очереди на отправку событий в систему мониторинга¶
После получения события, агент мониторинга не сразу посылает его системе мониторинга, а помещает в очередь. После этого агент мониторинга выбирает из очереди самое ранее событие, которое еще не было доставлено системе мониторинга, проверяет его согласно правилам и отправляет запрос системе мониторинга. Если система мониторинга подтвердила, что сообщение получено успешно, события помечаются как доставленные, но не удаляются из очереди. Если в процессе отправки событий возникли проблемы, события помечаются в очереди как «были отправлены, но неудачно». Такие события будут отправлены в следующий раз. Фактически, пока агент мониторинга работает, ни одно событие не будет удалено из очереди, а будет только менять свой статус. Очистка очереди происходит при старте агента мониторинга, только тогда все успешно доставленные события физически удаляются из БД.
Очередь реализована на основе локальной БД, находящейся в файле MonitoringAgent.db в папке агента мониторинга.
Гарантированная доставка событий в систему мониторинга¶
Для доставки событий системе мониторинга в настройках агента мониторинга должен быть определен адрес системы мониторинга по которому отправляются сообщения о событии (параметр RemoteMonitoringUrl). Если параметр не определен, события будут накапливаться в очереди агента мониторинга.
В настройках можно задать параметр RemoteMonitoringTimeoutSec – таймаут на выполнение операции отправки запроса системе мониторинга. Под операцией отправки запроса понимается подключение к системе мониторинга, получение подтверждения о подключении, отправка запроса, получение ответа. По умолчанию, таймаут равен 10 секундам на каждую операцию. На каждое отправленное сообщение о событии агент мониторинга ожидает подтверждение и отправляет подтверждение при получении события. Возможны следующие варианты:
Отправляется запрос о событии системе мониторинга. На запрос ожидается ответ об успешном приеме по протоколу, поддерживаемому системой мониторинга.
Получено сообщение о событии от ПроАТМ. Посылается подтверждение о получении события в ПроАТМ.
От системы мониторинга получены команды для ПроАТМ. Команды пересылаются в ПроАТМ. Результаты их выполнения пересылаются системе мониторинга или, при возникновении проблем, в подтверждении возвращаются код и описание возникшей проблемы.
Подтверждение имеет следующий вид:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring>
<result code='0' status='ok' description='Сообщение доставлено'/>
</monitoring>
Атрибуты тега <result> определяют результат передачи сообщения:
code (обязательный атрибут) – результат обработки: начение «0» означает, что сообщение было обработано успешно. В противном случае, произошла ошибка
status – определяет тип подтверждения. Может быть «ok», «warning», «error»;
source – определяет источник сообщения (ПроАТМ или агент мониторинга);
description – более подробно описывает проблему.
Фильтрация событий по определенным правилам¶
Перед отправкой события в систему мониторинга агент мониторинга проверяет его на соответствие правилам. Описание правил содержится в файле rules.xml в папке агента мониторинга. Для выбора другого файла воспользуйтесь настройкой EventRulesFileName. Правила описываются в формате xml и выглядят следующим образом:
<?xml version='1.0' encoding='windows-1251'?>
<rules>
<rule name='rule1'>
<event_attrs a1='v1' a2='v1' a4='v4'/>
<event_params delivery='never' period='never'/>
</rule>
<rule name='rule2'>
<event_attrs a1='v1' a2='v2'/>
<event_params delivery='guaranteed' period='immediately'/>
</rule>
<rule name='rule3'>
<event_attrs a1='v1' a2='v2' a3='_EXIST'/>
<event_params period='count_5,timeout_60'/>
</rule>
</rules>
Все правила находятся внутри тега <rules>. Каждое правило описывается тегом <rule> и имеет один необязательный атрибут name (имя правила). Это имя необходимо для отслеживания, какое правило было применено к тому или иному событию. Внутри тега <rule> находится тег <event_attrs>. Этот тег содержит атрибуты, описывающие событие (но не обязательно только их) так, чтобы к нему было применено данное правило. Значения атрибутов в правиле и событии должны совпадать. Также, для атрибута тега <event_attrs> можно задать специальное значение «_EXIST» (необходимо указать значение, точно совпадающее с указанным, – первый символ «подчеркивание», заглавные буквы). Это значение определяет, что для совпадения достаточно, чтобы событие содержало такой же атрибут без сравнения их значений. Если тег <event_attrs> содержит атрибут, отсутствующий в событии, правило считается не подходящим.
Также внутри тега <rule> должен находиться тег <event_params/>, который определяет условия доставки события. Он имеет следующик атрибуты:
delivery – признак гарантированной доставки. Возможные значения:
never– не доставлять никогда,guaranteed(по умолчанию) – доставлять гарантированно.period – период доставки. Возможные значения:
never– не доставлять никогда,immediately(по умолчанию) – доставлять немедленно,count_<N>– отложить доставку до накопления в очереди <N> событий,timeout_<S>– отложить доставку минимум на <S> секунд. Событие по такому правилу не будет доставлено сразу по истечении таймаута, а будет дожидаться следующего сеанса доставки событий в систему мониторинга. Значение атрибута period может содержать оба значения:count_<N>иtimeout_<S>, разделенные запятой, пробелом и т.д.
Пример: агент мониторинга получил из очереди событие на отправку следующего вида:
<event severity='normal' device='12' a1='v1' a2='v2' a3='v3'/>
Применяя правила по порядку, агент мониторинга обнаружит, что:
Правило rule1 не подходит (значения атрибутов a2 не совпадают и в правиле описан атрибут a4, отсутствующий в событии);
Правило rule2 подходит (все атрибуты правила присутствуют в событии и их значения совпадают);
Правило rule3 подходит (все атрибуты правила присутствуют в событии и их значения совпадают).
Из трех правил два подходят, но правило rule3 подходит больше (совпадают три атрибута против двух в правиле rule2), поэтому оно и будет выбрано. Согласно этому правилу событие не нужно отправлять немедленно, а следует подождать, пока в очереди не накопится 5 событий или 1 минуту.
События, отправляемые ПроАТМ в систему мониторинга¶
ПроАТМ в процессе работы генерирует события, которые могут быть отправлены в систему мониторинга. Формат сообщений описывается для каждой системы мониторинга отдельно. Поля сообщений генерируется ПроАТМ следующим образом: Из ветки реестра [HKEY_LOCAL_MACHINE\SOFTWARE\FS365\Monitoring\<система мониторинга>\<событие>] (см.) читаются все параметры. Наименование параметра = наименование поля, значение параметра = значение поля. В значениях полей могут быть как фиксированные строковые значения, так и переменные в виде макросов (#ИМЯ_МАКРОСА#). Макросы могут быть общими для всех сообщений или специфическими для конкретного сообщения.
Пересылка команд от системы мониторинга в ПроАТМ¶
С помощью агента мониторинга передаются команды в ПроАТМ. Команда может выглядеть следующим образом:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring atm=”00000040”>
<command id='1' name='GO_OUT_OF_SERVICE'/>
</monitoring>
Тег <monitoring> имеет атрибут atm – числовой идентификатор терминала, которому предназначена команда. Если значение атрибута atm не совпадет с идентификатором терминала, то команда выполнена не будет, о чем будет сообщено в ответном сообщении. Т.к. идентификатор – число, то необязательно писать его так же, как на терминале. Значение 40 и 00000040 равнозначны.
Описание команды находится в теге <command>, который содержит несколько атрибутов:
id – идентификатор команды. Необязательный атрибут. Предназначен для того, чтобы следить за ходом команды, отличать одну команду от другой, вести лог и т.п.
name – название команды, которую должен выполнить ПроАТМ. Реализованы команды: REBOOT (перезагрузка терминала), GO_IN_SERVICE (перевести терминал в состояние обслуживания клиента), GO_OUT_OF_SERVICE (перевести терминал в состояние «не обслуживает»), GET_STATUS (получить статус устройства), RESET (сбросить состояние устройства).
Внутри тега <command> могут находится теги <param> описывающие параметры команды, если они требуются. Тег <param> имеет следующие атрибуты:
name – название параметра.
value – значение параметра.
Оба параметра являются опциональными, как и сам тег <param>.
Для каждой команды определяется свой набор параметров. В ответ на полученные команды ПроАТМ возвращает результат их выполнения:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring atm=”00000040”>
<result code='0' status='ok' source='ProATM' description='Команды обработаны'>
<command_result code='0' status='ok' source='ProATM' description='Терминал будет переведен в состояние не обслуживает' id='1'/>
</monitoring>
В ответном сообщении тег <monitoring> имеет такой же вид, как и в полученном сообщении. Тег <result> определяет результат передачи и обработки сообщения, а теги <command_result> – результаты выполнения команд. Сколько в сообщении команд, столько тегов <command_result> и будет содержать ответ. Атрибуты тега <command_result> определяют результат выполнения команды.
code = 0 (обязательный атрибут) – означает, что команда была выполнена успешно. В противном случае, произошла ошибка.
status – определяет тип подтверждения. Может быть
okилиerror.source – определяет источник сообщения. ПроАТМ или Агент мониторинга.
description – описание результатов выполненной команды.
Внутри тега <command_result> может содержаться набор тегов характерный для конкретной команды.
Команды подразделяются на синхронные и асинхронные. Синхронными являются команды, которые можно выполнить за короткий промежуток времени. При получении синхронной команды ПроАТМ выполняет ее, после чего возвращает результат. При получении асинхронной команды ПроАТМ запускает ее выполнение, и, не ожидая окончания, возвращает результат. О ходе выполнения асинхронной команды можно узнать из логов и событий мониторинга. Такое разделение необходимо для того, чтобы выполнение команд не блокировало другие процессы ПроАТМ и работу хоста, приславшего команду.
Команды системы мониторинга¶
REBOOT¶
Перезагрузить терминал.
Вид команды:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring atm=”00000001”>
<command id='1' name=' REBOOT'/>
</monitoring>
Если терминал находится в состоянии ожидания клиента или «не обслуживает», то команда будет выполнена синхронно, в противном случае – асинхронно (ПроАТМ будет ждать перехода в нужное состояние). Не содержит дополнительных параметров. Ответное сообщение содержит стандартный результат выполнения команды: удалось ли запустить перезагрузку терминала.
GO_IN_SERVICE¶
Перевести терминал в состояние обслуживания клиента.
Вид команды:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring>
<command id='1' name='GO_IN_SERVICE'/>
</monitoring>
Команда асинхронная. Не содержит дополнительных параметров. Ответное сообщение содержит стандартный результат выполнения команды: удалось или нет запустить перевод терминала в нужное состояние.
GO_OUT_OF_SERVICE¶
Перевести терминал в состояние «не обслуживает».
Вид команды:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring>
<command id='1' name='GO_OUT_OF_SERVICE'/>
</monitoring>
Команда асинхронная. Не содержит дополнительных параметров. Ответное сообщение содержит стандартный результат выполнения команды: удалось или нет запустить перевод терминала в нужное состояние.
GET_STATUS¶
Получить статус устройства.
Вид команды:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring>
<command id='1' name=' GET_STATUS '>
<param value=”CIM”/>
</command>
</monitoring>
Команда синхронная. Команда позволяет запросить состояние какого-либо XFS-устройства на терминале по имени этого устройства либо версии программ, входящих в ПроАТМ и установленных, на терминале. Она должна содержать хотя бы один параметр – название устройства, состояние которого необходимо получить (возможные значения: SIU, PIN, PRR, PRJ, CDM, IDC, CIM) или ProATM для получения информации о версиях программ, входящих в состав ПроАТМ (версия ПроАТМ, версия XFS-драйверов и версия кастомизации). Ответное сообщение содержит стандартный результат выполнения команды: удалось ли получить состояние устройства. Тег <command_result> будет содержать дополнительный атрибут param – имя устройства, состояние которого нужно было получить. Внутри тега <command_result> будет находиться тег <status>, описывающий состояние устройства.
<?xml version='1.0' encoding='UTF-8'?>
<monitoring atm='0000001'>
<result code='0' status='ok' source='ProATM' description='Команды обработаны'/>
<command_result code='0' status='ok' source='ProATM' description='Статус устройства' id='1' param='CIM'>
<status device_name="cim">
<component name="device" code="0" description="Устройство готово к работе" />
<component name="safedoor" code="1" description="Сейф купюроприемника не имеет двери" />
<component name="acceptor" code="0" description="Приемник банкнот купюроприемника в рабочем состоянии" />
<component name="stacker" code="0" description="Стекер купюроприемника пуст" />
<component name="stackeritems" code="4" description="Банкноты отсутствуют в стекере купюроприемника или отсутствует сам стекер" />
<component name="banknotereader" code="0" description="Блок идентификации банкнот купюроприемника готов к работе" />
</status>
</command_result>
<command_result code='0' status='ok' source='ProATM' description='Статус устройства' id='2' param='proatm'>
<status device_name="proatm">
<component name="proatm_version" code="0" description="5.5.0.16499" />
<component name="xfs_version" code="0" description="5.3.0.14477" />
<component name="customization_version" code="1" description="unknown" />
</status>
</command_result>
</monitoring>
Состояние устройства описывается набором тегов <component>. Каждый тег <component> описывает состояние узла устройства. Каждый тег <component> имеет три атрибута:
name – название узла устройства. В ответе на команду получения статуса ПроАТМ «proatm» – название тега(proatm_version, xfs_version, customization_version).
code – XFS-код, описывающий состояние узла. В ответе на команду получения статуса ПроАТМ «proatm» – 0 (удалось получить версию), 1 (не удалось).
description – «человеческое» описание состояния узла. Собственно версия или «unknown» если версию определить не удалось.
RESET¶
Сбросить состояние устройства.
Вид команды:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring>
<command id='1' name='RESET'>
<param value=”CIM”/>
</command>
</monitoring>
Если терминал находится в состоянии ожидания клиента или «не обслуживает», то команда будет выполнена синхронно, в противном случае, – асинхронно: ПроАТМ будет ждать перехода в нужное состояние. Команда должна содержать хотя бы один параметр – название устройства, состояние которого необходимо сбросить. Ответное сообщение содержит стандартный результат выполнения команды: удалось ли сбросить состояние устройства. Тег <command_result> будет содержать дополнительный атрибут param – имя устройства, состояние которого необходимо сбросить.
<monitoring atm='00000001'>
<result code='0' status='ok' source='ProATM' description='Команды обработаны'/>
<command_result code='0' status='ok' source='ProATM' description='Состояние устройства было сброшено' id='1' param='CIM'/>
</monitoring>
GET_CASH_UNIT_INFO¶
Получить информацию о состоянии кассет.
Вид команды:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring>
<command id='1' name='GET_CASH_UNIT_INFO'>
<param value=”CIM”/>
</command>
</monitoring>
Если терминал находится в состоянии ожидания клиента или «не обслуживает», то команда будет выполнена синхронно, в противном случае – асинхронно (ПроАТМ будет ждать перехода в нужное состояние). Команда должна содержать хотя бы один параметр – название устройства. Возможные значения параметров: CIM, CDM. Допускается указание двух параметров. Ответное сообщение содержит стандартный результат выполнения команды WFS_INF_CIM_CASH_UNIT_INFO (для значения CIM) или WFS_INF_CDM_CASH_UNIT_INFO (для значения CDM). Тег <command_result> будет содержать дополнительный атрибут param – имя устройства, для которого запрашивалось состояние кассет.
<?xml version='1.0' encoding='UTF-8'?>
<monitoring atm='00000040'>
<result code='0' status='ok' source='ProATM' description='Команды обработаны'/>
<command_result code='0' status='ok' source='ProATM' description='CashUnitInfo' id='1' param='CIM'>
<CimCashUnitInfoList>
<CimCashUnitInfo>
<usNumber>1</usNumber>
<fwType>WFS_CIM_TYPECASHIN</fwType>
<fwItemType>WFS_CIM_CITYPALL</fwItemType>
<strUnitID>FLBV </strUnitID>
<strCurrencyID> </strCurrencyID>
<ulValues>0</ulValues>
<ulCashInCount>2</ulCashInCount>
<ulCount>2</ulCount>
<ulMaximum>1000</ulMaximum>
<usStatus>WFS_CIM_STATCUMANIP</usStatus>
<bAppLock>FALSE</bAppLock>
<NoteNumberList>
<Note>
<usNoteID>1</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>2</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>3</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>4</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>5</usNoteID>
<ulCount>2</ulCount>
</Note>
<Note>
<usNoteID>6</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>7</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>8</usNoteID>
<ulCount>0</ulCount
</Note>
<Note>
<usNoteID>9</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>10</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>17</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>18</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>19</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>20</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>21</usNoteID>
<ulCount>0</ulCount>
</Note>
<Note>
<usNoteID>22</usNoteID>
<ulCount>0</ulCount>
</Note>
</NoteNumberList>
<physicalCUList>
<PhysicalCU>
<strPhysicalPositionName>CASHIN1</strPhysicalPositionName>
<strUnitID>FLBV </strUnitID>
<ulCashInCount>2</ulCashInCount>
<ulCount>2</ulCount>
<ulMaximum>1000</ulMaximum>
<usPStatus>WFS_CIM_STATCUMANIP</usPStatus>
<bHardwareSensors>FALSE</bHardwareSensors>
<ulInitialCount>0</ulInitialCount>
<ulDispensedCount>0</ulDispensedCount>
<ulPresentedCount>0</ulPresentedCount>
<ulRetractedCount>0</ulRetractedCount>
<ulRejectCount>0</ulRejectCount>
</PhysicalCU>
</physicalCUList>
<usCDMType>0</usCDMType>
<strCashUnitName>UNKNOWN</strCashUnitName>
<ulInitialCount>0</ulInitialCount>
<ulDispensedCount>0</ulDispensedCount>
<ulPresentedCount>0</ulPresentedCount>
<ulRetractedCount>0</ulRetractedCount>
<ulRejectCount>0</ulRejectCount>
<ulMinimum>0</ulMinimum>
</CimCashUnitInfo>
</CimCashUnitInfoList>
</command_result>
<command_result code='0' status='ok' source='ProATM' description='CashUnitInfo' id='1' param='CDM'>
<CdmCashUnitInfoList>
<CdmCashUnitInfo>
<usNumber>1</usNumber>
<usType>WFS_CDM_TYPERETRACTCASSETTE</usType>
<strCashUnitName>RETRACTBOX</strCashUnitName>
<strUnitID>___RT</strUnitID>
<strCurrencyID> </strCurrencyID>
<ulValues>0</ulValues>
<ulInitialCount>0</ulInitialCount>
<ulCount>0</ulCount>
<ulRejectCount>0</ulRejectCount>
<ulMinimum>0</ulMinimum>
<ulMaximum>1</ulMaximum>
<bAppLock>FALSE</bAppLock>
<usStatus>WFS_CDM_STATCUOK</usStatus>
<physicalCUList>
<PhysicalCU>
<strPhysicalPositionName>REJECT</strPhysicalPositionName>
<strUnitID>_RTRT</strUnitID>
<ulInitialCount>0</ulInitialCount>
<ulCount>0</ulCount>
<ulRejectCount>0</ulRejectCount>
<ulMaximum>2</ulMaximum>
<usPStatus>WFS_CDM_STATCUOK</usPStatus>
<bHardwareSensor>FALSE</bHardwareSensor>
<ulDispensedCount>0</ulDispensedCount>
<ulPresentedCount>0</ulPresentedCount>
<ulRetractedCount>0</ulRetractedCount>
</PhysicalCU>
</physicalCUList>
<ulDispensedCount>0</ulDispensedCount>
<ulPresentedCount>0</ulPresentedCount>
<ulRetractedCount>0</ulRetractedCount>
</CdmCashUnitInfo>
<CdmCashUnitInfo>
<usNumber>2</usNumber>
<usType>WFS_CDM_TYPEREJECTCASSETTE</usType>
<strCashUnitName>REJECTBOX</strCashUnitName>
<strUnitID>___RJ</strUnitID>
<strCurrencyID> </strCurrencyID>
<ulValues>0</ulValues>
<ulInitialCount>0</ulInitialCount>
<ulCount>5</ulCount>
<ulRejectCount>0</ulRejectCount>
<ulMinimum>0</ulMinimum>
<ulMaximum>100</ulMaximum>
<bAppLock>FALSE</bAppLock>
<usStatus>WFS_CDM_STATCUOK</usStatus>
<physicalCUList>
<PhysicalCU>
<strPhysicalPositionName>REJECT</strPhysicalPositionName>
<strUnitID>_RTRJ</strUnitID>
<ulInitialCount>0</ulInitialCount>
<ulCount>5</ulCount>
<ulRejectCount>0</ulRejectCount>
<ulMaximum>100</ulMaximum>
<usPStatus>WFS_CDM_STATCUOK</usPStatus>
<bHardwareSensor>FALSE</bHardwareSensor>
<ulDispensedCount>0</ulDispensedCount>
<ulPresentedCount>0</ulPresentedCount>
<ulRetractedCount>0</ulRetractedCount>
</PhysicalCU>
<PhysicalCU>
<strPhysicalPositionName>REJECT</strPhysicalPositionName>
<strUnitID>_RJRJ</strUnitID>
<ulInitialCount>0</ulInitialCount>
<ulCount>0</ulCount>
<ulRejectCount>0</ulRejectCount>
<ulMaximum>100</ulMaximum>
<usPStatus>WFS_CDM_STATCUOK</usPStatus>
<bHardwareSensor>FALSE</bHardwareSensor>
<ulDispensedCount>0</ulDispensedCount>
<ulPresentedCount>0</ulPresentedCount>
<ulRetractedCount>0</ulRetractedCount>
</PhysicalCU> </physicalCUList>
<ulDispensedCount>0</ulDispensedCount>
<ulPresentedCount>0</ulPresentedCount>
<ulRetractedCount>0</ulRetractedCount>
</CdmCashUnitInfo>
<CdmCashUnitInfo>
<usNumber>3</usNumber>
<usType>WFS_CDM_TYPEBILLCASSETTE</usType>
<strCashUnitName>CASHOUT1</strCashUnitName>
<strUnitID>CASH4</strUnitID>
<strCurrencyID>RUB</strCurrencyID>
<ulValues>50</ulValues>
<ulInitialCount>2000</ulInitialCount>
<ulCount>1999</ulCount>
<ulRejectCount>1</ulRejectCount>
<ulMinimum>50</ulMinimum>
<ulMaximum>0</ulMaximum>
<bAppLock>FALSE</bAppLock>
<usStatus>WFS_CDM_STATCUOK</usStatus>
<physicalCUList>
<PhysicalCU>
<strPhysicalPositionName>CASHOUT4</strPhysicalPositionName>
<strUnitID>44444</strUnitID>
<ulInitialCount>2000</ulInitialCount>
<ulCount>1999</ulCount>
<ulRejectCount>1</ulRejectCount>
<ulMaximum>0</ulMaximum>
<usPStatus>WFS_CDM_STATCUOK</usPStatus>
<bHardwareSensor>TRUE</bHardwareSensor>
<ulDispensedCount>0</ulDispensedCount>
<ulPresentedCount>0</ulPresentedCount>
<ulRetractedCount>0</ulRetractedCount>
</PhysicalCU>
</physicalCUList>
<ulDispensedCount>0</ulDispensedCount>
<ulPresentedCount>0</ulPresentedCount>
<ulRetractedCount>0</ulRetractedCount>
</CdmCashUnitInfo>…
</CdmCashUnitInfoList>
</command_result>
</monitoring>
GET_CIM_NOTETYPES¶
Получить информацию о типах принимаемых банкнот.
Вид команды:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring>
<command id='1' name='GET_CIM_NOTETYPES'>
<param value=”CIM.CashCode2”/>
</command>
</monitoring>
Вид ответа:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring atm='387'>
<result code='0' status='ok' source='ProATM' description='Команды обработаны'/>
<command_result code='0' status='ok' source='ProATM' description='CimNoteTypes' id='1' param='CIM.CashCode2'><CimNoteTypes device_name="CIM.CashCode2">
<NoteType id="3">
<Values>10</Values>
<Currency>RUB</Currency>
</NoteType>
<NoteType id="4">
<Values>50</Values>
<Currency>RUB</Currency>
</NoteType>
<NoteType id="5">
<Values>100</Values>
<Currency>RUB</Currency>
</NoteType>
<NoteType id="6">
<Values>500</Values>
<Currency>RUB</Currency>
</NoteType>
<NoteType id="7">
<Values>1000</Values>
<Currency>RUB</Currency>
</NoteType>
<NoteType id="8">
<Values>5000</Values>
<Currency>RUB</Currency>
</NoteType>
</CimNoteTypes>
</command_result>
</monitoring>
GET_DEVICE_INFO¶
Получить сведения о версиях ПО и оборудовании УС.
Посредством команды сервер может запросить у устройства самообслуживания информацию о версиях терминального ПО, ПО уровня XFS, кастомизации, а также hardware-информацию об отдельных узлах УС. Данная команда подразумевает два возможных варианта использования: получение полной информации об УС или либо информации об отдельном компоненте/устройстве.
Получение информации об отдельном(-ых) компоненте(-ах) (с параметрами)¶
Вид команды:
<?xml version="1.0" encoding="UTF-8"?>
<monitoring atm="%atm id%">
<command id="%id команды%" name="GET_DEVICE_INFO">
<param value="%id компонента/устройства%" />
…
</command>
</monitoring>
%atm id% – идентификатор терминала;
%id компонента/устройства% – идентификатор компонента/устройства. Элемент command может содержать несколько вложенных элементов param.
Допустимые значения для идентификатора компонента/устройства:
software– используется для получения версий ПО;%класс устройства% [.%наименование сервиса% (опц.)] – используется для получения сведений о модели, прошивках, серийных номерах для конкретного CEN/XFS класса устройств. Имя сервиса используется в случае работы с несколькими устройствами одного класса, например CIM.CashCode1 и CIM.CashCode2, если УС оборудовано двумя купюроприемниками и логические имена XFS-сервисов купюроприемников CashCode1 и CashCode2.
На данный момент в ПроАТМ 5.7.x. реализована поддержка CIM (модуль приема наличных), PIN (pin-клавиатура) для значения %класс устройства%. Перечень устройств, для которых реализовано получение сведений о модели, серийных номерах и версий прошивок:
Модуль приема наличных ( param=“CIM“ ):
CashCode SM/FL/FLS/GX;
MEI Cashflow;
MEI Advance;
JCM - ID003;
Hitachi HCM HT-3842.
Клавиатура EPP ( param=“PIN“ ):
ZT59x F17,F20;
ZT59x H12-H15, H20, H21;
ZT59x H13,H14;
Cryptera INT1217/1218 4210;
Cryptera INT1217/1218 541x.
Вид ответа:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring atm='%atm id%'>
<result code='0' status='ok' source='ProATM' description='Команды обработаны'/>
<command_result code='%код выполнения команды%' status='%статус выполнения команды%' source='ProATM' description='%описание команды%' id='%id команды%' param='%id компонента/устройства% команды GET_DEVICE_INFO'>
<!-- Для param='software', если была получена хотя бы одна из версий ПО, элемент command_result содержит вложенный элемент software_info -->
<software_info>
<!-- software_info содержит один или более элементов version -->
<version product_id="%id ПО%">
<value>%версия ПО%</value>
</version>
…
</software_info>
<!-- либо для param='класс устройства', если была получена информация о SN/FW запрашиваемого устройства, элемент command_result содержит вложенный элемент hardware_info -->
<hardware_info>
<device class="%класс устройства%" service_name="%наименование сервиса%" model="%наименование модели%" sp_version="%версия сервис-провайдера(XFS)% ">
<! Элемент device может содержать вложенные элементы serial_no/ firmware_version содержащие информацию о SN/FW при условии получения соответствующих данных от XFS-драйвера устройства -->
<serial_no type="%тип серийного номера%">
<value>%значение серийного номера%</value>
</serial_no>
<firmware_version type="%тип прошивки%">
<value>%версия прошивки%</value>
</firmware_version>
</device>
</hardware_info>
</command_result>
</monitoring>
%код выполнения команды% =
0– команда выполнена успешно (информация о версиях ПО/информация об устройстве);%код выполнения команды% =
145– не удалось получить информацию о версиях ПО;%код выполнения команды% =
151– неизвестное устройство (УС не оборудовано устройством данного класса);%код выполнения команды% =
121– информация об устройстве недоступна(получение информации для данного типа устройств не реализовано/не удалось получить информацию от XFS-драйвера устройства);%статус выполнения команды% –
okпри нулевом значения кода выполнения команды, в противном случае –error;%id ПО% – proatm/xfs/customization;
%версия ПО% – версия приложения (если получение версии недоступно, то значение
unknown);%наименование сервиса% – логическое имя XFS-сервиса устройства (опциональный атрибут);
%версия сервис-провайдера(XFS)% – номер версии сервис-провайдера (опциональный атрибут).
Получение полной информации об УС (без параметров)¶
Вид команды:
<?xml version="1.0" encoding="UTF-8"?>
<monitoring atm="%atm id%">
<command id="%id команды%" name="GET_DEVICE_INFO" />
</monitoring>
%atm id% – идентификатор терминала;
%id команды% – идентификатор команды.
Вид ответа:
<?xml version='1.0' encoding='UTF-8'?>
<monitoring atm='%atm id%'>
<result code='0' status='ok' source='ProATM' description='Команды обработаны'/>
<command_result code='%код выполнения команды%' status='%статус выполнения команды%' source='ProATM' description='%описание команды%' id='%id команды%' param=''>
<software_info>
<!-- Секция software_info содержит информацию о версиях ПО(один или более вложенных элементов version), формат аналогичен описанию, приведенному для варианта использования 1 -->
…
</software_info>
<hardware_info>
<!-- Секция hardware_info содержит информацию об оборудовании УС(один или более вложенных элементов device), формат аналогичен описанию, приведенному для варианта использования 1-->
…
</hardware_info>
</command_result>
</monitoring>
%код выполнения команды% =
0– команда выполнена успешно(информация о версиях ПО/информация об устройстве);%код выполнения команды% =
111– информация о версиях ПО и оборудовании УС недоступна.
События от ПроАТМ к системе мониторинга¶
Отправка информации о событиях ПроАТМ к системе мониторинга осуществляется с учетом особенностей транспортного уровня каждой системы мониторинга. Общим для всех систем мониторинга является набор генерируемых событий (источником событий является ПроАТМ) и механизм формирования сообщения для системы мониторинга.
Взаимодействие с системой мониторинга «УРАЛСИБ»¶
Транспортом для взаимодействия агента мониторинга и системы мониторинга «УРАЛСИБ» является сетевой протокол TCP/IP, посредством которого передаются сообщения. Сообщение состоит из заголовка и тела. Для доставки событий от Агента мониторинга в систему мониторинга используется протокол HTTP. Параметры события передаются в URL.
Рисунок 69. Схема взаимодействия с системой мониторинга «УРАЛСИБ»¶
В ответ на каждый HTTP-запрос агент мониторинга ожидает подтверждение. Событие считается доставленным, если ответ на HTTP-запрос имеет статус от 200 до 300 включительно. Пока подтверждение не будет получено, сообщение не считается доставленным, и будет посылаться вновь и вновь. Для отправки сообщения в систему мониторинга «УРАЛСИБ» необходимо, чтобы заголовок пакета, содержащий сообщение о событии, содержал 4 байта со значением «URAL». Пример HTTP запроса о событии:
<event severity="normal" device="12" message="Запущено терминальное ПО ProATM" agent="ProATM" atm="00000040" eventtime="1290606064"/>
выглядит следующим образом:
http://RemoteMonitoringUrl?severity=normal&device=12&message=Запущено терминальное ПО ProATM&agent=ProATM&atm=00000040&eventtime=1290606064
Настройка взаимодействия с ПроКСИМА¶
Для параметра MSG_SIGNATURE задайте значение
JSON.В параметре RemoteCommandsUrl укажите URL сервера мониторинга ПроКСИМА. Если значение данного параметра не указано, то команды от ПроКСИМА обрабатываться не будут.
Макросы в сообщениях от ПроАТМ к системе мониторинга¶
Макрос |
Описание |
|---|---|
#EVENT_TIME# |
время возникновения события в секундах. Трансформируется в общепринятый формат времени агентом мониторинга |
#EVENT_TIME_FORMATTED# |
время возникновения события в формате «ГГГГ.ММ.ДД ЧЧ:ММ:СС» |
#TERMINAL_ID# |
идентификатор терминала в процессинге ISO-8583 (8 символов) |
#PROSET_MACHINE_NO# |
идентификатор терминала в системе ПроСЭТ (6 символов) |
#PROATM_VERSION# |
версия управляющего ПО ПроАТМ в формате «N.N.N.nnnnn» |
#TERMINAL_ID# |
номер терминала в системе |
Текст сообщения |
Дополнительные макросы |
|---|---|
«Перезагрузка уже выполняется. Команда не будет выполнена» |
#COMMAND_ID# – идентификатор команды, которую отправил агент мониторинга для выполнения |
«Произошла ошибка во время ожидания перехода терминала в состояние подходящее для перезагрузки. Принудительная перезагрузка терминала» |
Те же |
«Истекло время ожидания перехода Ogre в нужное состояние. Принудительная перезагрузка терминала» |
Те же |
«Терминал перезагружается» |
Те же |
«Не удалось запустить перезагрузку терминала» |
Те же |
«Неизвестное устройство» 1 |
#COMMAND_ID# – идентификатор команды, которую отправил агент мониторинга для выполнения #DEVICE# – идентификатор узла, сгенерировавшего событие (число или трехсимвольное имя устройства согласно спецификации CEN/XFS):
|
«Устройство не поддерживает команду Reset» 1 |
Те же |
«При выполнении команды Reset произошла ошибка» 1 |
Те же |
«Состояние устройства было сброшено» 1 |
Те же |
«Карта была захвачена» |
– |
#MESSAGE# |
|
#MESSAGE# (состояние узлов устройства) 2 |
#MESSAGE# – текст отчёта о состоянии. Каждый узел устройства генерирует своё сообщение. #SEVERITY# – уровень критичности сообщения:
#DEVICE# – идентификатор узла, сгенерировавшего событие (число или трехсимвольное имя устройства согласно спецификации CEN/XFS):
#DEVICE_NAME# – логическое имя устройства. #COMPONENT# – наименование компонента узла, который сгенерировал событие. #STATUS# - идентификатор ошибки (если есть). #REPORT_TIME# – время генерации отчёта в секундах. #OPER_CYCLE# – номер текущего ОЦ для того узла, который сгенерировал отчёт (подставляется либо для #DEVICE# = 3, либо для #DEVICE# = 7). #OPER_CYCLE_SUM# – сумма принятых денежных средств в рамках текущего ОЦ для того узла, который сгенерировал отчёт (подставляется только для 3 в том случае, если #STATUS# не равен 0). Тег <oper_cycle_sum> может иметь, например, вид «{152488,-2;RUB}:{5800,0;EUR}:..», что означает 1524.88 RUB и 5800 EUR. Вторая цифра после запятой – степень десятки (экспонента). Двоеточие разделяет компоненты разных валют. #INIT_STATE# – флаг: сообщение содержит информацию о начальном состоянии устройства. #OPER_CYCLE_CLOSE_DATE# – время закрытия ОЦ. #OPER_CYCLE_OPEN_DATE# – время открытия ОЦ |
#MESSAGE# (дублирует записи в журнал ПроАТМ) 3 |
#MESSAGE# – текст сообщения, который был записан в журнал. #MESSAGE_PAPER# – текст сообщения, который был записан на бумажный носитель (этот текст может отличаться форматированием от текста, записанного в электронный журнал). #DEST# – идентификатор типа журнала (битовая маска), может содержать несколько значений:
#JOURNAL_MSG_ID# – идентификатор события, записанного в журнал |
#MESSAGE# (готовность и/или результат выполнения команд мониторинга) |
#MESSAGE# – текст, описывающий событие асинхронного задания. #TIMEOUT_DESCRIPTION# – текстовое описание таймаута, который сработал при загрузке документа внешнего web-приложения, исполняемого ПроАТМ. |
#MESSAGE# (сообщает об изменениях состояния авторизатора ISO8583) |
#MESSAGE# – текст сообщения об изменении состояния авторизатора ISO8583. #SEVERITY# – важность сообщения («normal», «warning», «critical»). #ISO8583_AUTH_STATUS# – статус авторизатора. Возможные значения:
|
#MESSAGE# (сообщает информацию об изменении статуса АДМ) |
#MESSAGE# – текст сообщения об изменении статуса АДМ (статус является интегральным). #ADM_STATUS# – статус АДМ (0 – «В работе» и 1 – «Не активна»). #SEVERITY# – важность сообщения:
|
«Не удалось загрузить страницу web-приложения» |
– |
«Восстановлена связь с web-приложением» |
– |
«Ошибка в коде web-приложения: #ERROR_MESSAGE#. URL: #ERROR_URL#. Строка: #ERROR_LINE#» |
#ERROR_MESSAGE# – сообщение об ошибке, произошедшей в процессе работы web-приложения (генерируется компонентом, отображающим web-приложения). #ERROR_URL# – URL, при загрузке или при отображении которого произошла ошибка. #ERROR_LINE# – номер строки, в которой произошла ошибка. |
Пустое сообщение (служит для отслеживания работоспособности ПроАТМ и агента мониторинга) |
– |
«Запущено терминальное ПО ProATM» |
– |
«Остановлено терминальное ПО ProATM» |
#APPLICATION_STATE# – идентификатор состояния ПО ПроАТМ, в котором находилось приложение до момента остановки. Состояния могут быть следующими:
|
«Изменено состояние приложения с #OLD_APPLICATION_STATE_TEXT# на #NEW_APPLICATION_STATE_TEXT#» |
#OLD_APPLICATION_STATE_TEXT# – текстовое описание предыдущего статуса ПО ПроАТМ. #NEW_APPLICATION_STATE_TEXT# – текстовое описание нового статуса ПО ПроАТМ. |
«Сброшен счетчик захваченных карт» |
– |
«Сработал таймаут загрузки документа: #TIMEOUT_DESCRIPTION#» |
#TIMEOUT_DESCRIPTION# – текстовое описание таймаута, который сработал при загрузке документа внешнего web-приложения, исполняемого ПроАТМ. #TIMEOUT_ID# – идентификатор сработавшего таймаута. |