FAQs - Finesse - Cisco DevNet (2024)

General

What is Finesse?
What can a developer do with Finesse?
What is the difference between the Finesse REST API and the Finesse JavaScript API?
Where can I find the Finesse documentation?
How do you use the Finesse documentation?
I need to build an application that works for both UCCE and UCCX, can I build one application for both deployments?
Does Finesse support High-Availability installations?
Does Finesse support 2-Way SSL Web Service calls?
Does Finesse support Cross-Origin Resource Sharing (CORS)?
I created a workflow that makes a non-Finesse HTTP request. Where do I enter in the authentication credentials for the HTTP request?
Can the columns of the desktop layout be different widths?
What are the supported browsers for Finesse version XX.X(X)?
How do I add additional filters to the Live Data Gadget?
How do I add a Historical Report to the Finesse desktop?
None of the FAQ here answers my question. Help!

Finesse REST API

Where can I find the Finesse REST API documentation?
I want to use the Finesse REST APIs, but where do I start?
Does Finesse have an API to _________?
What port should I use for my REST APIs?
What type of authentication do the REST APIs use?
How do I authenticate Finesse REST APIs with SSO?
How do I get the access token from the Cisco Identity Service?
Which role (agent, supervisor, administrator) can use _________ API?
Can I use the credentials/token for one user to make REST API requests on behalf of multi users?
What format is the Finesse REST API request/response?
Some values in the Finesse responses are a pass through from UCCE or UCCX. Where can I find more information about these values?
Where can I find the supported agent state transitions?
What languages can I use to develop an application that uses Finesse REST APIs?

Finesse Notification Service

What is the Finesse Notification Service?
What port should I use to connect to the Finesse Notification Service?
How do I connect to the Finesse Notification Service with SSO?
My application needs to receive Finesse notifications. Do I need to subscribe to the nodes to get notifications?
Can the same user log into the Finesse Agent Desktop and also establish a connection to the Finesse Notification Service to receive Finesse notifications?
Which XMPP/BOSH/WebSocket library should I use to communicate to the Finesse Notification Service?

Finesse JavaScript Library

Where can I find the Finesse JavaScript Library documentation?
I want to build a gadget using the Finesse JavaScript Library, but where do I start?
Where do I get the Finesse JavaScript Library file (finesse.js) for Finesse 10.6 and above?
Where can I find sample gadgets?
Where do I upload my third-party gadget that I built?
What are these handlers/callbacks in the sample gadgets?
How do I create/update gadgets to work with SSO?
None of the sample gadgets are working. Help!
After I upgraded Finesse, my gadget stopped working.
I made code changes to my gadget, why don't I see the changes on the desktop?
I want to modify an out of the box gadget, where do can I get the code?
How do I get the loading indicator (the spinning circle) for my gadget like the Finesse gadgets?
How do I change the height of the team performance gadget?
How do I change the height of the Embedded WebApp Sample Gadget?
How do I call a third-party REST API from a Finesse gadget?

Q: What is Finesse?

Finesse is a next generation agent desktop that is designed to provide the optimal user experience for agents. It is 100% browser based so agent client machines do not need any contact center specific applications. Finesse Overview for more info.

Q. What can a developer do with Finesse?

Finesse is built for developers. It provides two types of APIs, the Finesse REST API and the Finesse JavaScript Library API.

There are three paths for customization:

Use the Finesse REST APIs.
- Integrate Finesse into your existing application (whether it is thick or thin)
- Create a completely custom agent desktop
Use the Finesse JavaScript Library APIs to create gadgets to be added to the Finesse out of the box agent desktop. These gadgets do not have to be Finesse or Cisco specific.
Create gadgets of existing applications to be added to the Finesse out of the box agent desktop without using any Finesse specific APIs.

Q: What is the difference between the Finesse REST API and the Finesse JavaScript API?

The Finesse REST APIs are HTTP based and can be used to build custom applications and/or integrate into existing applications. They work alongside the events from the Finesse Notification Service. The REST APIs can be used server side as well as client side.

The Finesse JavaScript API is a JavaScript wrapper on top of the Finesse REST APIs, but also includes other classes and methods to seamlessly handle the Finesse Notification Service events and communicate to other gadgets within the Finesse out of the box desktop. These APIs can only be used within a custom Finesse gadget for the Finesse out of the box desktop.

Q. Where can I find the Finesse documentation?

The documentation for the latest version of Finesse can be found on the Finesse DevNet site under Docs -> Guides:

