Cisco CUCM – SOAP Overview

Hey guys,

Today I’m going to talk about SOAP AXL. A powerful and useful type of communication model. Most of the Cisco Unified Communications Manager (CUCM) APIs are exposed via SOAP-based XML Web Services.
I’ve been using it to create some Dashboards for CUCM!

The Administrative XML Web Service (AXL) is a XML/SOAP based interface that provides a mechanism for inserting, retrieving, updating and removing data from the Unified Communication configuration database.
Developers can use AXL and the provided WSDL to Create, Read, Update, and Delete objects such as gateways, users, devices, route-patterns and much more.

SOAP provides an XML-based communication protocol and encoding format for communication. For example, to describe a phone using XML, you would define the following structure.

image

Now, how do you know what types of requests you are allowed to make, what types of data those requests require, and what type of response you expect to receive?
This is where the Web Services Description Language (WSDL) comes into play. A WSDL file (along with any associated XML schema files) can be used to fully describe the capabilities of a SOAP API.

Luckily  CUCM provides a WSDL file for each of the SOAP-based APIs it supports and there are tools to read WSDL files and then make the SOAP API service methods available easily. The eventual goal is to leverage a programing language such as Python (I’ll cover that in future posts) to interface with the various SOAP API’s, but it helps to manually explore the API using a visual tool that can understand the WSDL file. One of these tools is SoapUI, and you can download it from here HERE.

Let’s see now step by step how to use SOAP and send some requests.

Step 1 – Download the AXL API WSDL File

The CUCM AXL API WSDL file is published on the CUCM server itself, as part of the Cisco AXL Toolkit plugin.

  • Access your CUCM
  • Navigate to ApplicationPlugins and click Find
  • Next to Cisco AXL Toolkit, click Download. The file axlsqltoolkit.zip is downloaded.
  • From your Downloads folder, extract this downloaded file (right-click Extract All…) to the default location (should be in the Downloads\axlsqltoolkit folder)
  • Once extracted, in the schema folder you will notice there are a number of folders. These are for various older CUCM versions. For this lab, we are interested in current. That folder contains the current CUCM’s AXL WSDL (AXLAPI.wsdl) and schema (.xsd) files.

Step 2 – Start SoapUI

Now you can load this WSDL into SoapUI, get things configured, and start sending queries. Follow these steps to load the WSDL into SoapUI.

  • Launch the SoapUI application.
  • Close any open Endpoint Explorer or other windows that may show up when launching SoapUI.
  • Click FileNew SOAP Project

image

  • For the Project Name enter UCMSOAP
  • Below that field, for the Initial WSDL file, click Browse. Navigate to your current AXL WSDL file extracted earlier:

Step 3 – Run an AXL Request from SoapUI

Once the API is loaded, you must set some of the default parameters, specifically the CUCM hostname or IP address and the credentials so that they don’t have to be re-entered for every query.

  • In SoapUI, in the Navigator pane on the left, you’ll see the new project folder named UCMSOAP and the AXLAPIBinding object. Right-click on the AXLAPIBinding and click Show Interface Viewer (same as double-clicking or pressing Enter).

image

  • In the AXLAPIBinding properties, select the Service Endpoints tab.

image

  • You’ll notice the Endpoint is set to https://CCMSERVERNAME:8443/axl/ (with blank username and password)
  • Double-click on CCMSERVERNAME so it can be edited and replaced by the hostname of your CUCM. Press Enter
  • Double-click on the Username and Password to enter the credentials. Be sure to press Enter for the field to be saved.
  • Close the AXLAPIBinding window by clicking the X in the right of its blue title bar .

So now SOAP is all set up and ready for issuing queries.
I’ll give you now an example of how to do that.

For example, a basic thing as getting the CUCM Version:

  • Choose AXLAPIBinding
  • Scroll Down till getCCMVersion. Expand it and you will find Request 1.
  • Double-click to open it, and you will find its XML Request.

image

You will observe there is a ?  in the processNodeName field. When a new request is created for an operation in SoapUI, all available options are presented, so there are often many that either need to be removed or filled in with valid data (instead of the default ? placeholder).

So, remove it, and click in the green button to send this request. The Response will show up at right:

image

