Почтовый шлюз (Mail Processing)

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

Функции почтового шлюза

• Управление очередью входящих и исходящих почтовых сообщений (SenderMessage)
• Отправка уведомлений о событиях
• Отправка исходящей почты из очереди сообщений
• Загрузка входящей почты в очередь сообщений
• Хранение правил обработки входящих сообщений (MailRule)
• Обработка входящих сообщений согласно настроенным правилам (MailProcessing)

Каналы E-mail сообщений (Mail Channel)

Каналы E-mail сообщений настраиваются администратором системы в разделе Администрирование (Admin).

Направление канала определяется по указанному протоколу:

• SMTP - канал исходящих сообщений;
• IMAP - канал входящих сообщений.

Атрибуты

• Наименование (Name) - String - имя канала, выводимое в системе. Обязательный атрибут.
• Протокол (Proto) - ChannelProto - почтовый протокол. Возможные значения:
  • SMTP - канал исходящих сообщений;
  • IMAP - канал входящих сообщений.
• Шифрование (Encryption) - ChannelEncryption - шифрование. Возможные значения:
  • NONE;
  • SSL;
  • TLS.
• Тип аутентификации (Auth type) - ChannelAuthType - тип аутентификации. Возможные значения:
  • NONE - аутентификация отсутствует;
  • LOGIN - аутентификация по имени пользователя и паролю;
• Хост (Host) - String - имя или IP-адрес почтового сервера.
• Порт (Port) - Integer - порт сервера. Заполняется автоматически или может быть указан вручную. Автоматическое заполнение в соответствии со значениями полей Протокол, Шифрование:
  • SMTP, NONE = 25;
  • SMTP, SSL = 465;
  • SMTP, TLS = 587;
  • IMAP, NONE = 143;
  • IMAP, SSL = 993;
  • IMAP, TLS = 143.
• Адрес отправителя (Address) - String - E-mail, который будет подставляться в заголовок From:. Указывается только для протокола SMTP (канал исходящих сообщений).
• Имя пользователя (Username) - String - Имя пользователя.
• Пароль (Password) - String - Пароль. Указывается для типа аутентификации LOGIN.
• Рабочий процесс (Workflow) - String - Идентификатор рабочего процесса. Выбирается из списка рабочих процессов. Обязателен для протокола IMAP.
• Каталог IMAP (IMAP Folder)** - String - Только для протокола IMAP. Наименование каталога IMAP. Обязательный атрибут. Значение по-умолчанию: INBOX.
• Основной (Main) - Boolean - Только для протокола SMTP. Канал помеченный как основной, будет использоваться для отправки уведомлений и сообщений, для которых не указан рабочий процесс.
• Удалять полученные (Delete received) - Boolean - Только для протокола IMAP. Признак указывает, что при получении сообщения оно должно быть удалено с сервера.
• Отладка (Debug) - Boolean - Включает вывод отладочной информации по каналу в логи системы.
• Активно (Active) - Boolean - Признак, что канал является активным.

Ключевые принципы

Регистрация каналов (Channel Service)

• При запуске система (ChannelService) получает список каналов, являющихся активными (active = true).
• Для каждого активного канала выполняется процедура его валидации.
• Если канал прошел валидацию, выполняется процедура его регистрации в памяти приложения.
• При изменении настроек каналов система автоматически обновляет их регистрацию в памяти приложения. Также, обновление выполняется в фоне, с периодичностью, указанной в конфигурационном параметре sender.channel-init-delay-in-millis (по-умолчанию - каждую минуту).

Создание исходящего сообщения (Sender Message Factory)

• Компоненты системы и внешние сервисы создают в очереди сообщений (SenderMessage) сообщения для отправки (атрибут direction = OUTBOX).
• Выбирается канал для отправки. Если канал не удалось определить, используется канал, имеющий признак основного (main = true).
• Происходит заполнение поля Отправитель (From) по шаблону: senderMessage.sender <channel@address>, где:
  • senderMessage.sender - имя отправителя, указанное в сообщении;
  • channel@address - E-mail, указанный в настройках выбранного канала.
• Если поле senderMessage.sender пустое, то в поле Отправитель указывается значение из channel@address.
• Для сообщения устанавливается число попыток для отправки (атрибут retries), указанное в конфигурационном параметре sender.retries (по-умолчанию = 3).

Отправка исходящего сообщения (Sender Service)

• Сервис отправки сообщений (SenderService) осуществляет проверку очереди сообщений (SenderMessage) с периодичностью, указанной в конфигурационном параметре sender.send-delay-in-millis (по-умолчанию - каждую минуту).
• Отбираются сообщения, имеющие значение атрибутов: retries (число повторов) > 0 и complete (признак обработанного сообщения) = false.
• Если отправка успешна, система устанавливает значение атрибутов: retries = 0, complete = false.
• Если отправка не успешна, система уменьшает значение атрибута retries на 1 и записывает stacktrace ошибки в поле exception.

Получение входящих сообщений (Receiver Service)

