API сервера унифицированных коммуникаций CommuniGate Pro

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

В случаях с коммуникациями к этому обычно добавляется потребность в дополнительной обработке корреспонденции, звонков и сообщений, как правило, с целью безопасности, контроля сотрудников и сбора статистики.

В этой статье мы рассмотрим набор инструментов, которым располагает сервер CommuniGate Pro для

• Автоматизации административных задач
• Обработки писем и звонков
• Подключения сторонних программ и скриптов
• Построения HTML интерфейсов
• Создания UC клиентов и утилит на различных платформах

CLI

Интерфейс командной строки — стандартный способ управления многими продуктами. Удобен для автоматизации административных задач. Формат и полное описание команд выходит за рамки статьи, но их можно посмотреть в мануале, приведем лишь несколько примеров:

Доступ по poppwd

В сервере есть несколько способов доступа к CLI. Одним из самых удобных для ознакомления с командами можно считать модуль PWD. При стандартной конфигурации сервера достаточно набрать в коммандной строке ОС «telnet server.address 8106» (или «telnet server.address 106», в зависимости от ОС и версии). Изначально этот модуль был просто реализацией протокола смены пароля — poppwd:

$ telnet localhost 8106 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. 200 mymac.ru CommuniGate Pro PWD Server 6.0.5 ready <1.1381912847@mymac.ru> user postmaster 300 please send the PASS pass ****** 200 login OK, proceed newpass ****** 200 Password updated 

Но нет никакой причины, чтобы останавливаться на одной текстовой команде:

listdomains 200 data follow (mymac.ru) listaccounts mymac.ru 200 data follow {   pbx =  macnt;   postmaster =  macnt;   user1 =  macnt;   user2 =  macnt; } 

Слово macnt в этом ответе означает Multi-mailbox Account

Доступ по HTTP

CLI команды так же можно выполнить отправив простой POST или GET запрос с параметром «command» по адресу server.name:[http port]/CLI/.

Бибилиотеки

Поскольку для практических задач «голый» текстовый доступ не очень удобен, мы создали Perl и Java библиотеки для работы с CLI.

На нашем сайте есть специальный раздел, где представлены примеры CLI скриптов для решения часто попадающихся задач.

Выполнение команд CLI также возможно в протоколе XIMSS (команда «cliExecute») и в CG/PL программе (функция ExecuteCLI()), о чем мы поговорим в соответствующих разделах.

Почтовые и сигнальные правила

Наверное, причисление правил к API можно назвать натяжкой, но в Communigate Pro правила применяются не только для перенаправления писем и звонков между учетными записями и ящиками, но и передают письма сторонним программам (например различным фильтрам), запускают CG/PL программы и даже запускают скрипты в операционной системе — вобщем, активно используются для интеграции как сами по себе, так и в связке с другими API.

Сигналами в Communigate Pro называют специальные объекты, которые применяются в коммуникациях «реального времени» (Real-time). Сигнал — это единица Real-time комуникации. Различные участники(SIP, XMPP клиенты, PBX приложения, …) пересылают друг другу сигналы для организации, обрыва и обновления статусов диалогов и других действий .

Как работают правила

Правила разбиты на три уровня — серверные, доменные и уровень учетной записи (аккаунта). На каждом из этих уровней есть отдельные правила для сигналов и для почты.

У каждого правила есть имя и приоритет, у сигнальных правил есть еще условие «Когда». Чем выше приоритет — тем раньше, при одинаковых остальных условиях, сработает правило. Условие «Когда» определяет в какой момент сработает правило — на какой секунде обработки сигнала или при возникновении ошибки с определенным кодом (Не отвечает, Занято или другие ошибки):

Порядок обработки почтовых сообщений:

• Применяются все серверные правила
• Те письма, которые в результате маршрутизации попали в локальные учетные записи, обрабатываются доменными правилами и правилами в учетных записях следующим образом:
  
  • Доменные правила с приоритетом >5
  • Правила в учетной записи
  • Доменные правила с приоритетом <=5

Порядок обработки сигналов:

• Применяются серверные сигнальные правила с пустым полем «Когда» (это означает, что они применяются сразу)
• Те сигналы, которые в результате маршрутизации попали в локальные учетные записи, обрабатываются оставшимися серверными правилами (поле Когда не пустое), доменными правилами и правилами в учетных записях следующим образом:
  
  • Серверные правила с приоритетом >5
  • Доменные правила с приоритетом >5
  • Правила в учетной записи
  • Доменные правила с приоритетом <=5
  • Серверные правила с приоритетом <=5

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

