V3 App Zone [PLUGIN]

XCALLY section	App Zone → Plugins
On this page	1 What's about 2 Plugins 3 Upload and Install a Plugin 4 Edit/Modify a Plugin 5 Plugin Sample 6 Add the Plugin to the Staff 7 How to create a Plugin 8 Plugin automatic restart system 9 Plugins on New Client Experience 10 FAQ

What's about

In the App Zone section you can define the external applications you want to use inside XCALLY Motion environment.

The type of integration you can achieve can be:

Html: in this case you will open a web page or a custom html file using a link internal to an XCALLY Motion Module;
Script: in this case the application will be installed and run as a "local" application.

All you need to do is to:

develop a Plugin, where the software is provided either by third parties and Partners and by the XCALLY developing team;
upload it in your server configuration Plugins;
install the plugin;
enable the users and/or the agents to use it.

Plugins

Here’s a list of available plugins. Click on the icon to see how to use them:

TWITTER

VIBER

LINE

MICROSOFT TEAMS

INSTAGRAM

ASTERISK CLI

SSH CONSOLE

MICROSOFT SQL

Upload and Install a Plugin

In the App Zone section, click on the Upload Icon (on the bottom right).

Drop the .zip file in the dialog window and click on “finish”.

NB. The plugin zip file must be 50 MB maximum.

At the end the plugin will be shown in the Plugins list:

Click on

and then install the plugin:

and the installation process starts:

At the end of the process the Active mark for the plugin is set and the application name is inserted in the Plugins Menu section (if the app is configured in order to be available to the admin):

Once the plugin has been installed, it can be started/stopped (script only), unistalled, removed or edited and modified.

Edit/Modify a Plugin

Click on

and then on Edit plugin.

The Settings for the Script type Plugin are as in the following screenshot:

The values shown in the Settings must be defined in the manifest.json file before uploading the plugin

In the following screenshot you can see the Settings of an HTML type Plugin:

Plugin Sample

In this paragraph we analyse a plugin sample, in which you can view different functionalities that you can do with plugins (how to call Motion, how to connect to socketIO, how to call internal API…).

You can download source code from this link: https://bitbucket.org/xenialab/angular-plugin

in plugin folder, you can find plugin files (manifest, client, server...) to upload on Motion
project contains the frontend Angular project
build.bat: batch file that build the Angular project and create the zip file to be uploaded to XCALLY

To build the plugin you need to follow these instructions:

cd project
npm ci
cd ..
build.bat

npm ci installs npm packages

build.bat creates zip for XCALLY

Upload plugin zip in App Zone/Plugins section and then click on Install plugin

At the end of installation, you can open the plugin from Plugins section and you will view a visualisation like that:

Front-end is developed in Angular 16.

Then the example phrase on the top is only an example of API plugin call. In fact plugin exposes API and in backend server folder, the 'api/test' allows to read JSON and returns in this case a quote

This shows that from the frontend of the plugin, you can call the plugin's API and display the response on the platform.

Instead on api.service.ts you can view that to call plugin internal API, you have to use /api/plugins/webhook, by indicating then port (with the plugin listening) and endpoint url

On Agents tab, it’s visible the list of agents to show an example in the plugin source of how to call Motion API

Consider that no login or authentication is required, because the plugin runs on an iframe served by the same server, so browser sends cookies with authentication saved and it is possible to make API calls directly with the same user used in XCALLY.

SocketIO tab to show that from plugin it’s possible to connect to Motion SocketIO (stable connection between browser and server that remains in communication at all times, e.g. for chat messages, realtime data).

On tail tab, it’s possible to view a server log file. It’s necessary to put socketIO within plugin.

On server part is initialised socketIO, then files are monitored with TailFile and when new data arrive, the plugin sends emit message with data.

Frontend connects to this socketIO and when new data arrive, it shows them on the tab tail

Consider that all plugins you install, server-side, listen on localhost (thus not accessible from the outside).
On system environment level, configuration is required to turn traffic in the correct way.

Add the Plugin to the Staff

Edit the Staff members Profile and enable the Plugin in order to let them use it (of course, if the application settings allows it):

User Profile:

Agent Profile:

For the Users with Admin role, all modules are enabled by default

How to create a Plugin

Step 1: Manifest reference

The manifest.json must contains the configuration of your plugin and must be included inside the zip file, like in the following example:

Script Example