The Finesse REST API: Finesse Web Services Developer Guide
The Finesse JavaScript Library API: Finesse JavaScript Library API Reference
For Finesse versions 10.6(1) or higher, the Finesse JavaScript Library API documentation can be referenced directly from the Finesse server via URL: http(s)://<FQDN>:<port>/desktop/assets/js/doc/index.html

Documentation for older versions of Finesse can be found in the Previous Documentation section under Docs -> Downloads -> Previous Documentation (PDFs).

Q. How do you use the Finesse Web Services Developer Guide?

The Finesse Web Services Developer Guide is the documentation for the Finesse REST APIs. It is separated into the following sections:

Cisco Finesse Desktop APIs
Cisco Finesse Configuration APIs
Cisco Finesse Serviceability APIs

Each section is then categorized to the individual objects, which are further broken down to each REST API.

Each REST API is documented with a table that provides the necessary information needed to make the REST API request. The following image defines each row of the table:

Q. I need to build an application that works for both UCCE and UCCX, can I build one application for both deployments?

Yes. For all common features between UCCE and UCCX (about 95%), the Finesse APIs are the same. There may be functionality difference between the two (e.g. agent state transition), but most of the API request and response format are the same with be the values of the response being different. The Finesse Web Services Developer Guide will state if the API is applicable to a particular deployment in the documentation details of API as well as any differences between the deployments.

Q. Does Finesse support High-Availability installations?

Yes. Finesse has an active/active model where all Finesse servers are connected to the CTI Server, receive the CTI Server messages, and is IN_SERVICE. In Finesse 11.5(1) and below, for a UCCX deployment, it has an active/standby model where the active server is the only server that is IN_SERVICE. See Finesse Overview for more details.

Q. Does Finesse support 2-Way SSL Web Service calls?

No, Finesse does not support 2-Way SSL Web Service calls because it does not have a mechanism to validate or authenticate client-side certificates.

Q. Does Finesse support Cross-Origin Resource Sharing (CORS)?

Finesse has Cross-Origin Resource Sharing (CORS) support for starting 11.5(1), with the exception of the SSO APIs.

In Finesse 11.5(1) & 11.6(1), in order to enable CORS support, Finesse expects the third-party web server to send a specific header that contains the Origin Host name. The Host name value in Origin is used by Finesse to populate the Response Header named Access-Control-Allow-Origin.

Starting Finesse 12.0(1), CORS support needs to be enabled by an administrator via the CLI. Please see the CORS Support for Finesse REST APIs section of the Finesse Web Services Developer Guide for more details.

Q. I created a workflow that makes a non-Finesse HTTP request. Where do I enter in the authentication credentials for the HTTP request?

If the workflow’s "Location" is set to "Other", an authentication modal will appear when the workflow gets triggered. The user will enter the authentication credentials at that time. If the authentication is correct, the HTTP request will be executed. If the authentication is not correct, the authentication modal will reappear, giving the user another chance to enter the correct credentials (an infinite number of times). If the "Cancel" button is pushed, the HTTP request will not be executed.

Q. Can the columns of the desktop layout be different widths?

No. When you add a column to the desktop layout, the layout will automatically divide the columns equally. For example, if there are 3 columns in the layout, each column will be about 33.33% wide.

Q. What are the supported browsers for Finesse version XX.X(X)?

The browser support is listed in the Installation and Upgrade guide. Select the guide that matches your Finesse version. Then go to Installation Preparation -> Client Requirements.

Q. How do I add additional filters to the Live Data Gadget?

You can use the compositeFilterId filter to add additional filters to the Live Data Gadget. Please see the Configure Live Data Gadgets in Cisco Finesse with compositeFilterId section for more info.

Q. How do I add a Historical Report to the Finesse desktop?

You can add historical reports to the Finesse desktop by using the Cisco provided Historical Gadget and applying the necessary filters. Please see the Configure Historical Report Gadgets in Cisco Finesse section for more info.

Q. None of the above answers my question. Help!

Take a look at the Finesse Troubleshooting Tips and the Finesse Knowledge Base.

If you still have an issue, ask your question in the Finesse forum or open a DevNet support ticket.

Q. I want to use the Finesse REST APIs, but where do I start?

The best place to start is to go through Finesse Overview page, and then the Getting started with using the Finesse REST APIs section of the Getting Started page of the Finesse DevNet site. You can also try one of the Finesse Learning Labs.

