Функционал Lazy approval для задачи

Примечание

Требуется лицензия разработчика либо лицензия с функцией lazy-approval.

Lazy approval – функционал, позволяющий принимать решения из электронной почты, не заходя в Citeck.

Пользователь получает письмо с кликабельными ссылками-вердиктами. При нажатии на ссылку открывается почтовый клиент с предзаполненным ответным письмом. После отправки ответа система автоматически завершает задачу от имени пользователя.

Для работы необходимы совместимые версии ecos-process, ecos-integrations и ecos-notifications, лицензия и настроенный маршрут чтения ответной почты.

1. Принцип работы

  1. Задача создаётся в BPMN-процессе (UserTask с ecos:laEnabled="true").

  2. Система отправляет email исполнителю(ям) задачи с вердиктами-ссылками.

  3. Пользователь нажимает на ссылку вердикта → почтовый клиент открывает предзаполненное ответное письмо с нужной темой и телом.

  4. Пользователь добавляет комментарий между метками [comment]...[comment] и отправляет письмо.

  5. Apache Camel читает почтовый ящик через IMAP и передаёт письмо в LazyApprovalEndpoint (ecos-integrations).

  6. Система парсит тему письма: Prefix-{taskId}-{outcome}-{taskToken}.

  7. Система извлекает комментарий из тела письма.

  8. Задача завершается от имени пользователя с нужным вердиктом и комментарием.

  9. Отправляется отчётное письмо (если настроено).

Формат темы ответного письма:

<Prefix>-<taskId>-<Outcome>-<taskToken>

Где:

  • Prefix — произвольная строка (например CA); текущий парсер не использует её как отдельный тип письма.

  • taskId — UUID идентификатор задачи Camunda. Подставляется автоматически через переменную ${task_id}.

  • Outcome — идентификатор вердикта (id из ecos:outcomes задачи). Должен совпадать с id вердикта задачи.

  • taskToken — UUID токен безопасности, генерируемый при создании задачи. Подставляется через ${task_token}.

Извлечение комментария из тела письма:

Комментарий извлекается из текста между метками [comment] и [comment]:

Вердикт: Согласовать

Поле комментарий обязательно для заполнения

$[comment]
Ваш комментарий здесь
[comment]

${default_comment}

Пользователь сам редактирует текст между маркерами; автоматической замены $[comment] почтовым клиентом не предусмотрено. Парсер извлекает текст между [comment] и [comment], удаляет HTML-теги и обрезает пробелы. Если фрагмент не найден, передаётся пустой комментарий; обязательность комментария определяется отдельными правилами завершения задачи.

Текущий парсер ожидает UUID со строчными a–f, а адрес отправителя извлекает из From вида Имя <user@example.com>. Для MIME-письма читаются непосредственные части text/plain; HTML-only и сложные вложенные MIME-структуры требуют проверки используемого клиента и маршрута.

2. Переменные конфигурации

Для обеспечения работы Lazy approval необходимо заполнить некоторые переменные в конфигурации Citeck:

Ключ конфигурации

Описание

lazy-approval-mail-for-reply

Email-адрес, на который пользователь отправляет ответ с вердиктом. Именно этот адрес настраивается в Camel DSL для чтения входящих писем. Подставляется в шаблон через переменную ${mail_for_answer}.

lazy-approval-default-comment

Комментарий по умолчанию, который вставляется в тело ответного письма. Подставляется в шаблон через переменную ${default_comment}.

3. Настройка UserTask в BPMN

Lazy approval включается на уровне конкретного UserTask через ECOS-атрибуты.

Атрибут

Описание

ecos:laEnabled="true"

Включает Lazy approval для задачи. При создании задачи система автоматически готовит письмо при наличии лицензии, адресатов и шаблона; токен сохраняется локально в задаче при подготовке email. Смена назначения уже существующей задачи сама по себе не гарантирует нового письма.

ecos:laNotificationType="EMAIL_NOTIFICATION"

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

ecos:laNotificationTemplate="notifications/template@<id>"

Ссылка на шаблон уведомления с вердиктами. Статически заданный шаблон.

ecos:laManualNotificationTemplateEnabled="true"

Включает режим динамического шаблона (из переменной процесса). Если true, используется laManualNotificationTemplate вместо laNotificationTemplate.

ecos:laManualNotificationTemplate="${variable}"

Шаблон уведомления из переменной процесса. Может содержать expression ${varName} или прямой ref notifications/template@<id>.

ecos:laNotificationAdditionalMeta

Дополнительные переменные для модели шаблона (JSON-объект).

ecos:laReportEnabled="true"

Включает отправку отчётного письма после обработки ответа пользователя.

ecos:laSuccessReportNotificationTemplate

Шаблон отчётного письма об успешном завершении задачи (переопределяет значение из конфигурации).

ecos:laErrorReportNotificationTemplate

Настройка шаблона ошибочного отчёта задачи. В проверенной версии её применение ограничено дефектом, описанным в разделе отчётов ниже.

