Отправка уведомлений из BPMN (Send Task)
1. Общее описание
Для отправки уведомлений из BPMN-процесса используется элемент Send Task — специальный компонент платформы Citeck.
Несмотря на название, Send Task в Citeck не является стандартным BPMN Send Task: его поведение полностью определяется Citeck-расширениями и реализует отправку уведомлений через микросервис ecos-notifications.
Уведомления отправляются через ecos-notifications.
Не следует отправлять уведомления напрямую из кода микросервиса или из скриптов процесса, минуя ecos-notifications.
Важно
На данный момент из BPMN Send Task поддерживается только тип уведомления EMAIL_NOTIFICATION. Указание любого другого типа вызовет ошибку при сохранении или публикации процесса.
Подробное описание компонента в редакторе BPMN — см. Уведомление.
2. XML-представление Send Task
В XML BPMN-файла Send Task описывается через элемент <bpmn:sendTask> с атрибутами
из пространства имён ecos: (xmlns:ecos="http://www.citeck.ru/ecos/bpmn/1.0").
Пример — уведомление с получателями по ролям:
<bpmn:sendTask
id="Activity_notify_initiator"
name="Уведомление инициатору"
ecos:notificationType="EMAIL_NOTIFICATION"
ecos:notificationTemplate="notifications/template@ecos-contract-approval-notification-template"
ecos:notificationLang="ru"
ecos:notificationTo="["initiator"]"
ecos:notificationToExpression="[]"
ecos:notificationCc="[]"
ecos:notificationCcExpression="[]"
ecos:notificationBcc="[]"
ecos:notificationBccExpression="[]"
ecos:notificationSendCalendarEvent="false"
ecos:notificationAdditionalMeta="{}">
</bpmn:sendTask>
Пример — уведомление с динамическим получателем из переменной процесса:
<bpmn:sendTask
id="Activity_notify_confirmer"
name="Уведомление согласующему"
ecos:notificationType="EMAIL_NOTIFICATION"
ecos:notificationTemplate="notifications/template@ecos-contract-approval-notification-template"
ecos:notificationLang="ru"
ecos:notificationTo="[]"
ecos:notificationToExpression="["${confirmer}"]"
ecos:notificationCc="[]"
ecos:notificationCcExpression="[]"
ecos:notificationBcc="[]"
ecos:notificationBccExpression="[]"
ecos:notificationSendCalendarEvent="false"
ecos:notificationAdditionalMeta="{}">
</bpmn:sendTask>
Пример — уведомление с явным указанием отправителя из ecos-config:
<bpmn:sendTask
id="Activity_notify_with_from"
name="Уведомление инициатору о создании заявки"
ecos:notificationType="EMAIL_NOTIFICATION"
ecos:notificationTemplate="notifications/template@sd-request-create"
ecos:notificationLang="ru"
ecos:notificationFrom="${Config.getNotNull("app/service-desk$send-sd-email-from").asText()}"
ecos:notificationTo="["initiator-role"]"
ecos:notificationToExpression="[]"
ecos:notificationCc="[]"
ecos:notificationCcExpression="[]"
ecos:notificationBcc="[]"
ecos:notificationBccExpression="[]"
ecos:notificationSendCalendarEvent="false"
ecos:notificationAdditionalMeta="{}">
</bpmn:sendTask>
3. Атрибуты Send Task
3.1 Основные атрибуты
Атрибут |
Описание |
|---|---|
|
Тип уведомления. Поддерживается только |
|
Ссылка на шаблон уведомления в формате |
|
Заголовок письма напрямую (без шаблона). Только статический текст, без динамических переменных. |
|
Тело письма напрямую (без шаблона). Только статический текст. |
|
Язык шаблона: |
|
Базовый документ для модели шаблона; поддерживает выражение. При пустом результате используется документ процесса. |
|
|
|
Исходящий адрес отправителя. Можно указать напрямую или через expression. Если не указан — используется значение по умолчанию из настроек ecos-notifications. Поддерживает форматы:
|
|
JSON-объект с дополнительными переменными, доступными в шаблоне.
Значение, начинающееся с |
Итоговый From может быть заменён настройкой ecos-notifications.email.from.fixed. См. настройку SMTP и исходящего адреса.
3.2 Получатели
Получатели задаются JSON-массивами строк. Атрибуты *To, *Cc, *Bcc принимают имена ролей документа; атрибуты *ToExpression, *CcExpression, *BccExpression — выражения (имя пользователя, email, recordRef или ${variable}).
Атрибут |
Описание |
|---|---|
|
JSON-массив ролей получателей. Платформа резолвит email всех пользователей роли.
Пример: |
|
JSON-массив выражений для получателей.
Пример: |
|
JSON-массив ролей для копии (CC). |
|
JSON-массив выражений для копии. |
|
JSON-массив ролей для скрытой копии (BCC). |
|
JSON-массив выражений для скрытой копии. |
Роли и выражения можно комбинировать: статические роли — в *To, динамические — в *ToExpression.
Форматы получателей в *Expression-атрибутах:
ivan.petrov— имя пользователяivan.petrov@company.com— email напрямуюGROUP_company_accountant— группа (раскрывается в подходящие email её участников)emodel/authority-group@company_accountant— recordRef группыemodel/person@ivan— recordRef пользователя${someVariable}— переменная процесса, содержащая любое из вышеперечисленных значений${someService.getEmails()},petya.voks— несколько через запятую
COMBINED формирует одно письмо всем адресатам; PER_ROLE — письмо каждой непустой роли и отдельную группу адресатов из выражений; PER_RECIPIENT — письмо на адрес внутри каждой группы. Один человек в разных ролях может получить несколько сообщений. Для сообщений роли в дополнительной модели доступны recipientRoleId и recipientRoleName.
Отключённые пользователи и пустые email отбрасываются при разрешении пользовательских ссылок. Если адресаты не найдены, уведомление может завершиться статусом RECIPIENTS_NOT_FOUND.
4. Приглашение в календарь (iCal)
Send Task поддерживает отправку iCal-вложения (приглашения в календарь) вместе с письмом.
В текущей реализации зона организатора преобразуется в UTC или фиксированное целочасовое смещение. При сезонном переводе времени и дробных смещениях проверьте результат в используемом клиенте.
<bpmn:sendTask
id="Activity_meeting_invite"
name="Приглашение на встречу по согласованию"
ecos:notificationType="EMAIL_NOTIFICATION"
ecos:notificationTemplate="notifications/template@contract-meeting-notification"
ecos:notificationTo="["initiator"]"
ecos:notificationToExpression="[]"
ecos:notificationCc="[]"
ecos:notificationCcExpression="[]"
ecos:notificationBcc="[]"
ecos:notificationBccExpression="[]"
ecos:notificationLang="ru"
ecos:notificationSendCalendarEvent="true"
ecos:notificationCalendarEventSummary="Встреча по согласованию договора"
ecos:notificationCalendarEventDescription="Необходимо согласовать договор №${docNum}"
ecos:notificationCalendarEventOrganizer="initiator"
ecos:notificationCalendarEventDate="${meetingDate}"
ecos:notificationCalendarEventDuration="PT1H"
ecos:notificationAdditionalMeta="{}">
</bpmn:sendTask>
Атрибут |
Описание |
|---|---|
|
Включить отправку calendar invite: |
|
Название события в календаре. Поддерживает expression: |
|
Описание события. Поддерживает expression: |
|
ID роли организатора, например |
|
Организатор через выражение, например |
|
Дата начала события. Переменная процесса типа |
|
Альтернатива |
|
Длительность события в формате ISO 8601.
Примеры: |
|
Альтернатива |
При включённом приглашении обязательны название, описание, организатор, дата и длительность. Если заданы и основное поле даты/длительности, и альтернативное expression, используется непустое основное поле. Перед публикацией также проверяются тело или шаблон и наличие хотя бы одного из списков To/CC/BCC.
5. Шаблон уведомления
Ссылка на шаблон задаётся в атрибуте ecos:notificationTemplate в формате:
notifications/template@<template-id>
Где <template-id> — идентификатор из метаданных шаблона. Имя каталога может отличаться. Для локального шаблона используйте полный RecordRef с префиксом области, полученный системой.
Подробно о создании шаблонов — см. Шаблоны уведомлений.
6. Переменные шаблона
В шаблоне доступны:
Атрибуты документа — резолвятся по полю
modelметафайла шаблона.Переменные процесса — через
$process.<имя переменной>вmodel.Переменные события (для event sub-process) — через
$process.event.<атрибут>.Контекстные переменные:
Выражение в
modelОписание
$nowТекущая дата и время.
$userТекущий пользователь системы.
$process.webUrlURL процесса.
$process.someVarПеременная процесса
someVar.
$process.event.textАтрибут события, запустившего уведомление. Например, текст комментария.
$process.event._meta.idID события.
$process.event._meta.typeТип события.
$process.currentRunAsUserПользователь, от имени которого выполняется процесс.
$str.<КОНСТАНТА>Строковая константа без вычисления. Например:
$str.APPROVED→"APPROVED".
Пример model для уведомления по событию добавления комментария:
{
"documentDisp": ".disp",
"documentCreated": "_created",
"now": "$now",
"user": "$user",
"commentText": "$process.event.text",
"eventType": "$process.event._meta.type",
"currentRunAsUser": "$process.currentRunAsUser"
}
Для прикрепления вложений из события (например, файлов из комментария):
{
"_attachments": "$process.event.attachments[]._as.ref._content{bytes,meta:?json}"
}
7. Дополнительная модель (additional meta)
Через ecos:notificationAdditionalMeta можно передать дополнительные данные в шаблон,
не извлекая их из документа или процесса через model.
Ключ — имя переменной, доступной в шаблоне.
Значение:
Если начинается с
!str_— символы после префикса передаются как строка-константа.Иначе — строка считается recordRef, и платформа пытается загрузить атрибуты по этому ref.
Пример:
{
"myConstant": "!str_someValue",
"relatedDoc": "emodel/some-type@some-id"
}
В шаблоне ${myConstant} вернёт someValue.