Настроить сервис синхронизации 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.

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

Способы развертывания сервиса 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
   

   На заметку. Если вам нужно отключить маркировку загружаемых писем категорией “С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.

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

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

   

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

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

   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.

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