Настроить сервис синхронизации Email Listener

Продукты
Все продукты

Сервис Email Listener (ранее Exchange Listener) реализует синхронизацию с почтовыми провайдерами MS Exchange и IMAP/SMTP, используя механизм подписки. Email Listener обеспечивает возможность горизонтального масштабирования для активного использования блока синхронизации почты и контролируемого использования ресурсов.

Начиная с версии Creatio 7.17.2 использование сервиса синхронизации является обязательным для работы с почтой на платформе .NET Framework и .NET Core. В данной статье описаны системные требования, а также схемы и процесс развертывания сервиса синхронизации для Creatio on-site.

Сервис состоит из следующих компонентов:

  1. Email Listener (EL API) — используется для создания исходящего подключения к EWS API или IMAP. При этом используются учетные данные почтового ящика и создается подписка (subscription) для получения событий при поступлении новых писем. Открытая подписка остается в памяти компонента для обеспечения максимально оперативной реакции на получение нового письма. При наступлении соответствующего события создается задание в очереди и в дальнейшем выполняется загрузка экземпляра письма. Для развертывания сервиса достаточным условием является использование in-memory хранилища. Обязательный компонент сервиса.
  2. NoSQL СУБД Redis— используется для создания масштабируемой и отказоустойчивой системы узлов-обработчиков. Хранилище Redis содержит информацию об обслуживаемых почтовых ящиках. Это позволяет любому контейнеру обработать запросы Creatio на создание новой подписки или проверить статус конкретной подписки, независимо от того, на каком узле она открыта. Необходимым требованием к Redis является выделение отдельной базы данных для работы сервиса Email Listener. Обязательный компонент сервиса.
  3. Email Worker (EL Worker) — используется для поддержания масштабируемой и отказоустойчивой работы основного модуля Email Listener. Дополнительный модуль выполняет скачивание писем с почтового сервера и доставку их в приложение Creatio. Таким образом сглаживается обработка пиковых потоков писем для высоконагруженных сервисов. В этом случае API-компоненты менее загружены и не занимаются скачиванием писем, а доступны для управления подпиской и отправкой исходящих писем.
  4. RabbitMQ — используется для поддержания масштабируемой и отказоустойчивой работы сервиса. Брокер очередей выполняет распределение задач между компонентами в высоконагруженных средах.

Определить конфигурацию сервиса Email Listener 

Конфигурация сервиса Email Listener для вашего приложения определяется на основании среднего потока писем в секунду (исходящих и входящих), который проходит через почтовые ящики компании.

Например, если в компании используется один почтовый ящик службы поддержки с потоком 4 письма в секунду, то рекомендуемая конфигурация будет включать 15 реплик EL Worker, 4 реплики EL API и сервис RabbitMQ.

scr_exchange_listener_table_system_requirements.png

На заметку. Количество активных реплик дополнительного компонента сервиса (EL Worker) напрямую влияет на скорость обработки писем. В продуктивном использовании письма приходят не равномерным потоком, а волнообразно, поэтому часть времени некоторые реплики EL Worker могут простаивать. В статье приведены рекомендуемые параметры конфигурации, но вы можете использовать меньше реплик, чем указано в таблице. В этом случае в период высокой нагрузки письма будут обрабатываться дольше. Оптимальный баланс между скоростью обработки писем и утилизацией ресурсов следует подбирать согласно требованиям бизнеса.

Системные требования для реплик компонентов 

Компонент vCPU Объем памяти
EL Worker 0,1 1,1 Гб
EL API 0.150 850 Мб
Redis 0,5 3 Гб
Rabbit MQ 0,5 4 Гб

На заметку. Значения в таблице являются рекомендуемыми, реальное потребление может отличаться в зависимости от сценариев использования сервиса. Рекомендуется выполнять мониторинг потребления CPU и памяти на развернутых сервисах для оптимизации доступных лимитов.

