Расширения

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

Пример:

json

{
  "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 окружения запуска сценария.

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

json

{
  "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 (квадратные).

Пример:

json

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

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

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

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

Точка входа `createConf`

createConf
Создаёт видеоконференцию.
Параметры доступны в словаре Vars().startParameter:
- title (опционально)
  Тема конференции.
- description (опционально)
  Подробное описание темы конференции.
- isAllDay (опционально)
  Флаг, определяющий тип конференции, если конференция длится целый день с 0 до 24 часов - 1, если конференция имеет любое другое время начало и конца - 0.
- rRule (опционально)
  Правило повторения события и ВКС, согласно RFC5545, section 3.8.5.3.
  Примеры:
  - FREQ=DAILY;UNTIL=20241215T000000Z
    ежедневное повторение, до 15 декабря 2024 г.
  - FREQ=WEEKLY;BYDAY=SU,MO,TU,WE,TH,FR
    еженедельное повторение каждый день недели.
  - FREQ=MONTHLY;INTERVAL=2;BYMONTHDAY=2;UNTIL=20250328T000000Z
    ежемесячно каждый второй месяц второй день до 28 марта 2025 г.
  - FREQ=MONTHLY;BYDAY=-1SU,-1MO,-1TU,-1WE,-1TH,-1FR,-1SA;UNTIL=20250319T000000Z
    ежемесячно каждый последний понедельник, вторник, среду, четверг, пятницу, субботу, воскресенье до 19 марта 2025 г.
  - FREQ=MONTHLY;INTERVAL=2;BYDAY=1SU,1TU,1FR;UNTIL=20250321T000000Z
    ежемесячно каждый второй месяц каждый первый вторник, пятницу, воскресенье до 21 марта 2025 г.
  - FREQ=YEARLY;BYMONTH=4;BYMONTHDAY=6;UNTIL=20261231T000000Z
    ежегодно каждый четвертый месяц каждое шестое число до 31 декабря 2026 г.
- from (опционально)
  Время начала конференции в UnixTime.
- duration (опционально)
  Продолжительность конференции в секундах.
- offset (опционально)
  Смещение временной зоны организатора относительно UTC (0) в секундах.
- participants (опционально)
  Массив объектов, описывающих участников конференции.
  - name (опционально)
    Имя участника
  - email
    Адрес e-mail участника
Возвращаемое значение - словарь с полями:
- cid
  ID созданной конференции в строковом формате или ID созданной конференции и дополнительные параметры, если есть, в Base64Url после создания ВКС. Строка должна быть URL friendly и не содержать пробелов, двоеточия.
- link
  Общая ссылка на подключение к конференции.
- participantLinks (опционально)
  Cловарь, содержащих в себе индивидуальные ссылки на подключение к конференции для всех зарегистрированных участников. Если данная интеграция не поддерживает создание индивидуальных ссылок, параметр можно не указывать, ключ в словаре - aдрес e-mail участника, значение - индивидуальная ссылка для подключения к конференции:
- description (опционально)
  Подробное описание темы конференции. Если поле будет возвращено, то оно перезапишет данное поле в календарном событии. Возвращённая пустая строка очистит поле в календарном событии.
Ошибка:
- error
  Текстовое описание ошибки при создании конференции. Если произошла ошибка, поле должно присутствовать.

Точка входа `updateConf`

updateConf
Обновляет видеоконференцию.
Параметры доступны в словаре Vars().startParameter. Аналогичны параметрам точки входа createConf плюс cid.
- cid
  Идентификатор конференции или идентификатор конференции и дополнительные параметры в Base64Url, необходимые для обновления ВКС.
- title (опционально)
  Тема конференции.
- description (опционально)
  Подробное описание темы конференции.
- isAllDay (опционально)
  Флаг, определяющий тип конференции, если конференция длится целый день с 0 до 24 часов - 1, если конференция имеет любое другое время начало и конца - 0.
- rRule (опционально)
  Правило повторения события и ВКС, согласно RFC5545, section 3.8.5.3.
  Примеры:
  - FREQ=DAILY;UNTIL=20241215T000000Z
    ежедневное повторение, до 15 декабря 2024 г.
  - FREQ=WEEKLY;BYDAY=SU,MO,TU,WE,TH,FR
    еженедельное повторение каждый день недели.
  - FREQ=MONTHLY;INTERVAL=2;BYMONTHDAY=2;UNTIL=20250328T000000Z
    ежемесячно каждый второй месяц второй день до 28 марта 2025 г.
  - FREQ=MONTHLY;BYDAY=-1SU,-1MO,-1TU,-1WE,-1TH,-1FR,-1SA;UNTIL=20250319T000000Z
    ежемесячно каждый последний понедельник, вторник, среду, четверг, пятницу, субботу, воскресенье до 19 марта 2025 г.
  - FREQ=MONTHLY;INTERVAL=2;BYDAY=1SU,1TU,1FR;UNTIL=20250321T000000Z
    ежемесячно каждый второй месяц каждый первый вторник, пятницу, воскресенье до 21 марта 2025 г.
  - FREQ=YEARLY;BYMONTH=4;BYMONTHDAY=6;UNTIL=20261231T000000Z
    ежегодно каждый четвертый месяц каждое шестое число до 31 декабря 2026 г.
- from (опционально)
  Время начала конференции в UnixTime.
- duration (опционально)
  Продолжительность конференции в секундах.
- offset (опционально)
  Смещение временной зоны организатора относительно UTC (0) в секундах.
- participants (опционально)
  Массив объектов, описывающих участников конференции.
  - name (опционально)
    Имя участника
  - email
    Адрес e-mail участника
Возвращаемое значение - словарь с полями, полностью совпадает по формату с возвращаемым значением точки входа createConf.
- cid (опционально, возвращается, если при обновлении удалилась старая ВКС)
  ID созданной конференции в строковом формате. Строка должна быть URL friendly и не содержать пробелов, двоеточия.
- link (опционально, возвращается, если при обновлении удалилась старая ВКС)
  Общая ссылка на подключение к конференции.
- participantLinks (опционально)
  Словарь, содержащий в себе индивидуальные ссылки на подключение к конференции для всех зарегистрированных участников. Если данная интеграция не поддерживает создание индивидуальных ссылок, параметр можно не указывать, ключ в словаре - aдрес e-mail участника, значение - индивидуальная ссылка для подключения к конференции.
- description (опционально)
  Подробное описание темы конференции. Если поле будет возвращено, то оно перезапишет данное поле в календарном событии. Возвращённая пустая строка очистит поле в календарном событии.
Ошибка:
- error
  Текстовое описание ошибки при обновлении конференции. Если произошла ошибка, поле должно присутствовать.

Точка входа `deleteConf`

deleteConf
Удаляет видеоконференцию.
Параметры доступны в словаре Vars().startParameter:
- cid
  идентификатор конференции или идентификатор конференции и дополнительные параметры в Base64Url, необходимые для удаления ВКС (ID и дополнительные параметры, закодированные в Base64Url, разбирает сам плагин на своё усмотрение).
- description (опционально)
  Подробное описание темы конференции.
Возвращаемое значение - словарь с полями:
- description (опционально)
  Подробное описание темы конференции. Если поле будет возвращено, то оно перезапишет данное поле в календарном событии. Возвращённая пустая строка очистит поле в календарном событии.
Ошибка:
- error
  Текстовое описание ошибки при удалении конференции. Если произошла ошибка, поле должно присутствовать.

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

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

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

Пример:

json

{
  "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`

getFreeBusy
Получение информации Free/Busy.
Параметры доступны в словаре Vars().startParameter:
- email (обязательно)
  e-mail пользователя для которого запрашивается информация.
- timeStart (опционально)
  Начало запрашиваемого периода информации о занятости в формате временной метки.
- timeEnd (опционально)
  Окончание запрашиваемого периода информации о занятости в формате временной метки.
Возвращаемое значение - строка в формате iCalendar Object RFC 5545, section 3.4, включающий в себя компонент RFC 5545, section 3.6.4. В случае ошибки должна возвращаться пустая строка.

В скрипте доступны следующие данные, кроме описанного выше Vars().startParameter:

Vars().pluginSettings - словарь
Общие настройки расширения, описанные в extends/config
Vars().freebusySettings - словарь
Настройки домена получения Free/Busy, описанные в extends/freebusy/freebusyid_/config
- Host
  Host адрес почтового сервера для домена
- ...
  Остальные параметры, указанные в секции extends/freebusy/config и настроеные администратором сервера/домена.

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

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;
  }

}

Помощники

В расширении можно добавить исполняемые файлы помощников (как бинарные, так и на скриптовых языках). Используются так же как и установленные и настроенные на странице Помощники.

Помощники в расширениях могут быть двух типов: фильтрации сообщений и помощники приложений. Имя помощника определяется названием секции в cgplugin.json. Включение помощников осуществляется включением выключением расширения. Настройка помощников осуществляется со страницы настройки расширения. Параметры настройки определяются также в cgplugin.json. Помощникам, установленным в составе расширений, доступны настройки расширения. Для получения настроек расширения помощник должен отправить серверу (после установки версии протокола) GETCONFIG, подписка на обновление конфигурации расширения, команда серверу SUBSCRIBECONFIG и ответ сервера в случае изменения настроек CONFIGUPDATED. Описание протокола.

Пример протокола (I - сообщения сервера, O - сообщения помощника):

O: H00007 GETCONFIG
I: H00007 OK { type = "cat" }

O: H00005 SUBSCRIBECONFIG
I: H00005 OK

I: 00010 CONFIGUPDATED { type = "dog" }
O: 00010 OK

Помощники определяются в объекте helpers объектами с описаниями программ для разных архитектур. В разделе all могут быть указаны помощники, написанные на скриптовых языках и независимые от архитектуры, при этом, если для текущей архитектуры будет переопределён helper_id, то будет использоваться именно он. (в примере ниже на архитектуре x86_64 будут запущены два помощника: all/@helper_id1 и x86_64/helper_id2). Наличие в секции config параметров LogLevel, RestartPause, Timeout необходимо для задания настройки помощников в расширении. Если они не заданы, то сервер установит в этом случае предопределённые настройки.

json

{
  "extends": {
    "config": {
      "LogLevel": {
        "type": "string",
        "required": false,
        "title": "LogLevelTitle"
      },
      "RestartPause": {
        "type": "string",
        "required": false,
        "title": "RestartPauseTitle"
      },
      "Timeout": {
        "type": "string",
        "required": false,
        "title": "TimeoutTitle"
      },
      "SomeExtensionParameter1": {
        "type": "string",
        "required": false,
        "title": "SomeExtensionParameter1Title"
      },
      "SomeExtensionParameter2": {
        "type": "string",
        "required": false,
        "title": "SomeExtensionParameter2Title"
      }
    },
    "helpers": {
      "all": {
        "helper_id1": {
          "system_exe": "/usr/bin/bash",
          "exe": "script1.sh",
          "params": "--logAll -k value1 --key2=value2",
          "type": "filter"
        },
        "helper_id2": {
          "system_exe": "/usr/bin/perl",
          "exe": "script2.pl",
          "params": "--p1 --p2 --p3",
          "type": "app"
        }
      },
      "x86_64": {
        "helper_id2": {
          "exe": "program2",
          "params": "--p1 --p2",
          "type": "app"
        }
      }
    }
  }
}

В описании помощников в расширениях должен быть задан хотя бы один из элементов system_exe, exe.

system_exe (опционально) - исполняемый файл, уже присутствующий в системе, предполагался для указания интерпретатора скриптового языка.
exe (опционально) - исполняемый файл в составе расширения, бинарный или на скриптовом языке.
params (опционально) - Параметры, передаваемые помощнику.
type (обязательно) - тип помощника, app или filter.

Интерфейсы

В расширении можно добавить файлы интерфейсов (wssp, wcgp, изображения, js, css...) Файлы из расширения будут использоваться при совпадении имени скина и имени файла. Порядок поиска файлов скинов: интерфейсы, заданные для домена, "общесерверные" интерфейсы, интерфейсы в расширениях, интерфейсы в поставке сервера (стоковые). При этом в расширениях может только один раз указываться конкретный интерфейс. Если расширение выключено, указанные в нём файлы и скины не участвуют в поиске. При включении / выключении расширения с файлами интерфейсов на сервере происходит сброс кэша интерфейсов.

Описывается в секции WebSkins в виде объекта с именами интерфейсов, где в каждом объекте указывается каталог с файлами или список файлов. Для неименованного интерфейса можно указать в качестве имени интерфейса (объекта с описанием используемых файлов) пустую строку или строки unnamed, noname

json

{
  "extends": {
    "WebSkins": {
      "": {
        "dirs": ["WebSkins"]
      },
      "hPronto-": {
        "files": ["login.wssp", "login.css"]
      }
    }
  }
}

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

dirs (опционально) - список каталогов (не более 1 каталога) с файлами интерфейса.
files (опционально) - файлы интерфейса, лежащие в корне расширения.

Технология единого входа (Single sign-on)

В расширении указывается список методов авторизации SSO. Для этого необходимы скрипты wcgp из неименованного (базового) скина. Данное расширение "несамостоятельно" и требует наличия точки расширения Интерфейсы (WebSkins) с неименованным интерфейсом.

Описывается в массиве SingleSignOn список объектов с полями

script (обязательно) - имя файла скрипта wcgp, добавляемого тем же плагином, на который Web-интерфейс потом будет перенаправлен при нажатии соответствующей кнопки на экране входа (должен быть в плагине и добавлен в неименованный интерфейс).
title (обязательно) - cтрока из файлов локализации, которая будет использоваться при отображении метода входа.
icon - (опционально) имя файла в формате svg иконки. (Файл должен быть в плагине и добавлен в неименованный интерфейс)

Пример

json

{
  "extends": {
    "WebSkins": {
      "unnamed": {
        "dirs": ["WebSkins"]
      }
    },
    "SingleSignOn": [
      {
        "script": "sso1.wcgp",
        "title": "Title1",
        "icon": "icon1.svg"
      },
      {
        "script": "sso2.wcgp",
        "title": "Title2"
      }
    ]
  }
}

Файлам wcgp и wssp доступен список Single Sign-On, как массив словарей по переменной SingleSignOnList.

Каждый элемент массива - словарь с полями, описанными выше: script, title, icon (опционально). Кроме того, в каждом элементе есть поле PluginId, его можно использовать для перевода поля title (подстановки строк из файла локализации плагина).

Расширения ​

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

Локализация ​

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

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

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

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

Точка входа createConf ​

Точка входа updateConf ​

Точка входа deleteConf ​

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

Точка входа getFreeBusy ​

Помощники ​

Интерфейсы ​

Технология единого входа (Single sign-on) ​

Расширения

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

Локализация

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

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

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

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

Точка входа `createConf`

Точка входа `updateConf`

Точка входа `deleteConf`

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

Точка входа `getFreeBusy`

Помощники

Интерфейсы

Технология единого входа (Single sign-on)