Add customized features to Rainbow applications (custo-manifest)

This article allows to add customized features to the Rainbow applications of company members using a set of actions configurable from a custo-manifest.json file. Customized features are available for companies associated to Cloud PBX or Alcatel-Lucent Enterprise PBX (OmniPCX Enterprise or OXO Connect).

The available actions are:

• Actions automatically triggered following events:
  • on-outgoing-pbx-call-actions: to execute an action when an outgoing call occurs
  • on-incoming-pbx-call-actions: to execute an action when an incoming call occurs
  • on-answering-incoming-pbx-call-actions: to execute an action when an incoming call is answered
  • on-releasing-incoming-pbx-call-actions: to execute an action when an incoming call is ended

On incoming calls, actions can launch a script, application or web page with information on the incoming call.

• Actions triggered via button use:
  • on-incoming-pbx-call-button-actions: to execute an action by clicking a button added in the incoming call pop-up window
  • on-call-log-list-actions: to execute an action by clicking a button inserted in each item of call log
  • on-contact-list-actions: to execute an action by clicking a button inserted in each item of contacts
  • on-contact-detail-actions: to execute an action by clicking a button inserted in the contact detailed area
  • on-communication-card-actions: to execute an action by clicking a menu inserted in the call manager bar.
  • on-bubble-actions: to execute an action by clicking a button inserted in the bubble menu property
  • on-bubble-conference-actions: to execute an action by clicking a button inserted in the conference call menu

By clicking buttons, actions can open pop-up windows with possibility to join contacts or services by e-mail.

• Actions with automatic information display:
  • on-incoming-pbx-call-display-actions: to insert information in the incoming call pop-up
  • on-contact-card-display-actions: to insert information in the contact detailed area

• Action with third-party application display:
  • on-main-window-actions: to display a third-party application in the Rainbow application (only with popout option set to true: see: Additional fields)

By clicking the dedicated icon in the left panel, action can display a third-party application in the right part of the Rainbow application.

These actions are configured from the custo-manifest.json file deployed to the Rainbow applications for company members.

The custo-manifest.json file can be deployed to desktop Rainbow applications without restrictions and to web Rainbow applications with restrictions: see: Main fields.

Configuration consists in:

1. From the administration Rainbow application, exporting a template of the custo-manifest.json file on computer
2. Editing and completing the custo-manifest.json file
3. Importing the custo-manifest.json on administration Rainbow application
4. Deploying the custo-manifest.json to Rainbow applications for company members 

When deploying from the administration Rainbow application, the custo-manifest.json file can no longer be configured locally from the Rainbow application of company members: export/import options are no longer offered.

Prerequisites

• You must have an administrator account in the company with a Business, Enterprise or Attendant license.

Custo-manifest file overview

The custo-manifest file consists of two parts:

• The first part lists all the available actions, and provides for each action, a template with the main parameters to complete.
  Example:
  
• The second part provides a help guide to be read for configuration.

An action is defined by a set of parameters described in the following sections.

The following actions support up to three extensions:

• on-main-window-actions
• on-contact-detail-actions
• on-communication-card-actions
• on-bubble-actions
• on-bubble-conference-actions

Example of on-main-window-actions with two extensions: 

Main fields

• "name": is a text used to identify action or the label of button for actions using button
• For actions using button:
  • "icon": is the access path to the button icon
  • "tooltip": is the access path to the tooltip displayed when the mouse is moved over the button
• "command": defines the action to be executed

• "url": is the path or URL to access local application, web page or REST API

  Note: The backslash must be double in access path to local application (e.g. C:\\MicroCRM\\MicroCRM.exe).
• "params": is a string with variables ${xx} which will be replaced by their value in action execution

• "commandType": specifies action type:

  • Not defined: launches a local application or a web page (if url starts with 'http' or 'https')
  • "rest": executes a REST API call
  • "file": fetches the file content to fetch (mainly for debugger tuning)
  Note: The actions with rest" and "file" command types are not supported when applied to Web Rainbow applications. Pop-ups open indicating that actions will be ignored.

• "responseType: defines the type of content returned by action: "markdown", "json" or "adaptiveCard".

  If set to "json", then:

  • "displayJsonField": defines the field which value is the content to be displayed
  • "firstNameJsonField": defines the field which value must substitute to the caller first name
  • "lastNameJsonField": defines the field which value must substitute to the caller last name
  • "companyJsonField": defines the field which value must substitute to the caller's company name

  If set to "adaptiveCard", then:

  • "adaptiveCardTemplateJsonField": defines the template of the adaptive card to be displayed
  • "adaptiveCardContentJsonField": defines the content of the adaptive card to be displayed