Способы развертывания сервиса Email Listener 

Для развертывания сервиса предпочтительным способом является использование оркестратора Kubernetes и пакетного менеджера Helm. Подробнее >>>

Для более быстрого развертывания в среде разработки можно использовать Docker. Подробнее >>>

Развернуть сервис синхронизации с использованием Kubernetes 

Развертывания сервиса синхронизации выполняется с использованием программного брокера сообщений RabbitMQ.

Для развертывания сервиса выполните следующие шаги:

  1. Настройте целевое окружение:
    1. Кластер Kubernetes. Подробно о том, как настроить и администрировать кластер, читайте в документации Kubernetes.
    2. Пакетный менеджер Helm. Установка пакетного менеджера подробно описана в документации Helm
  2. Установите Redis. Установка Redis с использованием Helm подробно описана на сайте GitHub.
    Пример команды для установки Redis
    helm install --namespace default --set usePassword=true –set password=<password> --set=slave.persistence.enabled=false --set master.persistence.enabled=false --set cluster.enabled=false redis bitnami/redis
    

    В этом примере:

    default — наименование (namespace), куда будет установлен Redis;

    redis — произвольное имя для экземпляра Redis.

  3. Установите брокер очередей RabbitMQ. Используйте стандартный helm-пакет bitnami/rabbitmq в namespace Exchange Listener, используя рекомендованные параметры для RabbitMQ. Подробнее: bitnami/rabbitmq (GitHub).

    На заметку. При установке лимита памяти для RabbitMQ используйте опцию rabbitmqMemoryHighWatermark по формуле ниже (в helm-пакете bitnami/rabbitmq эта опция установлена по умолчанию): ## rabbitmqMemoryHighWatermark = 0,4 * resources.limits.memory

    Пример установки RabbitMQ с минимальным набором аргументов
    helm install --atomic --namespace exchange-listener --set resources.limits.cpu=500m --set resources.limits.memory=4Gi --set persistence.enabled=false test-rabbit bitnami/rabbitmq 
    

    В установленном экземпляре RabbitMQ создайте virtual host и пользователя для Email Listener:

    1. Подключитесь к RabbitMQ и выполните команду:
      kubectl exec test-rabbit-rabbitmq-0 -n exchange-listener --stdin --tty shell-demo -- /bin/bash
    2. Создайте virtual host:
      rabbitmqctl add_vhost ExchangeListener
    3. Создайте пользователя и укажите пароль, например, “creatio”:
      rabbitmqctl add_user creatio
    4. Настройте права пользователя на созданный virtual host:
      rabbitmqctl set_permissions --vhost ExchangeListener creatio ".*" ".*" ".*"
    5. Установите модуль Email Listener. Для установки модуля скачайте helm-пакет. Доступные параметры helm-пакета описаны в таблице ниже.

    Важно. Для более новых версий Kubernetes укажите версию API, добавив параметр: --set apiVersion=apps/v1

    Пример команды с использованием адреса и относительного пути
    helm install --set ApiUrl=<kubernetes_url>  
    
    --set ingress.enabled=true  
    
    --set ingress.path=<listener_path>  
    
    --set apiVersion=apps/v1  
    
    --set-string Redis.Connection="<redis_host>\,password=<password>"  
    
    --namespace <namespace_name>  
    
    --set WorkerReplicaCount=2 
    
    --set ReplicaCount=2 
    
    --set RabbitMQ.ExchangeName=NewExchange;  
    
    --set RabbitMQ.QueueName=NewQueue;  
    
    --set RabbitMQ.Host=test-rabbit-rabbitmq;  
    
    --set RabbitMQ.HostApi=test-rabbit-rabbitmq;  
    
    --set RabbitMQ.HttpPort=15672;  
    
    --set RabbitMQ.AmqpPort=5672;  
    
    --set RabbitMQ.VirtualHost=ExchangeListener;  
    
    --set RabbitMQ.Login=creatio;  
    
    --set RabbitMQ.Password=creatio 
    
    exchangelistener  
    </namespace_name></password></redis_host></listener_path></kubernetes_url>

    В этом примере:

    <redis_host> — адрес Redis-сервера;

    <kubernetes_url> — URL или IP-адрес Kubernetes.

    ReplicaCount — количество EL API реплик на основе количества почтовых ящиков и среднего потока писем для вашей компании (таблица расчетов приведена выше).

    WorkerReplicaCount — количество EL Worker реплик на основе количества почтовых ящиков и среднего потока писем для вашей компании (таблица расчетов приведена выше).

    Для настройки подключения с использованием HTTPS необходимо установить сервис с Ingress и действительным SSL сертификатом, а в адресе сервиса Email Listener <kubernetes_url> указать HTTPS.

    Чтобы проверить доступность, сделайте запрос как показано на Рис. 1.

    <kubernetes_url>/<listener_path>/api/listeners/status
    Пример команды с использованием Node IP и адреса порта
    helm install --set env.host=<redis_host> --set service.type=<node_IP> --set service.nodePort=<node_port> --set apiVersion=apps/v1 --namespace <namespace name> exchangelistener </path/to/helm/exchangelistener.tgz>
    
    Рис. 1 — Пример ответа сервиса Email Listener
    chapter_exchange_listener_answer.png

    На заметку. Если вам нужно отключить маркировку загружаемых писем категорией “Сreatio”, то при установке приложения в команде helm install нужно указать параметр --set FeaturesMarkEmailsAsSynchronized=false.

    Доступные параметры helm-пакета Email Listener

    Параметр

    Описание параметра

    Значение по умолчанию

    replicaCount

    Количество StatefulSet-обработчиков.

    2

    service.type

    Тип сервиса. Детально типы сервисов Kubernetes описаны в документации Kubernetes.

    ClusterIP

    service.nodePort

    Если параметр service.type равен NodePort, то в этом параметре указывается внешний порт сервиса.

    Детально тип NodePort описан в документации Kubernetes.

     

    env.host

    Адрес хоста Redis.

     

    env.port

    Порт хоста Redis.

    6379

    env.base

    Номер базы данных Redis.

    0

    ingress.enabled

    Использование переопределения адресов при помощи ingress.

    false

    ApiUrl

    Адрес сервиса при ingress.enabled=true.

     

    ingress.path

    Относительный путь сервиса.

     

    log4Net.level

    Уровень логирования по умолчанию.

    Info

Для расчета требований к серверам воспользуйтесь калькулятором системных требований.

Развернуть сервис синхронизации в Docker 

Для настройки сервиса необходим сервер (физический или виртуальный компьютер) с установленной ОС Linux или Windows.

Важно. Развертывание сервиса синхронизации в Docker рекомендуется к установке только для dev-среды. Данный способ отличает высокая скорость развертывания, но он не обеспечивает выполнение требований, актуальных для продуктивной среды: отказоустойчивости функции, масштабирования для обработки большого количества запросов и единого подхода к управлению компонентами с использованием систем оркестрации контейнеров. Для продуктивных сред настоятельно рекомендуется установка с использованием оркестратора Kubernetes и пакетного менеджера Helm.

Для развертывания сервиса выполните следующие шаги:

  1. Предварительно настройте платформу контейнеризации Docker.

    Для установки Docker Desktop на Windows Server необходимо использовать отдельную инструкцию на сайте Microsoft.

    Для установки Docker на операционную систему Linux воспользуйтесь инструкцией в документации Docker. Для проверки установленной версии Docker запустите команду:

    docker --version.

    Вы можете установить все компоненты Docker, воспользовавшись файлом-инструкцией Docker-Compose. Подробнее об установке Docker-Compose читайте в документации Docker.

  2. Установите и запустите Email Listener:
    1. На сервере, выделенном для установки Email Listener, перейдите в папку, где будет развернут сервис.
    2. Распакуйте в открытую папку архив с установочными файлами. Скачать архив.
    3. Перейдите в папку с компонентами / Creatio Email Listener и выполните команду:
      docker-compose up -d

      Команда может выполняться несколько минут.

  3. Проверьте, что в логах нет ошибок, выполнив команду: docker logs ListenerAPI.
  4. Проверьте готовность установки, перейдя по адресу http://localhost:10000/, где localhost — адрес сервера Email Listener.

