FAQ - Administrative XML Web Service (AXL)

Getting Started

How To

Troubleshooting

I am attempting to create a user or application user via SQL and the request... however passwords and pins for these users are not working..?
Licensing APIs do not return correct data

Database Tables

The SQL 'device' table in UCM 8.0 no longer contains an 'XML' field for storing vendor config, custom XML configurations. How can I read/write this data?

Trace Settings

Reading/updating CUCM Service trace settings

Getting Started

Is HTTP version required during AXL POST?

In CUCM the HTTP is mandatory; however, the version number being passed could be either 1.0 or 1.1

What permissions/roles are required for a user to access AXL?

The minimum AXL permissions are:

Standard CCM Admin Users - this grants access to the UCM web services. Note, it does not grant full admin access.
Standard AXL API Access - this grants read/write access to the AXL API

Note these are roles. By default there is no group which includes just those roles, so it is customary to create a new group, assign those two roles, and put the AXL application user in that group.

The AXL service has a built-in throttle mechanism for AXL update requests, how should my application work with it?

The AXL throttling mechanism takes into account the dynamic state of Unified CM. It considers the number of outstanding change notifications across the Unified CM cluster at any given time. If a node haD-Code: 503 Service Unavailable response and sets AXL performance counters which can be viewed using RTMT. When a 503 Service Unavailable response is returned, Cisco recommends that the application sleep for a number of seconds or milliseconds (as determined by the developer) to allow pending write requests to be processed. The application should then continue submitting requests. There are two AXL performance counters:

ThrottleCount—Determines number of times Administrative AXL throttling has been engaged.
ThrottleState—Determines the state of AXL throttling. That is, whether AXL throttling is currently active (throttling is engaged).

AXL Query Limits

Total Records - No limits for total number of records. But size of total records must be less than 8MB per request and 16MB is the maximum buffer allocated for parallel processing of requests.

Which phones cannot be configured with a Locale?

The following list of IP Phones cannot be configured with a locale through AXL

Cisco 12 SP+ Cisco 12 SP Cisco 12 S Cisco 30 SP+ Cisco 30 VIP Cisco 7935 Cisco 7910 Cisco 7920 Cisco 7936

Note : CTI Port cannot be configured with a locale through AXL. All other IP phones can be configured with a locale.

Why don't I receive localized characters when retrieving data from certain AXL commands?

The CCM database stores the data in the format in which it is entered. AXL replies retrieve the data as it has been entered in the database but normally applications assume the format to be UTF-8.

Because some web pages on the CCM interface take localized characters e.g. User configuration web pages, it is possible to enter data which is not in UTF-8 format. AXL SOAP will return what has been entered and the application may not match character strings correctly.

The only workaround at present for this localization issue is to know which format the data was entered in to the CCM and convert it appropriately

How to

How can I use the AXL .xsd schema files to validate that an XML object is properly formatted?

AXL-SOAP is provided along with several .xsd format XML schema definition files:

axlsoap.xsd AXLEnums.xsd axl.xsd axlmessage.xsd

These XML schema files contain full detail about the AXL API format, including the request names, fields/elements, data types used, field validation rules, etc. One advantage of .xsd schema files is that they can be used to automatically/programatically validate a particular XML document against the schema, ensuring it is well formatted and valid according to the schema specs.

There are many XML editing application and programmatic tools and components that can use .xsd schema files to validate XML documents, and details about how to do so may vary. The main necessary detail, however is to define the 'xsi:schemaLocation' attribute with a URI pointing to the axlsoap.xsd schema file.

xml

Copy<SOAP-ENV:Envelope xmlns:SOAP-ENV="https://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema">
    <SOAP-ENV:Body>
        <axlapi:getUser xmlns:axlapi="https://www.cisco.com/AXL/API/1.0" xmlns:axl="https://www.cisco.com/AXL/1.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://www.cisco.com/AXL/API/1.0 C:\AXL\axlsoap.xsd">
            <userid>jksmith</userid>
        </axlapi:getUser>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In the above example, the xsi:schemaLocation for AXL has been definied as ''C:\AXL\axlsoap.xsd''.

Make sure the axlsoap.xsd file (along with axl.xsd. AXLEnums.xsd, and axlmessage.xsd) can be found at the URI provided, and that the versions of these schema files are compatible with the version of CUCM you wish to validate against (AXL .xsd schema files are likely to change from major release to major release.)

