Функционал Lazy approval для задачи
Примечание
Требуется лицензия разработчика либо лицензия с функцией lazy-approval.
Lazy approval – функционал, позволяющий принимать решения из электронной почты, не заходя в Citeck.
Пользователь получает письмо с кликабельными ссылками-вердиктами. При нажатии на ссылку открывается почтовый клиент с предзаполненным ответным письмом. После отправки ответа система автоматически завершает задачу от имени пользователя.
Для работы необходимы совместимые версии ecos-process, ecos-integrations и ecos-notifications, лицензия и настроенный маршрут чтения ответной почты.
1. Принцип работы
Задача создаётся в BPMN-процессе (UserTask с
ecos:laEnabled="true").Система отправляет email исполнителю(ям) задачи с вердиктами-ссылками.
Пользователь нажимает на ссылку вердикта → почтовый клиент открывает предзаполненное ответное письмо с нужной темой и телом.
Пользователь добавляет комментарий между метками
[comment]...[comment]и отправляет письмо.Apache Camel читает почтовый ящик через IMAP и передаёт письмо в
LazyApprovalEndpoint(ecos-integrations).Система парсит тему письма:
Prefix-{taskId}-{outcome}-{taskToken}.Система извлекает комментарий из тела письма.
Задача завершается от имени пользователя с нужным вердиктом и комментарием.
Отправляется отчётное письмо (если настроено).
Формат темы ответного письма:
<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:
Ключ конфигурации |
Описание |
|---|---|
|
Email-адрес, на который пользователь отправляет ответ с вердиктом.
Именно этот адрес настраивается в Camel DSL для чтения входящих писем.
Подставляется в шаблон через переменную |
|
Комментарий по умолчанию, который вставляется в тело ответного письма.
Подставляется в шаблон через переменную |
3. Настройка UserTask в BPMN
Lazy approval включается на уровне конкретного UserTask через ECOS-атрибуты.
Атрибут |
Описание |
|---|---|
|
Включает Lazy approval для задачи. При создании задачи система автоматически готовит письмо при наличии лицензии, адресатов и шаблона; токен сохраняется локально в задаче при подготовке email. Смена назначения уже существующей задачи сама по себе не гарантирует нового письма. |
|
Тип уведомления. На текущий момент поддерживается только |
|
Ссылка на шаблон уведомления с вердиктами. Статически заданный шаблон. |
|
Включает режим динамического шаблона (из переменной процесса).
Если |
|
Шаблон уведомления из переменной процесса. Может содержать expression |
|
Дополнительные переменные для модели шаблона (JSON-объект). |
|
Включает отправку отчётного письма после обработки ответа пользователя. |
|
Шаблон отчётного письма об успешном завершении задачи (переопределяет значение из конфигурации). |
|
Настройка шаблона ошибочного отчёта задачи. В проверенной версии её применение ограничено дефектом, описанным в разделе отчётов ниже. |
Режим ${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"
Общий принцип работы:
В системе создается бин типа «email», что указывает, что сообщения необходимо обрабатывать, как сообщения, пришедшие из почты. (В дальнейшем количество типов может быть расширено).
Затем устанавливается route, в котором указываются настройки параметров подключения почты и правил обработки сообщений.
Полученные сообщения из почты отправляются в систему, где бин (который описан выше) их обрабатывает и делает соответствующие действия в системе.
Параметры route uri:
Параметр |
Описание |
|---|---|
|
Email-адрес, на котором настроено чтение ответных писем. Должен совпадать
со значением конфига |
|
Пароль для подключения к почтовому серверу. |
|
Удалять ли письма из ящика после обработки. Рекомендуется |
|
Выбирать непрочитанные письма. Используйте |
|
Частота проверки почтового ящика в миллисекундах. Пример: |
5. Шаблоны уведомлений для Lazy approval
5.1 Переменные шаблона
Помимо стандартных переменных из модели шаблона, в шаблонах Lazy approval автоматически доступны следующие переменные:
Переменная |
Описание |
|---|---|
|
UUID идентификатор задачи. Используется в теме ответного письма. |
|
UUID токен безопасности, сгенерированный при создании задачи. Защищает от несанкционированного завершения задачи. |
|
Email для отправки ответа с вердиктом. Берётся из конфигурации
|
|
Комментарий по умолчанию. Берётся из конфигурации
|
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- номер тестовой заявки, который берется из карточки.
Уведомление |
Ответ с вердиктом |
|---|---|
|
|
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-шаблон. Не рассчитывайте на переопределение ошибочного отчёта задачей до исправления сервиса. Успешный отчёт использует выбранный шаблон с переходом к общему при его отсутствии.
Данный шаблон будет выбран в том случае, если необходимо отправить сообщение пользователю, но в задаче не указан шаблон.
В случае, если шаблон нигде не указан (ни в конфигурации, ни в задаче), то сообщение отправлено не будет.
6.1 Коды ошибок
Все коды ошибок, доступные в переменной error_code отчётных шаблонов:
Код |
Описание |
|---|---|
|
Не удалось разобрать тему письма (неверный формат |
|
Пользователь, с email которого пришло письмо, не найден в системе. |
|
Задача с указанным |
|
Задача уже завершена ранее. |
|
Указанный в теме письма вердикт не найден среди доступных вердиктов задачи. |
|
Токен безопасности из темы письма не совпадает с токеном задачи. |
|
Произошла непредвиденная ошибка при завершении задачи. |
6.2 Переменные шаблонов отчётов
Тип отчёта |
Переменная |
Описание |
|---|---|---|
Базовый шаблон об ошибке |
|
Тема сообщения от пользователя с префиксом «Re: « (для формирования письма как ответного сообщения) |
Базовый шаблон об ошибке |
|
Код сообщения об ошибке. Возможные варианты: |
Уведомление об успешном выполнении задачи |
|
Название задачи |
Уведомление о неудачном выполнении задачи |
|
Название задачи |
Уведомление о неудачном выполнении задачи |
|
Код сообщения об ошибке. Возможные варианты: |
Уведомление о неудачном выполнении задачи |
|
Текст сообщения об ошибке |