Настроить сервис Email Listener на стороне Creatio 

  1. Убедитесь, что анонимный сервис ExchangeListenerService доступен по адресу Адрес приложения Creatio/0/ServiceModel/ExchangeListenerService.svc (Рис. 2).

    Рис. 2 — Пример ответа сервиса ExchangeListenerService
    chapter_exchange_listener_creatio.png
  2. Установите нужные значения системных настроек. Для этого:

    1. Перейдите в дизайнер системы, например, по кнопке btn_system_designer.png.

    2. В блоке “Настройка системы” перейдите по ссылке “Системные настройки”.

    3. Укажите значения системных настроек:

      ExchangeListenerServiceUri”(код “ExchangeListenerServiceUri”). Формат значения настройки: адрес сервиса, используемый при установке/api/listeners.

      URL сервиса обработки событий Exchange в Creatio” (код “BpmonlineExchangeEventsEndpointUrl”). Формат значения настройки: адрес анонимного сервиса ExchangeListenerService/NewEmail. Например, https://mycreatio.com/0/ServiceModel/ExchangeListenerService.svc/NewEmail.

Диагностика настроек Email Listener 

На странице диагностики настроек сервиса Email Listener представлены инструменты контроля и проверки работы сервиса.

Здесь вы можете:

  • проверить подключение необходимой функциональности;
  • убедиться в доступности сервиса;
  • получить информацию о подписках;
  • проверить правильность заполнения системной настройки “ExchangeListenerServiceUri”;
  • проверить работоспособность почтового ящика;
  • проверить сетевую доступность от микросервиса к сайту Creatio.

Перейти на страницу диагностики настроек Email Listener можно несколькими способами:

  • Из меню на вкладке Email коммуникационной панели (Рис. 3).
  • Со страницы настроенных почтовых сервисов.
  • В адресной строке браузера добавить “/0/ClientApp/#/IntegrationDiagnostics/ExchangeListener” к URL-адресу вашего сайта Creatio и нажать Enter. Например, http://mycreatio.com/0/ClientApp/#/IntegrationDiagnostics/ExchangeListener.
Рис. 3 — Переход к диагностике настроек Email Listener
scr_open_diagnostics_page.png

Страница диагностики состоит из нескольких блоков с параметрами синхронизации, по которым можно запустить диагностику (Рис. 4). Чтобы отобразилась информация о параметрах подключения, необходимо в блоке с интересующим вас параметром нажать Запустить диагностику.

Рис. 4 — Диагностика настроек Email Listener
chapter_exchange_listener_diagnostics_page_full.png

Состояние доступности функциональности

Для данного блока диагностика запускается автоматически при открытии страницы.

Выполняется проверка подключения в Creatio функциональности Email Listener:

  • ExchangeListenerEnabled;
  • EmailIntegrationV2;
  • SendEmailsV2.

Подробнее о подключении функциональности читайте в статье Механизм отключения функциональности Feature Toggle документации по разработке.

Проверка доступности сервиса

Выполняется проверка доступности сервиса Email Listener из вашего приложения Creatio.

Получение информации по подпискам

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

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

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

Проверка работоспособности почтового ящика

Выполняется проверка работы почтовых ящиков MS Exchange. Установите признак Отправить тестовое письмо, чтобы при запуске диагностики на указанный адрес было отправлено тестовое email-сообщение.