Ограничение пересылки в камках домена:

Все звонки с адресатами вне определенных доменов перенаправляются на заданный адрес:

Helper

В Communigate Pro реализован Helper протокол, который позволяет пользоваться внешними по отношению к серверу программами для различных задач.

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

Пример некоторой обобщенной сессии для хелпер протокола (I — ввод в программу, O — вывод):

O: * My Helper program started I: 00001 INTF 1 O: 00001 INTF 1 I: 00002 COMMAND parameters O: 00002 OK I: 00003 COMMAND parameters I: 00004 COMMAND parameters O: * processing 00003 will take some time O: 00004 ERROR description O: 00003 OK I: 00005 QUIT O: * processed: 5 requests. Quitting. O: 00005 OK 

Здесь команда INTF — согласовывает версию протокола, а QUIT заканчивает сессию, * — это информационное сообщение на которое сервер не реагирует, но записывает в лог.

В рамках этого протокола разработаны более специализированные для:

• Обработки тела письма
• Внешней аутентификация
• Подключения баннерной системы
• Добавления RADIUS запросов в аутентификацию
• Управление распределением нагрузки в кластере

Все они подключаются на странице Настройки->Общие->Помощники WebAdmin интерфейса.

Все пути к исполняемым файлам отсчитываются от Базовой директории Communigate Pro (директория с пользовательскими данными).

Обработка тела письма

Обработчики писем запускаются почтовым правилом, например таким:

Детальное описание команд этого и других хелперов можно найти в мануале. В статье будем приводить лишь общее описание.

Хелперы такого типа используются в основном для подключения к CGPro анти-вирус и анти-спам движков.

Внешняя аутентификация

Хелпер протокол для внешней аутентификации обычно используются если:

• Нужен метод аутентификации не поддерживаемый сервером напрямую
• Часть аккаунтов расположена в другой системе (например AD)
• Нужен сложный роутинг
• Нужно внешнее управление услугами\настройками учетной записи

Примеры хелперов этого типа можно найти на этой странице.

Остальные помощники

Хелперы баннерной системы предоставляют серверу банеры для XIMSS и других (например HTTP) клиентов.
RADIUS хелперы позволяют добавить в процесс аутентификации дополнительные проверки по RADIUS протоколу.
Хелперы распределения нагрузки управляют Балансировщиком нагрузки в кластерной конфигурации Communigate Pro.

WSSP

WSSP (Web Server-side Pages) — это язык для шаблонов Web страниц.
Перед тем как говорить о WSSP, нужно замолвить пару слов про организацию Web скинов на сервере.

Каждый Web скин состоит из трех видов файлов:

• Статические файлы — графика, стили, …
• WSSP файлы
• Языковые и строковые файлы

Вместе с дистрибутивом Communigate Pro поставляется небольшой набор стандартных (stock) Web интерфейсов. Один из них безымянный (Unnamed), остальные именнованные. Эти демонстрационные скины хранятся в Application папке сервера (папка в ОС, где находится исполняемый файл) и поэтому они заменяются при обновлении сервера. Администраторы не должны изменять демонстрационные скины в своих конфигурациях, при установке обновления эти изменения могут потеряться. Вместо этого нужно воспользоваться тем, что файлы скинов образуют иерархию.

Иерархия файлов в скинах

Каждый скин может быть серверным, доменным или стандартным.

При обработке запросов от браузера пользователя серверу обычно нужно достать файлы с определенными именами из скина. При этом если файл не найден в доменном скине, то его ищут в серверном скине с таким же именем. А если не нашли в серверном, то ищут в стоковом. Если же файл по прежнему не найден и текщий скин именованный, то файл ищется в безымянных скинах.

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

То есть при таком подходе можно как проделывать небольшие изменения в стандартных скинах, так и разрабатывать свои с нуля.

Строковые файлы

.data файлы содержат текстовые данные (UFT-8) в формате CG/PL словаря эти данные используются различными модулями сервера для формирования строк в интерфейсе или в качестве значений настроек.

Эти файлы также образуют иерархию, но уже на уровне ключей в словаре, то есть если какой-то ключ отсутствует в файле strings.data домена, сервер пытается найтиего в файле strings.data на уровне сервера и т.д.

Английский язык является языком по-умолчанию для строк в интерфейсе. Если же язык пользователя (сессии) отличен от английского, значения ключей из языковых файлов (french.data, russian.data) замещают значения из strings.data файла.