{
  "name": "MyScriptPlugin",
  "version": "1.0.0",
  "description": "Displays the MyPlugin",
  "author": {
    "name": "AuthorName",
    "email": "name@name.com",
    "website": "https://www.name.com"
  },
  "type": "script",
  "sidebar": "always",
  "icon": "icon-apps",
  "parameters": {
    "scriptName": "my-plugin",
    "scriptPath": "app/index.js",
    }
  }

Html Example

{
  "name": "MyHtmlPlugin",
  "version": "1.0.0",
  "description": "Displays the myPlugin",
  "author": {
    "name": "AuthorName",
    "email": "name@name.com",
    "website": "https://www.name.com"
  },
  "type": "html",
  "sidebar": "adminOnly",
  "icon": "icon-apps",
  "parameters": {
    "views": {
      "admin": "https://www.name.com"
    }
  }

Name

Specifies a name for the plugin. Required.

Version

Specifies a version number for the plugin. Required.

Description

Specifies the plugin’s functionality. Required.

Author

Specifies the author of the plugin. It contains a JSON object with the following properties:

name: an individual or a company.
email: the address to which users can send support requests.
website: url pointing to a page about the author or the plugin.

Type

Specifies the type of the plugin. Required.

html: displays the url or the custom html page specified.
script: launch the Node.js application provided inside the zip.

Sidebar

Specifies the plugin’s visibility [default: always]

always: visible on both admin’s and agent’s sidebar
adminOnly: visible on the admin’s sidebar only
agentOnly: visible on the agent’s sidebar only
never: hidden on both admin’s and agent’s sidebar

Icon

Specifies the icon that will be displayed on the agent’s sidebar. [default: icon-apps]

Here it’s possible to see all the Motion default icons that can be inserted:
https://fuse-3d648.firebaseapp.com/ui/icons

Pdf Icon List:

Parameters

Contains all the information needed for the correct functioning of the plugin. Required.

scriptName: the name used for the new process when starting the Node.js application. Required for script type plugin only.
scriptPath: the path to where the Node.js application launcher file is located. Required for script type plugin only.
views: a JSON object with the following properties (required for html type plugin only):
- admin: an url or the path to a custom html file that will be displayed on the admin side
- agent: an url or the path to a custom html file that will be displayed on the agent side

Motion Variables

You can use User Variables in the agent view property (i.e. https://www.name.com?name={{user.name}}))

Step 2: Create the Plugin Application and the .zip file

As an example we consider a Script Plugin:

The application must be developed in node.js like in the following example:

var express = require('express');

var app = express();

app.listen(9006, function () {
  console.log('Sample Node Application Plugin Service listening on port ' + 9006);
});

Remember that the pakage.json file must be added in the zip file, according to the node.js specification. For more information click here.

and this is the corresponding manifest.json file:

{
  "name": "Sample Script",
  "version": "1.0.0",
  "description": "Sample plugin developed in Node.js",
  "author": {
    "name": "Xenialab",
    "email": "xenialab@xcally.com",
    "website": "https://www.xcally.com/en/"
  },
  "type": "script",
  "sidebar": "always",
  "parameters": {
    "scriptName": "sample",
    "scriptPath": "app/index.js",
    "views": {
      "admin": "admin/index.html",
      "agent": "https://www.xcally.com/en/"
    }
  }

The script can use the XCALLY Motion style (angular material): in this case it must be defined in the index.html file.

Plugin automatic restart system

The plugin restart system is an opt-in fix and requires enabling .env variables.
The restart system must allow restarting after a chosen time delay, in order to give XCALLY time to fully boot before plugins start making requests.

The restart system is disabled by default

.env variables:

XC_PLUGIN_RESTART = If set to false, or not present, plugin will not restart
XC_PLUGIN_RESTART_DELAY = If plugin restart is active, and this variable is not set, by default is 300 seconds (5 minutes). On the other hand, if the restart plugin is active and the variable is set, the restart waits for the indicated seconds of delay

Consider that if you don’t enable the variable as true, plugins will not reboot at Motion restart

Plugins on New Client Experience

FROM VERSION 3.50.0

If you enable New Client Experience, you can get this visualisation of the list of created plugins:

In this section you can:

search for a specific plugin
set and clear filters
manage columns
activate the advanced search for each field
delete plugins (single or bulk delete)
export to CSV, if you select at least 1 row
edit, stop, restart, download and uninstall a specific plugin
create a new plugin, by clicking on Add and uploading the .zip file: