CUCM Administrative XML (AXL)
Provisioning API

Administrative XML Web Service (AXL) is an XML/SOAP based API that provides a mechanism for inserting, retrieving, updating and removing data from the CUCM configuration database. The AXL API provides you with access to the entire CUCM database. The AXL API is purely for provisioning and does not provide access to run-time or performance data. There are several other APIs we will discuss later that are used to provide this type of information.

Before exploring more of the AXL API using SoapUI, here are a few things you should know about the API:

AXL Authentication

AXL API utilizes HTTPS Basic Authentication. Any CUCM User (Application or EndUser) will have read/write access via AXL if they are members of the Standard CCM Super Users access control group or any group with the Standard AXL API Access role assigned to it. This means that all super user accounts implicitly already have access to the AXL API. To create an account dedicated for AXL API use, you must first create an access control group and assign the Standard AXL API Access role to it, then associate the application user with the newly created group.

To provide read-only AXL API access you can create a separate Access Control Group and assign only the Standard AXL Read Only API Access role to it.

In the interests of simplicity in this lab, you will use the admin account which is a member of the Standard CCM Super Users group. However, the best-practice in a production environment is to use a separate account dedicated for each AXL API application.

AXL Method Types

AXL has two distinct method types which operate in very different ways.

  • Thick AXL: Provides (operations) that allow you to perform certain tasks against the CUCM database in a very structured format that has been built around each type of object available in the CUCM database. For example, there are methods for things like phones, route lists, route patterns, and calling search spaces, just to name a few. If the object can be configured from the CUCM Administration page, there is a Thick AXL method that lets you list, add, remove, and update that object. For example, for phones the following Thick AXL methods exist: listPhone, addPhone, removePhone, updatePhone. In this lab you will only utilize Thick AXL API Methods.
  • Thin AXL: Provides only two methods, executeSQLQuery and executeSQLUpdate, that give you direct access to the CUCM SQL database through the use of SQL queries (e.g. SELECT, INSERT, DELETE, etc...). Using Thin AXL requires in-depth understanding of the database schema and is subject to breaking across CUCM releases because the database schema is not guaranteed to be backwards compatible across releases.

AXL Versioning

AXL API has built-in supports versioning for Thick AXL API requests only. Thick AXL API requests can specify the AXL schema version in the request header SOAPAction: CUCM:DB ver=15.0 as well as in the XML namespace URI for the the SOAP Envelope element within body of the request xmlns:ns="http://www.cisco.com/AXL/API/15.0". Both SOAPAction header and the XML namespace URI should indicate the same version. The SOAPAction request header is optional but if supplied it supersedes the version specified in the XML namespace URI. The AXL schema version in the XML namespace URI is always required.

The version specified in the AXL API request indicates which AXL schema version the request payload will follow and the response should follow.

CUCM maintains backwards compatibility with the running release minus 2 major versions. For example, applications written with CUCM 12.5 schema will still be supported through CUCM version 15 (because there was no version 13, so the next two versions are 14 and 15).

Although not recommended for schema dependant Thick AXL methods such as addPhone or updatePhone, if an AXL API client wishes not to specify a specific schema version, for example, when using the getCCMVersion method, we can omit the SOAPAction header and include a particular schema version 1.0 in the AXL XML namespace URI. In this case, CUCM will attempt to apply the lowest schema version supported by that CUCM release. For example: The AXL Developer Guide - Versioning on developer.cisco.com has more information including supported schema versions per CUCM major release as well as backward compatibility best practices and more.

AXL Performance

The AXL SOAP Service has dynamic throttling to protect system resources. When receiving an AXL write request, the CUCM publisher node via Cisco Database Layer Monitor service dynamically evaluates all database change notification queues across all nodes in the cluster and if any one node has more then 1500 change notification messages pending in its database queues, the AXL write requests will be rejected with a "503 Service Unavailable" response code. Even if the CUCM Cluster is keeping up with change notification processing and DB queues are NOT exceeding a depth of 1500, only 1500 AXL Write requests per minute are allowed.

The database change notifications queue can be monitored via the following CUCM Performance Counter on each node (\\cucm\DB Change Notification Server\QueuedRequestsInDB). This counter can be viewed using the Real Time Monitoring Tool (RTMT), but we will also show you how to retrieve CUCM Perfmon Counter values programmatically as well in the next section.

AXL read requests are NOT throttled even while write requests are being throttled.

In addition to AXL requests throttling, the following AXL query limits are always enforced: A single request is limited to returning under 8MB of data. Concurrent requests are limited to under 16MB of data.

The Data Throttling and Performance page on developer.cisco.com has more information on this topic.

AXL Schema