Q. Does Finesse have an API to _________?

The best place to find a list of all of the Finesse APIs is the Finesse Web Services Developer Guide.

Q. What port should I use for my REST APIs?

The REST API port differs depending on the Finesse deployment type and version.

For a UCCX deployment:

HTTP port:
- Finesse 12.5 or above: HTTP is not supported
- Finesse 12.0 and below: 8082
HTTPS port is 8445

For a UCCE deployment:

HTTP port:
- Finesse 12.5 or above: HTTP is not supported
- Finesse 12.0 and below: 80 or 8082 (You do not need to include the port number in the URI for HTTP requests)
HTTPS port:
- Finesse 11.0 or above: 8445
- Finesse 10.5 or below: 8443

Q. What type of authentication do the REST APIs use?

For all non-SSO users, Finesse APIs use HTTP BASIC authentication, which requires the credentials to be sent in the "Authorization" header. The credentials contain the username and password, separated by a single colon (:), within a BASE64-encoded string. For example, the Authorization header would contain the string **"Basic YWdlbnRiYXJ0b3dza2k6Y2FybWljaGFlbA=="** where "YWdlbnRiYXJ0b3dza2k6Y2FybWljaGFlbA==" is the Base64-encoded string of "agentbartowski:carmichael" (agentbartowski being the username and carmichael being the password).

SSO for REST API is supported starting Finesse 12.0(1). For all SSO users, Finesse APIs use Bearer Token authentication, where the token is the access token provided by the Cisco Identity Service (IdS). For more information about SSO with Finesse REST APIs, take a look at the Single Sign-On section of the Finesse Web Services Developer Guide.

Q. How do I authenticate Finesse REST APIs with SSO?

SSO support is also available for the Finesse out of the box desktop and custom gadgets.

Q. How do I get the access token from the Cisco Identity Service?

In order to get a user's access token from the Cisco Identity Service, the client must be able to:

Follow server issued redirects
Store and forward cookies
Honor the various cookie attributes
Execute JavaScript in HTML responses

For instructions on the SSO token retrieval procedure, take a look at the Client Integration section of the Finesse Web Services Developer Guide.

NotesIn Finesse 11.6(1) and 12.0(1):

HYBRID mode is not supported (must be SSO only).
The Single Sign-On—Get User Authentication Mode API is not available.
The username must be provided in a cookie with a key of cc_username for the Single Sign-On—Fetch Access Token API.

Q. Which role (agent, supervisor, administrator) can use _________ API?

In the Finesse Web Services Developer Guide, take a look at the "Security Constraints" row of the specific API’s table.

Q. Can I use the credentials/token for one user to make REST API requests on behalf of multi users?

No. The Finesse REST API is built for users to make their own REST API request. There are some APIs where a supervisor can make a request to get information about an agent in their team, but it is selective. Take a look at the "Security Constraints" row of the specific API’s table to see which user is allowed to make the REST API request.

Q. What format is the Finesse REST API request/response?

The format of the Finesse REST API’s request and response body is Extensible Markup Language (XML).

Q. Some values in the Finesse responses are a pass through from UCCE or UCCX. Where can I find more information about these values?

If the information is not in the Finesse Web Services Developer Guide, then take a look at the deployment specific developer guide:

For UCCE: CTI Server Message Reference Guide
For UCCX: UCCX CTI Protocol Guide

Q. Where can I find the supported agent state transitions?

The agent state transitions can be found in the User—Change Agent State section of the Finesse Web Services Developer Guide.

Q. What languages can I use to develop an application that uses Finesse REST APIs?

Any programming language that supports HTTP/HTTPS calls can be used to make Finesse REST API calls. Most programming languages have a library that provide wrappers that enable you to issue REST API calls from your native programming environment, parse the result that the server returns, and make that result available in the native programming environment.

Q: What is the Finesse Notification Service?

Cisco Finesse Notification service uses XMPP protocol as the data communication channel and encoding mechanism for dispatching user and dialog events to the client via a seemingly asynchronously. Events to be notified to the client from the Finesse Tomcat service are available via the Finesse Notification service. The Finesse Notification service works hand-in-hand with the Finesse REST APIs. The events that are dispatched can be both successful events as well as errors.

For a better understanding on how the Finesse Notification service works, it is best to manually make a Finesse REST API request via a HTTP REST Client tool and view the resulting event via a XMPP client application. Please see the Environment and Tools section in the Finesse Web Services Developer Guide for more details.

For details about the Cisco Finesse Notification Service, please see the Cisco Finesse Notification Service section in the Finesse Overview page.

Q. What port should I use to connect to the Finesse Notification Service?

To connect to the Finesse Notification Service over TCP, use port 5222 for a non-secure connection and 5223 for a secure connection.

Starting Cisco Finesse 12.5(1), the non-secure 5222 port is disabled by default. Set the utils finesse set_property webservices enableInsecureOpenfirePort to true to enable this port.

For more information about the Finesse Notification Service over TCP, see the Connect to XMPP over TCP section of the Finesse Web Services Developer Guide.

To connect to the Finesse Notification Service over HTTP (WebSocket), the port will depend on the Finesse version.

For Finesse 12.0(1) & 12.5(1): 7443
For Finesse 12.6(1) and above: 8445

Starting Cisco Finesse 12.6(1), support for notifications over BOSH (long polling) and the usage of port 7443 are deprecated. Applications should switch to WebSocket-based notifications and use port 8445 or notifications over direct XMPP (over TCP).

For more information about the Finesse Notification over HTTP, see the Connect to XMPP over HTTP (BOSH/WebSocket) using Finesse EventTunnel section of the Finesse Web Services Developer Guide.

Q. How do I connect to the Finesse Notification Service with SSO?

To connect to the Finesse Notification Service for users with SSO, log in by using the username and bearer token as the credentials.

Q. My application needs to receive Finesse notifications. Do I need to subscribe to the nodes to get notifications?

Each user is automatically subscribed to the following notification feeds, where {id} represents the agent ID for that agent:

User - /finesse/api/User/{id}
Dialogs - /finesse/api/User/{id}/Dialogs
Media - /finesse/api/User/{id}/Media/{mrd-id}
SystemInfo - /finesse/api/SystemInfo

The user must explicitly subscribe to the other nodes. Please see the Cisco Finesse Notifications section of the Finesse Web Services Developer Guide for more info.

Q. Can the same user log into the Finesse Agent Desktop and also establish a connection to the Finesse Notification Service to receive Finesse notifications?

No. Finesse does not support multiple instances connecting to the Finesse notification service per user. The Finesse Agent Desktop is considered one connection instance to the Notification Service.

Q: Which XMPP/BOSH/WebSocket library should I use to communicate to the Finesse Notification Service?

You can find a list of XMPP libraries on the XMPP.org site: https://xmpp.org/software/libraries.html

Based on feedback from the community, DevNet has seen a lot of developers use the Smack and the Strophe.js libraries to communicate with the Finesse Notification Service. Please note that Cisco does not provide support for any issues specific to the XMPP library.

Q. I want to build a gadget using the Finesse JavaScript Library, but where do I start?

The best place to start is to go through Finesse Overview page, and then the Getting started with your own Finesse gadgets section of the Getting Started page of the Finesse DevNet site. You can also look at the code of one of the Sample Gadgets. Make sure to download the sample gadget version matching your Finesse version.

Q. Where do I get the Finesse JavaScript Library file (finesse.js) for Finesse 10.6 and above?

Starting with Finesse 10.6, the Finesse JavaScript Library is now hosted on the Finesse server. It can be found using the url: http(s)://:/desktop/assets/js/finesse.min.js

The jQuery library is also hosted on the Finesse server under: http(s)://<FQDN>:<port>/desktop/assets/js/jquery.min.js

Third-party gadgets that are hosted on the Finesse server via the 3rdpartygadgets account can reference the JavaScript library accordingly:

<!-- jQuery --><script type="text/javascript" src="/desktop/assets/js/jquery.min.js"></script><!-- Finesse Library --><script type="text/javascript" src="/desktop/assets/js/finesse.min.js"></script>

Third-party gadgets that are hosted on a separate web server can reference the JavaScript library accordingly:

<UserPref name="scheme" display_name="scheme" default_value=""/><UserPref name="host" display_name="host" default_value=""/><UserPref name="hostPort" display_name="hostPort" default_value=""/><!-- jQuery --><script type="text/javascript" src="__UP_scheme__://__UP_host__:__UP_hostPort__/desktop/assets/js/jquery.min.js"></script><!-- Finesse Library --><script type="text/javascript" src="__UP_scheme__://__UP_host__:__UP_hostPort__/desktop/assets/js/finesse.min.js"></script>

Q. Where can I find sample gadgets?

