CommuniGate Pro
Версия 6.3
Разное
 
 
Расширения
 

Расширения

Расширения позволяют простым способом, установив всего один файл, расширять функционал сервера CommuniGate и его пользовательского интерфейса, не прибегая к модификации встроенного функционала сервера.

Установить расширение, скачанное с сайта communigatepro.ru или разработанное самостоятельно, можно в разделе Пользователи → Расширения интерфейса администрирования Dash.



Формат файла расширения

Файл расширения представляет собой ZIP-архив с расширением .cgplugin.

В корне архива обязательно должен находиться файл описания расширения cgplugin.json. JSON-Schema для него: cgplugin.schema.json.

Основные параметры файла конфигурации расширения:

  • id (обязательно) - Название расширения. Латиница, цифры и подчёркивание. Должно быть уникальным для конкретного расширения. Рекомендуется использовать обратную запись названия домена перед именем расширения, например, ru_communigatepro_ExamplePlugin
  • author (обязательно) - Имя автора расширения. Например, Ivan Ivanov или AO SBK
  • version (обязательно) - Версия расширения по SemVer 2.0. Например, 1.0.0
  • title (обязательно) - Имя поля из словарей локализации, которое будет использоваться при отображении расширения в интерфейсе администрирования. Например, PluginTitle.
  • description (необязательно) - Имя поля из словарей локализации, которое будет использоваться при отображении описания расширения в интерфейсе администрирования. Например, PluginDescription.
  • url - Адрес домашней страницы расширения. Например, https://communigatepro.ru/
  • icon - Опциональное имя файла иконки из архива для отображения расширения при просмотре его через интерфейс администрирования. Иконка должна быть в формате svg и иметь пропорции 1:1 (квадратные).
  • min_product_version - Опциональный параметр, который указывает минимальную версию сервера, необходимую для корректной работы плагина. Если параметр не указан, предполагается, что плагин совместим со всеми версиями сервера.

Локализация

При загрузке расширения из него автоматически загружаются доступные файлы локализации с расширением .data в формате Словарей CommuniGate Pro.

Данные из этих словарей будут доступны другому коду, в том числе, скриптам на CG/PL, содержащимся в расширении, с префиксом вида <id расширения>..

Точки расширения

Список точек расширения заполняется в секции extends файла описания. Доступны несколько типов расширений, описанные ниже.

Параметры конфигурации

Описываются в секции config в виде объекта с описаниями параметров конфигурации. Каждый ключ - идентификатор одного параметра конфигурации, под которым он будет храниться и передаваться запускаемым из расширения скриптам CG/PL.

  • type (обязательно) - Тип параметра, используется для выбора формата хранения параметра и типа отображаемого в интерфейсе администрирования виджета. На данный момент поддерживаются только параметры типов string и boolean.
  • title (обязательно) - Строка из файлов локализации, которая будет использоваться при отображении названия параметра в интерфейсе администрирования.
  • required - Обязателен ли параметр конфигурации для заполнения (если поле отсутствует, параметр необязательный).
  • editPresentation - Позволяет указать способ отображения элемента управления для параметра. Для типа string поддерживаются password и multilineText. Если для string ничего не указано, будет показано обычное однострочное поле ввода.
  • enum - Позволяет задать несколько допустимых вариантов для параметра конфигурации.
  • enumTitle (обязательно, если есть enum) - Строка из файлов локализации, которая указывает на словарь, который будет использоваться при отображении вариантов параметра конфигурации в интерфейсе администрирования.

Пример:

{
  "extends": {
    "config": {
      "APIKey": {
        "type": "string",
        "editPresentation": "password",
        "title": "APIKeyTitle",
        "required": true
      },
      "ServerType": {
        "type": "string",
        "enum": ["proxy", "DNS", "mail"],
        "enumTitle": "ServerTypeEnumTitle",
        "required": true,
        "title": "ServerTypeTitle"
      }
    }
  }
}

Проверка параметров конфигурации

В расширение можно добавить файл сценария на языке CG/PL, выполняющий проверку корректности заполнения параметров конфигурации. Данный файл должен находиться в архиве с расширением.

Такой файл сценария может как выполнять базовые проверки по регулярным выражениям или заполнению полей, так и проверять корректность введённых параметров путём обращения к внешнему серверу. В файле сценария должен содержаться метод checkConfig, выполняющий проверку параметров конфигурации, доступных ему через свойство pluginSettings окружения запуска сценария.

Пример параметра:

{
  "extends": {
    "config": {
      "APIKey": {
        "type": "string",
        "title": "APIKeyTitle",
        "required": true
      }
    },
    "checkConfig": "checkconfig.scgp"
  }
}

Пример файла сценария:

entry checkConfig {
  var settings = Vars().pluginSettings;

  if (Length(settings.APIKey) != 10) {
    SetResult("invalid API key")
  }
}

Видеоконференции

Описываются в секции vcs в виде объекта с описаниями предоставляемых расширением скриптов для интеграции систем видеоконференцсвязи (далее - ВКС). Ключ - идентификатор, который будет использоваться для определения конкретной системы ВКС внутри CommuniGate Pro. Каждое описание - объект со следующими параметрами:

  • title (обязательно) - Строка из файлов локализации, которая будет использоваться при отображении параметра в интерфейсе пользователя.
  • script (обязательно) - Имя (с расширением) находящегося в архиве файла сценария на языке CG/PL, реализующего интеграцию с ВКС.
  • icon - Опционально: имя svg-файла с пиктограммой из архива. Пиктограмма будет отображаться пользователю в элементах интерфейса, связанных с конкретной системой видеоконференций. Она должна иметь пропорции 1:1 (квадратные).

Пример:

{
  "extends": {
    "vcs": {
      "bbb": {
        "title": "BBBTitle",
        "script": "bbb.scgp",
        "icon": "bbb.svg"
      }
    }
  }
}

Каждый модуль поддержки видеоконференции должен быть отдельным сценарием CG/PL в формате scgp.

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

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

createConf

Создаёт видеоконференцию.

Параметры:

title
(опционально) Тема конференции.
description
(опционально) Подробное описание темы конференции.
isAllDay
(опционально) Флаг, определяющий тип конференции, если конференция длится целый день с 0 до 24 часов - 1, если конференция имеет любое другое время начало и конца - 0.
from
(опционально) Время начала конференции в UnixTime.
duration
(опционально) Продолжительность конференции в секундах.
offset
(опционально) Смещение временной зоны организатора относительно UTC (0) в секундах.
participants
(опционально) Массив объектов, описывающих участников конференции.
name
(опционально) Имя участника
email
Адрес e-mail участника

Возвращаемое значение:

cid
ID созданной конференции в строковом формате или ID созданной конференции и дополнительные параметры, если есть, в Base64Url после создания ВКС. Строка должна быть URL friendly и не содержать пробелов, двоеточия.
link
Общая ссылка на подключение к конференции.
participantLinks

(опционально) Словарь объектов, содержащих в себе индивидуальные ссылки на подключение к конференции для всех зарегистрированных участников. Если данная интеграция не поддерживает создание индивидуальных ссылок, параметр можно не указывать, ключ в словаре - aдрес e-mail участника, значение - индивидуальная ссылка для подключения к конференции:

Параметры:

email
(опционально) Адрес e-mail участника
link
индивидуальная ссылка для подключения к конференции

Ошибка:

error
Текстовое описание ошибки при создании конференции
updateConf

Обновляет видеоконференцию.

Параметры:

ID
Идентификатор конференции или идентификатор конференции и дополнительные параметры в Base64Url, необходимые для обновления ВКС.
isAllDay
(опционально) Флаг, определяющий тип конференции, если конференция длится целый день с 0 до 24 часов - 1, если конференция имеет любое другое время начало и конца - 0.
from
(опционально) Время начала конференции в UnixTime.
duration
(опционально) Продолжительность конференции в секундах.
offset
(опционально) Смещение временной зоны организатора относительно UTC (0) в секундах.
participants
(опционально) Массив объектов, описывающих участников конференции.
name
(опционально) Имя участника
email
Адрес e-mail участника

Возвращаемое значение:

cid
(опционально, возвращается, если при обновлении удалилась старая ВКС)ID созданной конференции в строковом формате. Строка должна быть URL friendly и не содержать пробелов, двоеточия.
link
(опционально, возвращается, если при обновлении удалилась старая ВКС)Общая ссылка на подключение к конференции.
participantLinks

(опционально) Словарь объектов, содержащих в себе индивидуальные ссылки на подключение к конференции для всех зарегистрированных участников. Если данная интеграция не поддерживает создание индивидуальных ссылок, параметр можно не указывать, ключ в словаре - aдрес e-mail участника, значение - индивидуальная ссылка для подключения к конференции:

Параметры:

email
(опционально) Адрес e-mail участника
link
индивидуальная ссылка для подключения к конференции

Ошибка:

error
Текстовое описание ошибки при обновлении конференции
deleteConf

Удаляет видеоконференцию.

Параметры:

ID
идентификатор конференции или идентификатор конференции и дополнительные параметры в Base64Url, необходимые для удаления ВКС (ID и дополнительные параметры, закодированные в Base64Url, разбирает сам плагин на своё усмотрение).

Возвращаемое значение:

Ошибка:

error
Текстовое описание ошибки при удалении конференции

Занятость участников