Режим ${varName} читает переменную с указанным именем. Это не вычисление произвольного JUEL-выражения, например вызова сервиса.

Пример XML UserTask с Lazy approval:

<bpmn:userTask
  id="approvalTask"
  name="Согласование"
  ecos:laEnabled="true"
  ecos:laNotificationType="EMAIL_NOTIFICATION"
  ecos:laNotificationTemplate="notifications/template@my-approval-la-template"
  ecos:laReportEnabled="true">
</bpmn:userTask>

Пример с шаблоном из переменной процесса:

<bpmn:userTask
  id="approvalTask"
  name="Согласование"
  ecos:laEnabled="true"
  ecos:laNotificationType="EMAIL_NOTIFICATION"
  ecos:laNotificationTemplate="notifications/template@my-approval-la-template"
  ecos:laManualNotificationTemplateEnabled="true"
  ecos:laManualNotificationTemplate="${laTemplateRef}"
  ecos:laReportEnabled="false">
</bpmn:userTask>

4. Настройка обработки ответных сообщений через Camel DSL

В системе обработка ответных сообщений от пользователей обеспечивается за счет чтения почты на основе конфигурации через Camel DSL:

Пример настройки Camel DSL lazy-approval-email-configuration:

---
id: lazy-approval-email-configuration
type: YAML
state: STARTED
content: |-
  - beans:
      - name: "lazyApprovalEndpoint"
        type: ru.citeck.ecos.integrations.domain.lazyapproval.api.LazyApprovalEndpoint
        properties:
          type: "email"
  - route:
      from:
        uri: "imaps://imap.yandex.com?username=testuser1@mail.ru&password=password&delete=false&unseen=true&delay=60000"
        steps:
          - to: "bean:lazyApprovalEndpoint"
../../_images/LA_07.png

Общий принцип работы:

В системе создается бин типа «email», что указывает, что сообщения необходимо обрабатывать, как сообщения, пришедшие из почты. (В дальнейшем количество типов может быть расширено).

Затем устанавливается route, в котором указываются настройки параметров подключения почты и правил обработки сообщений.

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

Параметры route uri:

Параметр

Описание

username

Email-адрес, на котором настроено чтение ответных писем. Должен совпадать со значением конфига lazy-approval-mail-for-reply.

password

Пароль для подключения к почтовому серверу.

delete

Удалять ли письма из ящика после обработки. Рекомендуется false.

unseen

Выбирать непрочитанные письма. Используйте true и проверьте, как маршрут помечает обработанные сообщения. Один этот параметр не гарантирует однократную обработку при любых сбоях.

delay

Частота проверки почтового ящика в миллисекундах. Пример: 60000 = 1 минута.

5. Шаблоны уведомлений для Lazy approval

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

Помимо стандартных переменных из модели шаблона, в шаблонах Lazy approval автоматически доступны следующие переменные:

Переменная

Описание

task_id

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

task_token

UUID токен безопасности, сгенерированный при создании задачи. Защищает от несанкционированного завершения задачи.

mail_for_answer

Email для отправки ответа с вердиктом. Берётся из конфигурации lazy-approval-mail-for-reply.

default_comment

Комментарий по умолчанию. Берётся из конфигурации lazy-approval-default-comment.

../../_images/LA_03.png

5.2 FTL-шаблон с вердиктами

FTL шаблон с использованием вердиктов:

<p>
Тестовое тело нотификации!
</p>
<div style="width: 100%; font-family:'GE Inspira',sans-serif;">
    <fieldset>
        <p style="font-weight:bold">Вердикты:</p>
        <div>
            <p><a href="mailto:${mail_for_answer}?Subject=CA-${task_id}-Done-${task_token}&body=Вердикт: Согласовать %0D%0A %0D%0A Поле комментарий обязательно для заполнения %0D%0A %0D%0A $[comment] %0D%0A %0D%0A ${default_comment} %0D%0A %0D%0A [comment]" target="_top">Согласовать / Approve</a></p>
        </div>
    </fieldset>
</div>

Структура ссылки вердикта:

mailto:${mail_for_answer}
  ?Subject=CA-${task_id}-<Outcome>-${task_token}
  &body=...%0D%0A$[comment]%0D%0A${default_comment}%0D%0A[comment]
  • CA — произвольный префикс (может быть любым).

  • <Outcome> — id вердикта, строго совпадающий с id в ecos:outcomes задачи.

  • %0D%0A — перенос строки (URL-encoded \r\n).

  • $[comment] / [comment] — маркеры для извлечения комментария.

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


5.3 Пример уведомления Lazy approval к задаче

Рассмотрим пример уведомления Lazy approval к задаче согласования со следующими вердиктами:

Тело шаблона:

<p>
Добрый день! Вам назначена задача "Согласование" по Тестовой заявке № ${registrationNumber}
</p>
<div style="width: 100%; font-family:'GE Inspira',sans-serif;">
    <fieldset>
        <p style="font-weight:bold">Вердикты:</p>
        <div>
            <p><a href="mailto:${mail_for_answer}?Subject=CA-${task_id}-Approve-${task_token}&body=Вердикт: Согласовать %0D%0A %0D%0A Поле комментарий обязательно для заполнения %0D%0A %0D%0A $[comment] %0D%0A %0D%0A ${default_comment} %0D%0A %0D%0A [comment]" target="_top">Согласовать / Approve</a></p>
        </div>
        <div>
            <p><a href="mailto:${mail_for_answer}?Subject=CA-${task_id}-Rework-${task_token}&body=Вердикт: На доработку %0D%0A %0D%0A Поле комментарий обязательно для заполнения %0D%0A %0D%0A $[comment] %0D%0A %0D%0A ${default_comment} %0D%0A %0D%0A [comment]" target="_top">На доработку / On rework</a></p>
        </div>
    </fieldset>
</div>

Помимо описанных выше задана дополнительная переменная registrationNumber- номер тестовой заявки, который берется из карточки.

../../_images/sample_02.png

Уведомление

Ответ с вердиктом

../../_images/sample_03.png ../../_images/sample_04.png

../../_images/sample_05.png

6. Сообщения с отчетами об обработке

В системе предусмотрены ответные сообщения пользователю об успешно выполненных задачах через Lazy approval или о неудачных выполнениях.

Они делятся на 3 типа:

Тип сообщения

Когда отправляется

Базовое сообщение об ошибке

Отправляется при наличии общего шаблона и адреса ответа; флаг отчётов задачи его не отключает. Обрабатывает ошибки, возникшие раньше, чем система смогла добраться до самой задачи и посмотреть её конфигурацию (например: не удалось распарсить тему письма).

Уведомление об успешном выполнении задачи

Задаётся в самой задаче. Если шаблон в задаче не указан — используется базовый шаблон из конфигурации Citeck.

Уведомление о неудачном выполнении задачи

Задаётся в самой задаче, можно отключить через свойство задачи. Если шаблон в задаче не указан — используется базовый шаблон из конфигурации Citeck.

Установление шаблонов по умолчанию для ответных сообщений Lazy approval

Через конфигурацию Citeck устанавливаются базовые версии шаблонов для отправки ответных сообщений пользователям о результатах обработки их сообщений, отправленных через Lazy Approval.

Ключи конфигурации: la-base-error-template, la-report-success-template и la-report-error-template. Отправка требует доступного адреса ответа (Return-Path либо адрес из From) и шаблона. Флаг laReportEnabled отключает успешный и ошибочный отчёты задачи, но не базовое сообщение ранней ошибки разбора.

Предупреждение

В проверенной версии ecos-integrations 2.40.0 есть дефект: ошибочный отчёт отправляется по общему la-report-error-template, даже если в задаче выбран другой error-шаблон. Не рассчитывайте на переопределение ошибочного отчёта задачей до исправления сервиса. Успешный отчёт использует выбранный шаблон с переходом к общему при его отсутствии.

../../_images/LA_message_01.png

Данный шаблон будет выбран в том случае, если необходимо отправить сообщение пользователю, но в задаче не указан шаблон.

В случае, если шаблон нигде не указан (ни в конфигурации, ни в задаче), то сообщение отправлено не будет.

6.1 Коды ошибок

Все коды ошибок, доступные в переменной error_code отчётных шаблонов:

Код

Описание

INCORRECT_DATA

Не удалось разобрать тему письма (неверный формат Prefix-taskId-Outcome-token). Возникает до поиска задачи.

USER_NOT_FOUND

Пользователь, с email которого пришло письмо, не найден в системе.

TASK_NOT_FOUND

Задача с указанным taskId не найдена.

TASK_ALREADY_COMPLETED

Задача уже завершена ранее.

OUTCOME_NOT_FOUND

Указанный в теме письма вердикт не найден среди доступных вердиктов задачи.

TOKEN_NOT_FOUND

Токен безопасности из темы письма не совпадает с токеном задачи.

EXCEPTION

Произошла непредвиденная ошибка при завершении задачи.

6.2 Переменные шаблонов отчётов

Тип отчёта

Переменная

Описание

Базовый шаблон об ошибке

subject

Тема сообщения от пользователя с префиксом «Re: « (для формирования письма как ответного сообщения)

Базовый шаблон об ошибке

error_code

Код сообщения об ошибке. Возможные варианты: INCORRECT_DATA, USER_NOT_FOUND, TASK_NOT_FOUND

Уведомление об успешном выполнении задачи

task_name

Название задачи

Уведомление о неудачном выполнении задачи

task_name

Название задачи

Уведомление о неудачном выполнении задачи

error_code

Код сообщения об ошибке. Возможные варианты: TASK_ALREADY_COMPLETED, OUTCOME_NOT_FOUND, TOKEN_NOT_FOUND, EXCEPTION

Уведомление о неудачном выполнении задачи

error_message

Текст сообщения об ошибке