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