The sample gadgets can be found on the Finesse DevNet site under Docs -> Downloads -> Sample Gadgets. Make sure to download the sample gadget version that matches the Finesse version you are developing against. If the matching version is not available, download the latest version that is earlier than your version.

Q. Where do I upload my third-party gadget that I built?

There are two options for hosting your third-party gadget:

Use the Finesse server as the webserver:

Enable the 3rdpartygadget account.
Upload your third-party gadget to the Finesse server.

Use your own web server. Ensure that the Finesse server has access to your web server.

Q. What are these handlers/callbacks in the sample gadgets?

A handler is a function that can be called as a result of an action. This function is also known as a callback, which is a function passed as an argument to another function. Since most of the Finesse REST APIs are asynchronous and relies on an event from the Finesse Notification to indicate whether the request was successful or not, the Finesse gadgets utilize handlers and callbacks to be executed when the notification arrives. The Finesse JavaScript Library API Reference specifies which API requires handlers as well as the different handler options for each specific API.

For more information about handlers, please see the Request Handlers section of the Finesse JavaScript Library API Reference.

Q. How do I create/update gadgets to work with SSO?

There is no change to the gadget code for SSO. The Finesse JavaScript Library (finesse.js) detects if the logged in user is SSO enabled and automatically sends the correct authentication format.

Q. None of the sample gadgets are working. Help!

Make sure that the sample gadget you downloaded is compatible with the Finesse product version. The sample gadgets can be found on the Finesse DevNet site under Docs -> Downloads -> Sample Gadgets. Make sure to download the sample gadget version matching your Finesse version. If the matching version is not available, download the latest version that is earlier than your version.

Q. After I upgraded Finesse, my gadget stopped working. What happened?

Finesse tries to maintain backwards compatibility of the Finesse JavaScript Library APIs, but it is not guaranteed. There were minor changes made between Finesse 10.5, 10.6, and 11.0 where all three versions have different formats. The changes are very minimal. Please see the blog post How to convert your existing 10.5.1 custom gadget to work with 10.6.1, 11.0.1/11.5.1/11.6.1/12.0.1/12.5.1 to convert your existing gadget to the right version. There has not been gadget changes since 11.0.1, so all 11.0.1 gadgets will work on 11.0.1 and above.

Q: I made code changes to my gadget, why don't I see the changes on the desktop?

The Finesse out of the box desktop caches the gadgets for performance reasons. When developing a gadget, it is recommended to use the nocache parameter in the URL.

Q: I want to modify an out of the box gadget, where do can I get the code?

Unfortunately, the Finesse out of the box gadgets are not open sourced and is not available for customization.

All Finesse gadgets (Team Performance, Call Control and Queue Stats) are powered by public Finesse REST APIs, so you would need to build your own gadget.

All product specific out of the box gadgets (Live Data, Chat and Email, MediaSense, etc.) use internal REST APIs, so it is not possible to build a gadget with similar capabilities.

Q. How do I get the loading indicator (the spinning circle) for my gadget like the Finesse gadgets?

Follow the steps in the Loading Indicator Feature section of the Finesse Web Services Developer Guide.

Q. How do I change the height of the team performance gadget?

For Finesse versions 11.0(1) and below, the team performance gadget height is fixed. The "gadgetHeight" parameter does not work for this gadget and only applies for CUIC specific gadgets.

Starting Finesse 11.5(1), the height of the team performance gadget is configurable by modifying the desktop layout XML in the Finesse Administration Console. Add the maxRows parameter to the desktop layout: <gadget>/desktop/gadgets/TeamPerformance.jsp?maxRows=20</gadget>, where the number of rows determines the height of the gadget. If you do not set or if you set the height to less than 10 rows, then default value of 10 is applied.

Q. How do I change the height of the Embedded WebApp Sample Gadget?

In the EmbeddedWebApp.js file, change the line of code from:

var html = '<iframe src="' + _urlToLoad + '" id="displayFrame"></iframe>';

var html = '<iframe src="' + _urlToLoad + '" id="displayFrame" width="100%" height="600"></iframe>';

Q. How do I call a third-party REST API from a Finesse gadget?

Use the ExternalRestApiSampleGadget as the base and modify the code to use your third-party REST API.

Alternatively, the third-party server can be configured to allow CORS requests from the Finesse domain by configuring a CA signed certificate or a pre-imported X.509 certificate. This will allow the gadget to directly call a third-party REST API. This route will provide better performance.