Такая система позволяет включать в слегка модифицированные интерфейсы (файлы strings.data) включать только те ключи значения которых были изменены (например название компании, фирменные бренды), а не их полный набор.

Обработка запросов

Когда браузер соединяется с сервером по HTTP протоколу, сервер извлекает имя хоста из запроса и ищет домен с таким именем. Если домен найден, то сервер находит скин выбранный в качестве Web интерфейса по-умолчанию для пользователей этого домена. Запускается страница login.wssp.

Файлы wssp состоят из кода разметки (обычно HTML) с некоторыми дополнительными элементами:

• текст ограниченный с двух сторон двойным символом % (%%element%%)
• структуры такого формата —

Пример такого документа:

<html> <body>  <h1>Добро пожаловать на %%server%%. Ваш логин %%ID%%.</h1>  <!--%%IF EXISTS(lastLogin)--> Последний раз вы заходили %%lastLogin%% <!--%%ENDIF-->   </body> </html> 

После обработки сервером все специальные конструкции будут заменены на строки или массивы строк из «окружения» — значения ключей из .data файлов в скине, имя домена или других объектов в сервере, значения настроек.

Любые другие файлы просто отдаются клиенту.

Базовые демонстрационные web интерфейсы можно рассматривать как отличные иллюстрации возможностей WSSP страниц. Но WSSP довольно ограничены в вопросах преобразования форматов данных или обращения к различным модулям и выполнения каких либо действий на сервере. И тут уже на помощь приходит более мощный инструмент.

CG/PL

Про язык CG/PL и разработку PBX приложений на нем мы уже рассказывали на Хабре в этой статье.

Помимо PBX его активно используют при разработке Web интерфейсов Communigate Pro. Если открыть список файлов даже базового Web скина (Пользователи->Интерфейсы), то там будет 14 файлов с небольшими CG/PL программами, обрабатывающими HTTP запросы.

Чтобы вызвать CG/PL программу для обработки HTTP запроса, нужно записать ее в любом текстовом редакторе, сохранить как .wcgp и загрузить в какой-либо Web скин.

После этого запрос к URL вида:

http://domain.name:[port]/programFile.wcgp/?Skin=skin_name 

Запустит программу на выполнение.

http://domain.name:[port]/auth/programFile.wcgp/?Skin=skin_name 

Запустит на выполнение от имени аккаунта с предварительной аутентификацией

http://domain.name:[port]/sys/programFile.wcgp 

Этот запрос ищет программу только в серверном Unnamed скине и запускает от имени пользователя postmaster (серверный администратор)

В качестве примера рассмотрим небольшой скрипт выполняющий CLI команду «listaccounts» и преобразующий результат в JSON формат:

entry sysEntry is  void(executeCLI("listaccounts mymac.ru")); accountList = Vars().executeCLIResult;  SetHTTPResponseCode(200); SetHTTPResponseData(ObjectToJSON(accountList));  end entry; 

XIMSS

При таком большом количестве функциональности на стороне сервера — голос, мгновенные сообщения (включая СМС), календари, контакты, почта, файловый сервер у провайдеров сервиса возникают определенные сложности с написанием унифицированного клиента. Нужно подобрать или разработать библиотеки реализующие SIP, набор *DAV протоколов, SMTP, IMAP, XMPP. При этом нагрузка по разбору сообщений и форматов данных из этих протоколов ложится на клиент.

Как решение этих проблем мы разработали протокол XIMSS — XML Interface to Messaging, Scheduling and Signaling.

Все команды этого протокола — простые XML документы с прозрачными по смыслу атрибутами. Например эта простая команда перенаправит (fork) входящий звонок на двух пользователей:

C:
user1@example.comuser2@example.com

S:/>

Все форматы данных (MIME, vCard) приходят XIMSS клиенту в удобном для использования виде.

Также этот протокол позволяет выполнять все CLI команды доступные на сервере — через него можно регулировать все виды настроек, включая административные

Для ряда платформ нами разработаны готовые XIMSS библиотеки.

В качестве примеров возможностей XIMSS клиентов рекомендуем серию приложений Pronto!, Web версии которых (HTML5 и Flash) можно попробовать на нашем стенде bestvoip.ru.

В заключение

Communigate Pro это платформа, поведение которой можно регулировать на разных уровнях. От клиента до доступа в основные коммуникационные модули и разработки собственной функциональности на базе стандартных протоколов. При этом решение стабильно и выдерживает большие нагрузки.

Несмотря на то, что входной порог во все Communigate API в совокупности может казаться довольно большим, они покрывают большинство задач стоящих перед администраторами коммуникационных сервисов.