Launch external applications on an incoming phone call v2

Rainbow allows you to retrieve information about incoming phone calls. You can use this information by transferring it to another application.
With this "Computer Telephony Integration" you can benefit from Rainbow information combined with another database.

A specific configuration is required for each external application you want to use for this type of integration, refer to their documentation for the correct syntax for the transmission of variables.
At the end of this article you'll find some examples of integration between Rainbow and the test tool "MicroCRM".

Configure the custo-manifest.json file

With this new version you can directly, from the desktop app, export (1) a template of the new custo-manifest.json file including some syntax help. Once you have modified the file you can import (2) the configuration on the same setting page.

This file contains a list of actions to be performed on a predefined event.

Events for incoming calls:

There are 4 events available:

• on-incoming-pbx-call-actions  (external app launched when a new incoming call is presented)
• on-incoming-pbx-call-display-actions (CPaaS usage - display more information when a new incoming call is presented, either from a file, using REST API or launching a Rainbow Bot)
• on-answering-incoming-pbx-call-actions (external app launched when an incoming call is answered)
• on-releasing-incoming-pbx-call-actions (external app launched when an incoming call is released)
• on-incoming-pbx-call-button-actions (external app launched only on click on a button added in the incoming call popup)

For the selected Event you'll have to configure at least the "command" section composed of an "url" and "params". The "name" field has to be completed only for the event on-incoming-pbx-call-button-actions, it will be the name displayed on the button in the incoming call pop-up

"url" - External application location

in the URL field you'll provide either the url or the path of the external application

"params" - Variable to be transmitted to the external application

Different variables are available:

Called party (Rainbow user currently connect to the desktop app):

• ${localUser.firstName}
• ${localUser.lastName}
• ${localUser.email}
• ${localUser.canonicalNumber}
• ${localUser.phoneNumber}
• ${localUser.internalNumber}

Calling party

• ${caller.firstName}
• ${caller.lastName}
• ${caller.phoneNumber}

Called phone number (when call is redirected or when Rainbow gets the group number) 

• ${called.phoneNumber}

Call context (Only for OXE)

• ${call.callId}
• ${call.globalCallId}

Specific options for on-answering-incoming-pbx-call-actions

"RaiseChangeCall": false | true | only

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

Template file

{
"version": "2",
"extension-points": {
	"on-incoming-pbx-call-actions": [
		{
			"name": " ",
			"command": {
				"url": " ",
				"params": " "
			}
		}
	],
        "on-incoming-pbx-call-display-actions": [
                {
                        "name": " ",
                        "command": {
                             "commandType": " ",
                             "url": " ",
                             "method": " ",
                             "params": " ",
                             "header": [
                                " "
                             ],
                             "Jid": ""
                        },
                        "responseType": " ",
                        "jsonField": " "
                }
        ],
	"on-answering-incoming-pbx-call-actions": [
		{
			"name": " ",
			"command": {
				"url": " ",
				"params": " "
			},
                        "RaiseChangeCall": false
		}
	],
	"on-releasing-incoming-pbx-call-actions": [
		{
			"name": " ",
			"command": {
				"url": " ",
				"params": " "
			}
		}
	],
	"on-incoming-pbx-call-button-actions": [
		{
			"name": " ",
			"command": {
				"url": " ",
				"params": " "
			},
			"AnswerOnClick": false
		}
	]
},

"help": [
  " This Json file contents events customization for Rainbow Desktop application ",
  " Sources of events: ",
  " - on-incoming-pbx-call-actions : when a new incoming call is presented. ",
  " - on-incoming-pbx-call-display-actions : when a new incoming call is presented. ",
  " - on-answering-incoming-pbx-call-actions : when an incoming call is answered. ",
  " - on-releasing-incoming-pbx-call-actions : when an incoming call is released. ",
  " - on-incoming-pbx-call-button-actions : on click on a button added in the incoming call popup",
  " ",
  " name : is used only for the action button as the label of the button. ",
  " filter: set with value NoShortNumber will no invoke command if caller number is an internal. ",
  " AnswerOnClick: only for `on-incoming-pbx-call-button-actions` when set to `true`, the click ",
  " button will both answers the call and invoke the command ",
  " RaiseChangeCall: only for `on-answering-incoming-pbx-call-actions` when set to `true` or `only`",
  " will raise the event in transfer/switch call. ",
  " responseType: only for `on-incoming-pbx-call-display-actions` with commandType `file` or `rest`",
  " and can be `markdown` or `json`. ",
  " jsonField: only for `on-incoming-pbx-call-display-actions` with responseType `json` ",
  " ",
  " Available command keys: ",
  " url: is the path of the executable or an URL ",
  " params: is string with variable ${xx} which will be replaced by value when command invoked ",
  " commandType: only for `on-incoming-pbx-call-display-actions` and can be `file` or `rest` or `rainbowBot`",
  " method: only for `on-incoming-pbx-call-display-actions` with commandType `rest`and can be `GET` or `POST`",
  " header: only for `on-incoming-pbx-call-display-actions` with commandType `rest` is optional ",
  " and will be inserted as a header line in REST request ",
  " Jid: only for `on-incoming-pbx-call-display-actions` with commandType `rainbowBot` ",
  " ",
  " Variable for Rainbow user (ME) ",
  " ${localUser.firstName} ${localUser.lastName} ${localUser.email} ",
  " ${localUser.canonicalNumber} ${localUser.phoneNumber} ${localUser.internalNumber} ${localUser.phonePbx}",
  " ",
  " Variable for caller user ",
  " ${caller.firstName} ${caller.lastName} ${caller.phoneNumber} ",
  " ",
  " Variable for called number - when call is redirected or when Rainbow gets the group number ",
  " ${called.phoneNumber} ",
  " ",
  " Variable for call context ",
  " ${call.callId} ",
  " ${call.globalCallId} (OXE only) ",
  " ${call.correlatorData} ",
  " ${call.hexCorrelatorData} " 
 ]
}