Описывается в секции freebusy в виде объекта с описаниями предоставляемых расширением скриптов для получения информации о занятости (далее - Free/Busy). Ключ - идентификатор, который будет использоваться для определения типа сервера, откуда будет загружаться информация о занятости внутри CommuniGate Pro. Каждое описание - объект со следующими параметрами:

  • title (обязательно) - Строка из файлов локализации, которая будет использоваться при отображении в интерфейсе пользователя типа подключаемого источника.
  • script (обязательно) - Имя (с расширением) находящегося в архиве файла сценария на языке CG/PL, реализующего получение информации о занятости.
  • config (опционально) - Параметры, передаваемые в скрипт, аналогичны параметрам расширения. Доступны в скрипте в словаре Vars().freebusySettings.
  • checkConfig (опционально) - Имя (с расширением) находящегося в архиве файла сценария на языке CG/PL, реализующего проверку параметров FreeBusy (из секции config выше).

Пример:

{
  "extends": {
    "config": {},
    "freebusy": {
      "CommunigatePro": {
        "title": "CommunigateProTitle",
        "script": "freebusy.scgp",
        "config": {
          "Host": {
            "type": "string",
            "required": true,
            "title": "HostTitle"
          }
        },
        "checkConfig": "checkFreeBusyConfig.scgp"
      }
    }
  }
}

Каждый модуль получения информации о доступности / занятости участников (Free/Busy) должен быть отдельным сценарием CG/PL в формате scgp.

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

getFreeBusy

Получение информации Free/Busy.

Параметры:

email
(обязательно) e-mail пользователя для которого запрашивается информация. Находится в словаре Vars().startParameter
timeStart
(опционально) Начало запрашиваемого периода информации о занятости в формате временной метки. Находится в словаре Vars().startParameter
timeEnd
(опционально) Окончание запрашиваемого периода информации о занятости в формате временной метки. Находится в словаре Vars().startParameter

Возвращаемое значение: строка в формате iCalendar Object RFC 5545, section 3.4, включающий в себя компонент RFC 5545, section 3.6.4. В случае ошибки должна возвращаться пустая строка.

Каждой функции доступны в точке вызова следующие данные:

pluginSettings
Общие настройки расширения, описанные в extends/config
freebusySettings
Настройки домена получения Free/Busy, описанные в extends/freebusy/freebusy_id/config
Host
Host адрес почтового сервера для домена
...
Остальные параметры, указанные в секции extends/freebusy/config и настроеные администратором сервера/домена.
startParameter
параметры выполнения функции получения Free/Busy.
email
Как описано выше включает e-mail пользователя

Пример файла сценария:

entry getFreeBusy is

  // email передаётся в словаре startParameter
  var param = Vars().startParameter;
  var email = param.email;
  var timeStart = param.timeStart;
  var timeEnd = param.timeEnd;
  if (isDate(timeStart)) {
    // обработать временные данные
  }

  // pluginSettings и freebusySettings общие для запросов на данный Free/Busy домен (в сервере передаётся как переменные среды окружения env)
  var pluginSettings = Vars().pluginSettings;
  var freebusySettings = Vars().freebusySettings;

  var host = freebusySettings.Host;

  // отправиляем запрос за информацией
  var params = NewDictionary();
  params.responseFormat = "";
  var url = host + "~" + email + "/freebusy.vfb";
  var httpResult = HTTPCall(url, params);
  if (isString(httpResult)) {
    SetResult(httpResult);
  } else {
    SetResult(httpResult.body);
  }

end entry;

Файл сценария проверки параметров получения информации о доступности / занятости участников (Free/Busy) может как выполнять базовые проверки по регулярным выражениям или заполнению полей, так и проверять корректность введённых параметров путём обращения к внешнему серверу. Это должен быть отдельный сценарий в формате scgp. В файле сценария должен содержаться метод checkConfig, выполняющий проверку параметров конфигурации Free/Busy, доступных ему через словарь Vars().freebusySettings окружения запуска сценария. Так же доступны общие парамеры расширения в словаре Vars().pluginSettings.

Пример файла сценария проверки параметров Free/Busy:

entry checkConfig {
  // Общие настройки расширения, если необходимы
  var pluginSettings = Vars().pluginSettings;

  // Настройки Free/Busy
  var freebusySettings = Vars().freebusySettings;


  if (Length(freebusySettings.Host) == 0) {
    SetResult("Host is empty");
    stop;
  }

  if (Length(freebusySettings.Password) < 6) {
    SetResult("Password too short");
    stop;
  }

  var req = NewDictionary();
  req.method = "GET";
  var res = HTTPCall(freebusySettings.Host), req);

  if (!res.isDictionary()) {
    SetResult("failed to connect to server");
    stop;
  }

}
Руководство CommuniGate Pro. Copyright © 2024, АО Система Безопасных Коммуникаций