Plugins
Extensions allow you to extend the functionality of the CommuniGate server and its user interface in a simple way, by installing just one file, without having to modify the built-in functionality of the server.
You can install a plugin downloaded from communigatepro.ru or developed by yourself in the Users → Plugins section of the Dash administration interface.
Plugin file format
The plugin file is a renamed ZIP archive with .cgplugin extension.
The plugin description file cgplugin.json must be placed in the root of the archive. JSON-Schema: cgplugin.schema.json.
Basic parameters of the plugin configuration file:
id(required) - The name of the plugin. Latin characters, numbers and underscores. Must be unique to a particular plugin. It is recommended to use the reverse of the domain name before the plugin name, for example,ru_communigatepro_ExamplePluginauthor(required) - The name of the author of the plugin. For example,Ivan IvanovprAO SBKversion(required) - Version of the plugin, following SemVer 2.0 rules. For example,1.0.0title(required) - Field name from locale files that would be used to display the plugin title in the admin interface. For example,PluginTitle.description(optional) - Field name from locale files that would be used to display the plugin description in the admin interface. For example,PluginDescription.url- The address of the plugin's home page. For example,https://communigatepro.ru/icon- Optional file name of the icon from the archive to display the plugin when viewing it through the administration interface. The icon must be in svg format and have 1:1 (square) proportions.min_product_version- Optional parameter that specifies the minimal server version required for the plugin to work correctly. If the parameter is not specified, it is assumed that the plugin is compatible with all server versions.
Locales
When you load a plugin, the available locale files with .data extension written in a CommuniGate Pro Dictionary format are loaded automatically.
Data from these dictionaries will be available to other code, including CG/PL scripts contained in the plugin, with a prefix of the form <plugin id>..
Extension points
The list of plugin points is populated in the extends section of the description file. Several types of plugins are available, described below.
Configuration options
Described in the config section as an object with descriptions of configuration parameters. Each key is an identifier of one configuration parameter, under which it will be stored and passed to CG/PL scripts run from the plugin.
type(required) - Parameter type, used to select the parameter storage format and type displayed in the admin interface widget. At the moment only parameters of thestringandbooleantypes are supported.title(required) - A string from the localization files that will be used when the parameter is displayed in the administration interface.required- Whether the configuration parameter is mandatory to be filled in (if the field is missing, the parameter is optional).editPresentation- Allows you to specify how the parameter input control is displayed. We supportpasswordandmultilineTextpresentations forstringparameters. If nothing is specified forstring, a standard single line input field will be shown.enum- Allows you to specify multiple valid options for a configuration parameter.enumTitle(required if there is an enum) - A string from the locales files that points to the dictionary that will be used for displaying configuration options in the administration interface.
Example:
{
"extends": {
"config": {
"APIKey": {
"type": "string",
"editPresentation": "password",
"title": "APIKeyTitle",
"required": true
},
"ServerType": {
"type": "string",
"enum": ["proxy", "DNS", "mail"],
"enumTitle": "ServerTypeEnumTitle",
"required": true,
"title": "ServerTypeTitle"
}
}
}
}Configuration check scripts
A script file in CG/PL language can be added to the plugin to check whether the configuration parameters are filled in correctly. This file must be located in the archive with plugin.
Such a script file can both perform basic checks on regular expressions or filling in fields, and check the correctness of entered parameters by accessing an external server. The script file must contain a single method checkConfig, which checks the configuration settings available to it via the pluginSettings property of the script's startup environment.
Config example:
{
"extends": {
"config": {
"APIKey": {
"type": "string",
"title": "APIKeyTitle",
"required": true
}
},
"checkConfig": "checkconfig.scgp"
}
}Script example:
entry checkConfig {
var settings = Vars().pluginSettings;
if (Length(settings.APIKey) != 10) {
SetResult("invalid API key")
}
}Video conferences
Described in the vcs section as an object with descriptions of scripts provided by the plugin for integration of videoconferencing systems (hereinafter - VCS). Key - an identifier that will be used to identify a particular VCS system inside CommuniGate Pro. Each description is an object with the following parameters:
title(required) - A string from the localization files that will be used when displaying the parameter in the user interface.script(required) - File name (with extension) of the script file contained in the archive in CG/PL language, implementing integration with VCS.icon(optional) svg file name with icon from the archive. The icon will be displayed to the user in the interface elements associated with the specific videoconferencing system. It should have 1:1 proportions (square).
Example:
{
"extends": {
"vcs": {
"bbb": {
"title": "BBBTitle",
"script": "bbb.scgp",
"icon": "bbb.svg"
}
}
}
}Each video conferencing support module should be a separate CG/PL script in scgp format.
Each function must be implemented by a separate method within the script file (a separate "entry point"). The script is always run in the context of the user creating the conference, be it through a calendar event or through a button in the chat room.
The entry points to be implemented in the script file code are described below.
Entry createConf
createConfCreates videoconference.
Parameters available in dictionary
Vars().startParameter:title(optional)Conference topic.
description(optional)Detailed conference topic description.
isAllDay(optional)The flag indicating the type of conference, if the conference lasts the whole day from 0 to 24 hours - 1, if the conference has any other start and end time - 0.
rRule(optional)The rule of recurrence of the event and the VCS, according to RFC5545, section 3.8.5.3.
Example:
FREQ=DAILY;UNTIL=20241215T000000Zdaily recurrence, until December 15, 2024.
FREQ=WEEKLY;BYDAY=SU,MO,TU,WE,TH,FRweekly recurrence every day of the week.
FREQ=MONTHLY;INTERVAL=2;BYMONTHDAY=2;UNTIL=20250328T000000Zmonthly, every second month, the second day until March 28, 2025.
FREQ=MONTHLY;BYDAY=-1SU,-1MO,-1TU,-1WE,-1TH,-1FR,-1SA;UNTIL=20250319T000000Zmonthly every last Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday until March 19, 2025.
FREQ=MONTHLY;INTERVAL=2;BYDAY=1SU,1TU,1FR;UNTIL=20250321T000000Zmonthly every second month, every first Tuesday, Friday, Sunday until March 21, 2025.
FREQ=YEARLY;BYMONTH=4;BYMONTHDAY=6;UNTIL=20261231T000000Zannually, every fourth month, every sixth day until December 31, 2026.
from(optional)Conference start time in UnixTime.
duration(optional)The duration of the conference in seconds.
offset(optional)The offset of the organizer's time zone relative to UTC (0) in seconds.
participants(optional)Array of objects containing the list of the conference participants.
name(optional)Participant name
emailParticipant e-mail address
The return value is a dictionary with fields:
cidThe ID of the created conference in string format. The string must be URL friendly and must not contain spaces.
linkShared link to connect to the conference.
participantLinks(optional)A dictionary containing individual links to connect to the conference for all registered participants. If this integration does not support the creation of individual links, the parameter can be omitted. The key in the dictionary is the participant's e-mail address, the value is an individual link to connect to the conference:
description(optional)Detailed conference topic description. If a value is returned, it will overwrite the given field in the calendar event. The returned empty string will clear the field in the calendar event.
Error:
errorText description of an error when creating a conference. If an error has occurred, the field must be present.
Entry updateConf
updateConfUpdates videoconference.
Parameters available in dictionary
Vars().startParameter. Similar to the parameters entrycreateConfwith the addition of `cid:cidConference ID or conference ID and additional parameters in Base64Url required to update the VCS.
title(optional)Conference topic.
description(optional)Detailed conference topic description.
isAllDay(optional)The flag indicating the type of conference, if the conference lasts the whole day from 0 to 24 hours - 1, if the conference has any other start and end time - 0.
rRule(optional)The rule of recurrence of the event and the VCS, according to RFC5545, section 3.8.5.3.
Example:
FREQ=DAILY;UNTIL=20241215T000000Zdaily recurrence, until December 15, 2024.
FREQ=WEEKLY;BYDAY=SU,MO,TU,WE,TH,FRweekly recurrence every day of the week.
FREQ=MONTHLY;INTERVAL=2;BYMONTHDAY=2;UNTIL=20250328T000000Zmonthly, every second month, the second day until March 28, 2025.
FREQ=MONTHLY;BYDAY=-1SU,-1MO,-1TU,-1WE,-1TH,-1FR,-1SA;UNTIL=20250319T000000Zmonthly every last Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday until March 19, 2025.
FREQ=MONTHLY;INTERVAL=2;BYDAY=1SU,1TU,1FR;UNTIL=20250321T000000Zmonthly every second month, every first Tuesday, Friday, Sunday until March 21, 2025.
FREQ=YEARLY;BYMONTH=4;BYMONTHDAY=6;UNTIL=20261231T000000Zannually, every fourth month, every sixth day until December 31, 2026.
from(optional)Conference start time in UnixTime.
duration(optional)The duration of the conference in seconds.
offset(optional)The offset of the organizer's time zone relative to UTC (0) in seconds.
participants(optional)An array of objects describing the participants of the videoconference.
name(optional)Participant name
emailParticipant's e-mail address
Return value is a dictionary with fields:
cid(optional, if you need to delete the VCS for the update)The ID of the created conference in string format. The string must be URL friendly and not contain spaces, colons.
link(optional, if you need to delete the VCS for the update)General link to connect to the conference.
participantLinks(optional)A dictionary, containing individual links to connect to the conference for all registered participants. If this integration does not support the creation of individual links, the parameter can be omitted. The key in the dictionary is the participant's e-mail address, the value is an individual link to connect to the conference:
description(optional)Detailed conference topic description. If a value is returned, it will overwrite the given field in the calendar event. The returned empty string will clear the field in the calendar event.
Error:
errorText description of the error when updating the conference. If an error has occurred, the field must be present.
Entry deleteConf
deleteConfDeletes videoconference.
Parameters available in dictionary
Vars().startParameter:cidThe conference ID or conference ID and additional Base64Url parameters required to delete the VCS are converted in the plugin.
description(optional)Detailed conference topic description.
Return value is a dictionary with fields:
description(optional)Detailed conference topic description. If a value is returned, it will overwrite the given field in the calendar event. The returned empty string will clear the field in the calendar event.
Error:
errorText description of the error when deleting the videoconference. If an error has occurred, the field must be present.
Free/Busy
freebusy section as an object with descriptions of scripts provided by the plugin for getting Free/Busy information. Key is an identifier that will be used to identify the Free/Busy source server type which will be used to load Free/Busy information into CommuniGate Pro. Each description is an object with the following parameters:
title(required)A string from the localization files that will be used when displaying the parameter in the user interface.
script(required)File name (with extension) of the script file contained in the archive in CG/PL language, implementing integration with freebusy.
config(optional)Parameters passed to the script are the same as extension parameters. Available in script as Vars().freebusySettings dictionary.
checkConfig(optional) File name (with extension) of the script file contained in the archive in CG/PL language, , implementing validation freebusy parameters config.
Example:
{
"extends": {
"config": {},
"freebusy": {
"CommunigatePro": {
"title": "CommunigateProTitle",
"script": "freebusy.scgp",
"config": {
"Host": {
"type": "string",
"required": true,
"title": "HostTitle"
}
},
"checkConfig": "checkFreeBusyConfig.scgp"
}
}
}
}Each freebusy script must be a separate CG/PL script in scgp format. And must define entry points listed below:
Entry getFreeBusy
getFreeBusyReceive Free/Busy information.
Parameters available in dictionary
Vars().startParameter:email(required)e-mail address of the user for whom the information is requested.
timeStart(optionally)Start of the requested employment information period in timestamp format.
timeEnd(optionally)End of the requested employment information period in timestamp format.
Returned value: string containing an iCalendar Object RFC 5545, section 3.4 including a RFC 5545, section 3.6.4 component. In case of an error, an empty string should be returned.
The following data are available in script in addition to described above Vars().startParameter:
Vars().pluginSettings- dictionaryCommon plugin settungs, described in
extends/config.Vars().freebusySettings- dictionaryFree/Busy receiving settings for domain, described in
extends/freebusy/freebusyid_/configHostaddress of the user's domain.
...the rest of parameters declared in
extends/freebusy/configsection and filled by server/domain administrator.
Example of a script file:
entry getFreeBusy is
// email is passed on in the dictionary startParameter
var param = Vars().startParameter;
var email = param.email;
var timeStart = param.timeStart;
var timeEnd = param.timeEnd;
if (isDate(timeStart)) {
// process timestamps if passed
}
// pluginSettings and freebusySettings common for requests to the given Free/Busy domain (passed in the server as env environment variables)
var pluginSettings = Vars().pluginSettings;
var freebusySettings = Vars().freebusySettings;
var host = freebusySettings.Host;
// send request
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;The script for checking the parameters for obtaining information about the availability / occupancy of participants (Free/Busy) should also be a separate CG/PL script. Entry point checkConfig. The script also has access to parameters for obtaining information about employment (Free/Busy) Vars().freebusySettings and general expansion parameters Vars().pluginSettings.
Example of a script file for validation Free/Busy settings:
entry checkConfig {
// common plugin settings
var pluginSettings = Vars().pluginSettings;
// Free/Busy settings for current domain
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;
}
}Helpers
In the plugin you can add executable files of helpers (both binary and in scripting languages). They are used in the same way as those installed and configured on the page Helpers.
Helpers from plugins can be one of two types: Message Filters and Application Helpers. Helper's name defines name of object in cgplugin.json. Helpers are enabled by turning the extension on and off. Helpers can be configured from the extension settings page. Configuration parameters are also defined in cgplugin.json. For Helpers installed as part of plugins are available protocol command to server to receive plugin settings GETCONFIG, subscription to update plugin configuration, command to server SUBSCRIBECONFIG and server response if settings are changed CONFIGUPDATED. Read more in helper's protocol description.
Example of protocol message exchange (I - server message, O - helper message):
O: H00007 GETCONFIG
I: H00007 OK { type = "cat" }
O: H00005 SUBSCRIBECONFIG
I: H00005 OK
I: 00010 CONFIGUPDATED { type = "dog" }
O: 00010 OKHelpers described in the helpers extension point of plugin, objects with program descriptions for different architectures. In all object can be listed independent of architecture helpers, mostly written in scripting languages, If helper_id is overridden for the current architecture, it will be used. (In the example below on the machine with x86_64 will be started 2 helpers: all/@helper_id1 and x86_64/helper_id2). The presence of LogLevel, RestartPause, Timeout parameters in the config section is necessary to specify the configuration of helpers in the plugin. If they are not specified, the server will set the predefined settings in this case..
{
"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"
}
}
}
}
}In the description of the helpers in the extensions. At least one of the elements must be specified system_exe, exe.
system_exe(optional) - The executable file already present in the system was intended to specify the scripting language interpreter.exe(optional) - executable file as part of an plugin, binary or in a scripting language.params(optional) - command line arguments passed to helper.type(required) - helper's type,apporfilter.
Skins
Skins files can be added to plugin (wssp, wcgp, images, js, css...) If a skin name matches and files in plugins are found, they can be used. The order of skin files search: domain-specific interfaces, “server-wide” interfaces, interfaces in plugins, server-supplied (stock) interfaces. A specific interface can only be specified once in an all extensions. If an plugin is disabled, the files and skins specified in it do not participate in the search. When you enable/disable an plugin with skins files on the server, the skins cache is reset.
Described in the WebSkins section as an object with skin name, where each object specifies a file directory or list of files. For an unnamed interface, you can specify an empty string as the interface name (an object with a description of the files used) or strings unnamed, noname
{
"extends": {
"WebSkins": {
"": {
"dirs": ["WebSkins"]
},
"hPronto-": {
"files": ["login.wssp", "login.css"]
}
}
}
}In the description of the skins in the plugins at least one of dirs, files must be present. All files listed in a files array must be present in plugin. Same for directory listed in dirs.
dirs(optional) - List of dirs (0 or 1) with skin files in the plugin.files(optional) - Skin files in the root of plugin.
Single sign-on
The extension specifies a list of SSO authorization methods. This requires wcgp scripts from an unnamed (base) skin. This extension is required an extension point Skins with unnamed skin.
Described in SingleSignOn array objects with the following fields:
script(required)File name of the
wcgpscript from the archive (must be added to an unnamed skin), added by the same plugin, which will be used to redirect the user to for logging in using SSO method when the corresponding button on the login screen is pressed .title(required)Field name from locale files, that would be used to display in the user interface.
icon(optional)File name of the icon from the archive to display in the user interface. The icon must be in
svgformat. (The file must be in a plugin and added to an unnamed interface)
Example
{
"extends": {
"WebSkins": {
"unnamed": {
"dirs": ["WebSkins"]
}
},
"SingleSignOn": [
{
"script": "sso1.wcgp",
"title": "Title1",
"icon": "icon1.svg"
},
{
"script": "sso2.wcgp",
"title": "Title2"
}
]
}
}Each element of the array is a dictionary with the fields described above: script, title, icon (optional). In addition, each element has a field PluginId, it can be used to translate a field title (string translations from the plugin localization file).