Main fields:

Type of content in "json":

Additional fields

• "AnswerOnClick": when set to true, executes the action and answers the incoming call at the same time (for action on-incoming-pbx-call-button-actions only)
• "filter": if set to "NoShortNumber", it will not trigger event if caller number is a short number
• "RaiseChangeCall": allows to configure the behavior when receiving a transferred call:

  • false: only direct calls to the user will trigger the event

  • true: the event is triggered for direct calls to the user and also for calls that have been transferred to this user

  • only: only transferred calls to the user trigger the event

• "Popup": when set to true, displays a third-party application in the right part of the Rainbow application (for action on-main-window-actions only)

Variables ${xx}

The action template can include variables ${xx} configured in the "url", "params" and "bodyParameters" (for REST API) parameters. They are replaced by their value when the action is executed.

The variables ${xx} can be:

A regular expression (i.e. regex) can be applied to a variable ${xx}.

Syntax is: ${rainbowVariable.regex(regexPatternValue, replacementValue)}

The regex will be applied to the variable ${xx} before sending it to the external application if it is part of the request or before passing it to the Web application if it is part of a response.

Examples:

When substituting ${localUser.phonePbx} by its value, it also applies a regex on it.

"params": "pbx=${localuser.phonepbx.regex(^\\+33\|^\\+1, 0)}="0)}"

In this example, "+333909090" will be changed to "03909090".

"params": "byEmail=${localUser.email.regex(alcatel.com, al-enterprise.com)}"

In this example, “someone@alcatel.com" will be changed to “someone@al-enterprise.com".

Exporting a template of custo-manifest file on computer

This operation can only be performed from a desktop Rainbow application.

1. From the administration Rainbow application, click on the avatar in the left panel, then Settings menu.
2. In the left-hand menu, select Telephony.
   The Settings - Telephony configuration window opens.
3. Expand the window up to the Customization section.
4. Click on Export file and use the browser to export the custo-manifest file on the computer.
5. Click on Close to exit the telephony settings window.

Configuring the custo-manifest file on computer

1. Open the custo-manifest file using a text editor.

2. Configure the parameters of the actions to be used.

   Warning: do not delete the space between the double quotation marks for the unused parameters ("name": " ", "url": " ", "params": " "), otherwise the imported file will not be taken into account.
3. Remove the parameters of all the unused actions.
4. Save the custo-manifest file.
5. If the custo-manifest file refers to external sources (images and/or text files), create a *.zip file with both custo-manifest file and external sources.
   Example:
   
   In this example, the *.ZIP file must contain the custo-manifest.json, basketball.png and FileDisplay.txt files.

Importing the custo-manifest file on administration Rainbow application

One or several custo-manifest files can be imported in the administration Rainbow application for the company. After import, the custo-manifest file is accessible to all company administrators for deployment or update.

File import can be performed from a desktop or web Rainbow application.

1. From the administration Rainbow application, click on Manage your company in the left panel. 
2. In the MY COMPANY panel, click on the name of the company.
3. In the left panel, click on Information.
4. In the right part of the window, click on the Customization tab, then the Custom manifest files tab.
5. Click on Add and use the browser to select and import into the Rainbow application either the custo-manifest file only (*.json), or the custo-manifest file and its external sources (*.ZIP).
6. Click on Add to validate import.
   The custo-manifest file is displayed in the list and can be exported by any company administrator for update: select the target file, click on , and select Download.

Deploying the custo-manifest file to Rainbow applications for company members

The custo-manifest file can be deployed to the Rainbow applications for company members, one by one or in a single step using mass provisioning. After deployment, the custo-manifest will be taken into account on Rainbow applications at restart: export/import options are no longer offered on Rainbow application.

Mass provisioning can be performed using any of the following:

• A CSV file: The operation consists in deploying the custo-manifest file for one company member (see procedure below), export a populated csv file with company member data, complete in the CSV file the column selectedManifestName for the target company members, and import the CSV file: see: Manage Company Members Using Bulk Provisionning
• The company LDAP directory: The operation consists in synchronizing the company directory in Rainbow with the company LDAP directory after modifying the predefined attribute mapping with user attribute selectedAppCustomisationTemplateName set to const(<name of custo-manifest file>): see: Provisioning of company members via an Active Directory (LDAP Connector)

