Calabrio Call Recording

Overview

The call recording function of b+s Connects for ServiceNow has the following features:

• Buttons in the agent UI to pause/resume recording and to save/delete the current recording segment
• Saving an URL to the recording in the ServiceNow call interaction
• Saving the ID of the ServiceNow interaction into the metadata of the recording
• Optionally assigning hoteling user to the current device

Installation

The Calabrio Call Recording feature is already part of b+s Connects for ServiceNow and only needs to be activated in Service Layout settings by selecting it as the Call Recording Product.

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. You will also have to specify the username and password of this API User in Service Layout settings as Server Login Username and Server Login Password.

Write ServiceNow Interaction ID to Calabrio

b+s Connects for ServiceNow allows you to save the ServiceNow Interaction ID into the metadata of the corresponding Calabrio recording. In order to do that, a metatata field of type Text has to be configured in the Calabrio Metadata Manager. You will also have to specify this field key in Service Layout settings as Recording Meta Data Key.

Write Calabrio recording URL to ServiceNow

b+s Connects for ServiceNow allows you to save the Calabrio call recording URL to the corresponding ServiceNow Interaction. In order to do that, you must add custom field of type String or URL in ServiceNow into table Interaction. You will also have to specify the name of this custom field in Service Layout settings as the Recording Link Field.

Configure Calabrio users and devices

Calabrio users can be set up in two modes:

• Fix Device assignment
• Hoteling User (shared desk)

Fix device assignment

The devices can be assigned in Calabrio Device Associations directly to CCE/CCX users.

Hoteling user (shared desk)

If the same device is used by multiple agents, you can configure the devices in Calabrio for hoteling users. The device is assigned in Calabrio Device Associations to a default hoteling user and can then be temporarily re-assigned to the specific hoteling users of the agents. When the agent logs in to Finesse with a specific extension, this extension will be re-assigned by performing an additional login with the hoteling user to Calabrio.

b+s Connects for ServiceNow therefore needs to know the user name of the agents hoteling user in order to automatically process the login. These hoteling user names have the format of an email address.

To configure the agents hoteling user names in ServiceNow, you have to add a custom String field named u_rec_calabrio_user_id into the table Call Center Agent and fill in the agents hoteling user names. If this user name can be deduced from any other available information (e.g. with the ServiceNow user id or the real email address), you can also create a function field to return the required user name instead of creating a normal string field.

Enable CORS

For Calabrio On Premise deployments, CORS (Cross Origin Resource Sharing) must be enabled on the Calabrio Server to allow access from the domain connects.bucher-suter.com and YOUR_INSTANCE.service-now.com.

See Annex below for more information about CORS.

Annex I - CORS (Cross Origin Resource Sharing)

Guides

The following documents can be consulted to help define the terms CORS and CSRF used in this documentation.

Abbreviation	Name	Link
CORS	Cross-Origin Resource Sharing	https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
CSRF	Cross-Site Request Forgery	https://infosec.mozilla.org/guidelines/web_security#csrf-prevention

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-premise deployments of Calabrio and cannot be performed on application servers hosted in the cloud.

caution

This requires a restart of Calabrio Web Server Services to apply the changes. It is recommended to schedule a downtime window to test and restore changes if necessary.

Allow CORS requests to Calabrio Application Server

In this example, the goal is to allow all CORS requests from the following website:

https://fiddle.jshell.net

In your environment, replace this with the origin that your traffic originates from.

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

2. Find the XML tag for <VirtualHost *:443> in the httpd.conf file.

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

4. Add CORS rules to allow certain protocols and methods of access to the request.

Note: 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"

Note: 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"

5. Save the file and 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 environment.

1. Backup the following registry section:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Apache Software Foundation\Procrun 2.0\ciWFOTomcat\
    \Parameters\Java

2. 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, edit the request as shown below:

-Dsecondary.public.hosts=fiddle.jshell.net

The following print screen shows the changes made in this example:

tip

If there is more than one host, the values can be separated with a comma.

3. Restart The following Calabrio services:

• Calabrio ONE Application Server
• Calabrio ONE Web Server

Allow CORS requests to the Calabrio Data Server

1. Backup the following file:

C:\Program Files\Calabrio ONE\Data Server\Tomcat\conf\web.xml

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

3. 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 was allowed from the origin https://jsfiddle.net/.

1. Navigate to https://jsfiddle.net/
2. 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);
});

3. Modify the script to point to your Calabrio deployment with a valid username/password.

4. Modify the JSFiddle settings 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).

5. Open your browser's Developer console -- 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 since one is the "Pre-Flight" request to validate what the server allows and 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 is 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.