Calabrio Recording Toolbar
Introduction
This document provides information to install, configure, and manage the Bucher + Suter (b+s) Connects for Salesforce Recording Toolbar for Calabrio solution. b+s Connects for Salesforce Recording Toolbar for Calabrio is the name of the software solution developed by b+s to integrate Salesforce CRM and Cisco customer contact solution with the Calabrio recording solution.
Compatibility
Supported versions
- Calabrio On-Prem 11.5
- Calabrio Cloud
- Supported in Cisco CCE and CCX deployments.
- Recording feature must be enabled by b+s on request.
- This integration requires Calabrio ONE Authentication to be enabled.
- Gateway recording deployments are not supported.
Installation
The Recording Toolbar is integrated in the b+s Connects for Salesforce package as Add-on feature. Follow the sub-chapters in this chapter in the order to configure the Recording Toolbar correctly.
Contact b+s to have the Recording Toolbar activated.
Calabrio can be deployed On-Prem or Cloud based. Both ways use different authentication methods. Please refer to its corresponding chapter, On-Prem authorization credentials or Calabrio Cloud - Salesforce Named Credentials
Due to a limitation in the Calabrio API it is not possible to show the current state of the recording inside the Recording Toolbar.
Configuration
Follow the sub-chapters in this chapter to configure the Recording Toolbar accordingly.
Calabrio User Configuration
Calabrio user can be set up in two modes:
- Hoteling User (shared desk)
- Fix Device assignment
Hoteling User (shared desk)
In Calabrio, the devices (agent phones) are not fix assigned to the agents (Calabrio user). The agent must login the Calabrio Recording Toolbar to assign the device (agent phone) to his Calabrio user.
Required config for the Recording Toolbar:
- User Login Required: Checked
- User ID Field
- User ID Appendix
Please refer to the user configuration in the Calabrio ONE documentation to proceed in Hoteling User configuration.
Fix Device assignment
In Calabrio, the devices can be assigned directly to users, making the login process different. As soon as the Calabrio server detects a device (extension) that wants to login, it checks the configuration and proceeds accordingly. No User Login Required is needed in this deployment.
Required config for the Recording Toolbar:
- User Login Required: Unchecked
- User ID Field: not needed. Leave it blank.
- User ID Appendix: not needed. Leave it blank.
Please refer to the user configuration in the Calabrio ONE documentation to proceed in Fixed Device assignment configuration.
Calabrio Server Configuration
Create an API User
This integration requires Calabrio ONE Authentication to be enabled and an API User configured properly. An API user is configured the same as a system administrator, but the purpose of this user is to enable third-party applications to authenticate with Calabrio ONE.
Write CRM ID to Calabrio Metadata
In order to save the CRM ID of the call activity to the Calabrio metadata. A type “text” metadata field has to be configured in the Calabrio Metadata Manager. You will have to specify the same key in the Recording Toolbar Settings Meta Data Keys field.
Enable CORS (On-Prem only)
For On-Prem deployments, CORS (Cross Origin Resource Sharing) must be enabled on the Calabrio Server. See Annex I - CORS (Cross Origin Resource Sharing)
Salesforce Configuration
Depending on the deployment model, the User credentials for the API users are defined and stored in different ways:
- Calabrio Cloud deployments: Salesforce Named Credentials
- Calabrio On-Premises deployments: On-Prem authorization credentials
Calabrio Cloud
After adding the Calabrio Cloud
Addon to the Custom Toolbars (ref), a new section Calabrio Cloud Setting
is now visible under the Integrations
section.
Due to Salesforce security changes introduced in Winter '24 release, the connection to a Calabrio Cloud server using the new Named Credentials is only possible when using a version of b+s Connects for Salesforce solution greater or equal to 5.9.4. Legacy Named Credentials are only supported in versions below (and including) 5.8.
b+s Connects for Salesforce version 5.9.4 shows an "Insufficient privileges" error for Users lacking the View Setup and Configuration
permission in their Profile. Upgrading to the latest version of the b+s Connects for Salesforce connector is recommended instead of assigning the View Setup and Configuration
setting to the Users' profile.
Before to proceed with the configuration, in order to establish a connection to the Calabrio Cloud server, it's required to create and configure at least one set of Named Credentials and External Credentials using the button in the b+s Configuration record page (ref).
As of b+s Connects for Salesforce v.5.9, the Legacy Named Credentials
(ref) are no longer supported.
1. Create the Named Credential and External Credential pair
In order to create the required pair of Named Credential and External Credential, click on the button "New Named Credential" present in the "Calabrio Cloud Settings" section of the
in use b+s Configuration record page. The button will change color once the operation is done, signaling the success or failure of the operation. If the operation is successful, the new Named Credential created will be available to be selected in the adjacent "Calabrio Cloud Named Credential" dropdown and a direct link to its configuration page in Salesforce Setup will also appear on the right of the button.
Click on the "Open in Setup" link to open the new Named Credential record just created in a new tab.
Due to Salesforce's security settings limitations introduced in Winter '24 release, Managed Packages are unable to fully access the data stored in Named Credentials and External Credentials, therefore it is required to create the pair of these records by using the "New Named Credential" button in the b+s Configuration record page as described above.
2. Configure the Named Credential record
Setup | Security | Named Credentials
If required, change the Label field. The Name field can also be changed, but the Named Credential record must be then re-assigned to the b+s Configuration record.
Label: Named Credential record's display name
Name: API Name of the Named Credential record. It is recommended not to change this value. When changed, the Named Credential must be re-assigned to the b+s Configuration record(s).
Enabled for Callouts: checked
(true)
Allowed Namespaces: cnx
Do not change the other fields' value.
Click on Save
button
3. Configure the External Credentials record
Setup | Security | Named Credentials | External Credentials (tab)
Label: External Credential record's display name
Name: Do not change this value if unsure.
In the Principals section, find the Calabrio Cloud Server Credentials
Principal and, under Actions, click on Edit
.
In the Authentication Parameters
section, click on Add
button
In Parameter 1:
Name: Username
Value: <The API User's username>
In the Authentication Parameters
section, click on Add
button.
In Parameter 2:
Name: Password
Value: <The API user's password>
Click on Save
button (wait for the page to reload, it may take a while)
4. Assign required permissions
Setup | Users | Permission Sets
Create a new Permission Set with the following settings:
- Apps > Object Settings > User External Credentials > Enable
Read
- Apps > External Credential Principal Access > Click
Edit
> Select your External Credential record fromAvailable External Credential Principals
column and add it underEnabled External Credential Principals
Assign the Permission Set to the required User(s).
5. Complete the configuration in the b+s Configuration record
User Login Required
If auto recording is disabled, this setting needs to be enabled. To define the login information for the user either configure “userIdField” or “userIdExtension”.
Default: false
Example Value: false
User ID Field
Define the field on the user object that contains the Calabrio user ID, in order to login.
Default: Alias
Example Value: Alias
User ID Appendix
Instead of saving the Calabrio user ID in an extra field. The admin can configure an extension. This extension gets attached to the cisco username and the combination of both are used to log the user in.
Default: empty
Example Value: @abc.com
Calabrio Cloud Named Credentials
Select one of the available Named Credential records.
Please note that only the Named Credential records created using the button "New Named Credential" are displayed here.
New Named Credential button
Click on this button to create a new pair of Named Credential and External Credential that can be used by the b+s Connect for Salesforce package to connect to a Calabrio Cloud Server.
Recording Link Field
Field name of the Salesforce Activity custom field where the recording link will be stored. If key is not present, the recording link will not be written.
Default: empty
Example Value: pfx__MyCustomField__c
Meta Data Key
Field name of the Calabrio server metadata field to store Salesforce Task Id. If key is not present, the metadata will not be written in Calabrio Server.
Default: empty
Example Value: sf-id-key
Call Status Interval
Sets the timeout between two callStatus requests against the Calabrio Server. The callStatus requests are sent as soon as a call starts up to when we retrieve a contactId from Calabrio or the call has ended.
Default: 2000
Example Value: 2000
Agent Buttons
This list of checkboxes can be used to enable specific action buttons.
Default: all unchecked
Pause
: Enables the Pause action during a call.Resume
: Enables the Resume action during a call.Segment Save
: Enables the Segment Save action during a call.Segment Delete
: Enables the Segment Delete action during a call.
Calabrio On-Prem
For On-Prem deployments, store the Recording Server credentials in the fields On-Prem server Login Username and On-Prem server Login Password that you will find in the Calabrio On-Prem Settings section of the b+s Configuration record in use after adding the Calabrio On-Prem
Addon to the Custom Toolbars.
Recording Link Custom Field (Optional)
If you want to create a custom field on the task to write the recording link to.
Setup | Object Manager | Activity | Fields | New
Add a new field and choose the following options:
Data Type:
URL
Field Label:
your field label
Field Name:
your field name
Description:
optional
Required:
not checked
- Make sure that the Contact Center Agents have read and write access to the field.
- Add the newly created field to the Task object's Page Layouts in use.
- The API name of the new field can be found under Setup | Object Manager | Activity | Fields (needed below in the configuration of the custom toolbar)
b+s Configuration
Custom Toolbar and Integration Settings
To add the Recording Toolbar to the b+s Connects for Salesforce gadget, you will need to + Add a new Custom Toolbar, select the Location of the new Custom Toolbar, select Add-On in the URL dropdown and select either Calabrio On-Prem or Calabrio Cloud in the dropdown next to the URL one. Set the respective Height to 25.
Configure your Recording Toolbar in the new Calabrio Settings section displayed after you select the Add-On.
User Login Required
If auto recording is disabled, this setting needs to be enabled. To define the login information for the user either configure “userIdField” or “userIdExtension”.
Default: false
Example Value: false
User ID Field
Define the field on the user object that contains the Calabrio user ID, in order to login.
Default: Alias
Example Value: Alias
User ID Appendix
Instead of saving the Calabrio user ID in an extra field. The admin can configure an extension. This extension gets attached to the cisco username and the combination of both are used to login the user.
Default: empty
Example Value: @abc.com
On-Prem server Login Username
Login Username that will be used to authenticate against the Calabrio On-Prem recording server. For Cloud deployments leave this field blank.
Default: empty
On-Prem server Login Password
Login Password that will be used to authenticate against the Calabrio On-Prem recording server. For Cloud deployments leave this field blank.
Default: empty
Recording Link Field
Field name of the Salesforce Activity custom field where the recording link will be stored. If key is not present, the recording link will not be written.
Default: empty
Example Value: pfx__MyCustomField__c
Meta Data Key
Field name of the Calabrio server metadata field to store Salesforce Task Id. If key is not present, the metadata will not be written in Calabrio Server.
Default: empty
Example Value: sf-id-key
Recording Server
For the On-Prem deployments, specify the Calabrio Recording Server in the "Recording Server" field. It should contain the protocol (https) and the FQDN.
Example Value: https://FQDN
Call Status Interval
Sets the timeout between two callStatus requests against the Calabrio Server. The callStatus requests are getting send as soon as a call has started until we retrieve a contactId from Calabrio or the call has ended.
Default: 2000
Example Value: 2000
Agent Buttons
This list of checkboxes can be used to enable specific action buttons.
Default: all unchecked
Pause
: Enables the Pause action during a call.Resume
: Enables the Resume action during a call.Segment Save
: Enables the Segment Save action during a call.Segment Delete
: Enables the Segment Delete action during a call.
Chrome Browser Configuration
The Google Chrome 80 release changes the default cross-domain (SameSite) behavior of cookies.
SameSite is a reasonably robust defense against some classes of cross-site request forgery (CSRF) attacks, but developers currently need to opt in to its protections by specifying a SameSite attribute. In other words, developers are vulnerable to CSRF attacks by default. This change would allow developers to be protected by default, while allowing sites that require state in cross-site requests to opt in to the status quo’s less-secure model.
In On-Prem deployments, you will need to disable the SameSite policy. Go to chrome://flags and disable the "SameSite by default cookies". This will disable the treatment of cookies that do not specify a SameSite attribute as if they were SameSite=Lax.
Troubleshooting
Error message is displayed when login
Symptom
After doing a successful login in the softphone, a "Could not login" error is displayed
Possible cause(s)
- Calabrio server is down
- Calabrio server connection is blocked
- Calabrio server certificates are expired or not trusted
Solution
- Check Calabrio server is up and running
- Check client computer has access to the Calabrio server. Access to
https://<calabrioserver>
from the same browser the agent uses to connect to Salesforce - Check Calabrio certificates are accepted by the client computer. Do the same step as when checking the connection: Access to
https://<calabrioserver>
from the same browser the agent uses to connect to Salesforce
Recording Control Buttons Do Not Show After Login
If after logging in the agent in the b+s Connects for Salesforce gadget the Recording Control buttons do not show up after the agent’s state is not ready or ready, it can have the following reasons.
Error: Invalid Extension with HD Login/Logout
Symptom
The Connects gadget shows an error: Invalid Extension with HD Login/Logout.
Possible cause(s)
The VoIP device is assigned to a specific agent on Calabrio server. To support this configuration the call center definition configuration needs the userLoginRequired setting.
The userLoginRequired setting must correspond with the Calabrio server configuration.
Error: No active recording found
Symptom After successfully loading the Calabrio toolbar (i.e. the recording buttons are visible and greyed out), when a call is accepted or connected, an error message is displayed below the recording buttons: "No active recording found".
Cause The Calabrio server cannot validate and match the Agent's firstname and lastname.
Solution Verify that the Agent's firstname and lastname are identical on both Calabrio and Cisco Finesse.
Annex I - CORS (Cross Origin Resource Sharing)
Preknowledge
The following documents can be consulted to help define the terms Cross-Origin Resource Sharing (CORS) and Cross-Site Request Forgery (CSRF) used in this documentation:
Cross-Origin Resource Sharing (CORS)
Allowing HTTP requests from Cross Site resources in Calabrio
Making the changes suggested in this guide will allow external resources to access Calabrio. Therefore, it is recommended to read the documents listed above beforehand. In addition, it is recommended that before making any changes, all configuration files are backed up for possible recovery.
The following changes may cause Calabrio Web Services to become unresponsive if not performed properly. Please note: This solution only applies to On-Prem deployments of Calabrio.
This will require restarting Calabrio Web Server services to apply the changes. It is recommended that you plan an outage window that gives you time to test your changes and sufficient time should you need to restore back to a previous configuration.
Allow CORS requests to Calabrio Application Server
In this example, the goal is to allow all CORS requests from the following sample url:
https://fiddle.jshell.net
Please replace this sample url in your environment with the origin that your traffic originates from.
- Back up your httpd.conf file. For a standard Calabrio installation, the file is located here:
C:\Program Files\Common Files\Calabrio ONE\Server\config
Find the XML tag for
<VirtualHost *:443>
in the httpd.conf file. This section will allow us to set rules for all traffic that crosses the HTTPS protocol.Add the following re-write rules:
RewriteCond %{REQUEST_METHOD} OPTIONS
RewriteRule ^(.*)$ $1 [R=200,L]
This change will allow Pre-Flight requests to return with a Status of 200 allowing the application to send a follow up request.
- Add CORS rules to allow certain protocols and methods of access to the request. This should be specific to what your application is doing to ensure its limited to the minimum that you need.
Modify the following lines in your website's origin. This must include the http/https requirements.
Header always set Access-Control-Allow-Origin "https://fiddle.jshell.net"
Header always set Access-Control-Allow-Credentials "true"
Apache does not support multiple origins in this field or additional entries. Consult Apache Documentation for additional options if this method is not applicable.
Header always set Access-Control-Allow-Origin "https://fiddle.jshell.net"
Header always set Access-Control-Allow-Credentials "true"
Header always set Access-Control-Allow-Methods "POST,GET,OPTIONS,DELETE,PUT"
Header always set Access-Control-Max-Age "3600"
Header always set Access-Control-Allow-Headers "X-Requested-With, Content-Type, Origin,
Authorization, Accept, Client-Security-Token, Accept-Encoding"
Full example:
<VirtualHost *:443>
#Protocols h2 http/1.1
ServerName localhost
SSLEngine on
SSLCertificateFile "C:/Program Files/Common Files/Calabrio One/Server/config/localhost.crt"
SSLCertificateKeyFile "C:/Program Files/Common Files/Calabrio One/Server/config/localhost.key"
SSLUseStapling on
RewriteEngine On
#Disable TRACE and TRACK http methods
RewriteCond %{REQUEST_METHOD} ^(TRACE|TRACK)
RewriteRule .* - [F]
RewriteRule ^/$ https://%{HTTP_HOST}/index.html [R=301]
RewriteRule ^/login/index.html$ https://%{HTTP_HOST}/index.html [R=301]
RewriteCond %{REQUEST_METHOD} OPTIONS
RewriteRule ^(.*)$ $1 [R=200,L]
Header always set Access-Control-Allow-Origin "https://fiddle.jshell.net"
Header always set Access-Control-Allow-Credentials "true"
Header always set Access-Control-Allow-Methods "POST,GET,OPTIONS,DELETE,PUT"
Header always set Access-Control-Max-Age "3600"
Header always set Access-Control-Allow-Headers "X-Requested-With, Content-Type, Origin,
Authorization, Accept, Client-Security-Token, Accept-Encoding"
- Save the file, Restart The following Calabrio services:
- Calabrio ONE Application Server
- Calabrio ONE Web Server
Allow CSRF requests to Calabrio Application Server
This step will need to be applied to each Calabrio Application server in your stack.
- Backup the following registry section:
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Apache Software Foundation\Procrun 2.0\
\ciWFOTomcat\Parameters\Java
- Modify the "Options" key to include the following line:
-Dsecondary.public.hosts={HOST MAKING REQUEST}
If you are using https://jsfiddle.net/ to make your request you would edit the request to look as follows:
-Dsecondary.public.hosts=fiddle.jshell.net
To determine the value, you will need to issue a request and inspect the request headers for the "Origin" tag, for this particular origin it would be:
Origin: https://fiddle.jshell.net
Example of Registry Change:
If you have more than one host you can separate the values with a comma.
- Restart The following Calabrio services:
- Calabrio ONE Application Server
- Calabrio ONE Web Server
Allow CORS requests to Calabrio Data Server
- Backup the following file: *Note: Your installation directory may differ.
C:\Program Files\Calabrio ONE\Data Server\Tomcat\conf\web.xml
- Append the following attributes to your web.xml file.
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>*</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.methods</param-name>
<param-value>GET,POST,HEAD,OPTIONS,PUT</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.headers</param-name>
<param-value>Content-Type,X-Requested-With,accept,Origin,Access-Control-Request-Method,
Access-Control-Request-Headers</param-value>
</init-param>
<init-param>
<param-name>cors.exposed.headers</param-name>
<param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>
</init-param>
<init-param>
<param-name>cors.support.credentials</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>cors.preflight.maxage</param-name>
<param-value>10</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
- Restart the following Calabrio service:
- Calabrio ONE Data Server Web Services
Testing
This test can be used to validate that the filter is blocking/allowing traffic from specific origins. In this example CSRF and CORS traffic is allowed from the origin https://jsfiddle.net/
- Navigate to
https://jsfiddle.net/
- Paste the following code into the "Javascript" window:
var settings = {
"url": "https://yourCalabrioAddress/api/rest/authorize",
"method": "POST",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
"data": JSON.stringify({"userId":"yourUser@email.com","password":"YourPassword","locale":"en"}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
- Modify the script to point to your Calabrio deployment with a valid username/password. (This will allow us to test that we can send a POST request to the Calabrio server and authenticate an API session -- you can perform other API calls after this step if you so choose).
- Modify the settings of JSFiddle to point to the proper JavaScript frameworks to support this code snippet: Select the drop down for a menu. Note: This setting is in the pane for "Javascript" on the site. (You can see this same option in Step 3's screenshot in the top left corner).
- Open Developer console of your browser -- and press the "Run" button for Jsfiddle.
If your test was successful you should see Status "200" back on your authentication (Network tab) and session details logged to the console.
You will see two authorize events as one is the "Pre-Flight" request to validate what the server allows where the other is the actual payload with our javascript request.
Your developer console will show:
How to determine your "Origin"
To capture your "Request-Origin" you will need to inspect the payload you are sending -- All HTTP Requests will have "Request Headers" set -- The browser will automatically set this particular header for us.
Inspecting the request in Developers tools will show us a "Request Headers" Section under the "Headers" pane. The "Origin" is the element of interest.
Annex II - SameSite
SameSite is a cookie attribute. The Recording Toolbar sends an authorize request to the Calabrio application server and it responds with a token that is stored into a cookie (set-cookie response header). Whenever a request is sent to the Calabrio domain, the cookie gets attached to the request and the Calabrio server can validate the token. With the latest browser versions, all cookies without a SameSite=None attribute are defaulted to 'lax' which prevents the browser from sending the cookie in a cross-domain request.
The solution is to inject SameSite=None to the cookie attributes from the On-Prem Calabrio Application server.
Open the previously modified httpd.conf
file located in the standard Calabrio installation folder
C:\Program Files\Common Files\Calabrio ONE\Server\config
from the Calabrio Application server and check that
LoadModule headers_module modules/mod_headers.so
is added to the LoadModule list.
Check that it does not have a #
at the beginning of the line.
Add the following chunk of code after the LoadModule list:
<ifmodule mod_headers.c>
Header always edit Set-Cookie (.*) "$1; SameSite=None"
Header onsuccess edit Set-Cookie (.*) "$1; SameSite=None"
Header edit Set-Cookie ^(.*);\s?SameSite=None;?\s?(.*);\s?SameSite=None;?\s?(.*)$ "$1; $2; $3; SameSite=None"
Header edit Set-Cookie ^(.*);\s?;\s?(.*)$ "$1; $2"
</ifmodule>
Restart the Calabrio One Application Server
and the Calabrio One Web Server
services.
Annex III - Private Network Access Preflight
The following document can be consulted to help define the term Private Network Access (PNA) preflight used in this documentation:
https://developer.chrome.com/blog/private-network-access-preflight/
Private Network Access (formerly known as CORS-RFC1918) restricts the ability of websites to send requests to servers on private networks.
The specification also extends the Cross-Origin Resource Sharing (CORS) protocol so that websites must now explicitly request a grant from servers on private networks before being allowed to send arbitrary requests.
Private network requests are requests whose target server's IP address is more private than that from which the request initiator was fetched. For example, a request from a public website (https://example.com) to a private website (http://router.local), or a request from a private website to localhost.
In order to keep the Calabrio integration working, two chenges will need to be done in the On-Prem Calabrio Application server.
Open the previously modified httpd.conf
file located in the standard Calabrio installation folder
C:\Program Files\Common Files\Calabrio ONE\Server\config
from the Calabrio Application server and adapt the code so it looks like the following:
[...]
Header always set Access-Control-Allow-Methods "POST,GET,OPTIONS,DELETE,PUT"
Header always set Access-Control-Max-Age "3600"
Header always set Access-Control-Allow-Private-Network "true"
Header always set Access-Control-Allow-Headers "X-Requested-With, Content-Type, Origin,
Authorization, Accept, Client-Security-Token, Accept-Encoding, Access-Control-Request-Private-Network"
[...]
Changes: the line Header always set Access-Control-Allow-Private-Network "true"
is new and the Access-Control-Request-Private-Network
was added to the Access-Control-Allow-Headers
list.
Restart the Calabrio One Application Server
and the Calabrio One Web Server
services.