You have successfully sent an AXL/SOAP request to CUCM and received a valid response!!
From now on you can start playing with other types of requisitions, like add, update or delete.

Enjoy it Smile

Bruno

Cisco Finesse – Disconnection Problems

Hi everybody,

Today,  I’m going to give you a troubleshooting tip about an issue I’ve been facing, on Cisco Finesse.

Agents started complaining that they suddenly get disconnected, and when you see the reports on CUIC, the reason is Connection Failure.

For this case, we are using Cisco UCCX 11.6.2.

First of all, we have to check the Layer 1. Make sure the phone is not losing connection due a cabling faulty.
If you are using Jabber, make sure you network connection is stable, and if it’s VPN, your internet is stable.
Voice traffic is really sensitive, so any minimum interruption can cause a disconnection.

Another thing Cisco recommends is, if your agent has Deskphone and Jabber configured with the same line (but not using at the same time, as UCCX does not support shared lines), you have to keep only one added to the End user and to the Application user. If you have both, it work, but you will have that disconnection some times as well (yes, I faced that in the past).

Now, the latest I’ve heard from them!

As per this Troubleshooting, these presence driven logouts occur when UCCX does not receive presence available status from the agent PC/browser.  The system logs the agent out after 60 seconds.

So, seen all this points, there are 2 more difficult things to be caught, and I recently came across.

  1. Browser.
    Chrome v88+ and Edge are known to cause these issues.

    For agents logged out with the tab minimized/backgrounded:Disable Automatic Tab Discarding:
    For versions 75 and above: Add chrome extension ‘Disable automatic tab discarding’https://chrome.google.com/webstore/detail/disable-automatic-tab-dis/dnhngfnfolbmhgealdpolmhimnoliiok
  2. IntensiveWakeUpThrottlingEnabled Starting with Chrome 88: Improved resource consumption for background tabs To save on CPU load and prolong battery life, Chrome will limit the power consumption of background tabs. Specifically, Chrome will allow the timers in the background tabs to only run once per minute. If agents are using Chrome v88+, navigate to “chrome://flags” in the agent Chrome browser, search the above flag and ensure it is disabled (default=enabled).

  3. Network LatencyOne of the Finesse requirements is the that the Network Latency cannot be higher than 400ms.
    And that was exactly the problem I found on my network!!!

    But how do we find out that the latency is going over 400ms??

    Here are the instructions to gather the clientlogs from the agent Desktop side,

      *   Clear browser cache
      *   Load the following URL: <protocol>://<ip/host>:<port>/desktop/locallog and select “Sign In With Persistent Logging“.  You will be redirected to login page with the appropriate query parameter url.
      *   Sign into Finesse
      *   Operate Finesse as usual
      *   When you run into the problem open a new window or a tab and reopen with same browser type using the following URL: <protocol>://<ip/host>:<port>/desktop/locallog and select Refresh button
      *   Now you have all the logs in the contents of the console output.

  4. Conclusion


    After analysing the logs, I could find the following:

    Line 384: 2021-03-29T09:28:50.812 +02:00: 39DED1: <a href="http://<http://<<uccx_server>&gt;: Mar 29 2021 09:28:50.728 +0200: Header : Client: 2021-03-29T07:28:50.518Z, Server: 2021-03-29T07:28:50.434Z, Drift: -84ms, Network Latency (round trip): 587ms

    image

    In this Log’s pieces, we can see that the roundtrip latency for the agent that was logged out, spikes above the 400ms threshold allowed by Finesse. This latency means that the server does not receive the “Presence available” notifications from the agent PC.  After 60 seconds without receiving a notification, the system will log the agent out per design.              

  5. So now you have to troubleshoot your network to find the source of that Latency.

    That’s it guys!

    I hope this post can help you out!

    See ya!

    Bruno

    Media Resources on CUCM (Conference Bridge and Transcoder)

    Hi people,

    In this post I’ll cover a little bit of resources on CUCM, more specifically Transcoding and Conference Bridge.

    The requirements to have them configured on your Voice Gateway, and consequently being used on CUCM, are DSPs.
    DSPs reside either directly on a voice network module, on PVDM2s that are installed in a voice network module or on PVDMs that are installed directly onto the motherboard, such as on the Cisco 2800 and 3800 series voice gateway routers.

    Having your DSP, let’s configure this bad boy in your Voice Gateway.

    • Configuring SCCP

    !— This sccp ccm command adds CallManager server(s) !— to the list of available servers to which the voice gateway can register.
    Gateway(config)#sccp ccm 192.168.252.18 identifier 18 priority 1 version 4.1
    Gateway(config)#sccp ccm 192.168.198.10 identifier 5 priority 2 version 4.1
    Gateway(config)#sccp ccm 192.168.198.11 identifier 4 priority 3 version 4.1
    Gateway(config)#sccp ccm 192.168.198.12 identifier 11 priority 4 version 4.1

    !— Selects the local interface that SCCP applications !— use to register with CUCM.
    Gateway(config)#sccp local loopback 1

    !— Enables SCCP and brings it up administratively.
    Gateway(config)#sccp Gateway(config)#exit

    • Configuring DSP Farm for Transcoding


    !— The dsp services dspfarm command enables DSP farm services for the voice card.

    Gateway(config)#voice-card 0
    Gateway(config-voicecard)#dsp services dspfarm


    !— The dspfarm profile 111 transcode command enters the !— DSP farm profile configuration mode !— to define a profile for DSP farm services. !— For this profile, a transcode profile is created.

    Gateway(config-voicecard)#exit
    Gateway(config)#dspfarm profile 111 transcode


    !— Specifies the codecs supported by a DSP farm profile.

    Gateway(config-dspfarm-profile)#codec ?
       g711alaw      G.711 A Law 64000 bps
       g711ulaw      G.711 u Law 64000 bps
       g729abr8      G.729ab 8000 bps
       g729ar8       G.729a 8000 bps
       g729br8       G.729b 8000 bps
       g729r8        G.729 8000 bps
       pass-through  Stream Pass Through

    !— Specifies the maximum number of sessions that are !— supported by the profile. !— Number is determined by the available registered !— DSP resources.
    Gateway(config-dspfarm-profile)#maximum sessions 20

    !— The associate application sccp command associates the SCCP protocol !— to the DSP farm profile.
    Gateway(config-dspfarm-profile)#associate application sccp

    !— Enables the profile, allocates !— DSP farm resources, and associates the application.
    Gateway(config-dspfarm-profile)#no shutdown
    Gateway(config-dspfarm-profile)#exit
    Gateway(config)#gateway

    !— Sets the Real-Time Transport !— Protocol (RTP) timeout interval to clear hanging connections. !— Seconds range is 180 to 1800. The default is 1200.
    Gateway(config-gateway)#timer receive-rtp 600

    • Creating Call Manager group

    Gateway>enable
    Gateway#configure terminal
    Gateway(config)#sccp ccm group 111

    !— Adds a Cisco Unified CallManager server to the Cisco !— Unified CallManager group and establishes its priority within the group.
    Gateway(config-sccp-ccm)#associate ccm 18 priority 1
    Gateway(config-sccp-ccm)#associate ccm 5 priority 2
    Gateway(config-sccp-ccm)#associate ccm 4 priority 3
    Gateway(config-sccp-ccm)#associate ccm 11 priority 4

    !— Associates a DSP farm profile to the Cisco Unified CallManager group. !— The device-name must match the device name configured in Cisco Unified CallManager.
    Gateway(config-sccp-ccm)#associate profile 111 register DE_XCODE_01


    !— Binds an interface to the Cisco Unified CallManager group.

    Gateway(config-sccp-ccm)#bind interface loopback 1
    Gateway(config-sccp-ccm)end

    Now, let’s do the same for Conferencing Bridge

    The process is purely the same, so I’ll just put the commands here:

    Gateway>enable
    Gateway#configure terminal
    Gateway(config)#voice-card 0
    Gateway(config-voicecard)#dsp services dspfarm
    Gateway(config-voicecard)#exit
    Gateway(config)#dspfarm profile 999 conference
    Gateway(config-dspfarm-profile)#description conference profile 999
    Gateway(config-dspfarm-profile)#codec ?
       g711alaw      G.711 A Law 64000 bps
       g711ulaw      G.711 u Law 64000 bps
       g729abr8      G.729ab 8000 bps
       g729ar8       G.729a 8000 bps
       g729br8       G.729b 8000 bps
       g729r8        G.729 8000 bps
       pass-through  Stream Pass Through

    Gateway(config-dspfarm-profile)#maximum sessions 4
    Gateway(config-dspfarm-profile)#associate application sccp
    Gateway(config-dspfarm-profile)#no shutdown
    Gateway(config-dspfarm-profile)#exit
    Gateway(config)#gateway
    Gateway(config-gateway)#timer receive-rtp 600
    Gateway(config-gateway)#exit

    Gateway>enable
    Gateway#configure terminal
    Gateway(config)#sccp ccm group 999
    Gateway(config-sccp-ccm)#associate ccm 18 priority 1
    Gateway(config-sccp-ccm)#associate ccm 5 priority 2
    Gateway(config-sccp-ccm)#associate ccm 4 priority 3
    Gateway(config-sccp-ccm)#associate ccm 11 priority 4
    Gateway(config-sccp-ccm)#associate profile 999 register 00C88B514BDF
    Gateway(config-sccp-ccm)#bind interface loopback 1

    Gateway(config-sccp-ccm)end

    Time now to add them to our Unified Communications Manager

    • Transcoder

    On CUCM, go to Media Resources >> Transcoder >> Add new

    Choose Cisco IOS Enhanced Media Termination Point for the Transcoder Type, and fill the rest with your Device Pool,  and for the Device Name, use the name you added on the Gateway:

    image

    Save and Reset it. You must see it as registered

    • Conference Bridge

    On CUCM, go to Media Resources >> Conference Bridge >> Add new

    Choose Cisco Conference Bridge Hardware for the Conference Bridge Type, and fill the rest with your Device Pool, Location, and for the Mac Address, use the name you added on the Gateway:

    image

    Save and Reset it. You must see it as registered

    Now, added them both in a Media Resource Group, and then add this group to a Media Resource Group List.

    Job done!!

    Cheers Smile

    Creating an ODBC connection with UCCX

    Hey everybody,

    Today  I want to show you how to create an ODBC connection with UCCX, which can be mainly used for Wallboards/Dashboards.

    To be able to access and pull information out from its Database, UCCX already provides some users with some specifics rights. They are:

    • uccxwallboard: Has access to real-time database tables that contain snapshots of real-time statistics, more specifically to tables RTCSQsSummary and RTICDStatistics.
    • uccxhruser:  Has access to many configuration and historical tables in the UCCX database. It can only be used for custom historical reporting and Cisco Unified Workforce Management (WFM).
    • uccxworkforce: Has access to the Team, Resource, and Supervisor tables and it’s used for Cisco Unified Quality Management (QM).

    For this connection we are creating now, we are going to use uccxhruser.
    Let’s start off going to UCCX >> Tools >> Password Management to set a new password (in case you don’t know)

    image

    Once done, let’s now focus on the ODCB configuration!

    First of all, you need to download the IBM Informix Client SDK. It will allow the client to stablish a ODBC connection with your Database on UCCX.
    You can download the SDK here.

    • Go to Control Panel >> Administrative Tools >> ODBC Data Sources (64-bit).
    • Chose the tab System DNS and hit Add.

    image

    • You see now a list of available data sources. Select IBM INFORMIX ODBC DRIVER. Click Finish.
    • Time to create a new DNS. In the Tab General, give a name to your connection.

    • Go to the Tab Environment, and fill the information following the rules below:
      • Server Name: Instance name of Informix server of the set up.  Please pay attention because there are tricky rules for entering the name such as:
        1. Name MUST be in lower case (even if your server name are in upper case)
        2. Any hyphens MUST be converted to underscore
        3. If your server name begins with a number, add “i” in front of it.
        4. Add “_uccx” to the end of the hostname.

      For example: If your server name is 1-EMEA-UCCX, you have to enter i1_emea_uccx_uccx

      • Hostname: The actual hostname or IP address of the UCCX
      • Service: 1504
      • Protocol: onsoctcp
      • Options: leave it blank
      • Database name: db_cra
      • UserID: uccxhruser
      • Password: Password of uccxhruser

      image

      • Go now to the Tab Environment.

            Fields Client Locale and Database Locale must be as: en_US.UTF8

      3

      • Go back to the Tab Connection. It’s now time to test if it’s working.

      Click on Apply and Test Connection. You must see that message:

      6

      That’s it for now! I hope this post can be useful !!

      See ya!!

      Cisco Single Number Reach

      Hey guys!
      Here is Bruno, and I’ll be in charge of the Cisco side of this Blog, more specifically, Collaboration.

      For my opening post, I’d like to talk about a feature on CUCM that, due all this pandemic situation, is being largely implemented.


      Cisco Single Number Reach (SNR), or known as Mobile Connect, is a feature which allows users to answer incoming calls to their extension on either their desktop IP phone or at a remote destination, such as a mobile phone. 

      As many companies had to send employees to work from home, SNR becomes really useful to cover some gaps you may have in your infrastructure.

      To give you some practical examples, there were 2 situations where I configured SRN to save user’s life.
      In the first, a small company didn’t have a good infra to send users to home (lack of bandwidth, poor VPN) and in the second, users were vendors and firewalls didn’t allow them to have Jabber connected to VPN.
      In both situations, users had to receive calls from a queue on UCCX.
      I came up with SNR for both cases, so users could work from home, and even though they weren’t using any softphone, they could answer calls coming from they extension.

      Although Cisco does not mention in its Documentation, I configured and tested SNR with UCCX with success  Smile

      So, how does this work?

      When a call comes in to your Extension Number,  SNR will reroute the call not only to a DN, but also to your remote number, that can be your mobile phone. If needed, you can configure rerouting to a group of remote numbers that belong to an employee.
      In other words, SNR provides you a functionality similar to Shared Line. The difference is that in this case a shared line is organized between an office phone and some remote device that isn’t necessary in a cluster, not between the phones within a cluster.

      image
      Said that, let’s get down to business!

      What do you need to configure?

      Configuring End User

      Configuring Remote Destination Profile

      Configuring Remote Destination

      Configuring End User

      In the End User page, make sure the Device is already associated in the Controlled Devices and its Line is assigned as Primary Line

      imageimage

      Check the Enable Mobility check box. You can also, modify the Maximum Wait Time for Desk Pickup and Remote Destination Limit if required. Moreover, the default values can be seen in the image.

      image

      Configuring Remote Destination Profile

      Time to create a new Remote Destination Profile.
      On CUCM, go to Device > Device Settings > Remote Destination Profile > Add new

      You can choose any name, associate your user ID, give a calling search space and a rerouting CSS.
      CUCM attempts to reach the remote destination through the Rerouting calling search Space.

      image

      Click Save, now you can see an option to add a new Directory number (DN) .

      Click Add a new DN to navigate to directory number configuration, where you need to specify the directory number of the desk phone with which you need to associate the RDP and then click Save.

      imageimage

      Configuring Remote Destination

      Time to configure the Remote Destination.
      Specify the Destination number, as this is the number for your Remote destination.
      Ensure that the check box, Enable Unified Mobility features, Enable Single Number Reach, Enable Move to Mobile is checked.

      Single Number Reach Voicemail Policy provides two options: Timer control and User Control, of which the former one is default.

      Under the section Timer information, you can specify the amount of delay before which the Remote Destination should ring.
      In case if the Remote Destination is required to ring immediately, you should set the Wait as 0.
      It is also important to calibrate the time in which the service provider of the remote destination sends the call to the voice-mail of the remote destination. The Stop ringing this phone after value should be set lesser then that to ensure that call does not go to the voicemail of the cell phone. This time value is specified against Stop ringing this phone after.

      image

      If the SNR voicemail policy is configured for User Control, timer information changes as shown in the image:

      In case the SNR configuration needs to be restricted based on time and day then these options are modified as required. If no restriction is needed to be applied then Ring Schedule should be set to All the time and When receiving a call  during the above ring schedule should be set to Always ring this destination.
      After you complete the configuration of remote destination, click Save.

      IMPORTANT STEP!!!
      Check the checkbox, which is next to the line and click Save.

      image

      That’s all guys!
      I hope this post will help you out!

      See ya!

      Bruno Falco