As mentioned earlier, XML objects are defined in an XML schema file. The latest CUCM AXL Schema Reference (CUCM 15) can be found at https://developer.cisco.com/docs/axl-schema-reference/. This guide shows you the detailed structure of hundreds of methods available as part of the AXL API.

To reference an older version of the AXL schema, refer to https://developer.cisco.com/docs/axl/#archived-references.

You may refer to the AXL Operations by Release Matrix located at https://developer.cisco.com/docs/axl/#!operations-by-release to identify changes between Releases.

Now, with a background on the AXL API, you can use the SoapUI application to perform a common task via the API - adding a Phone to CUCM. At this point you are using the SoapUI application to construct the raw XML messages that will be transmitted to CUCM. Later you will do this in an easier, more programmatic way.

Add a Phone

  1. Open SoapUI with the UCMSOAP project that you created in the previous section of this lab. If for some reason you closed the file, follow the steps on the previous page to open the AXLAPI.wsdl in SoapUI and add the CUCM CUCM hostname or IP address and credentials.
  2. In the Navigator, under AXLAPIBinding, scroll down to the addPhone method and expand the node by clicking the '+'.
  3. Double-click on Request 1 under addPhone.
  4. In the previous example you executed the getCCMVersion method, which required no additional parameters. In this case, the addPhone method requires many more elements. Some of the input elements are optional and can be removed. In default SoapUI request payloads, these are prefixed by a line containing the following: For example, description element is optional as shown below:

    The same optional input element is documented in the AXL Schema for AddPhoneReq/phone element as shown below. Notice how the box around the word description has a dotted line. This indicates that parameter is optional:

  5. Do not enter the information provided in this step yet - this is just for your information. Here is a list of elements to use in the addPhone request:
    • name: CSFPOD6UCMUSER
    • description: Cisco Live LTRCOL-2574 - pod6ucmuser
    • product: Cisco Unified Client Services Framework
    • class: Phone
    • protocol: SIP
    • protocolSide: User
    • devicePoolName: Default
    • The Phone should also have a line associated with it. The required information for a line looks like this for the phone you are adding:
  6. You can try to enter all the above information into the existing template request that SoapUI provides, but to avoid typing errors, it is easier to just copy the whole request below and paste it into SoapUI. Notice there are far less parameters provided here than what is listed in the template because many of the template parameters are optional. Click the Copy button below and paste the text into the SoapUI request, replacing the existing text.
  7. Click the green Run button to execute the request. You should receive a valid response similar as the following (the UUID value in the curly brackets will be different):

    The response data above contains the UUID (Universally Unique IDentifier) for this Phone device just added to the CUCM database, which uniquely identifies this device in the database. It may be useful for modifying or removing this device. Within the CUCM Database, this is how this phone device will always be referenced. You can actually see this same ID if you log into the CUCM admin and, from the Device > Phone page, hover over the link to this phone. The URL would be something like: https://cucm1a.pod6.col.lab/ccmadmin/gendeviceEdit.do?key=06ea28c2-18ef-ecce-9ad1-e47f41c7e46f. In practice, if you are using Thick AXL, you should not need the UUID because you can always reference the device by the device name for any additional queries on the device.

  8. If an error is encountered, AXL will return a SOAP Fault. To see this in action, click the green Run button again to execute the request a second time. You should see a response like this:

    The response contains a SOAP Fault message indicating that the phone device could not be added because a device with the same name already exists in the CUCM database. In this case the error is expected because you are trying to add the same device twice, so you can ignore this error.

  9. Now that you have added the device to CUCM, From the Desktop or the taskbar of your PC, launch the Webex application and proceed to sign in.

  10. Enter your email address pod6ucmuser@collab-api.com and click Next
  11. Enter your password C1sco.123 and click Sign In
  12. You have now logged in your pod6ucmuser@collab-api.com to Webex. If instead of the Call Settings indicator at the bottom, you're notified that you need to sign in to phone services, click Open Settings

  13. Enter your UCM User account name pod6ucmuser and password C1sco.123 and click Sign in to complete phone services login

  14. Click on to acknowledge the Emergency Calling Notification, if necessary.

  15. You now have your Webex Client's Phone Services connected to your CUCM. Click Save to close the Webex Options window

  16. Your Webex client is now ready to place calls via your pod's CUCM

  17. Test calling from the laptop by clicking/dialing 5999999. This is your pod's Unity Connection Voice Mail Pilot number. Open Webex and click Yes to place your call. (NOTE: The call will FAIL!)

    18. Why are you hearing re-order tone? Because the Calling Search Space on the newly inserted phone device was not set. You will fix that later when you explore how to modify a device.

Now that you have your phone registered to CUCM using AXL Methods with the SoapUI tool, let's look into a few more AXL Methods but in a programmatic way using Python.