Уведомления
Примечание
Отображение уведомлений добавлено в версии 2.7.0 микросервиса ecos-notifications
Общие сведения
Микросервис ecos-notifications — единая точка отправки уведомлений в платформе Citeck.
Все уведомления (email и другие типы) должны отправляться только через него. Не следует отправлять уведомления напрямую из кода микросервиса или из скриптов процессов.
Основной сценарий использования — отправка email-уведомлений из BPMN-процессов через элемент Send Task. Также поддерживаются массовые рассылки и lazy approval.
Уведомления отправляются на основе шаблонов уведомлений. Маршрутизация и блокировка отправки настраивается через отправителей.
Примечание
При временной недоступности SMTP уведомления сохраняются, а повторные попытки выполняются в пределах настроенного бюджета. Доставка после восстановления соединения зависит от статуса, оставшихся попыток и окна повторов. Подробнее — в разделе 4. Повторные попытки отправки.
1. Сущность «Уведомление»
1.1 Форма, поля
Поле |
Описание |
|---|---|
Идентификатор |
Уникальный id уведомления. |
Статус |
Текущий статус уведомления. См. 1.2 Статусы. |
Рекорд |
Базовый рекорд уведомления — документ, по атрибутам которого вычислялась модель шаблона. |
Шаблон |
Шаблон уведомления, использованный при отправке. |
Тип уведомления |
Тип отправки: |
Отложенная отправка |
Время запланированной отправки. Если задано, уведомление не отправляется сразу. |
Изменено |
Время последнего изменения записи уведомления. |
Создано из |
Источник уведомления — ссылка на объект (например, массовую рассылку), из которого было создано уведомление. Для уведомлений из BPMN-процессов поле пустое. |
Количество попыток отправки |
Счётчик обработанных попыток, включая успешную. При ручном RETRY обнуляется. |
Время последней попытки |
Временная метка последней попытки отправки. |
Время следующей попытки |
Время, на которое запланирована следующая попытка отправки. Заполнено, пока уведомление находится в статусе |
Время первой ошибки |
Время первой неудачной попытки. От него отсчитывается окно повторов ( |
Тип ошибки |
Классификация последней ошибки: |
Сообщение ошибки |
Сообщение об ошибке, возникшей при последней попытке отправки. |
Трассировка стека ошибки |
Полный стек ошибки — используется для диагностики технических проблем. |
Данные уведомления |
Полное JSON-представление уведомления — вся полезная нагрузка (получатели, заголовок, тело, вложения и т.д.). Удобно для отладки: позволяет убедиться, что модель шаблона вычислилась корректно. |
Отправленное сообщение |
Итоговое сообщение в том виде, в котором оно было отправлено получателю (после подстановки шаблона и вычисления модели). |
Поля Время следующей попытки, Время первой ошибки и Тип ошибки заполняются микросервисом
и доступны только на чтение; в Records API им соответствуют атрибуты nextRetryAt, firstErrorAt
и failureKind.
1.2 Статусы
Статус |
Описание |
|---|---|
|
Уведомление поставлено в очередь, например для отложенной отправки или массовой рассылки. Синхронная отправка может сразу сохранить итоговый статус. |
|
Канал принял сообщение. Для email возможна частичная доставка; статус не гарантирует прочтение или доставку каждому адресату. См. 4.2 Частичная доставка. |
|
При отправке возникла ошибка, которая может пройти сама (недоступность SMTP, таймаут). Уведомление остаётся в очереди — см. поле Время следующей попытки. Это единственный нетерминальный статус после ошибки. |
|
Выявлена постоянная ошибка: например, некорректный адрес, ошибка шаблона или конфигурации отправителя. После её выявления автоматические повторы не назначаются. Постоянная ошибка может возникнуть и после нескольких временных ошибок. |
|
Бюджет повторов исчерпан — превышено максимальное количество попыток ( |
|
Отправка заблокирована одним из отправителей. Повторных попыток не будет. |
|
Отправка отменена — например, была удалена массовая рассылка, из которой создано уведомление. Запланированные повторы при этом останавливаются. |
|
Не найдены получатели. Сообщение не отправлено; проверьте To, CC, BCC и разрешение ролей/выражений. |
Примечание
Из статусов ERROR, FAILED и EXPIRED уведомление можно вернуть в очередь вручную —
действием Повторить отправку сейчас (см. 4.4 Ручная повторная отправка).
Типичный жизненный цикл уведомления:
WAIT_FOR_DISPATCH → SENT (успешная отправка)
WAIT_FOR_DISPATCH → ERROR → ... → SENT (успешная отправка после повтора)
WAIT_FOR_DISPATCH → ERROR → ... → EXPIRED (бюджет повторов исчерпан)
WAIT_FOR_DISPATCH → FAILED (постоянная ошибка, повтор бесполезен)
WAIT_FOR_DISPATCH → BLOCKED (заблокировано отправителем)
2. Журнал уведомлений
Журнал Уведомления расположен в Разделе администратора → Конфигурация уведомлений:
В журнале отображаются зарегистрированные уведомления с учётом прав, фильтров и контекста рабочего пространства. Тестовое письмо при старте сервиса отправляется отдельным путём и не обязано появляться в этом журнале.
На текущий момент поддерживается только простая текстовая фильтрация полей через ИЛИ.
3. Диагностика проблем с доставкой
Если уведомление не доходит до получателя, используйте журнал уведомлений для диагностики.
Алгоритм
Найдите нужное уведомление в журнале — по получателю, шаблону или времени отправки.
Проверьте Статус уведомления:
ERROR— временная ошибка, повторы продолжаются. Смотрите поля Сообщение ошибки и Время следующей попытки. Типичная причина — недоступность SMTP-сервера.FAILED— постоянная ошибка. Смотрите поля Сообщение ошибки и Трассировка стека ошибки. Типичные причины: неверный адрес получателя, ошибка рендеринга шаблона, некорректная конфигурация отправителя. Повтор без устранения причины не поможет.EXPIRED— бюджет повторов исчерпан. Смотрите Сообщение ошибки: как правило, SMTP-сервер был недоступен дольше, чем настроенное окно повторов.BLOCKED— уведомление заблокировано настройками отправителя. Проверьте конфигурацию активных отправителей и условия блокировки.WAIT_FOR_DISPATCH— уведомление ещё не обработано. Возможна проблема с доступностью SMTP или большой очередью.
Откройте поле Данные уведомления — убедитесь, что получатели, тема и тело письма вычислены корректно.
Откройте поле Отправленное сообщение — проверьте финальный вид письма.
Устранив причину (например, восстановив SMTP-сервер или исправив адрес получателя), вернитесь в журнал и выполните действие Повторить отправку сейчас (см. 4.4 Ручная повторная отправка).
4. Повторные попытки отправки
Примечание
Механизм повторных отправок переработан в релизе платформы 2026.3 (см. изменения обратной совместимости).
4.1 Как это работает
Если отправка уведомления не удалась, микросервис классифицирует ошибку и решает, имеет ли смысл повтор.
Постоянные ошибки — те, которые повтор не исправит: некорректный адрес получателя, ошибка шаблона,
нечитаемая конфигурация отправителя, большинство отказов SMTP с кодом 5xx. После выявления такой ошибки
уведомление переходит в FAILED, дальнейшие автоматические повторы не назначаются.
Временные ошибки — недоступность SMTP-сервера, таймаут, отказ с кодом 4xx, переполненный почтовый ящик
получателя. Уведомление остаётся в статусе ERROR, и повторы выполняются в рамках бюджета.
К временным относятся также SMTP 552 и ответы 5xx с указанием quota. Если в цепочке почтовых ошибок есть временная причина или остались допустимые, но не обслуженные адресаты, классификатор сохраняет возможность повтора. Явная постоянная ошибка конфигурации или шаблона имеет приоритет.
Неизвестные ошибки считаются временными: ложный вердикт «постоянная ошибка» безвозвратно теряет письмо, а лишние повторы стоят лишь нескольких дешёвых попыток.
Интервал между повторами растёт по экспоненте: первый повтор через initial-interval, каждый следующий
в multiplier раз дольше предыдущего, с ограничением базовой паузы max-interval. Затем добавляется случайный
разброс ±20%, поэтому фактические паузы не совпадают с настройками в точности — это не даёт всем
накопившимся уведомлениям пойти на SMTP-сервер одновременно. При настройках по умолчанию последовательность
пауз — примерно 1 мин, 3 мин, 9 мин, 27 мин, 81 мин, далее по 2 часа. Из-за разброса фактическая пауза может превышать max-interval до 20%.
Бюджет повторов ограничен с двух сторон: количеством попыток (max-attempts) и окном повторов
(retry-window, отсчитывается от первой ошибки). Что закончится первым, то и переводит уведомление
в статус EXPIRED.
Примечание
Захват записи и аренда защищают от одновременной обработки несколькими репликами. После сбоя записи снова становятся доступны по истечении lease-time. Это не гарантирует единственную доставку: если SMTP уже принял письмо, а результат не успел сохраниться, повтор может создать дубль.
4.2 Частичная доставка
Если письмо адресовано нескольким получателям и почтовый сервер принял его только для части из них,
уведомление считается отправленным (статус SENT), а список отклонённых адресов записывается в поле
Сообщение ошибки. Повторная отправка в этом случае не выполняется: она означала бы повторное письмо
для всех, кто уже его получил.
4.3 Настройка
Параметры задаются в конфигурации микросервиса (см. настройка подключения) в блоке ecos-notifications.retry:
Параметр |
По умолчанию |
Описание |
|---|---|---|
|
|
|
|
|
Как часто проверяется очередь повторов. |
|
|
Сколько уведомлений берётся в обработку за один проход. |
|
|
Максимум попыток отправки. |
|
|
Пауза перед первым повтором. |
|
|
Во сколько раз растёт пауза. |
|
|
Максимальная пауза между повторами. |
|
|
Окно повторов от первой ошибки. |
|
|
Аренда уведомления, взятого репликой в обработку. |
Показаны значения по умолчанию — задавать блок целиком не требуется, достаточно переопределить нужные параметры:
ecos-notifications:
retry:
max-attempts: 20
retry-window: 24h
Предупреждение
Некорректные значения (нулевой batch-size, multiplier меньше 1, неположительные интервалы)
не дают микросервису запуститься — ошибка будет видна в логе при старте.
Параметр lease-time должен превышать batch-size × максимальное время отправки одного письма,
иначе другая реплика может взять в работу уведомление, которое ещё отправляется. Таймауты
spring.mail.properties.mail.smtp.*timeout обязательно должны быть конечными.
Даже при enabled: false ручная повторная отправка продолжает работать: уведомление получит
ровно одну попытку.
Примечание
Устаревший блок настроек ecos-notifications.error-notification (параметры ttl, delay,
min-try-count) больше не влияет на поведение. Стенды с ним запускаются без ошибок, но в лог
пишется предупреждение — такие настройки следует перенести в блок retry.
4.4 Ручная повторная отправка
Действие Повторить отправку сейчас доступно в журнале уведомлений и на карточке уведомления — для
уведомлений в статусах ERROR, FAILED и EXPIRED. Действие возвращает уведомление в очередь
повторов со сброшенным бюджетом: счётчик попыток обнуляется, а запланированное Время следующей попытки
сбрасывается на текущий момент. Запись становится доступной для одного из ближайших проходов планировщика. Интервал между проходами по умолчанию 30 секунд; фактическое ожидание зависит от очереди и длительности предыдущей обработки.
Действие доступно администраторам и системным пользователям.
Примечание
Похожее по названию действие Отправить повторно (RESEND) предлагается для уведомлений в
остальных статусах, если не заполнены bulkMailRef и delayedSend. В штатном интерфейсе оно не предлагается для уведомлений рассылки и записей с отложенной отправкой:
Действие |
Для каких статусов |
Что происходит |
|---|---|---|
Повторить отправку сейчас |
|
Работает с той же записью уведомления: сбрасывает бюджет повторов и возвращает её в очередь. |
Отправить повторно ( |
Остальные статусы; |
Формирует и отправляет новое уведомление, оставляя исходную запись без изменений. |