Administrative XML FAQs
Getting Started
- Is HTTP version required during AXL POST?
- What role is required for a user to access AXL?
- The AXL service has a built-in throttle mechanism for AXL update requests, how should my application work with it?
- Which phones cannot be configured with a Locale?
- Why don't I receive localized characters when retrieving data from certain AXL commands?
How to
- How can I use the AXL .xsd schema files to validate that an XML object is properly formatted?
- How can I find out which node in a cluster is the Publisher?
- How do I add a new phone to CUCM using AXL?
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
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 role is 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
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).
- 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.
1 2 3 4 5 6 7 | <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <SOAP-ENV:Body> <axlapi:getUser xmlns:axlapi="http://www.cisco.com/AXL/API/1.0" xmlns:axl="http://www.cisco.com/AXL/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://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'
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.cisco.com/AXL/API/8.5"><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://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></soapenv:envelope> |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | <?xml version="1.0" encoding="UTF-8"?> <soapenv:Body> <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.)
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | <?xml version="1.0" encoding="UTF-8"?> <soapenv:Body> <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:
1 2 3 4 5 6 7 8 9 10 11 | <?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://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> |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | <?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://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.
