CommuniGate Pro
Version 6.3
Miscellaneous
 
 
Plugins
 

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_ExamplePlugin
  • author (required) - The name of the author of the plugin. For example, Ivan Ivanov pr AO SBK
  • version (required) - Version of the plugin, following SemVer 2.0 rules. For example, 1.0.0
  • title (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 the string and boolean types 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 support password and multilineText presentations for string parameters. If nothing is specified for string, 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 methodcheckConfig, 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 functions to be implemented in the script file code are described below.

createConf

Creates videoconference.

Parameters:

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.
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
email
Participant e-mail address

Return value:

cid
The ID of the created conference in string format. The string must be URL friendly and must not contain spaces.
link
Shared link to connect to the conference.
participantLinks

(optionally) A dictionary of objects 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:

Parameters:

email
(optionally)Participant's e-mail address
link
Individual link to connect to the conference

Error:

error
Text description of an error when creating a conference
updateConf

Updates videoconference.

Parameters:

ID
Conference ID or conference ID and additional parameters in Base64Url required to update the VCS.
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.
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
email
Participant's e-mail address

Return value:

cid
(optionally, 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
(optionally, if you need to delete the VCS for the update)General link to connect to the conference.
participantLinks

(optionally) A dictionary of objects 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:

Parameters:

email
(optionally)Participant's e-mail address
link
Individual link to connect to the conference

Error:

error
Text description of the error when updating the conference.
deleteConf

Deletes videoconference.

Parameters:

ID
The conference ID or conference ID and additional Base64Url parameters required to delete the VCS are converted in the plugin.

Return value:

Error:

error
Text description of the error when deleting the videoconference.

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.

getFreeBusy

Receive Free/Busy information.

Parameters:

email
(required) e-mail address of the user for whom the information is requested. Can be found in the Vars().startParameter dictionary.

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 to each function at the entry point:

pluginSettings
Common plugin settungs, described in extends/config.
freebusySettings
Free/Busy receiving settings for domain, described in extends/freebusy/freebusy_id/config
Host
address of the user's domain.
...
the rest of parameters declared in extends/freebusy/config section and filled by server/domain administrator.
startParameter
receive function execution Free/Busy parameters.
email
As described above includes the user's e-mail address
timeStart
Optional parameter. Start of period for Free/Busy information in TimeStamp format
timeEnd
Optional parameter. End of period for Free/Busy information in TimeStamp format

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

}
CommuniGate Pro Guide. Copyright © 2024, AO SBK