• Сервис получения сообщений (ReceiverService) получает список зарегистрированных каналов входящих сообщений с периодичностью, указанной в конфигурационном параметре sender.receive-delay-in-millis (по-умолчанию - каждую минуту).
• Для каждого из каналов выполняется подключение к серверу IMAP и получение сообщений.
• Полученные сообщения сохраняются в очередь сообщений (SenderMessage) с атрибутами:
  • direction = INBOX;
  • completed = false;
  • raw = полученное сообщение в “сыром” формате.
• Если канал имеет атрибут deleteReceived = true, происходит удаление сообщения. Иначе - сообщение помечается как прочитанное.

Обработка входящих сообщений (Mail Processing)

После получения входящего сообщения и помещения его в очередь (SenderMessage), система выполняет его обработку по следующему алгоритму:

1. Выбор сообщений для обработки

• Сервис обработки входящей почты (MailProcessingService) периодически (интервал задаётся параметром sender.receive-delay-in-millis, по умолчанию — 1 минута) выбирает из очереди все сообщения:
  • с направлением INBOX;
  • с retries > 0;
  • с completed = false.

2. Обработка сообщения

   Для каждого выбранного сообщения выполняется метод processMessage():

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

  Если тема письма содержит номер заявки (в формате [Ticket#XXXX]):

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

• Проверка связи с существующим комментарием

  Если в заголовках письма есть In-Reply-To или References, указывающие на SenderMessageId комментария:

  • система находит комментарий и связанную заявку;
  • создаётся комментарий с содержимым письма и вложениями;
  • обработка завершается.

• Создание новой заявки

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

  • выполняется подбор правил обработки писем (MailRule);

  • активные правила сортируются по убыванию приоритета (priority);

  • по каждой категории (OutputType):

    • WORKFLOW — определяется рабочий процесс;
    • TICKET_TYPE — тип заявки;
    • SERVICE_ENTITY — сервис;
    • значения присваиваются новой заявке.

  • создаётся новая заявка:

    • заголовок — тема письма (subject);
    • содержание — тело письма (HTML или plain text);
    • добавляются вложения;
    • определяется отправитель — если он совпадает с персоной или организацией, заполняются соответствующие поля.

  • создаётся комментарий типа INBOUND с содержимым письма и вложениями.

3. Результат обработки

• При успешной обработке:

  • сообщение помечается: completed = true, retries = 0.

• При ошибке обработки:

  • значение retries уменьшается на 1;
  • в поле exception сохраняется описание ошибки;
  • сообщение остаётся completed = false.

4. Повторные попытки

• Повторная обработка выполняется при следующих запусках задачи;
• сообщение будет обрабатываться, пока retries > 0;
• число попыток задаётся параметром sender.retries (по умолчанию = 3).

Сопоставление правил (Mail Rule)

Для автоматической обработки входящих сообщений используется справочник правил (Mail Rule). Каждое правило определяет, как обрабатывать письмо в зависимости от его полей (адресов или темы).

Атрибуты правила:

• RuleType — поле письма, к которому применяется правило:

  • TO — поле «Кому»;
  • FROM — поле «От»;
  • SUBJECT — тема письма.

• RuleValue — регулярное выражение (regexp), применяемое к значению выбранного поля.

• OutputType — тип объекта, к которому относится результат обработки:

  • WORKFLOW — рабочий процесс;
  • SERVICE_ENTITY — сервис;
  • TICKET_TYPE — тип заявки.

• OutputValue — идентификатор объекта (UUID), к которому будет привязана новая заявка.

• Priority — приоритет правила (чем выше — тем раньше применяется).

• Active — активность правила.

Алгоритм применения правил:

1. Все активные правила выбираются из справочника;
2. Для каждого правила выполняется проверка matchesRule():

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

3. Если сработало несколько правил:

• Для каждого OutputType (WORKFLOW, TICKET_TYPE, SERVICE_ENTITY) выбирается правило с наивысшим приоритетом (priority).

4. Применённые правила управляют полями создаваемой заявки.

Примеры использования правил:

Приоритет:

• Чем выше priority, тем раньше применяется правило для данного OutputType;
• Если несколько правил одного типа сработали — выбирается правило с наивысшим приоритетом.

Очередь сообщений (SenderMessage)

Очередь сообщений — это внутренний механизм хранения и обработки входящих и исходящих писем в системе.
Все E-mail сообщения (входящие и исходящие) записываются в очередь сообщений (таблица SenderMessage).

Очередь используется для:

• Асинхронной отправки исходящих писем;
• Приема и хранения входящих писем;
• Повторной отправки при ошибках;
• Хранения истории обработки сообщений;
• Связи сообщений с комментариями, заявками, событиями.

Атрибуты

Жизненный цикл сообщения

Примечания

• Все входящие письма сохраняются в raw виде (полный MIME) для возможности повторной обработки.
• Атрибут attachments содержит ссылки на файлы (Attachment), загруженные с письмом или прикрепленные к исходящему сообщению.
• Связь с комментариями осуществляется по полю messageId ↔ senderMessageId в комментарии.