Необходимые пакеты для работы с Omnichannel
Для использования продукта Omnichannel необходимо на систему установить следующие пакеты:
OmnichannelMessaging - пакет, разработанный Terrasoft, в котором описана вся необходимая логика создания чатов, распределения на операторов и т.д. (Доступен по умолчанию, начиная с версии 7.18.2)
BeesenderOmnichannel - пакет, в котором реализована логика взаимодействия коннектора Beesender с чатами Omnichannel.
Визуальные компоненты чатов Omnichannel от Terrasoft
В рабочих местах, раздел, в котором отображаются все имеющиеся чаты обозначается следующим образом:
На боковой панели справа располагается рабочее место оператора, которое выглядит следующим образом:
При отсутствии чатов в очереди, рабочее место оператора выглядит следующим образом
При поступлении сообщения из мессенджера в систему, в рабочем месте оператора появляется чат, который добавился в конкретную очередь, к которой относится текущий оператор. Внешний вид сообщения в очереди выглядит таким образом:
После принятия чата, в рабочем месте оператора раскрывается полностью чат, который выглядит следующим образом:
Картинки от клиента(из приложения канала) в систему приходят в следующем виде:
Файлы различного формата от клиента(из приложения канала) в систему приходят в следующем виде:
Картинки и файлы различного формата от оператора(из CRM) в приложение канала приходят в следующем виде:
Для закрытия чата из рабочего места оператора необходимо нажать на соответствующую кнопку в верхней части
Карточка чата, располагающаяся в разделе чатов выглядит следующим образом:
P.S. статистика чата проставляется на уровне логики, реализованной Terrasoft.
Необходимые системные настройки для работы чатов Omnichannel
Для работы чатов Omnichannel необходимо работать с такими системными настройками, как:
Название: OmniToken, Код: OmniToken
В данной настройке хранится токен Beesender для работы с коннектором. Данный токен индивидуальный для каждой системы и используется при синхронизации с коннектором Beesender и работе с каналами.Название: OmniConnectorHost, Код: OmniConnectorHost
Данная настройка хранит адрес коннектора Beesender (balance, bee-conn) и является аналогом настройки BeesenderOperatoHost.Название: OmniFileServiceHost, Код: OmniFileServiceHost
Данная настройка хранит адрес файлового сервиса Beesender, который участвует при отправке файлов различного формата из CRM в мессенджер.Название: OmniChannelUrl, Код: OmniChannelUrl
Данная настройка хранит путь запроса на коннектор Beesender (balance, bee-conn) для работы с каналами и является аналогом настройки BeesenderServices.Название: OmniCrmHost, Код: OmniCrmHost
В данной настройке хранится адрес текущей системы Creatio, который используется при синхронизации с коннектором Beesender.Название: OmniCrmUserLogin, Код: OmniCrmUserLogin
Настройка хранит значение логина конкретного аккаунта(с правами администратора), которое используется при синхронизации.Название: OmniCrmUserPassword, Код: OmniCrmUserPassword
Настройка хранит значение пароля конкретного аккаунта(с правами администратора), которое используется при синхронизации. В самой настройке значение будет недоступно для чтения(маскировка значения пароля).Название: OmniInstagramService, Код: OmniInstagramService
Данная настройка хранит адрес кнопки “Вход через facebook“, которая используется при добавлении канала facebook (стена и мессенджер) и инстаграм. Данная настройка является аналогом настройки BeesenderInstagramService.
Полезно для работы с системными настройками:
В случае, если вам необходимо поменять значение в системной настройке, а в самой карточке изменения не сохраняются, вы можете выполнить следующий SQL-запрос через “Консоль SQL запросов“ и таким образом поменять необходимое значение в конкретной системной настройке.
UPDATE SysSettingsValue SET TextValue = 'Необходимое значение' WHERE SysSettingsId = (SELECT Id FROM SysSettings WHERE Code = 'Код системной настройки')
Шаги для создания канала Omnichannel
1) Синхронизация с коннектором Beesender
В первую очередь, перед созданием канала, необходимо произвести синхронизацию системы с коннектором Beesender. Для проведения процесса синхронизации, необходимо в разделе “Чаты“/”Chats”, в раскрывающемся списке “Действия“/”Actions”, нажать на кнопку “Синхронизировать“/”Synchronize”.
В случае того, если на данной системе синхронизация проводится впервые, на экране появится модальное окно, требующее ввести данные для входа в CRM-систему, которые впоследствии запишутся в БД коннектора и будут использоваться для общения системы и коннектора.
Адрес системы Creatio будет подставлен автоматически и модификации не подлежит. Необходимо указать логин и пароль того аккаунта, который обладает правами администратора(например Supervisor).
После успешного сохранения, происходит синхронизация с коннектором Beesender, и в случае удачной синхронизации, на экране появится следующее модальное окно:
При каких-либо проблемах, возникающих в ходе синхронизации, пользователю также высветится в модальном окне информация об ошибке.
2) Создание приёмщика сообщений для конкретного канала
Логика создания конечной точки для принятия сообщения в конкретном мессенджере идентична чатам от Beesender. Поэтому данный пункт выполняется таким же образом, как и в статьях по добавлению каналов Beesneder. Пример: Viber .
3) Создание канала Omnichannel
Для настройки чатов существует отдельная страница, на которую можно попасть, зайдя в “Дизайнер системы“, а далее перейдя к разделу “Импорт и интеграции“ нажать на “Настройка чатов“.
P.S. если на системе стоит и Beesender и BeesenderOmnichannel, то в разделе “Импорт и интеграции“ будет две ссылки с одинаковыми названиями “Настройка чатов“. Для перехода на страницу настроек чатов именно Omnichannel, необходимо выбирать ту ссылку, которая располагается ниже.
Страница настроек чатов Omnichannel состоит из трёх деталей, где можно настраивать каналы, очереди чатов и определённые действия чатов.
P.S. Данная страница настроек чатов закрыта для модификации.
В данном списке отображаются всевозможные каналы, которые можно добавить. При нажатии на конкретный провайдер откроется страница добавления канала.
Далее будет показан пример страницы канала на примере провайдера Viber.
Страница добавления канала Viber состоит из 4 полей, таких как:
Название канала - произвольное название канала Viber, которое будет отображаться в качестве поля “Name” у записи объекта “Channel”.
Токен - токен канала Viber, который можно получить через панель администратора Viber. Подробнее тут -> Viber .
Очередь чатов - это своего рода группа операторов, в которую должен входить тот аккаунт, на которого вы хотите повесить конкретный чат. Это справочное поле и выбор производится на основе записей объекта “ChatQueue”. Всевозможные операции над “очередью чатов” можно производить на странице “Настройка чатов“ в соответствующей детали, как показано на рисунке выше.
Активен - статус канала, который влияет на создание чата.
Страница редактирования канала Viber отображается в таком же стиле, за исключением появления новой кнопки “Актуализировать“, позволяющей поменять значение WebHook при смене коннектора Beesender.
Для модификации конкретного канала или очереди чата, необходимо нажать на поле “Название“, которое является ссылкой. Страница редактирования “Очереди чатов“, где можно указывать нужного оператора, выглядит следующим образом:
4) Инициирование чата Omnichannel
После создания канала, для инициирования чата, необходимо из мессенджера написать сообщению связующему с CRM звену (написать боту, оставить пост на стене и т.д.). После чего, чат будет создан и направлен в очередь тому оператору, который указан в “Очереди чатов“, привязанной к каналу. То, каким образом происходит коммуникация оператора и клиента указано в пункте “Визуальные компоненты чатов Omnichannel от Terrasoft“, который размещён выше.
Информация для разработки
1) Компоненты (список должен пополнятся с выходом доработок)
1.Клиентские схемы:
OmniChannelPage - родительская страница для всех всех страниц добавления/редактирования канала.
OmniChannelCss - Модуль для описания CSS стилей в новых визуальных модулях (таких как ViberChannelPage)
ViberChannelPage - страница добавления и редактирования канала Viber.
WebSiteChannelPage - страница добавления/редактирования канала WebSite (Widget Beesender).
InstagramChannelPage - страница добавления/редактирования канала Instagram.
BsOmniChatConfigurationPage - модальное окно для заполнения полей для входа в систему Creatio при первой синхронизации.
LicenseOrderPage - страница получения токена для лицензии.
P.S. У визуальных модулей присутствует свой не визуальный модуль с таким же названием, только на конце используется слово Module. а не Page. Пример: ViberChannelPage и ViberChannelModule. В этих модулях как правило описаны стили во вкладке LESS, которые касаются только этого визуального модуля.
2.Исходный код:
BsOmniChatSetupService - веб-сервис, который вызывается из BsOmniChatConfigurationPage и OmniChatSection при синхронизации и работе с системными настройками.
BsOmniSynchronizer - класс, в котором реализована логика синхронизации с коннектором Beesender.
BsOmniChannelService - веб-сервис, который вызывается в ViberChannelPage при добавлении, обновлении и актуализации канала Omnichannel.
BsOmniChannelHandler - класс, в котором реализована вся необходимая логика для работы с каналами.
BsOmniMessagingService - веб-сервис, который вызывается коннектором при отправке сообщения от клиента(из мессенджера) в CRM-систему.
BsOmniIncomingMessageHandler - класс, в котором реализована логика создания и распределения чата на оператора.
BsOmniOutcomeMessageWorker - класс в котором реализована логика отправки сообщения из CRM-системы на коннектор.
BsOmniFileUploader - класс для обработки файлов из CRM через файловый сервис Beesender, перед отправкой на коннектор.
BsOmniExtensions - файл, в котором собраны все необходимые классы-расширения для имеющихся типов.
BsOmniEnums - файл, в котором собраны все необходимые перечисления (enums), необходимые для работы с каналами Omnichannel.
BsOmniHelper - файл, в котором собраны все вспомогательные классы, необходимые для работы с каналами Omnichannel (логгер, класс для работы с системными настройками и т.д.)
BsOmniAppEventListener - класс для маппинга необходимых интерфейсов от Terrasoft для работы с каналами Omnichannel.
BsOmniModels - файл, в котором собраны все необходимые модели данных, необходимые для работы каналов Omnichannel.
BsOmniIncomingMessageConverter - класс для конвертации пришедшего от коннектора сообщения в формат “MessagingMessage”, необходимый для работы логики чатов на уровне Terrasoft.
BsOmniMsgSettingsHandler - класс для работы с именной таблицей настроек конкретного канала BsOmni{Имя провайдера}MsgSettings.
BsOmniMsgSettingsExecutor - набор пользовательских типов данных для работы с BsOmni{Имя провайдера}MsgSettings, состоящий из интерфейса IBsOmniMsgSettingsExecutor и его реализаций под конкретные каналы.
BsOmniProviderHandler - набор пользовательских типов данных для индивидуальной работы с каждым провайдером в ходе добавления канала, обработки входящих и исходящих сообщений и так далее. Данная схема исходного кода состоит из интерфейса IBsOmniProviderHandler и его реализаций под конкретные каналы. Не для всех каналов есть реализации в связи с ненадобностью использования отдельного класса.
BsOmniProfileDataProvider - класс, реализующий интерфейс IProfileDataProvider от Terrasoft и предназначен для отображения данных о клиенте. Используется в BsOmniAppEventListener.
BsOmniAttachmentLoadWorker - класс, реализующий интерфейс IAttachmentsLoadWorker от Terrasoft и предназначен для работы с файлами. Используется в BsOmniAppEventListener.
BsOmniCrmRequestHelperService - веб-сервис, который даёт возможность отправить запрос в другую crm систему (Creatio).
BsOmniContactHandler - класс, в котором реализована вся необходимая логика для работы с контактом, который привязан к чату.
3.Бизнес-процессы:
DeletingEntryFromMsgsettingsTable - БП для удаления записи из объекта “BsOmni{Имя провайдера}MsgSettings” при удалении записи из объекта “Сhannel“.
AttachFileToChat - БП для записи сообщения из чата в объект “OmnichannelMessagefile“ до его закрытия. Это связано с тем, что все сообщения конкретного чата записываются в объекты “ChatMessages“ и “OmnichannelMessagefile“ только после закрытия чата, что мешает отображению файлов в РМО.
4.Объекты:
BsOmniLog - логгер (аналог BeesenderLog). В основном для поиска ошибок используется такой шаблон наименования логов: “Название класса“.”Название метода”Error. Пример: "BsOmniIncomingMessageHandler.ExecuteError"
BsOmniClient - пользователь мессенджера, на основе которого создаётся контакт в системе (аналог BeesenderClient)
BsOmniViberMsgSettings - именной объект для настроек канала Viber.
BsOmniInstagramMsgSettings - именной объект для настроек канала Instagram.
BsOmniWebSiteMsgSettings - именной объект для настроек канала WebSite.
Channel - канал, который хранит ссылку на объект из таблицы BsOmni{Имя провайдера}MsgSettings. Реализация Terrasoft.
ChatQueue - очереди чатов (группа операторов), в которой хранится название самой группы. Реализация Terrasoft.
ChatQueueOperator - оператор в конкретной очереди чатов. Реализация Terrasoft.
OmniChat - чат. Реализация Terrasoft.
ChannelProvider - конкретный провайдер канала (Viber, Telegram и т.д.), в котором должна указываться ссылка на страницу создания и модификации канала (поле “PageUrl“). Реализация Terrasoft.
OmnichannelMessageFile - файлы в чате. Реализация Terrasoft.
ChatMessages - текстовые сообщения в чате. Реализация Terrasoft.
OmnichannelChatStatus - статус чата. Реализация Terrasoft.
OperatorRoutingRules - правила распределения чатов на группу операторов. Реализация Terrasoft.
2) Инструкция по внедрению нового канала в Omnichannel
Документ с вопросами к Terrasoft касаемо устройства механизма чатов Omnichannel ->https://creatiocom-my.sharepoint.com/:w:/g/personal/n_kostruba_creatio_com/EdPF2QIn_sRIj-L-znKBDk0B10K3rNpzvkJ5D_jHHWR5sw?rtime=J7eoRhtV2kg
1. Создать таблицу настроек канала конкретного провайдера.
Перед внедрением нового канала в механизм чатов Omnichannel, необходимо создать специальную таблицу, в которой будут хранится все необходимые данные канала, такие как токен, секретные ключи и прочее, чего требует тот или иной провайдер.
Шаблон названия такой таблицы: BsOmni{Имя провайдера}MsgSettings
Придерживаться данному шаблону необходимо для корректной работы логики, реализованной нами. Колонки такой таблицы будут индивидуальны для конкретного провайдера и могут содержать всё необходимое. Id добавленной записи в конкретную таблицу будет служить внешним ключом для записи в таблице Channel.
2. Создать страницу для добавления и изменения канала
В связи с тем, что у нас нет возможности модифицировать страницу настроек чатов Omnichannel, которая была реализована со стороны Terrasoft, мы не можем создавать модальные окна для каналов, как это реализовано для Telegram, WhatsApp и FBM. Однако мы можем оставить ссылку на страницу, где можно проводить нужные манипуляции. Ссылка будет хранится в типе провайдера канала на детали каналов(об этом подробнее будет в следующих пунктах).
Для добавления страницы конкретного канала, необходимо создать два модуля:
{Название провайдера канала}ChannelPage - визуальный модуль представления страницы добавления и изменения конкретного канала. Данные модули должны наследоваться от OmniChannelPage. В качестве хранилища необходимых CSS-стилей можно использовать модуль OmniChannelCss либо же не визуальный модуль, который вызывает визуальный.
{Название провайдера канала}ChannelModule - не визуальный модуль для вызова визуального модуля, описанного выше.
В унаследованных визуальных модулях {Название провайдера канала}ChannelPage, для совершения тех или иных действий на странице, необходимо реализовать следующие методы, в которых будут производится вызовы методов веб-сервиса BsOmniChannelService:
addChannel - для добавления канала при нажатии на кнопку “Add“/”Добавить”. Метод веб-сервиса: AddChannel. Callback переопределять необязательно.
saveChannel - для сохранения изменений канала при нажатии на кнопку “Save“/”Сохранить” (режим изменения канала). Метод веб-сервиса: UpdateChannel. Callback переопределять необязательно.
actualizeChannel - для актуализации канала (если того требует провайдер канала) при нажатии на кнопку “Actualize“/”Актуализировать”. Метод веб-сервиса: ActualizeChannel. Callback переопределять необязательно.
addDataFromMsgSettingsTable - для загрузки необходимых данных канала из именной таблицы настроек канала BsOmni{Имя провайдера}MsgSettings, на страницу(режим изменения канала).
При передаче тела запроса в метод веб-сервиса, все данные канала, которые относятся к конкретному провайдеру и которые указаны в именной таблице настроек канала BsOmni{Имя провайдера}MsgSettings, должны быть упакованы в объект channelData, который будет вложенным для объекта, который передаётся в метод веб-сервиса.
Важно! Объект channelData необходимо переводить в строку, используя метод JSON.stringify() и вкладывать его внутрь объекта, которая передаётся в качестве тело запроса на веб-сервис.
Также необходимо переопределить метод init(), для установления значения атрибуту "ProviderName" в виде названия провайдера канала, который участвует в определении локализуемых строк на странице и отправке данных на веб-сервис. После присвоения значения, необходимо вызвать метод this.callParent(arguments).
Атрибуты "ChannelId" и "MsgSettingsId" инициализируются в родительской схеме OmniChannelPage и не требуют явного определения в дочерних схемах.
В родительском модуле OmniChannelPage реализованы атрибуты и компоненты diff, относящиеся к объекту Channel, которые можно использовать в унаследованных схемах:
Атрибут: ChannelName (TEXT) (В объекте Name). Компонент diff: ChannelNameInput.
Атрибут: ChatQueue (LOOKUP) (В объекте ChatQueue.Id и ChatQueue.Name). Компонент diff: ChatQueueList.
Атрибут: ChatLanguage (LOOKUP) (В объекте Language.Id и Language.Name). Компонент diff: ChatLanguageList.
Атрибут: IsActive (BOOL) (В объекте IsActive). Компонент diff: IsActiveCheck.
Все необходимые поля для канала, которые будут браться из объекта BsOmni{Имя провайдера}MsgSettings необходимо в унаследованном модуле определять самостоятельно.
P.S. В качестве примера можно взять модуль ViberChannelPage и делать по аналогии
3.Создать запись в таблице провайдеров каналов
После создания визуального и не визуального модуля для добавления и изменения конкретного канала, необходимо добавить провайдер канала в объект ChannelProvider. Это необходимо для того, чтобы появилась возможность работать с конкретным каналом через деталь “Channels” на странице “ChatSettings”
Необходимые поля для заполнения при добавлении записи в объект ChannelProvier:
Name - название провайдера канала, которое входит в состав названия объекта BsOmni{Имя провайдера}MsgSettings. Пример: Viber, WebSite.
IconId - Id иконки канала из объекта SysImage.
PageUrl - путь к странице для работы с каналом, который должен быть записан в следующем формате:
Nui/ViewModule.aspx#{Название не визуального модуля}/{Название визуального модуля}
4. Добавление необходимых классов в схемах исходного кода
Для того, чтоб можно было добавлять записи в именную таблицу настроек канала, необходимо создать класс, который будет реализовывать интерфейс IBsOmniMsgSettingsExecutor. Реализацию необходимо исполнять в схеме BsOmniMsgSettingsExecutor. Шаблон названия класса:
BsOmni{Название провайдера канала}SettingsExecutor
В данном классе, необходимо реализовать следующие методы:
Dictionary<string, string> ParseChannelDataJson(JObject json) - метод для парсинга json объекта channelData, который приходит из визуального модуля страницы добавления/изменения канала. В данном методе результат парсинга записывается в Map, где ключом является название колонки в объекте, а значением непосредственно само значение атрибута из json.
void SetMsgSettingsColumnsForAdding(Insert insert, Dictionary<string, string> channelData) - метод для добавления необходимых колонок в запрос на добавление записи в объект BsOmni{Имя провайдера}MsgSettings.
void SetMsgSettingsColumnsForUpdating(Update update, Dictionary<string, string> channelData) - метод для добавления необходимых колонок в запрос на обновление записи в объекте BsOmni{Имя провайдера}MsgSettings.
P.S. В качестве примера можно взять класс BsOmniWebSiteSettingsExecutor и делать по аналогии
В случае того, если при добавлении канала необходимо отправлять запросы на коннектор, то можно воспользоваться веб-сервисом BsOmniChannelService, а уже в нём, для реализации логики работы конкретного канала, можно создать экземпляр именного класса-обработчика. Шаблон названия такого класса: BsOmni{Название провайдера канала}Handler
P.S. В качестве примера можно взять модуль BsOmniWebSiteHandler и делать по аналогии
5. Расширение конкретных участков реализации логики работы каналов
В первую очередь, при внедрении нового канала, необходимо дополнить методы:
BindProfileDataProvider()
BindOutcomeMessageWorker()
BindAttachmentsLoadWorker()
Все они находятся в методе BindInterfaces() из класса BsOmniAppEventListener (название схемы совпадает с названием класса), следующим содержимым:
1)ClassFactory.Bind<IAttachmentsLoadWorker, BsOmniAttachmentLoadWorker>(ChannelType.{Название провайдера канала}.ToString()); в метод BindAttachmentsLoadWorker()
2)ClassFactory.Bind<IProfileDataProvider, BsOmniProfileDataProvider>(OmniChannelType.{Название провайдера канала}.ToString()); в метод BindProfileDataProvider()
3)ClassFactory.Bind<IOutcomeMessageWorker, BsOmniOutcomeMessageWorker>(OmniChannelType.{Название провайдера канала}.ToString()); в метод BindOutcomeMessageWorker()
Содержимое перечисления ChannelType хранится в схемах Terrasoft, однако аналог OmniChannelType можно найти в схеме исходного кода BsOmniEnums (взять это на заметку для дальнейших пунктов).
Важно! Во всех случаях, где необходимо использовать тип канала из перечисления, мы пользуемся только перечислением ChannelType. Перечисление OmniChannelType из схемы BsOmniEnums служит просто напоминанием о доступных типах каналов, но не применяется в реализации логики.Для добавления канала на коннекторе, необходимо правильно составить тело запроса, в котором будут находиться все необходимые поля для добавления канала в БД. Для этого необходимо в классе BsOmniChannelHandler (название схемы совпадает с названием класса), в методе DefineAllHttpRequestElementsForConnector добавить в конструкцию switch case с нужным типом канала (брать из перечисления ChannelType), в котором происходит определение конечного пути запроса, а также упаковка объекта нужными полями и перевод его в формат json для последующей отправки в качестве тела запроса на коннектор.
Для удобства, часть пути запроса для добавления канала (после services/) можно вынести в именованное поле класса ChannelPathType, которое располагается в схеме BsOmniModels. Название совпадает с именем провайдера канала.Для того, чтоб использовать нужный экземпляр IBsOmniMsgSettingsExecutor для добавления или изменения записи объекта BsOmni{Имя провайдера}MsgSettings, необходимо в методе GetMsgSettingsExecutorInstance класса BsOmniMsgSettingsHandler (название схемы совпадает с названием класса) добавить в конструкцию switch, case с созданием нужного экземпляра IBsOmniMsgSettingsExecutor, который создавался в пункте 4. Добавление необходимых классов в схемах исходного кода.
Для удобства, при составлении пути запроса на hook контроллер из коннектора, в отдельный класс HookPathType (схема BsOmniModels) можно вынести уникальное значение канала (пример: для Viber это vb). Пример можно увидеть в case с каналом Viber в конструкции switch из метода DefineAllHttpRequestElementsForConnector класса BsOmniChannelHandler.
6. Добавление канала и проверка
После выполнения всех перечисленных выше пунктов, можно произвести добавление канала, как рассказано в разделе Шаги для создания канала Omnichannel выше. В модальных окнах будет выводится результат обработки того или иного действия. Также уместно проверять объект BsOmniLog в консоли Sql/Sql Executor, для получения необходимой информации о возникающих ошибках.