UCCX Real-Time Agent Widget

The Real-Time Agent widget will require a Finesse connection


Variphy’s RTA widget uses the Finesse system that comes with a UCCX environment where the application can subscribe to XMPP Notifications upon Agent state or dialog (voice/chat) change. By hooking into this service, Variphy can provide a truly real time widget which gives an activity overview of what any agent in a UCCX system is currently doing (their state, their active dialog, etc.) along with some general information about the agent (login ID, extension, etc.).

Issues Encountered

No Data Available results in the Real-Time Agent widget. Other UCCX widgets are loading without issue.

The application logs should reflect an error connecting to the Finesse XMPP Service.

Edit the UCCX Cluster configuration; Settings–>Clusters–>UCCX:

The Variphy UCCX Cluster definitions for the Finesse connection:

The Finesse user account MUST have Administrator AND Agent capabilities:

The Finesse user account MUST have Administrator AND Agent capabilities:

If the Finesse account in UCCX does not list the capability of Agent, that would signify that the End User in CUCM does not have a controlled agent device/directory number associated to the JTAPI.

Once the CUCM End User profile has an IPCC Extension populated, that will replicate to the UCCX Resources as well as User Management where the Administrator and Agent Roles may be selected.


If a new CUCM End User account is created with an IPCC extension and assigned the Admin and Agent capabilities in UCCX , it normally takes 10-15 minutes for the newly created account to be able to access the Finesse API through Variphy. This is due to the CUCM/UCCX Resource sync.

Testing the Finesse API

When a UCCX Finesse user is an administrator & agent, it should have access to all API endpoints and XMPP nodes for all agents.

To test, simply browse to your internal UCCX Finesse API and enter the account intending to use within Variphy: https://Your_UCCX_IP_here:8445/finesse/api/ReasonCodes?category=NOT_READY

If the access is authorized, you will see a similar document tree of the NOT_READY category states for that Finesse user:

If the browsing/login test fails and throws a 401 error of some nature, that signifies that the Finesse user does not have access to the API endpoint (which Variphy needs). Check for a missing Agent capability on the UCCX user.

If the Finesse account has Administrator and Agent capabilities, API browsing test is successful, but the Real-Time Agent widget still doesn’t load or throws an unknown host exception error in the Variphy logs: Variphy support may have to make an addition to a host file for the UCCX FQDN due to DNS resolution (Linux OS specific).

We have seen some cases where the Finesse account has the appropriate capabiliites and the API browing test successfully, but the connection with just not work (401 Unauthorized errors in the Variphy logs.

In this case, we recommend making the Finesse account a secondary supervisor to the Teams in UCCX.

Troubleshooting Tips & Tricks

Some may see the Real-Time Agent Widget successfully communicating but have a delayed response in State changes. The XMPP Subscription service that we use to connect to UCCX is designed to be a real time delivery of agent activity as it happens live. Some suggestions to resolve the time delay are outlined below.

Re-Subscribe to the XMPP service

In Variphy you have the option of re-subscribing to XMPP service by simply saving your UCCX Cluster configuration with a bogus UserID and saving. Re-Edit the cluster with the correct Finesse UserID and Save. This will force a re-connection resulting in a re-subscription of the CCX XMPP service.

Server NTP

  • Determine if your Variphy Server (primarily Linux OVA) is using NTP time sync.
    • Take a peak at Variphy app logs. Does the content on bottom of log file show up as a time that is not current?
    • Use command timedatectl to determine if the NTP is in Sync with the specified NTP source.

variphyadmin@variphyinsight09:~$ timedatectl
Local time: Thu 2020-09-03 13:56:02 CDT
Universal time: Thu 2020-09-03 18:56:02 UTC
RTC time: Thu 2020-09-03 18:56:02
Time zone: US/Central (CDT, -0500)
System clock synchronized: yes
systemd-timesyncd.service active: yes
RTC in local TZ: no

  • In rare occurrences you may see that system-timesyncd.services active: yes BUT that the System clock synchronized: false. This implies that your NTP source is no longer syncing the correct time and is not aligned with the server hardware clock. Below are options to correct time settings on the Variphy server.
  1. Confirm/Edit NTP source to a new source: sudo cat /etc/systemd/timesyncd.conf. If edits are need to adjust your indicated NTP source, please use VI editor.
    sudo vi /etc/systemd/timesyncd.conf.
    Arrow down and over to the section needing to update.
    Letter ‘i‘ to enter Insert mode.
    Type in the new IP or path to the new NTP source
    ESC key, then :wq to wrtie and quit editor.
    sudo systemctl restart systemd-timesyncd.service
  2. Disable NTP, and run off server clock instead: sudo timedatectl set-ntp no. Reboot server with sudo reboot

After adjusting the NTP source and restarting the service and/or turning NTP off alltogether will allow the Variphy server to boot in current local time. Thus when the XMPP subcsription is made with the UCCX server, all packet info is logged with the correct time, and entries within the dashboard widget will be reflected in miliseconds.

If you have additional questions or would like assistance please submit a request to support@variphy.comPlease note that our normal support hours are Monday through Friday, 7:00 a.m. to 4:00 p.m. Pacific Time, excluding US holidays. After hours support may be arranged with advanced notice.

Updated on September 3, 2020

Was this article helpful?

Related Articles