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>

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

This indicates that UserMaskBit 0 (i.e. the first bit in the value) corresponds to 'H245 Message Trace'.

What may be the reason when the XML field of the VendorConfig element in DB is shown empty via Enterprise Manager? #

The values of VendorConfig field are actually present in DB. At sometimes, they are not visible through Enterprise Manager butyes able to see the values listed in the XML column for the devices using SQLQuery Analyzer. This can happen when the data contains line feed characters. In SQL Enterprise Manager that can make a field appear to be empty.
Both MS SQL Enterprise Manager and Query Analyzer have a limitation of displaying one line of text for each field in the results viewer. If the data contains CR/LF characters - which are valid in XML data - then only the first of the multiple lines in Enterprise Manager is seen. If the CR/LF precedes the first line the field will appear to be blank even though the data is present. In Query Analyzer the CR/LF is ignored, so all text appears on a single line.

In CUCM 4.2(3)SR3a with ES 70, why getPhoneResponse API returns incomplete VendorConfig-element? #

In general, the DB will not save the VendorConfig element if it uses default values. So the insertion of new devices does not require the content of the VendorConfig element to be set, unless non-default values are desired. Touching the record / updating the corresponding phone via BAT or Admin will fully populate the VendorConfig fields.

Why RIS API does not return the status of the phone even if the device is registered? #

When the "Cisco RIS Data Collector" service parameter "RIS Client Timeout" value is set to default and the number of nodes is more than 10 in a cluster, it causes single node time out value to be 0 second for some nodes... This results in timer expired before the RisDC reply/request reaches the particular node. This is because in RisDC, Unified CM has the logic to distribute 90% of total time-out time evenly among nodes involved, so the single node's time out value is not the Service parameter RisClientTimeout value. Hence, work around is to... change the value for the RisClientTimeout parameter to a bigger value and try the request again. Steps to change the RISClientTimeout parameter value:

• In CallManager Admin GUI, under "System" select "Service Parameter"
• Select the Server
• Select the Service as "Cisco RIS Data Collector"
• Change the Parameter value for RIS Client Timeout parameter
• Click Save

The corresponding CDETS for this issue is CSCsy06393.

Whether HTTP version is required during AXL POST? #

CCM 4.2 and previous versions sending the HTTP version in POST is not required, but in case of Unified CM 4.3 and later it is mandatory, though the version number being passed could be either 1.0 or 1.1

Where can one fetch the DBL error codes? #

Using SQL queries with AXL, one could find error codes in the table typedberrors. This way, you get the error codes for the CCM version you're using.

Which phones cannot be configured with a Locale on CCM 4.1.3? #

The following list of IP Phones cannot be configured with a locale through AXL on CCM 4.1.3:

Cisco 12 SP+ Cisco 12 SP Cisco 12 S Cisco 30 SP+ Cisco 30 VIP Cisco 7935 Cisco 7910 Cisco 7920 Cisco 7936
Also : CTI Port cannot be configured with a locale through AXL on CCM 4.1.3. All other IP phones can be configured with a locale

There is no 'addApplicationUser' request, how can I create this type of user? #

