FAQs

Top  Previous 

Getting Started

How to

Troubleshooting

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
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?

See How to Work with Data Throttling.

 

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.

<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'

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.cisco.com/AXL/API/8.5">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:listProcessNode>
         <searchCriteria>
            <name>%</name>
         </searchCriteria>
         <returnedTags>
           <name/>
           <nodeUsage/>
         </returnedTags>
      </ns:listProcessNode>
   </soapenv:Body>
</soapenv:Envelope>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:listProcessNodeResponse xmlns:ns="http://www.cisco.com/AXL/API/8.5">
         <return>
            <processNode uuid="{00000000-1111-0000-0000-000000000000}">
               <name>EnterpriseWideData</name>
               <nodeUsage>Subscriber</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.)

To view the request and response for this process please view the AXL Developers Cookbook.

 


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:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <soapenv:Fault xmlns:axis2ns5="http://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>
 

Developers interested in obtaining licensing information programmatically from Enterprise License Manager should send an email to elm-license-api-feedback@cisco.com. Please include detailed use case(s) illustrating how and what the application plans to use regarding licensing information.

 


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:

<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>
<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>
                <loadServer></loadServer>
                <recordingTone>0</recordingTone>
                <recordingToneLocalVolume>100</recordingToneLocalVolume>
                <recordingToneRemoteVolume>50</recordingToneRemoteVolume>
                <recordingToneDuration></recordingToneDuration>
                <displayOnWhenIncomingCall>0</displayOnWhenIncomingCall>
                <rtcp>0</rtcp>
                <moreKeyReversionTimer>5</moreKeyReversionTimer>
                <autoCallSelect>1</autoCallSelect>
                <logServer></logServer>
                <g722CodecSupport>0</g722CodecSupport>
                <headsetWidebandUIControl>0</headsetWidebandUIControl>
                <handsetWidebandUIControl>0</handsetWidebandUIControl>
                <headsetWidebandEnable>0</headsetWidebandEnable>
                <handsetWidebandEnable>0</handsetWidebandEnable>
                <peerFirmwareSharing>0</peerFirmwareSharing>
                <enableCdpSwPort>1</enableCdpSwPort>
                <enableCdpPcPort>1</enableCdpPcPort>
                <enableLldpSwPort>1</enableLldpSwPort>
                <enableLldpPcPort>1</enableLldpPcPort>
                <lldpAssetId></lldpAssetId>
                <powerPriority>0</powerPriority>
                <detectCMConnectionFailure>0</detectCMConnectionFailure>
                <minimumRingVolume>0</minimumRingVolume>
                <sideToneLevel>0</sideToneLevel>
                ')</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.

A set of XML files documenting this relationship is available here: AXLupdateProcessNodeService/userCategories decode file

Each service with trace settings is listed in the TraceServices.xml file. Note each service has a corresponding ID, for example the Call Manager service = 0. Each service has a separate set of trace settings, and so has a separate corresponding XML file. Refer to the individual <service id>.xml file corresponding to the service to find individual mappings.

For example the top of the Call Manager service (ID=0) XML file (0.xml) looks like this:

<TraceBitDefinition ServiceType="Call Manager" DeviceBasedTracing="yes" AllowXML="yes" XMLlines="2000" EnableAlarm="yes">
    <bit Definition="Enable H245 Message Trace" Help="H245 Message Trace" ConstantNameUsed="SUBSYS_H245">
        <UserMaskBit>0</UserMaskBit>
    </bit>
    <bit Definition="Enable CDR Trace" Help="CDR trace Information" ConstantNameUsed="SUBSYS_CDR">
        <UserMaskBit>1</UserMaskBit>
    </bit>
    ...

Please visit Cisco DevNet AXL FAQs online for the latest FAQ updates.