====== Создание сообщений о событиях в системной шине ADVANTA через API ======
===== Шина, события и бизнес-операции =====
Обмен информацией между модулями ADVANTA выполняется через «системную шину данных». В шине публикуются «сообщения» о случившихся в системе [[product:triggers:events|событиях]] и тех изменениях в данных, которые в результате произошли. Сообщения служат сигналами к запуску «триггеров» в модуле «Цифровой помощник».
Сообщения о событиях могут появляться в шине:
* в ответ на действия пользователя в интерфейсе.
* при запуске [[product:triggers:button|настраиваемых команд]].
* по расписанию.
* при вызове API-функций, изменяющих данные в системе.
* при вызове специальной API-функции «InsertTimerEvent», которая планирует возникновение в шине события на указанное время.
Помимо изменения данных, могут происходить и события, отражающие специфику бизнес-процессов предприятия, называемые [[product:triggers:timer#%D1%81%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA_%D0%B1%D0%B8%D0%B7%D0%BD%D0%B5%D1%81_%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D0%B8%D0%B9|бизнес-операциями]].
Бизнес-операции могут быть:
* повторяющиеся регулярные, запускаемые по таймеру;
* однократные, планируемые на определённую дату и время;
Примеры «регулярных» операций: еженедельная отправка отчётов руководителям проектов, планирование регулярных совещаний, периодический расчёт метрик, регулярный обмен данными с внешними системами
«Однократные» операции можно запускать, когда требуется:
* обработать событие, случившееся вне ADVANTA, в другой информационной системе.
* выполнить событие, сроки которого установлены регламентом или SLA относительно ранее произошедшего события.
\\
===== Пример внешнего события =====
Предположим, в системе электронного документооборота предприятия «утверждён» приказ о реализации проекта. Надо оповестить об этом ADVANTA, поместив в её шину данных сообщение о соответствующей бизнес-операции. Это можно сделать помощью API-функции «InsertTimerEvent». В сообщении можно передать необходимую информацию, например, идентификатор утверждённого проекта и присвоенный ему статус. В результате в ADVANTA выполнят свою работу триггеры, привязанные к бизнес-операции утверждения проекта: создадут необходимые объекты, оповестят проектную команду, запланируют установочное совещание и другое. Если в будущем потребуется выполнять в ADVANTA какое-то дополнительные действия по созданию нового проекта, достаточно будет создать новый триггер и подключить к уже существующей бизнес-операции.
\\
\\
===== Пример события с установленными сроками исполнения =====
Некоторые бизнес-процессы предприятия требуют выполнения работ в период времени, ограниченный регламентом или SLA. К примеру, при получении сообщения об утверждении проекта, его руководитель обязан в течение двух рабочих дней подготовить документ «паспорт проекта». Помимо простого уведомления о начале этой задачи будет полезно при наступлении планового срока завершения автоматически проверить, подготовил он документ или нет. Если не подготовил, надо оповестить всех заинтересованных участников проекта, напомнить исполнителю и запланировать следующую проверку, например, ещё через сутки.
В этом случае можно организовать работу следующим образом:
- В справочнике бизнес-операций зарегистрировать две операции: «№1 - Утверждён приказ о проекте», «№2 - Проверка подготовки паспорта проекта».
- После утверждения приказа в СЭД, в шине данных ADVANTA с помощью API «InsertTimerEvent» создаётся сообщение о бизнес-операции «№1 - Утверждён приказ о проекте» с датой исполнения на «текущий момент времени».
- Создать триггер, который исполняется при появлении в шине сообщения о бизнес-операции «Утверждён приказ о проекте». Этот триггер в свою очередь помещает в шине данных, с помощью всё той же API «InsertTimerEvent», сообщение о запуске бизнес-операции «№2 - Проверка подготовки паспорта проекта», но устанавливает дату запуска этого сообщения, в соответствие с регламентом, например, через двое суток от текущей даты.
- Как только наступит дата и время запланированного запуска второго сообщения, оно появится в шине данных и на него смогут отреагировать триггеры, выполняющие проверку, оповещения и прочие необходимые операции. Один из этих триггеров может в свою очередь запланировать повторную проверку, поместив с помощью API «InsertTimerEvent» ещё одно сообщение о запуске бизнес-операции «№2 - Проверка подготовки паспорта проекта» со сроком, например, ещё через сутки. Таких циклов эскалации проблемы можно создать столько, сколько необходимо.
\\
===== Как регистрировать в ADVANTA «бизнес-операции» =====
Перечень «бизнес-операций» и расписание регулярного таймера для их запуска можно найти в панели администратора ADVANTA, на странице «Дополнительные сервисы / Расписание пользовательских бизнес-операций»:
{{ :product:api:picture_1.png?600direct&400 |}}
//Рисунок 1. Запуск справочника пользовательских бизнес-операций//
\\
\\
Чтобы создать новую «бизнес-операцию» перейдите в справочник по ссылке «Справочник бизнес-операций»:
\\
{{ :product:api:picture_2.png?600direct&400 |}}
//Рисунок 2. Переход в справочник бизнес-операций//
\\
\\
На странице справочника «бизнес-операций» нажмите кнопку «Добавить»:
{{ :product:api:picture_3.png?600direct&400 |}}
//Рисунок 3. Добавление бизнес-операции//
\\
\\
Введите название новой бизнес-операции и нажмите «Сохранить»:
{{ :product:api:picture_4.png?600direct&400 |}}
//Рисунок 4. Создание новой бизнес-операции//
\\
\\
Операция появится в справочнике. Ей будет присвоен внутренний код, который потребуется при вызове API «InsertTimerEvent»:
{{ :product:api:picture_5.png?600direct&400 |}}
//Рисунок 5. Новая операция в справочнике бизнес-операций//
\\
\\
Если требуется реализовать регулярную, повторяющуюся бизнес-операцию, настройте запуск по таймеру. Это можно сделать, вернувшись на страницу расписания бизнес-операций (меню «Дополнительные сервисы / Расписание пользовательских бизнес-операций»).
Если требуется однократная операция, которая будет помещаться в шину через API «InsertTimerEvent», расписание не требуется.
Примечание! Следует подчеркнуть, что справочник бизнес-операций служит лишь для присвоения кода. Логика действий при появлении в шине сообщения о выполнении этой бизнес-операции закладывается в триггерах, реагирующих на это сообщение
\\
===== Создание сообщения через API «InsertTimerEvent» =====
Для планирования запуска бизнес-операции на определённый день и время служит API-функция «InsertTimerEvent». Описание этой API можно найти на странице службы «APIScheduledEvents». Относительный путь к странице этой службы на вашем стенде ADVANTA: «/components/services/APIScheduledEvents.asmx».
Формат тела запроса для вызова API «InsertTimerEvent» следующий:
dateTime
guid
int
string
\\
Описание параметров API-функции «InsertTimerEvent»:
^ Параметр ^ Описание ^
|SessionID|ID сессии пользователя, полученное при авторизации|
|CallTime|Дата и время, когда событие должно быть помещено в шину|
|ObjectID|Идентификатор объекта ADVANTA, к которому будет привязано событие|
|OperationCode|Код операции в справочнике пользовательских бизнес-операций ADVANTA|
|Parameters|Дополнительные параметры, в формате JSON, которые будут прикреплены к событию и доступны триггеру для обработки|
\\
===== Пример вызова API «InsertTimerEvent» в Postman =====
Протестировать создание сообщения о выполнении бизнес-операции проще всего через систему Postman. Ниже приведены снимки настроек SOAP-запроса в ней:
{{ :product:api:picture_6.png?600direct&400 |}}
//Рисунок 6. Настройки заголовков запроса (закладка «Headers»)//
\\
\\
{{ :product:api:picture_7.png?600direct&400 |}}
//Рисунок 7. Настройки тела запроса (закладка «Body»)//
\\
===== Пример триггера для обработки события =====
Проверить, что сообщение появилось в шине, можно с помощью триггера. Он должен реагировать на событие «Событие таймера, запланированное по подписке».
Общие настройки триггера:
{{ :product:api:picture_8.png?600direct&400 |}}
//Рисунок 8. Настройки триггера//
\\
Код проверки «условия» запуска триггера:
TriggerConsole.WriteLine($"Проверка условия: ID события - {Context.EventId}, отправлено - {Context.EventSentTime}");
// Реагируем только на бизнес-операцию с кодом №1
if (Event.BusinessOperationCode == 1){
TriggerConsole.WriteLine($"ID cобытия таймера: {Event.BusinessOperationCode}");
} else {
return false; // Если это не операция с кодом №1, не запускаем триггер
}
return true;
\\
Код «скрипта». В данном примере просто выводим в консоль ID и время сообщения, а также параметры, переданные в API-функции «InsertTimerEvent»:
TriggerConsole.WriteLine($"ID события = {Context.EventId}");
TriggerConsole.WriteLine($"Дата и время = {Context.EventSentTime}");
// Код бизнес-операции:
TriggerConsole.WriteLine($"BusinessOperationCode = {Event.BusinessOperationCode}");
// UID объекта, указанный при вызове API InsertTimerEvent:
TriggerConsole.WriteLine($"ObjectId = {Event.ObjectId}");
// Параметры, переданные через API InsertTimerEvent:
TriggerConsole.WriteLine($"Parameters = {Event.Parameters}");
\\
В результате, в логе триггера будут видны переданные через API значения:
{{ :product:api:picture_9.png?600direct&400 |}}
//Рисунок 9. Лог триггера//
\\
===== Просмотр очереди через API «CheckTimerEvent» =====
Увидеть всю очередь сообщений бизнес-операции можно с помощью API-функции «CheckTimerEvent». Информацию о способе её вызова также можно найти на странице службы «APIScheduledEvents» (относительный путь на стенде ADVANTA: «/components/services/APIScheduledEvents.asmx»).
Формат вызова API «CheckTimerEvent»:
string
guid
int
\\
Пример настройки POST-запроса для вызова «CheckTimerEvent» в Postman:
{{ :product:api:picture_10.png?600direct&400 |}}
//Рисунок 10. Настройки заголовков вызова API «CheckTimerEvent»//
\\
{{ :product:api:picture_11.png?600direct&400 |}}
//Рисунок 11. Настройки тела запроса API «CheckTimerEvent»//
\\
Если запрос настроен верно, в Postman появится перечень сообщений указанной бизнес-операции. Пример:
{{ :product:api:picture_12.png?600direct&400 |}}
//Рисунок 12. Пример списка запланированных сообщений//