Application users can be created by performing a SQL INSERT statement, via the AXL request, against the 'applicationuser' table (see the CallManager Database Dictionary for details about the contents of that table's fields.)
Note that the 'password' and 'pin' fields in the 'applicationuser' table are stored in the CallManager database in encrypted format, and should not be updated directly using SQL. Instead, use the UpdateApplicationUser AXL request to set the values of these fields.

How can I retrieve a list of Call Pickup Groups? #

Specific requests for managing Call Pickup Groups are not available as of CallManager 5.1, however by using , the database can be queried directly via SQL to find the information:

For 4.1(3) onwards and 5.X, use a query like the following to get the list of CallPickup Groups configured and the DNs associated.

"select pg.*, np.DNOrPattern from pickupgroup pg, Numplan np where pg.fknumplan_pickup=np.pkid"

• PickupGroup table contains name, description, notification etc.
• PickupGroupMember table contains associated CallPickupGroups.
• PickupGroupLineMap table contains the directory numbers associated with the CallPickupGroup.

For Callmanager versions prior to 4.1(3), then the following query would give the CallPickup numbers.

"select np.* from Numplan np where tkPatternUsage='4'"

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 can I retrieve more than 500 users with? #

Prior to CCM 4.1(2), the maximum # of users that could be queried was 500. Applications needing to query more than 500 users would need to narrow the search criteria in order to get under this limit, and submit multiple queries (i.e. multiple queries of 'lastname=A*' and 'lastname=B*' etc, instead of a single 'lastname=*').

CCM 4.1(2) introduced the element, which allows the application to specificy the maximum number of users to return (default=500.)

There is no enforced limit for &ltsearchLimit>, however querying large numbers of users can have a significant impact on CCM performance, impacting call processing. Applications are strongly cautioned to limit queries and submit multiple smaller requests when possible rather than submit huge single requests, and to test/monitor CCM performance carefully.

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 CallManager 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.

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

There are a number of considerations with regard to AXL and throttling:

• AXL can have a large impact on CallManager, impacting its ability to process calls in a timely manner. AXL 'reads' are generally much lighter weight than 'writes' and AXL does not impose a throttle on AXL reads, however it is still important that AXL applications understand (and test) the impact their reads will have on CCM, especially if the target data-set is potentially large or the potential # of reads is high (i.e. getPhone on 30K phones)
• AXL write operations have a wide range of impact, from small to very large (updating a single CSS on a very large operating CCM dataset can spike the CPU for many seconds). While the AXL throttle keeps a (very) general throttle window enforced, it is important that applications understand the real impact of their write operations and throttle themselves accordingly.
• AXL will attempt to execute requests in parallel. This can increase the overall as well as instantaneous impact of multiple requests if they arrive all at once, as threading and DB contention issues can occur. Even though the AXL write throttle will accept (and execute) many simultaneous requests - up to the throttle limit per minute - it is highly desireable that applications 'spread-out' requests so as to reach the target rate-per-minute (e.g. 60.)
• Other AXL applications can be contending for the (global) maximum request rate. Even though the CCM AXL rate parameter is set to a certain value, applications should be prepared to gracefully handle less than max rates when other AXL apps are also in operation.
• The global AXL request rate is both readable and writeable by AXL itself. Applications should use this to determine the throttling rate and ajust accordingly. They can also use this ability to increase the AXL throttle.
• perhaps temporarily increasing it to 999 to enable fast-as-possible operations during a down-time maintenance window (an onscreen warning is recommended!)

I am having problems getting XXXX compiler to accept the AXL WSDL file, why is this and what can I do? #

CallManager versions prior to 5.0(4)

The AXL XSD-format schema is designed using XML Spy 4.0. An automated process converts and exports multiple AXL XSD format files into a single WSDL format file, however this file is not tested with any specific WSDL compilers/consumers, and has known issues with .NET and Apache/AXIS compilers. Developers should expect to make modifications to the WSDL file in order to get it to work with specific compilers.

CallManager 5.0(4) and above

Improvements to the AXL schema and WSDL build process, along with basic testing with .NET and AXIS should improve general compatibility of the WSDL with standard compilers. Note the WSDL is still provided as an as-is reference, and developers may still need to make some modifications in order to work with a given compiler:

.NET 1.1 known issues with CallManager 5.0(4) AXL WSDL:

Resulting class AXLAPIService in AXLAPIService.cs needs at least three changes:

1. Create an ICertificatePolicy-derived class which will later be associated with the service. This example class is a brute-force approach to policy and certificate management. Developers may wish to expand on this class to allow greater control of the HTTPS-security mechanism. This is necessary in 5.0 AXL due to usage of HTTPS.

public class BruteForcePolicy : System.Net.ICertificatePolicy { public bool CheckValidationResult(System.Net.ServicePoint sp, System.Security.Cryptography.X509Certificates.X509Certificate cert, System.Net.WebRequest request, int problem) { return true; } }

2. Modify service constructor to take username/password credentials, CallManager IP as an argument, and associate the BruteForcePolicy class with the static CertificatePolicy manager.

public AXLAPIService(string ccmIp, string user, string password) { System.Net.ServicePointManager.CertificatePolicy = new TrustAllCertificatePolicy(); this.Url = "https://" + ccmIp + ":8443/axl/"; this.Credentials = new System.Net.NetworkCredential(user, password); }

3. Tomcat/AXIS is used by the CallManager AXL implementation. According to the linked issue, .NET uses the expects header incorrectly, and so AXIS rejects the request.

http://issues.apache.org/bugzilla/show_bug.cgi?id=31567 There are four workarounds for this problem:

a. Override the GetWebRequest method to use HTTP 1.0 due to error between TOMCAT/AXIS and .NET HTTP 1.1 Web Service request mechanism.

protected override System.Net.WebRequest GetWebRequest(Uri uri) { System.Net.HttpWebRequest request = base.GetWebRequest (uri) as System.Net.HttpWebRequest; request.ProtocolVersion = System.Net.HttpVersion.Version10; return request; }

b. Override the GetWebRequest method to manually embed authentication string. If you do this, do not use the line this.Credentials = new System.Net.NetworkCredential(user, password); from the constructor supplied in step 2.

protected override System.Net.WebRequest GetWebRequest(Uri uri) { System.Net.HttpWebRequest request = (System.Net.HttpWebRequest)base.GetWebRequest(uri); if (this.PreAuthenticate) { System.Net.NetworkCredential nc = this.Credentials.GetCredential(uri,"Basic"); if (nc != null) { byte credBuf = new System.Text.UTF8Encoding().GetBytes(nc.UserName + ":" + nc.Password); request.Headers"Authorization" = "Basic " + Convert.ToBase64String(credBuf); } } return request; }

c. If using wsdl2wse (WSE library) instead of wsdl.exe (as #4 assumes), you can not override the HTTP version or supply HTTP headers manually. If one wants to use WSE, you have to set Keep-Alive header to false for the generated class, or set the user-agent to restricted. This technique will work in lieu of approach (a) and (b).

Resolving Errors which Manifest During JIT:

With the current code, one can compile and attempt to instantiate the AXLAPIService class. However, one error will manifest as the types are inspected and loaded.

1. Class XUserUserGroup has a field which was generated incorrectly. One must remove one of the ?? from the two ?? brackets after XUserUserGroupUserRolesUserRole field:

public XUserUserGroupUserRolesUserRole userRoles;

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

Try using getServiceParameter to retrieve the value for the GlassHouseNodeId service parameter. This is the pkid of the publisher processNode node.

Then use that pkid in getProcessNode to retrieve the details of the server.

Can I find out the software version of CallManager via AXL? #

CallManager 4.0 and higher include the 'executeSQLQuery' request, which allows submitting a custom Select statement against the CCM configuration database. The results are returned in XML format.

Any information stored in the configuration database, including the version of the CallManager, can be retrieved via this method - sometimes with much greater efficiency than via the standard AXL requests. The main downside is the application has to have detailed knowledge of the CCM config DB schema.

The following query will retrieve the CallManager software version:

<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>
<axl:executeSQLQuery
xmlns:axl="[http://www.cisco.com/AXL/1.0"]
xsi:schemaLocation="[http://www.cisco.com/AXL/1.0]
[http://gkar.cisco.com/schema/axlsoap.xsd"]
sequence="1234">
<sql>SELECT Version FROM ComponentVersion WHERE SoftwareComponent LIKE 'Cisco CallManager'</sql>
</axl:executeSQLQuery>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Can I use 'wildcards' when perfoming AXL 'list' requests? #

Yes. For most <listXXX> requests, the standard MS SQL 2000 wildcards may be used in place of, or as part of, the search term (for example '%' to return all entries.)

The exception is <listUserByName>, where the '*' wildcard is used in place of '%' (the back-end data store here is LDAP.)

Note that wildcards may NOT be used for the <GetXXX> series of requests.

When trying to submit an AXL query to the CallManager, I receive an access denied error. What could be wrong? #

Access to the AXL-SOAP web service is controlled by IIS. By default, only members of the CallManager's Win2K 'Administrators' group have access to AXL.

If this isn't working (or you want to change this security scheme - recommended,) you will need to examine:

• The Windows Internet Services Manager security settings for the \Default Web Site\CCMApi application
• The regular Windows file system permissions for the SOAPISAPI.dll file (C:\CiscoWebs\API\AXL\V1\SOAPISAPI.dll). AXL users will need at least 'Read & Execute' rights.

How do I add a new phone to CallManager using AXL? #

Adding a phone is actually a two-step process:

The first step involves adding a line to the CCM (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 (also see samples,) 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.)

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 CallManager 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 must use the updateUser and updateApplicationUser AXL requests - which perform the appropriate encryption - to set user passwords and pins.

How can I get or set which device and line is the 'Primary Extension' for a User? #

CallManager 3.x/4.x

The Primary Extension of a User is stored with user data in the CallManager's LDAP directory, as a string 'Extension' field. This is read and writeable via the 'get/updateUser' request and the 'extension' element.

Note, there are a few caveats with the Primary Extension DN in CallManager versions less then 5.x:

1. The Extension field is a plain DN value. As a result it can be ambiguous if the user has multiple line appearances with the same DN (perhaps in different partitions) in their controlled device list 2. The Extension field can be blank if the Administrator has not specified a Primary Extension for a user 3. The Extension field can hold a 'stale' value if the actual line appearance has been deleted by the admin, or if the hosting phone has been removed from the user's controlled device list

CallManager 5.x

The Primary Extension of a user is stored in the CallManager dabase. The string DN can be retrieved as in CCM 3.x/4.x via 'getUser' and the 'extension' field, however additional information (including the Primary Extension's specific line appearance) can be obtained via the 'executeSQLQuery' and a direct SQL query (tables involved: enduser, endusernumplanmap, typednusage, numplan.)

Caveats:

1. When using 'getUser' the 'extension' value can still be ambiguous (as in CM3.x/4.x) if multiple line appearances with identical DNs in different partitions exist. 2. If a user does not have a Primary Extension assigned (i.e. 'None'), then there will be no corresponding row in the 'endusernumplanmap' table. 3. In addition to being a Primary Extension, a line appearance can also be designated as a user's 'IPCC Extension'. Be sure to check endusernumplanmap.tkdnusage for values of 1 (primary extension) or 2 (IPCC extension).

How can I list or get or set values for Service Parameters? #

get/updateServiceParameter can be used to read or write Service Parameter values, if you know the parameter name.

For a complete (raw listing), you can use executeSQLQuery to query the 'ProcessNodeConfig' table (see the corresponding CallManager DataDictionary for info on the various fields and values.)

Note, the service parameter default values can be found in 'ProcessNodeConfigDefaults'.

Issue with AXL response for the method executeSQLQuery under CCM 5.0 #

This is a limitation of the IDS JDBC driver (CallManager 5.0). When returning result sets with identical field names, us the 'AS' statement to create an alias for one or both of the field names, for example:

SELECT location.name AS name1,device.name as name2, device.description FROM device, location WHERE device.fklocation = location.pkid AND device.tkclass=254 AND device.tkdeviceprofile=1

The minimum permissions needed to access MAC, IP, and Phone Status information#

The best way for an application to get MAC, IP, and Phone status information is through AXL Serviceability. The minimum permissions needed to use the Serviceability SOAP ports are:

• Standard CCM Admin Users (to get in the front door of the web admin Tomcat instance - does not give full admin rights)
• Standard SERVICEABILITY Read Only (to access risport API)