Уведомления

Примечание

Отображение уведомлений добавлено в версии 2.7.0 микросервиса ecos-notifications

Общие сведения

Микросервис ecos-notifications — единая точка отправки уведомлений в платформе Citeck.

Все уведомления (email и другие типы) должны отправляться только через него. Не следует отправлять уведомления напрямую из кода микросервиса или из скриптов процессов.

Основной сценарий использования — отправка email-уведомлений из BPMN-процессов через элемент Send Task. Также поддерживаются массовые рассылки и lazy approval.

Уведомления отправляются на основе шаблонов уведомлений. Маршрутизация и блокировка отправки настраивается через отправителей.

Примечание

При временной недоступности SMTP уведомления сохраняются, а повторные попытки выполняются в пределах настроенного бюджета. Доставка после восстановления соединения зависит от статуса, оставшихся попыток и окна повторов. Подробнее — в разделе 4. Повторные попытки отправки.

1. Сущность «Уведомление»

1.1 Форма, поля

../../_images/notification_form_1.png

Поле

Описание

Идентификатор

Уникальный id уведомления.

Статус

Текущий статус уведомления. См. 1.2 Статусы.

Рекорд

Базовый рекорд уведомления — документ, по атрибутам которого вычислялась модель шаблона.

Шаблон

Шаблон уведомления, использованный при отправке.

Тип уведомления

Тип отправки: EMAIL_NOTIFICATION или FIREBASE_NOTIFICATION. Для Firebase требуется настройка соответствующего канала. BPMN Send Task поддерживает только email.

Отложенная отправка

Время запланированной отправки. Если задано, уведомление не отправляется сразу.

Изменено

Время последнего изменения записи уведомления.

Создано из

Источник уведомления — ссылка на объект (например, массовую рассылку), из которого было создано уведомление. Для уведомлений из BPMN-процессов поле пустое.

Количество попыток отправки

Счётчик обработанных попыток, включая успешную. При ручном RETRY обнуляется.

Время последней попытки

Временная метка последней попытки отправки.

Время следующей попытки

Время, на которое запланирована следующая попытка отправки. Заполнено, пока уведомление находится в статусе ERROR. Доступно также как колонка журнала уведомлений. См. 4. Повторные попытки отправки.

Время первой ошибки

Время первой неудачной попытки. От него отсчитывается окно повторов (retry-window).

Тип ошибки

Классификация последней ошибки: TRANSIENT — временная (повторы выполняются), PERMANENT — постоянная (повторы бесполезны).

Сообщение ошибки

Сообщение об ошибке, возникшей при последней попытке отправки.

Трассировка стека ошибки

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

Данные уведомления

Полное JSON-представление уведомления — вся полезная нагрузка (получатели, заголовок, тело, вложения и т.д.). Удобно для отладки: позволяет убедиться, что модель шаблона вычислилась корректно.

Отправленное сообщение

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

Поля Время следующей попытки, Время первой ошибки и Тип ошибки заполняются микросервисом и доступны только на чтение; в Records API им соответствуют атрибуты nextRetryAt, firstErrorAt и failureKind.

1.2 Статусы

Статус

Описание

WAIT_FOR_DISPATCH

Уведомление поставлено в очередь, например для отложенной отправки или массовой рассылки. Синхронная отправка может сразу сохранить итоговый статус.

SENT

Канал принял сообщение. Для email возможна частичная доставка; статус не гарантирует прочтение или доставку каждому адресату. См. 4.2 Частичная доставка.

ERROR

При отправке возникла ошибка, которая может пройти сама (недоступность SMTP, таймаут). Уведомление остаётся в очереди — см. поле Время следующей попытки. Это единственный нетерминальный статус после ошибки.

FAILED

Выявлена постоянная ошибка: например, некорректный адрес, ошибка шаблона или конфигурации отправителя. После её выявления автоматические повторы не назначаются. Постоянная ошибка может возникнуть и после нескольких временных ошибок.

EXPIRED

Бюджет повторов исчерпан — превышено максимальное количество попыток (max-attempts) или окно повторов (retry-window). Автоматических повторов больше не будет.

BLOCKED

Отправка заблокирована одним из отправителей. Повторных попыток не будет.

CANCELLED

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

RECIPIENTS_NOT_FOUND

Не найдены получатели. Сообщение не отправлено; проверьте 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. Журнал уведомлений

Журнал Уведомления расположен в Разделе администратора → Конфигурация уведомлений:

В журнале отображаются зарегистрированные уведомления с учётом прав, фильтров и контекста рабочего пространства. Тестовое письмо при старте сервиса отправляется отдельным путём и не обязано появляться в этом журнале.

На текущий момент поддерживается только простая текстовая фильтрация полей через ИЛИ.

../../_images/notification_journal.png

3. Диагностика проблем с доставкой

Если уведомление не доходит до получателя, используйте журнал уведомлений для диагностики.

Алгоритм
  1. Найдите нужное уведомление в журнале — по получателю, шаблону или времени отправки.

  2. Проверьте Статус уведомления:

    • ERROR — временная ошибка, повторы продолжаются. Смотрите поля Сообщение ошибки и Время следующей попытки. Типичная причина — недоступность SMTP-сервера.

    • FAILED — постоянная ошибка. Смотрите поля Сообщение ошибки и Трассировка стека ошибки. Типичные причины: неверный адрес получателя, ошибка рендеринга шаблона, некорректная конфигурация отправителя. Повтор без устранения причины не поможет.

    • EXPIRED — бюджет повторов исчерпан. Смотрите Сообщение ошибки: как правило, SMTP-сервер был недоступен дольше, чем настроенное окно повторов.

    • BLOCKED — уведомление заблокировано настройками отправителя. Проверьте конфигурацию активных отправителей и условия блокировки.

    • WAIT_FOR_DISPATCH — уведомление ещё не обработано. Возможна проблема с доступностью SMTP или большой очередью.

  3. Откройте поле Данные уведомления — убедитесь, что получатели, тема и тело письма вычислены корректно.

  4. Откройте поле Отправленное сообщение — проверьте финальный вид письма.

  5. Устранив причину (например, восстановив 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:

Параметр

По умолчанию

Описание

enabled

true

false — первая же ошибка переводит уведомление в терминальный статус.

poll-interval

30s

Как часто проверяется очередь повторов.

batch-size

50

Сколько уведомлений берётся в обработку за один проход.

max-attempts

20

Максимум попыток отправки.

initial-interval

1m

Пауза перед первым повтором.

multiplier

3.0

Во сколько раз растёт пауза.

max-interval

2h

Максимальная пауза между повторами.

retry-window

24h

Окно повторов от первой ошибки.

lease-time

15m

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

Показаны значения по умолчанию — задавать блок целиком не требуется, достаточно переопределить нужные параметры:

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. В штатном интерфейсе оно не предлагается для уведомлений рассылки и записей с отложенной отправкой:

Действие

Для каких статусов

Что происходит

Повторить отправку сейчас

ERROR, FAILED, EXPIRED

Работает с той же записью уведомления: сбрасывает бюджет повторов и возвращает её в очередь.

Отправить повторно (RESEND)

Остальные статусы; bulkMailRef и delayedSend пусты.

Формирует и отправляет новое уведомление, оставляя исходную запись без изменений.