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

Расширения

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

Установить расширение, скачанное с сайта old.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://old.communigatepro.ru/
  • icon - Опциональное имя файла иконки из архива для отображения расширения при просмотре его через интерфейс администрирования. Иконка должна быть в формате svg и иметь пропорции 1:1 (квадратные).

Локализация

При загрузке расширения из него автоматически загружаются доступные файлы локализации с расширением .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
(опционально) Подробное описание темы конференции.
participants
(опционально) Массив объектов, описывающих участников конференции.
name
(опционально) Имя участника
email
Адрес e-mail участника

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

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

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

Ключ в словаре - aдрес e-mail участника, значение - индивидуальная ссылка для подключения к конференции.

Ошибка:

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, АО Система Безопасных Коммуникаций