Расширения позволяют простым способом, установив всего один файл, расширять функционал сервера 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 .

  •  url  - Адрес домашней страницы расширения. Например,  https://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 ничего не указано, будет показано обычное однострочное поле ввода.

Пример:

{
  "extends": {
    "config": {
      "APIKey": {
        "type": "string",
        "editPresentation": "password",
        "title": "APIKeyTitle",
        "required": true
      }
    }
  }
}

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

В расширение можно добавить файл сценария на языке 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 

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