Once the xsi:schemaLocation attribute has been specified, and the .xsd schema files are in place, you can open the document in your favorite XML editing tool and choose the ''validate using .xsd schema'' option. Note that in many XML editors, if a schema has been defined for a document, the editor IDE may be able to offer ''intelli-sense'' like smart field completion and value lookups for you when designing/testing AXL requests documents.

How can I find out which node in a cluster is the Publisher?

Use the listProcessNode request, specifying <nodeUsage/> in the <returnedTags> list. One node will be listed with nodeUsage as 'Publisher'

xml

Copy<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="https://www.cisco.com/AXL/API/8.5">
  <soapenv:Body>
      <ns:listProcessNode>
            <searchCriteria>
                    <name>%</name>
            </searchCriteria>
            <returnedTags>
                <name/>
                <nodeUsage/>
            </returnedTags>
        </ns:listProcessNode>
    </soapenv:Body>
</soapenv:Envelope>

xml

Copy<?xml version="1.0" encoding="UTF-8"?> 
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/">   
    <soapenv:Body>
         <ns:listProcessNodeResponse xmlns:ns="https://www.cisco.com/AXL/API/8.5">
                <return>
                    <processNode uuid="{00000000-1111-0000-0000-000000000000}">
                        <name>EnterpriseWideData</name>           
                        <nodeUsage>Subscribern</nodeUsage>         
                    </processNode>         
                    <processNode uuid="{854A8C28-DAE6-42FD-93FB-46EDC2B5F2AA}">           
                        <name>10.88.131.141</name>           
                        <nodeUsage>Publisher</nodeUsage>         
                    </processNode>       
                 </return>     
           </ns:listProcessNodeResponse>   
     </soapenv:Body> 
</soapenv:Envelope>

How do I add a new phone to CUCM using AXL?

Adding a phone is actually a two-step process:

The first step involves adding a line to the CUCM (see the <addLine> sample in this FAQ database.) The return value of the <addLine> request will include the UUID of the new line.

