Call Recording Gadget integration in Cisco Finesse web client

Applies to:

IAS Version 2018.1.1 or newer

Cisco Finesse Version 10.6 or newer

Description:

This article has been prepared in order to describe how Imagicle Call Recording solution can be implemented in a Cisco UCCX-based Contact Center, where Cisco Finesse web client is used as agent's bar.

Moreover, we are describing how to integrate a generic contact center environment, where operators are equipped with CTI-enabled Cisco IP Phones and Finesse or other third-party, web-enabled CRM/ERP applications/agents' bars.

Requirements:

• Imagicle UC Suite Server must be reachable through a FQDN
• The UCCX/UCCE and the Imagicle UC Suite servers must be on the same site, this means that the         domain’s name’s suffix must be the same. For example, if the UCCX/UCCE’s domain is uccx.mycustomer.com, the Imagicle server’s domain must be ucs.mycustomer.com and not     ucs.notmycustomer.com. If the UCCX/UCCE and the Imagicle servers don’t respect this rule, the authentication of Call Recording gadget won't properly work.
• must be accessible via HTTPS, using a trusted certificate.

Enabling Imagicle gadget on Finesse web client

Application and Scope

Imagicle Call Recording is the solution that allow the recording of phones conversation, using always-on or on-demand mode, with the option to temporarily pause and resume current recording.

When a Cisco UCCX contact center solution is in place, it often happens that relevant operators/agents need to access to above feature.

Integration of Imagicle Call Recording gadget into Finesse allows the users to trigger the recording, pause/resume it and browse own audio recordings directly within Finesse web client.

Digital Certificate creation and upload

• Create a certificate for Imagicle UC Suite IIS having the Imagicle server FQDN both in the subject (CN) and in the SAN (Subject Alternative Names) attributes. You can either generate:
  • A trusted certificate, generated by a CA. This is the recommended option.
  • A self-signed certificate (see here for basic instructions). This is not recommended.
• Ensure IIS applies new certificate for HTTPS on port 443.
• Export Imagicle certificate from IIS, by following below procedure:
  • From Start menu, type and then execute Run.
  • In Run popup, type mmc and click OK.
  • In the User Account Control window, click Yes to allow the Microsoft Management Console to apply changes to the computer.
  • In the Console window, from top menu, click File ⇒ Add/Remove Snap-in.
  • In the Add or Remove Snap-ins window, under Available snap-ins (left side), click Certificates and then, click Add.

• In the Certificates snap-in window, select Computer account and then click Next.

• In Select Computer window, select Local computer: (computer this console is running on), and then click Finish.

• In the Add or Remove Snap-ins window, click OK.
• In the Console window, Console Root section, expand Certificates (Local Computer), expand the folder that contains the certificate that you want to export/back up and then click the associated Certificates folder. Your certificate will be in Personal folder.

• In the center section, right-click on the certificate that you want to export/back up and then click All Tasks ⇒ Export to open the Certificate Export Wizard.
• On the Welcome to the Certificate Export Wizard page, click Next.
• On the Export Private Key page, select No, do not export the private key, and then click Next.
• On the Export File Format page, select Base-64 encoded X.509 and then click Next
• Select path and assign a name to the certificate you are going to export and then hit Next
• Click on Finish

• Import the exported certificate certificate into UCCX to get the Imagicle server trusted.
  • If using a trusted certificate, upload the CA certificate chain into “tomcat trust” certificate repository (maybe already present) and then restart Tomcat service.
  •  If using a Self-signed certificate, upload such certificate into “tomcat trust” certificate    repository and then restart Tomcat service.
• Please refer to Cisco documentation for details of this step.

Finesse Gadget Provisioning

Imagicle Gadget for Finesse XML files are attached to this KB. Please pick the one related to your Finesse client version.

Once downloaded, please copy XML file into Imagicle server, in its installation folder: C:\Program Files (x86)\StonevoiceAS

Edit XML file and replace two <IMAGICLE_SERVER> occurrences with actual Imagicle server’s FQDN. See below:

In this file you can also change the fixed height of the gadget, 600 pixel by default, by changing two occurrences of the value on line 37 and 38. See below:

Now please login to the Cisco Finesse Administration portal, select “Desktop Layout” and amend it as below explained:
There are 2 different "roles" in the xml configuration (Agent and Supervisor), keep in mind to configure both if needed

Inside the <tab> tag, add the following instructions:

<tab>
    <id>ImagicleCallRec</id>
    <label>finesse.container.tabs.supervisor.manageRecordingsLabel</label>
    <columns>
        <column>
            <gadgets>
                <gadget>http://<IMAGICLE_SERVER>/fw/ImagicleCallRecorderGadget-v11-12.xml</gadget>
            </gadgets>
        </column>
    </columns>
</tab>

See below screenshot sample:

If, for any reason, the access to Imagicle gadget does not properly work, please copy the amended “ImagicleCallRecorderGadget-vxx.xml” file to UCCX into /3rdpartygadget/files/ folder, as described into Cisco guide for 3^rd party gadgets, and change “Desktop Layout” as below explained:

<tab>
    <id>ImagicleCallRec</id>
    <label>finesse.container.tabs.supervisor.manageRecordingsLabel</label>
    <columns>
        <column>
            <gadgets>
                <gadget>/3rdpartygadget/files/ImagicleCallRecorderGadget.xml</gadget>
            </gadgets>
        </column>
    </columns>
</tab>

Please restart Finesse client.

On imagicle UC Suite server, go to Control Panel ⇒ Internet Options ⇒ Security ⇒ Trusted sites, add the following entries, specifying the correct Imagicle FQDN name:

• https://<UCS_FQDN>/fw/Apps/ApplicationSuite/Web/Pages/Scripts/jquery-1.8.3.min.js
• https://<UCS_FQDN>/fw/Apps/Recorder/Web/Pages/jabber.html

Only if using a self-signed certificate: in order to avoid the Finesse end-users have annoying certificate validity warnings, import the Imagicle UC Suite self-signed certificate into each Finesse user PC, using the Windows certificate snap-in (certmgr.msc). The certificate must be imported in the Trusted Root Certification Authorities\Certificates folder of the PC. You can also push such certificate to all PCs using the Windows domain group policy mechanism.

The Gadget is then available to Finesse users, under “Manage Recordings” tab.

User should login with own Imagicle Server credentials. After login, the list of own recordings appears, together with start/stop and pause/resume recording buttons. See screenshot below:

Troubleshooting

Please make sure that your Cisco domains are added in Imagicle UCX Suite IIS trusted sources, otherwise the Imagicle gadget doesn't work and you get an error message as below sample:

More details are available here.

Cisco/Imagicle Workflow Integration

Calls from/to Cisco agents are routed through UCCX distribution engine, using preferred algorithm. Finesse web client is configured with a specific internal “Workflow” which is triggered upon call answering. This workflow invokes itself an “Action” item in charge of sending an HTTP POST message (REST API) to Imagicle server, including the agent’s extension number. When Imagicle server receives HTTP message, it immediately triggers BiB (or automated dial-in conference) Call Recording on agent’s phone and relevant RTP/sRTP streams are generated toward Imagicle server. See below diagram:

Imagicle server generates encrypted/compressed recording audio file at the end of conversation and assigns it to relevant agent. Above described Finesse workflow and action can be automatically triggered for every call (always-on mode) or by assigning them to a “Start Recording” soft-button in Finesse web GUI (on-demand mode).

Same method for on-demand recording trigger can be configured into any 3^rd party web-based CRM/ERP application, providing they allow the definition of customized soft-button to invoke above mentioned HTTP POST message.

Finesse Workflow Definition

Finesse workflow is required when agent wants to enable always-on recording upon call answering. This is typically needed if you want to automatically record only the relevant calls basing on specific workflow conditions (for instance if the calling party selected a particular option in the UCCX IVR before being transferred to the agent). 
See sample below, where “Imagicle Recording” action is triggered by workflow.

Finesse Action Definition

Finesse action is required for both always-on and on-demand recording modes and this is the configuration which actually calls Imagicle REST API to start the recording. This action can be automatically triggered by above workflow or it can be associated to soft-buttons in Finesse GUI. See below sample, for two different recording methods:

First time Authentication

Imagicle REST API for Call Recording require Basic Authentication, this means that an Authentication header is required in the HTTP POST message. Since Finesse Action configuration does not allow to add headers, the user will be prompted to enter username and password, the first time the action is triggered (see below screenshot). The user will be prompted again when session expires (default timeout is 4 hours).

Please note that applied user's credentials for authentication must have permission level 10 (Complete Management) for Call Recording application; for the other applications, same user can be configured at the lowest level, that is 1 (Base access/No access depending on application).

Please, notice that this is required only if you need to integrate Call Recording with Finesse using the workflow actions. 

Generic CRM/ERP Soft Button definition

Same Imagicle REST API to start the recording can be associated to soft-buttons into any web-based CRM/ERP application. Moreover, specific APIs have been developed to stop the recording, retrieve recording data or download unencrypted recording audio file in MP3 format.

Gadget SSO configuration

1. Edit in the installation folder: C:\Program Files (x86)\StonevoiceAS the XML file downloaded before (v10-v11-v12)
2. Replace this url https://<IMAGICLE-FQDN>/fw/Apps/Recorder/Web/Pages/jabber.html
   with this one http://<IMAGICLE-FQDN>/fw/autologin.asp?go=RecGadget
3. Save
4. Clear the browser's cache
5. Follow this guide to configure SSO correctly (SSO configuration guide)