Отправка уведомлений из BPMN (Send Task)

Общее описание

Для отправки уведомлений из BPMN-процесса используется элемент Send Task — специальный компонент платформы Citeck.

Несмотря на название, Send Task в Citeck не является стандартным BPMN Send Task: его поведение полностью определяется Citeck-расширениями и реализует отправку уведомлений через микросервис ecos-notifications.

Уведомления отправляются через ecos-notifications.

Не следует отправлять уведомления напрямую из кода микросервиса или из скриптов процесса, минуя ecos-notifications.

Важно

На данный момент из BPMN Send Task поддерживается только тип уведомления EMAIL_NOTIFICATION. Указание любого другого типа вызовет ошибку при сохранении или публикации процесса.

Подробное описание компонента в редакторе BPMN — см. Уведомление.

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="[&quot;initiator&quot;]"
  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="[&quot;${confirmer}&quot;]"
  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(&quot;app/service-desk$send-sd-email-from&quot;).asText()}"
  ecos:notificationTo="[&quot;initiator-role&quot;]"
  ecos:notificationToExpression="[]"
  ecos:notificationCc="[]"
  ecos:notificationCcExpression="[]"
  ecos:notificationBcc="[]"
  ecos:notificationBccExpression="[]"
  ecos:notificationSendCalendarEvent="false"
  ecos:notificationAdditionalMeta="{}">
</bpmn:sendTask>

Атрибуты Send Task

Основные атрибуты

Атрибут

Описание

ecos:notificationType

Тип уведомления. Поддерживается только EMAIL_NOTIFICATION.

ecos:notificationTemplate

Ссылка на шаблон уведомления в формате notifications/template@<id>. Взаимоисключающий с ecos:notificationTitle / ecos:notificationBody.

ecos:notificationTitle

Заголовок письма напрямую (без шаблона). Только статический текст, без динамических переменных.

ecos:notificationBody

Тело письма напрямую (без шаблона). Только статический текст.

ecos:notificationLang

Язык шаблона: ru, en и т.д. Если не указан — берётся язык по умолчанию.

ecos:notificationFrom

Исходящий адрес отправителя. Можно указать напрямую или через expression. Если не указан — используется значение по умолчанию из настроек ecos-notifications. Поддерживает форматы:

  • someAddress@mail.com

  • "Some Name" <someAddress@mail.com>

  • ${someExpressionToGetAddress}

  • ${Config.getNotNull("app/your-app$your-key").asText()}

ecos:notificationAdditionalMeta

JSON-объект с дополнительными переменными, доступными в шаблоне. Значение, начинающееся с !str_, передаётся как строка-константа. Пример: {"myKey": "!str_someConstant"} — в шаблоне доступно как ${myKey} со значением someConstant.

Получатели

Получатели задаются JSON-массивами строк. Атрибуты *To, *Cc, *Bcc принимают имена ролей документа; атрибуты *ToExpression, *CcExpression, *BccExpression — выражения (имя пользователя, email, recordRef или ${variable}).

Атрибут

Описание

ecos:notificationTo

JSON-массив ролей получателей. Платформа резолвит email всех пользователей роли. Пример: ["initiator", "lead-tech-role"]

ecos:notificationToExpression

JSON-массив выражений для получателей. Пример: ["${confirmer}", "${assigneesOfCurrentLine}"]

ecos:notificationCc

JSON-массив ролей для копии (CC).

ecos:notificationCcExpression

JSON-массив выражений для копии.

ecos:notificationBcc

JSON-массив ролей для скрытой копии (BCC).

ecos:notificationBccExpression

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 — несколько через запятую

Приглашение в календарь (iCal)

Send Task поддерживает отправку iCal-вложения (приглашения в календарь) вместе с письмом.

<bpmn:sendTask
  id="Activity_meeting_invite"
  name="Приглашение на встречу по согласованию"
  ecos:notificationType="EMAIL_NOTIFICATION"
  ecos:notificationTemplate="notifications/template@contract-meeting-notification"
  ecos:notificationTo="[&quot;initiator&quot;]"
  ecos:notificationToExpression="[]"
  ecos:notificationCc="[]"
  ecos:notificationCcExpression="[]"
  ecos:notificationBcc="[]"
  ecos:notificationBccExpression="[]"
  ecos:notificationLang="ru"
  ecos:notificationSendCalendarEvent="true"
  ecos:notificationCalendarEventSummary="Встреча по согласованию договора"
  ecos:notificationCalendarEventDescription="Необходимо согласовать договор №${docNum}"
  ecos:notificationCalendarEventOrganizer="{&quot;role&quot;:&quot;initiator&quot;}"
  ecos:notificationCalendarEventDate="${meetingDate}"
  ecos:notificationCalendarEventDuration="PT1H"
  ecos:notificationAdditionalMeta="{}">
</bpmn:sendTask>

Атрибут

Описание

ecos:notificationSendCalendarEvent

Включить отправку calendar invite: true / false.

ecos:notificationCalendarEventSummary

Название события в календаре. Поддерживает expression: ${someVar}.

ecos:notificationCalendarEventDescription

Описание события. Поддерживает expression: ${someVar}.

ecos:notificationCalendarEventOrganizer

Организатор. JSON-объект с полем role или expression.

  • По роли: {"role": "initiator"}

  • По выражению: {"expression": "ivan.petrov@company.com"}

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

ecos:notificationCalendarEventDate

Дата начала события. Переменная процесса типа Instant или ISO 8601-строка. Пример: ${meetingDate} или 2025-12-01T10:00:00Z. При создании события используется часовой пояс организатора.

ecos:notificationCalendarEventDateExpression

Альтернатива ecos:notificationCalendarEventDate — expression для вычисления даты. Должно вернуть java.util.Date, String (ISO 8601) или null.

ecos:notificationCalendarEventDuration

Длительность события в формате ISO 8601. Примеры: PT15S, PT1H30M, P14D.

ecos:notificationCalendarEventDurationExpression

Альтернатива ecos:notificationCalendarEventDuration — expression для длительности.

Шаблон уведомления

Ссылка на шаблон задаётся в атрибуте ecos:notificationTemplate в формате:

notifications/template@<template-id>

Где <template-id> — идентификатор шаблона, совпадающий с именем директории артефакта.

Подробно о создании шаблонов — см. Шаблоны уведомлений.

Переменные шаблона

В шаблоне доступны:

  1. Атрибуты документа — резолвятся по полю model метафайла шаблона.

  2. Переменные процесса — через $process.<имя переменной> в model.

  3. Переменные события (для event sub-process) — через $process.event.<атрибут>.

  4. Контекстные переменные:

    Выражение в model

    Описание

    $now

    Текущая дата и время.

    $user

    Текущий пользователь системы.

    $process.webUrl

    URL процесса.

    $process.someVar

    Переменная процесса someVar.

    $process.event.text

    Атрибут события, запустившего уведомление. Например, текст комментария.

    $process.event._meta.id

    ID события.

    $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}"
}

Дополнительная модель (additional meta)

Через ecos:notificationAdditionalMeta можно передать дополнительные данные в шаблон, не извлекая их из документа или процесса через model.

  • Ключ — имя переменной, доступной в шаблоне.

  • Значение:

    • Если начинается с !str_ — символы после префикса передаются как строка-константа.

    • Иначе — строка считается recordRef, и платформа пытается загрузить атрибуты по этому ref.

Пример:

{
  "myConstant": "!str_someValue",
  "relatedDoc":  "emodel/some-type@some-id"
}

В шаблоне ${myConstant} вернёт someValue.