The second step involves submitting an <addPhone> request with the line (or lines) desired as line appearances on the device included as children elements of the <lines> element. The <line> element will refer to the line by the UUID obtained in the first step (or by otherwise discovering the line's UUD via AXL.)

How can the model-specific phone settings found in CUCM admin under 'Product Specific Configuration' be retrieved/updated?

These configurations are contained in the <vendorConfig> element, e.g. in the AXL <addPhone>/<updatePhone>/<getPhone> requests. The <vendorConfig> element itself contains an XML document describing the configured settings. The contents of <vendorConfig> will reflect only options which have been modified from the default - if there are none, the element may be empty. The schema of the <vendorConfig> XML document (reflecting which configs/options are possible) varies from phone-to-phone and possibly from phone firmware-version-to-version as well.

Currently the schema definitions for <vendorConfig> contents are not documented, precluding full support for parsing/updating these settings. However, the XML contents are usually human readable/comprehensible, so it may be feasible to reverse-engineer them to enable updating by applications. One approach might be to create a target device, configure the desired Product Specific options in CUCM admin, then retrieve the resulting <vendorConfig> via AXL <getPhone>. These schemas are usually stable, with a known exception being signficant <vendorConfig> XML changes for certain video endpoint devices running CE firmware, appearing in CUCM 12.5.1 SU1.

Troubleshooting

I am attempting to create a user or application user via SQL and the request... however passwords and pins for these users are not working..?

User and application-user password and pin values are stored in the CUCM database in encrypted format. Writing values to these fields directly via SQL results in un-encrypted values being stored (and password/pin checks against these users made by the system later, to fail.)

Applications can use the updateUser, updateApplicationUser, addUser, or addAppUser AXL requests - which perform the appropriate encryption - to set user passwords and pins.

Licensing APIs do not return correct data

Enterprise License Manager (ELM) was introduced in Unified Communications release 9.0 to enable Customers to centrally manage licensing across multiple Unified CM clusters and UC applications. Licenses formerly stored on Unified CM are now installed and maintained in Enterprise License Manager.

The following AXL interfaces have been removed from all AXL schemas:

AddLicenseCapabilities
GetLicenseCapabilities
listLicenseCapabilities
updateLicenseCapabilities
getLicenseUnitReport
getLicensedUsers

If a license request is received using Unified CM 10.0 with CUCM: DB ver= 8.0/8.5/9.0/9.1, the following will result:

xml

Copy<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/">  
    <soapenv:Body>    
        <soapenv:Fault xmlns:axis2ns5="https://schemas.xmlsoap.org/soap/envelope/">      
            <faultcode>
                axis2ns5:Client
            </faultcode>      
            <faultstring>
                The endpoint reference (EPR) for the Operation not found is https://10.106.3.30:8443/axl/services/AXLAPIService and the WSA Action = CUCM:DB ver=10.0
            </faultstring>      
            <detail/>    
        </soapenv:Fault>  
    </soapenv:Body>
</soapenv:Envelope>

Database Tables

The SQL 'device' table in UCM 8.0 no longer contains an 'XML' field for storing vendor config, custom XML configurations. How can I read/write this data?

As the vendor config XML has become quite large for some phone models, this information has been split out into separate tables. In order to simplify access, two SQL stored procedures are available for reading/wring the data: dbreaddevicexml() and dbwritedevicexml(). These can be executed in direct SQL requests via <executeSqlQuery> and <executeSqlUpdate> AXL requests. The pkid/uuid of the device must be provided. Examples:

xml

Copy<?xml version="1.0" encoding="UTF-8"?> 
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="https://www.cisco.com/AXL/API/7.0">
    <soapenv:Header/>   
    <soapenv:Body>     
        <ns:executeSQLQuery sequence="1">       
            <sql>
                execute procedure dbreaddevicexml('01ad645f-9cd1-8e8d-4f29-db39d6587ffb')
            </sql>     
        </ns:executeSQLQuery>   
    </soapenv:Body> 
</soapenv:Envelope>

xml

Copy    
<?xml version="1.0" encoding="UTF-8"?> 
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="https://www.cisco.com/AXL/API/7.0">
  <soapenv:Header/> 
  <soapenv:Body> 
    <ns:executeSQLUpdate sequence="1"> 
      <sql> execute procedure dbwritedevicexml('01ad645f-9cd1-8e8d-4f29-db39d6587ffb',
                '<disableSpeaker>true</disableSpeaker> 
                <disableSpeakerAndHeadset>false</disableSpeakerAndHeadset> 
                <forwardingDelay>1</forwardingDelay> 
                <pcPort>0</pcPort> 
                <settingsAccess>1</settingsAccess> 
                <garp>1</garp> 
                <voiceVlanAccess>0</voiceVlanAccess> 
                <videoCapability>0</videoCapability> 
                <autoSelectLineEnable>0</autoSelectLineEnable> 
                <webAccess>0</webAccess> 
                <daysDisplayNotActive>1,7</daysDisplayNotActive> 
                <displayOnTime>07:30</displayOnTime>
                <displayOnDuration>10:30</displayOnDuration>                                  
                <displayIdleTimeout>01:00</displayIdleTimeout>                                  
                <spanToPCPort>1</spanToPCPort> 
                <loggingDisplay>1</loggingDisplay> 
                    ')
            </sql> 
    </ns:executeSQLUpdate> 
  </soapenv:Body> 
</soapenv:Envelope>

Trace Settings

Reading/updating CM Service trace settings

Updating Unified Communications Manager Service Trace Settings

General trace settings for individual CUCM services can be read/updated via the <updateProcessNodeService> request. However, granular trace settings (found under 'Trace Fields' in the CCM Admin service trace web UI) are accessed via the updateProcessNodeService/userCategories element, which is an integer value containing a bitmap.

For example under CM 6.0(1), the 'Call Manager' service trace settings 'userCategories' field contains: 1309183

For the Call Manager service, the first bit in this field corresponds to 'Enable H245 Message Trace' which here is enabled, since the first bit of 1309183 (in binary format: 100111111100111111111) is set to 1.

In order to decode which options are enabled/disabled, you will need a reference as to which bits (in binary representation of the userCategories integer field) represent which trace setting options.

The bit-map to trace flag mappings are not currently documented, and may need to be reverse engineered, e.g. by comparing the admin UI with changes to the bit-map field in the database.