Examples of configuration with the tool MicroCRM

To open or create a record in the MicroCRM database, to transmit the phone number the tool must be run with the -number parameter:

MicroCRM.exe -number phonenumber

• For the examples below we will use the caller phone number which is the variable ${caller.phoneNumber} 
• MicroCRM is installed on the PC in the following location C:\MicroCRM\MicroCRM.exe

Example 1 - Open MicroCRM on answered incoming call

You only have to modify following part of the file:

"on-answering-incoming-pbx-call-actions": [
 {
  "name": " ",
  "command": {
  "url": "C:\\MicroCRM\\MicroCRM.exe",
  "params": "-number ${caller.phoneNumber}"
   }
  }
 ],

Note: Do not forget to use double \\ for the path C:\\MicroCRM\\MicroCRM.exe

Example 2 - Open MicroCRM when you answer a call using the dedicated button in the incoming call notification

You only have to modify following part of the file:

"on-incoming-pbx-call-button-actions": [
 {
  "name": "Open MicroCRM",
  "command": {
  "url": "C:\\MicroCRM\\MicroCRM.exe",
  "params": "-number ${caller.phoneNumber}"
   },
  "AnswerOnClick": true
  }
 ]

Note: To open the external application and answering the call simultaneously you'll have to set the "AnswerOnClick" parameter to true.

Example 3 - Open French reverse directory webpage on incoming call

In this example we don't use an application installed on the PC but we will open a webpage and the variable is directly provided into the "url"

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

Installation options to deploy the custo-manifest.json using a Software Distribution Tools

The manifest file must first be deployed on the PC, for example, the file can be copied to a user folder C:\Users\username\Rainbow_custom_manifest\.

Then the Rainbow Desktop app setup must be launched with the parameter /Custom to apply the custom-manifest file for the user.

Using MSI setups:

msiexec /i "Rainbow_installer_user.msi" WRAPPED_ARGUMENTS="/Custom=C:\\Users\\username\\Rainbow_custom_manifest\\custo-manifest.json"

Using exe setups:

Rainbow_Installer.exe /Custom=C:\\Users\\username\\Rainbow_custom_manifest\\custo-manifest.json

Disable the feature

For an installation through Software distribution tool

To disable the use of the custom-manifest file run the installation with /Custom without any value
e.g. Rainbow_Installer.exe /Custom or uninstall and install again the Rainbow desktop app.

For Manual/User installation (import of custo-manifest file)

Go to the folder C:\Users\username\AppData\Roaming\Alcatel-Lucent Enterprise\Rainbow

Delete the file custo-manifest.json

Migration Launch external applications v1 to v2

A user already using version 1 can continue to use it without any change

The Import/Export will not be presented.

To migrate from version 1 to version 2 you must:

1. Save the Custom manifest file v1 
2. Changes the Rainbow Settings file and set the line "customizationDirectory": true
   • file location C:\Users\username\AppData\Roaming\Alcatel-Lucent Enterprise\Rainbow
   • note you'll have to quit Rainbow before changing the file 
3. Now in Settings->Telephony->Customization section becomes visible
4. Export the template, add in this file the custom commands from your file saved in step 1 and then import it again.