To deploy the custo-manifest file to Rainbow applications one by one:

1. From the administration Rainbow application, click on Manage your company in the left panel. 
2. In the MY COMPANY panel, click on the name of the company.
3. In the left panel, click on Members.
4. Click on the target company member and select the Information tab.
5. In the Custom manifest field, select the target file among listed available files. 
6. Click on Apply to validate and exit the company member settings window.

1. From the Rainbow application of company member, click on the avatar in the left panel, then Settings menu.
2. In the left-hand menu, select Telephony.
   The Settings - Telephony configuration window opens.
3. Expand the window up to the Customization section.
4. Click on Import file and use the browser to select and import into the Rainbow application either the custo-manifest file only (*.json), or the custo-manifest file and its external sources (*.ZIP).
5. Click on Continue to restart the Rainbow application and take into account the new customization file.

Removing the custo-manifest file from Rainbow applications for company members

1. From the administration Rainbow application, click on Manage your company in the left panel. 
2. In the MY COMPANY panel, click on the name of the company.
3. In the left panel, click on Information.
4. In the right part of the window, click on the Customization tab, then the Custom manifest files tab.
5. Select the target custo-manifest file, click on , and select Remove custom manifest.
   The custo-manifest file is automatically removed from Rainbow applications for company members.

Examples of configuration

Execute an application or script with parameters

Example 1:

The action on-incoming-pbx-call-actions executes an application (e.g. MicroCrm) with a parameter from 'params' (no return).

"version": "2",
"extension-points": {
"on-incoming-pbx-call-actions": [
 {
  "name": "Exec CRM",
  "command": {
  "url": "C:\\MyApp\\CustoApp\\MicroCRM.exe",
  "params": "-number ${caller.phoneNumber}"
   }
  }
 ],

Example 2:

The action on-incoming-pbx-call-actions executes a script (*.bat) with parameters from 'params' (no return).

"version": "2",
"extension-points": {
"on-incoming-pbx-call-actions": [
 {
  "name": "BatScript",
  "command": {
  "url": "C:\\MyApp\\MyApp.bat",
  "params": "IN-COMING canNr:${localUser.canonicalNumber} userIntNr:$"{localUser.internalNumber} caller[Nr:${calle.phoneNumber} FN:${caller.firstName} LN:${caller.lastName} .... CorData:[${call.correlatorData Hex:${call.hexCorrelatorData]"
   }   
  }
 ],

Open a web page with parameters

Example 1:

The action on-incoming-pbx-call-actions opens a web page with parameters from 'params' (no return).

"version": "2",
"extension-points": {
"on-incoming-pbx-call-actions": [
 {
  "name": "Yellow pages",
  "command": {
  "url": "https://www.pagesjaunes.fr/annuaireinverse/recherche",
  "params": "quoiqui=${caller.phoneNumber}&proximite=0"
  }
 }
],

Example 2:

The action on-incoming-pbx-call-actions opens a web page with parameters directly in URL (no return).

"version": "2",
"extension-points": {
"on-incoming-pbx-call-actions": [
 {
  "name": "Contact popup",
  "command": {
  "url": "http://localhost:3000/contactShow?phone=${caller.phoneNumber}",
  "params": " "
  }
 }
],

Execute a REST API call with parameters

Example 1:

When incoming call is released, the action on-releasing-incoming-pbx-call-actions creates an END call log in REST using GET method and parameters from "params" (no return).

"version": "2",
"extension-points": {
"on-releasing-incoming-pbx-call-actions": [
 {
  "name": "GetRestApi",
  "command": {
  "commandType": "rest",
  "method": "GET",
  "url": "http://localhost:3000/IncidentManager/CreateCallLog",
  "params": "byEmail=${localUser.email}&CustomerContact=${caller.phonenumber}"
  }
 }
],

Example 2:

When incoming call is released, the action on-releasing-incoming-pbx-call-actions creates an END call log in REST using POST method and parameters from "bodyParameters" (no return).

"version": "2",
"extension-points": {
"on-releasing-incoming-pbx-call-actions": [
 {
 "name": "PostRestApi",
 "command": {
 "commandType": "rest",
 "method": "POST",
 "url": "http://localhost:3000/IncidentManager/EndCallLog",
 "params": " "
 },
 "bodyParameters": {
 "caller": "${contact.phoneNumber}",
 "user": "${localUser.email}",
 }
],