Plugins

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://old.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.

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>..

The list of plugin points is populated in the extends section of the description file. Several types of plugins are available, described below.

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

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")
  }
}

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.

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

(optional) Dictionary of objects that contain 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 e-mail address of the participant, the value is an individual link to connect to the conference.

Error:

error

Text description of an error when creating a conference

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

}