Table Of Contents
Administrative XML Programming
New Information for Cisco Unified Communications Manager 7.1(2)
New Information for Cisco Unified Communications Manager 7.0(1)
Dynamic Throttling of Requests
New Information for Cisco Unified Communications Manager 6.1 (1)
New Information for Cisco Unified Communications Manager 6.0(1)
Changed Service Parameter for Cisco Unified Communications Manager 6.0(1)
New Information for Cisco Unified Communications Manager 5.1(1)
New Information for Cisco Unified Communications Manager 5.0(1)
New Information for Cisco Unified Communications Manager 4.2(2)
New Information for Cisco Unified Communications Manager 4.1(2)
Dynamic Throttling of Requests
Integration Considerations and Interoperability
Post-Installation Steps and Troubleshooting on the Linux Platform
Setting AXL API Access Permissions
Post-Installation Troubleshooting Checklist
Using the AXL API in a .NET Environment
Required Changes to the Generated Code
Names Containing Special Characters
Returned Namespace for AXIS and .NET Applications
Administrative XML Programming
This chapter describes the Administrative XML Layer (AXL) Application Programming Interface (API). It contains the following sections:
•
Dynamic Throttling of Requests
•
•
•
•
Overview
The AXL API provides a mechanism for inserting, retrieving, updating, and removing data from the Cisco Unified Communications Manager database by using an eXtensible Markup Language (XML) Simple Object Access Protocol (SOAP) interface. This approach allows a programmer to access the database by using XML and receive the data in XML form, instead of by using a binary library or DLL.
The AXL API methods, known as requests, use a combination of HTTPS and SOAP. SOAP is an XML remote procedure call (RPC) protocol. The server receives the XML structures and executes the request. If the request completes successfully, the system returns the appropriate AXL response. All responses are named identically to the associated requests, except that the word "Response" is appended.
For example, the XML response that is returned from an addPhone request is named addPhoneResponse.
If an error occurs, an XML error structure is returned, wrapped inside a SOAP Fault structure (see the "AXL Error Codes" section).
The AXL-SOAP web service is disabled by default on all Cisco Unified Communications Manager (Unified CM) servers that are running version 5.x or later. You should start the service before using the AXL APIs.
To access all AXL SOAP API downloads and AXL requests and responses that are found in this chapter, refer to http://www.cisco.com/pcgi-bin/dev_support/access_level/product_support.
This chapter assumes that the developer has knowledge of a high-level programming language such as C++, Java, or an equivalent language, and has knowledge of SOAP.
Developers must also have knowledge or experience in the following areas:
•
•
•
•
Users of the AXL API must have a firm grasp of XML syntax and Schema, which is used to define the AXL requests, responses, and errors. For more information about XML Schema, refer to http://www.w3.org/TR/xmlschema-0/. For more information about XML syntax/grammar, refer to http://www.w3.org/TR/rdf-syntax-grammar/.
Caution
AXL Compliance
The Cisco Unified Communications Manager AXL implementation complies with XML Schema 1.0, which was tested for XML Schema compliance with a third-party application that is called XML Spy version 4.x. Early versions of the MSXML schema validator did not support enough of the XML Schema 1.0 recommendation to be used.
The Cisco Unified Communications Manager AXL implementation also complies with SOAP 1.1 as defined by the World Wide Web Consortium as well as HTTPS 1.1. The AXL API runs as an independent service that can be accessed only via HTTPS.
New and Changed Information
The following sections describe the major changes in the AXL APIs for Release 7.1(2) and for previous releases:
•
•
•
•
•
•
•
•
For information about new, changed, or deprecated AXL API methods from the interface library, see Chapter 3, "Administrative XML Operations by Release".
New Information for Cisco Unified Communications Manager 7.1(2)
Cisco Unified Communications Manager (Unified CM) 7.1(2) APIs are compatible with all previous releases of Unified CM. For additional details about the Unified CM database schema changes, refer to the Cisco Unified Communications Manager Data Dictionary for Release 7.1(2).
The following sections describe API updates that were made in Cisco Unified Communications Manager 7.1(2):
New APIs
Table 2-1 describes new operations in Cisco Unified Communications Manager 7.1(2).
Changed Operations
Table 2-2 describes changed operations in Cisco Unified Communications Manager 7.1(2).
New Information for Cisco Unified Communications Manager 7.0(1)
Cisco Unified Communications Manager 7.0(1) APIs are compatible with all previous releases of Cisco Unified Communications Manager. For additional details about the Cisco Unified Communications Manager database schema changes, refer to the Cisco Unified Communications Manager Data Dictionary for Release 7.0(1).
The following sections describe API updates that were made in Cisco Unified Communications Manager 7.0(1):
New APIs
Table 2-3 describes new operations in Cisco Unified Communications Manager 7.0(1).
Changed Operations
Table 2-4 describes changed operations in Cisco Unified Communications Manager 7.0(1).
Dynamic Throttling of Requests
Cisco Unified Communications Manager 7.0 includes a new throttling mechanism called dynamic throttling of request. The MaxAXLWritesPerMinute service parameter, used in earlier releases, has been deprecated. For more information see, Dynamic Throttling of Requests.
New Information for Cisco Unified Communications Manager 6.1 (1)
Table 2-5 describes the API calls that changed in Cisco Unified Communications Manager 6.1(1). These changes may require updates to the existing user-code that uses these APIs.
Note
New Information for Cisco Unified Communications Manager 6.0(1)
For Cisco Unified Communications Manager Release 6.0(1), be aware that the defined AXL APIs are backward compatible. However, the executeSQLQuery request, which lets the user run a database query directly on the Cisco Unified Communications Manager database, is not backward compatible.
•
•
Note
•
–
–
•
For further details about the Cisco Unified Communications Manager database schema changes, refer to Cisco Unified Communications Manager Data Dictionary for Release 6.0(1).
Note
Cisco always advises running the AXL API on a completely upgraded cluster. When run on a cluster that is not upgraded completely, the response of the AXL API will be correct when executed on a server that already has been upgraded. However, if you execute the AXL API on a server that has not yet been upgraded, then it will return the Cisco Unified Communications Manager Version of the lowest node ID Cisco Unified Communications Manager per the server local database information.The following AXL API calls changed in Cisco Unified Communications Manager Release 6.0(1). These changes may require changes to the existing user-code that uses these APIs:
•
•
•
•
•
•
•
•
•
•
•
–
–
•
–
–
•
–
–
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
In axlsoap.xsd
–
–
–
•
In axl.xsd
–
In axlsoap.xsd
–
–
–
This release deprecated some of the fields that were removed from the Cisco Unified Communications Manager 6.0(1) database in AXL. This release adds annotation for such fields.
AXL Versioning Support
To improve backward compatibility, Cisco Unified Communications Manager introduced AXL schema versioning in Release 6.0(1). This feature is included in all subsequent Cisco Unified Communications Manager releases. Beginning with Release 6.0(1), the system duplicates the previous AXL 1.0 schema as the AXL 6.0(1) schema and numbers the AXL schema the same as the corresponding Cisco Unified Communications Manager release. This approach maintains AXL backward compatibility for one full release cycle.
Changed Service Parameter for Cisco Unified Communications Manager 6.0(1)
Cisco Unified Communications Manager 6.0(1) adds a new service parameter, EnableAXLEncodingInfo, to the Cisco Unified Communications Manager Administrator windows under the Cisco Database Layer Monitor service. This parameter allows the user to decide whether AXL responses should contain the encoding information. Consider encoding information as important if an AXL request has non-English characters in it.
Cisco Unified Communications Manager 5.1(1) added a new service parameter, Send Valid Namespace in the AXL response, under the Cisco Database Layer Monitor service. This parameter determines the namespace that is sent in the AXL response from the Cisco Unified Communications Manager. In the 6.0(1) release, the default value of this parameter changed from False to True.
•
•
To maintain backward compatibility with older applications, you might need to change the value to False. Cisco recommends that you set this parameter to True, so the Cisco Unified Communications Manager sends a valid namespace.
New Information for Cisco Unified Communications Manager 5.1(1)
The following list provides AXL API calls that are new in Cisco Unified Communications Manager 5.1(1):
•
•
•
•
These APIs add and update credentials (passwordreserve) in siprealm.
In addition, Cisco Unified Communications Manager Administration 5.1 release adds a new service parameter, "Send Valid Namespace in AXL Response," under the Cisco Database Layer Monitor service. This parameter determines the namespace that gets sent in the AXL response from Cisco Unified Communications Manager.
When this parameter specifies True, Cisco Unified Communications Manager sends the valid namespace in the AXL response so the namespace matches the AXL schema specification.
If the parameter specifies False, Cisco Unified Communications Manager sends an invalid namespace in the AXL response, which does not match the AXL schema specification.
The default service parameter value specifies False to maintain backward compatibility with the AXL response in the Cisco Unified Communications Manager 5.0 release. Cisco recommends that you set this parameter to True so Cisco Unified CallManager sends the valid namespace.
New Information for Cisco Unified Communications Manager 5.0(1)
The following AXL API calls are new in Cisco Unified Communications Manager 5.0(1):
•
•
•
•
•
•
•
The following AXL API calls have been changed in Cisco Unified Communications Manager 5.0:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
The following API calls that have been deprecated in Cisco Unified Communications Manager 5.0:
•
•
•
•
•
•
•
•
•
New Information for Cisco Unified Communications Manager 4.2(2)
This section describes the new or changed API calls for Cisco Unified Communications Manager 4.2(2) and a new service parameter for Cisco Database Layer Monitor.
Changed API Calls
Changes to the following API calls in Cisco Unified Communications Manager 4.2(2) support the Hold Reversion feature:
•
•
•
•
Because these new tags are disabled by default, these changes are backward-compatible with existing user code.
New Service Parameter
A new service parameter, EnableAXLEncodingInfo, has been added to Cisco Unified Communications Manager Administration under the Cisco Database Layer Monitor service. This parameter enables the user to decide if AXL responses should contain encoding information. Encoding information is important if an AXL request has non-English characters in it.
New Information for Cisco Unified Communications Manager 4.1(2)
The following AXL API calls are new in Cisco Unified Communications Manager 4.1(2):
addTimePeriod
updateTimePeriod
removeTimePeriod
getTimePeriod
addTimeSchedule
updateTimeSchedule
removeTimeSchedule
getTimeSchedule
addCMCInfo
updateCMCInfo
removeCMCInfo
getCMCInfo
addFACInfo
updateFACInfo
removeFACInfo
getFACInfo
The following AXL API calls have been changed in Cisco Unified Communications Manager 4.1(2):
addPhone
updatePhone
getPhone
addLine
updateLine
addUser
removeUser
updateUser
getUser
addDeviceProfile
updateDeviceProfile
getDeviceProfile
addRoutePattern
updateRoutePattern
getRoutePattern
addRouteList
updateRouteList
getRouteList
addGatewayEndpoint
updateGatewayEndpoint
getGatewayEndpoint
addH323Trunk
updateH323Trunk
removeH323Trunk
getH323Trunk
addHuntPilot
updateHuntPilot
removeHuntPilot
getHuntPilot
addProcessNode
updateProcessNode
removeProcessNode
getProcessNode
listAllProcessNodes
listProcessNodesByService
addRoutePartition
updateRoutePartition
removeRoutePartition
getRoutePartition
addH323Gateway
updateH323Gateway
removeH323Gateway
getH323Gateway
addH323Phone
updateH323Phone
removeH323Phone
getH323Phone
addHuntList
updateHuntList
removeHuntList
getHuntList
AXL Schema Documentation
The axlsqltoolkit.zip plug-in contains the following five AXL schema files:
•
•
•
•
•
These files encapsulate the complete AXL schema, including details of all requests, responses, XML objects, and data types.
In addition to these schema files, two folders exist:
•
•
Each of these folders contains AXLAPI.wsdl and AXLSoap.xsd files to be used for application development in AXIS or .NET client environments, respectively. The plug-in also contains version specific AXL in folders 1.0, 6.0, 6.1, and 7.0.
You can obtain complete documentation of all available AXL messages from the Cisco Developer Services web site: http://developer.cisco.com. This website requires a Cisco.com login.
You can use the Application > Plugins > Cisco Unified Communications Manager AXL SQL Toolkit command from the Cisco Unified Communications Manager server administration interface to obtain:
•
See also AXL Schema Documentation.
•
AXL Versioning Support
To improve backward compatibility, Cisco Unified Communications Manager introduced AXL schema versioning in Release 6.0(1). This feature is included in all subsequent Cisco Unified Communications Manager releases. Beginning with Release 6.0(1), the system duplicates the previous AXL 1.0 schema as the AXL 6.0(1) schema and numbers the AXL schema the same as the corresponding Cisco Unified Communications Manager release. This approach maintains AXL backward compatibility for one full release cycle.
Cisco highly recommends that developers include the version of AXL schema on which an AXL request is based because support for unversioned requests might be removed in future releases of Cisco Unified Communications Manager.
For those developers who are using the AXL APIs executeSQLQuery and executeSQLUpdate, changes have occurred to the Cisco Unified Communications Manager database schema that affect the direct SQL query approach. Refer to the Cisco Unified Communications Manager Database Dictionary, at http://www.cisco.com/en/US/products/sw/voicesw/ps556/products_programming_reference_guides_list.html, for the release that you are using. That document describes the specific changes in the database schema.
To help developers plan for AXL versioning, Table 2-6 provides the approach that Cisco will follow in supporting upcoming releases.
•
•
AXL Policy Under Consideration For Future Release
The following policies related to AXL versioning support is under consideration for future release:
•
•
•
•
•
•
The following sample AXL request carries version information:
Host:10.77.31.194:8443Authorization: Basic Q0NNQWRtaW5pc3RyYXRvcjpjaXNjb19jaXNjbw==Accept: text/*Content-type: text/xmlSOAPAction: "CUCM:DB ver=7.0"Content-length: 427SOAP-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:getUser xmlns:axl="http://www.cisco.com/AXL/7.0" si:schemaLocation="http://www.cisco.com/AXL/API/7.0 http://ccmserver/schema/axlsoap.xsd" sequence="1234"><userid>tttt</userid></axl:getUser></SOAP-ENV:Body></SOAP-ENV:Envelope>Sample AXL response:
HTTP/1.1 200 OKServer: Apache-Coyote/1.1Set-Cookie: JSESSIONIDSSO=12E52A7F9B34107BA6147096878E00F9; Path=/Set-Cookie: JSESSIONID=7B94F17D61C6A91B04C5C76A6E3F905E; Path=/axl; SecureSOAPAction: "CUCM:DB ver=7.0"Content-Type: text/xml;charset=utf-8Content-Length: 1936Date: Mon, 03 Mar 2008 10:17:38 GMTConnection: close<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Header/><SOAP-ENV:Body><axl:getUserResponse xmlns:axl="http://www.cisco.com/AXL/API/7.0" xmlns:xsi="http://www.cisco.com/AXL/API/7.0" sequence="1234"><return><user><firstname/><lastname>tttt</lastname><userid>tttt</userid><password/><pin/><telephoneNumber/><department/><manager/><associatedDevices><device>SEPA88888888888</device></associatedDevices><primaryExtension/><associatedPC/><associatedGroups><userGroup uuid="{6B126A13-8F47-B78D-13D4-9555D664F634}"><name>test</name><userRoles><userRole uuid="{A6BAE213-AAB5-F794-B71C-98EE94129C9B}">Standard AXL API Access</userRole></userRoles></userGroup></associatedGroups><enableCTI>true</enableCTI><digestCredentials/><enableMobility>false</enableMobility><enableMobileVoiceAccess>false</enableMobileVoiceAccess><maxDeskPickupWaitTime>10000</maxDeskPickupWaitTime><remoteDestinationLimit>4</remoteDestinationLimit><passwordCredentials><pwdCredPolicyName>Default Credential Policy</pwdCredPolicyName><pwdCredUserCantChange>false</pwdCredUserCantChange><pwdCredUserMustChange>false</pwdCredUserMustChange><pwdCredDoesNotExpire>false</pwdCredDoesNotExpire><pwdCredTimeChanged>February 14, 2008 16:10:12 IST</pwdCredTimeChanged><pwdCredTimeAdminLockout/><pwdCredLockedByAdministrator>false</pwdCredLockedByAdministrator></passwordCredentials><pinCredentials><pinCredPolicyName>Default Credential Policy</pinCredPolicyName><pinCredUserCantChange>false</pinCredUserCantChange><pinCredUserMustChange>false</pinCredUserMustChange><pinCredDoesNotExpire>false</pinCredDoesNotExpire><pinCredTimeChanged>February 14, 2008 16:10:12 IST</pinCredTimeChanged><pinCredTimeAdminLockout/><pinCredLockedByAdministrator>false</pinCredLockedByAdministrator></pinCredentials></user></return></axl:getUserResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>Authentication
The system controls user authentication via the HTTPS Basic Authentication scheme; therefore, you must include the Authorization header in the HTTPS header. Because Base64 encoding takes three 8-bit bytes and represents them as four printable ASCII characters, if the encoded header does not contain an even multiple of four ASCII characters (16, 20, 24, and so on), you must add padding characters (=) to complete the final group of four.
Ensure users are authorized to access AXL. For help with configuring authorization, see Post-Installation Steps and Troubleshooting on the Linux Platform.
If user authentication of the user fails, the system returns an HTTP 401 Access Denied error to the client.
For example, if the user agent wants to send the userid "larry" and password "curly and moe," it would use the following header field:
Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==where the string "bGFycnk6Y3VybHkgYW5kIG1vZQ==" provides the Base64 encoding of "larry:curly and moe."
Note
Data Encryption
Encrypt AXL SOAP messages by using HTTP Secure Sockets Layer (SSL). SSL remains functional on the web server by default. Ensure AXL requests are made by using the "https" protocol.
Dynamic Throttling of Requests
Cisco Unified Communications Manager releases earlier than 7.0 included the AXL service parameter MaxAXLWritesPerMinute, which has a default value of 50 and maximum value of 999. This service parameter designates the maximum number of write requests that AXL can encounter and process in one minute. Cisco Unified Communications Manager 7.0 includes a new throttling mechanism. The MaxAXLWritesPerMinute service parameter has been deprecated.
The new throttling mechanism takes into account the dynamic state of Cisco Unified Communications Manager. It considers the number of outstanding change notifications across the Cisco Unified Communications Manager cluster at any given time. If a node has more than 1,500 outstanding change notifications, AXL stops processing write requests until the outstanding change notifications are below 1,500. During throttling, HTTPS Status-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:
•
•
The AXL error message for throttling remains same as in earlier versions of Cisco Unified Communications Manager. There is no change required to AXL applications.
For example, consider an application that makes 1,000 phone insertions in 30 seconds. Assume that these insertions cause 2,000 change notifications to various applications such as Cisco Unified Communications Manager and Cisco TFTP, and that within 10 seconds all change notifications are consumed. In this situation, by the 40th second, the number of outstanding change notifications is zero and the throttling mechanism does not take effect. However, if these change notifications are not consumed, the throttling mechanism does take effect and write requests are throttled until the outstanding change notification value falls below 1,500.
The throttling mechanism considers the capacity of the Cisco Unified Communications Manager cluster to consume the change notifications that generated from all the write activities to the Cisco Unified Communications Manager database. In this way, it is dynamic. As long as all change notifications are consumed at a rate that is equal to or higher than the rate at which change notifications are generated, throttling does not take effect.
Note
•
Integration Considerations and Interoperability
The AXL API gives much power to developers to modify the Cisco Unified Communications Manager system database. The developer must use caution when using AXL because each API call impacts the system. Abuse of the API can lead to dropped calls and slower system performance. AXL acts as a provisioning and configuration API, not as a real-time API.
The AXL interface provides Developers with direct access to the Cisco Unified Communications Manager database via the ExecuteSQLQuery and ExecuteSQLUpdate methods. While the Dynamic Throttling mechanism protects system resources when multiple update (write) requests are received, by returning a "503: Service Unavailable" error message, there is no mechanism to guard system resources when large read requests are received.
Queries issued using the ExecuteSQLQuery method that result in a data sets greater than 8 MB may place Cisco Unified Communications Manager resources at risk. Cisco recommends developers using ExecuteSQLQuery method to follow these guidelines:
•
•
–
–
–
•
•
•
Note
Post-Installation Steps and Troubleshooting on the Linux Platform
The system implements AXL as a Java servlet. The Java implementation provides platform independence. AXL accesses the Cisco Unified Communications Manager database by using DBL2, which is a JDBC wrapper implementation. AXL gets packaged as a WAR file. Linux RPM installs the war file for AXL on Cisco Unified Communications Manager server.
Follow the procedures in Post-Installation Steps, to start the AXL service and set up user permissions. Next, follow the procedures in Post-Installation Troubleshooting Checklist, to check the installation.
Post-Installation Steps
You can start or stop the AXL web service from Cisco Unified Communications Manager Serviceability. The service is disabled by default. You should start the service before using the AXL APIs.
Starting the AXL Service
Step 1
Step 2
Step 3
Step 4
Upon starting the AXL service, AXL gets deployed as a web application within Apache Tomcat. The WAR file gets deployed to Tomcat under /usr/local/thirdparty/jakarta-tomcat/webapps/axl.
Setting AXL API Access Permissions
Step 1
Step 2
a.
b.
c.
d.
e.
Step 3
a.
b.
c.
Post-Installation Troubleshooting Checklist
Use the following checklist to avoid some common problems by fine-tuning your configuration before proceeding with the troubleshooting process:
Step 1
•
•
•
Use this URL for accessing AXL: https://server-name:port/axl/ (port is 8443).
•
Step 2
1.
For instance, enter https://server-name:8443/axl/ in the address text box.
2.
3.
This procedure verifies functionality and user access.
Step 3
Step 4
•
•
Step 5
AXL Trace Logs
AXL trace logs contain the text of every AXL request and response, along with user and origination IP information. Trace logs prove useful for identifying who is making AXL requests, inspecting the AXL XML request for format or syntax errors, and determining the actual AXL service response or errors.
The system writes the AXL trace logs to the /var/log/active/tomcat/logs/axl/log4j directory. You can view them with RTMT. File names are axl####.log, where # represents a number from 0000 (zero) to the maximum number of files allowed. The maximum file size is 1 MB by default. The maximum number of stored files defaults to 10. You can change these settings through the Serviceability windows .
Note
For .NET WSDL applications, including the xmlns attribute in the <password> tag would be typical behavior, and, in earlier releases, this could represent a security issue. If the SOAP message body contains a namespace tag, you do not need to specify the xmlns attribute for each individual tag.While analyzing the log files:
•
•
•
The following sample shows the AXL trace log output:
2007-03-17 05:32:26,512 INFO [http-8443-Processor21] axl.AxlListener - Received request 1173323669700 from CCMAdministrator at IP 10.77.31.2032007-03-17 05:32:26,513 INFO [http-8443-Processor21] axl.AxlListener - <!-- edited with XMLSPY v5 rel. 4 U (http://www.xmlspy.com) by Jerry Vander Voord (Cisco Systems) --><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Body><axlapi:addGatekeeper sequence="1" xmlns:axlapi="http://www.cisco.com/AXL/API/7.0" xmlns:axl="http://www.cisco.com/AXL/7.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.cisco.com/AXL/API/7.0 axlsoap.xsd"><gatekeeper><name>AXL-Sample-GK1</name><description>This is a sample gatekeeper</description><rrqTimeToLive>30</rrqTimeToLive><retryTimeout>30</retryTimeout><enableDevice>false</enableDevice></gatekeeper></axlapi:addGatekeeper></SOAP-ENV:Body></SOAP-ENV:Envelope>2007-03-17 05:32:26,668 INFO [http-8443-Processor21] axl.Handler - Handler initializing2007-03-17 05:32:26,788 INFO [http-8443-Processor21] axl.AxlListener - <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Header/><SOAP -ENV:Body><axl:addGatekeeperResponse xmlns:axl=http://www.cisco.com/AXL/7.0 xmlns:xsi="http://www.cisco.com/AXL/7.0" sequence="1"><return>{7EB31958-C24A-3E63-3E4B-A8446365D35}</return></axl:addGatekeeperResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>2007-03-17 05:32:26,789 INFO [http-8443-Processor21] axl.AxlListener - Request 1173323669700 was process in 356msThe AXL trace log contains:
•
•
•
•
•
•
•
Follow these steps to set the AXL trace level from the Serviceability window:
Step 1
Step 2
Step 3
Step 4
Step 5
Step 6
Step 7
Step 8
Step 9
Note
Using the AXL API with AXIS
This section explains how to use the AXLAPI.wsdl file in a Java programming environment.
Cisco has verified the AXLAPI.wsdl file in the WSDL-AXIS folder in the AXIS environment.
Cisco provides the associated schema file, AXLSoap.xsd, only for code generation. Cisco has modified this file to minimize the backwards compatibility impact of future changes in the database schema. Use the WSDL and the schema files in the parent directory for reference and for validation of responses.
When you run the wsdl2Java utility to create the Java source code by using AXLAPI.wsdl, the utility throws two errors that are specific to AXIS_1_4. For further details on these errors, refer to http://issues.apache.org/jira/browse/AXIS-2545 and http://issues.apache.org/jira/browse/AXIS-1280.
The incorrect ordering of the parameters that are passed to the constructor causes the first AXIS jira error. A code example follows:
public class XNPDirectoryNumberShareLineAppearanceCSS extends com.cisco.www.AXL.API._7_0.XCallingSearchSpace implements java.io.Serializable {>>super(uuid,name,description,clause,dialPlanWizardGenId,members);However, the parent constructor is defined as:
public XCallingSearchSpace(org.apache.axis.types.Name name,java.lang.String description,java.lang.String clause,org.apache.axis.types.NonNegativeInteger dialPlanWizardGenId,com.cisco.www.AXL.API._7_0.XCallingSearchSpaceMember[] members,java.lang.String uuid) {this.name = name;this.description = description;this.clause = clause;this.dialPlanWizardGenId = dialPlanWizardGenId;this.members = members;this.uuid = uuid;}You need to change either the constructor or the constructor calling as shown below:
super(name,description,clause,dialPlanWizardGenId,members,uuid);The second AXIS jira error relates to having a string constructor for simple types; for example
// Simple Types must have a String constructorpublic XLoadInformation(java.lang.String _value) {super(_value);}For such cases, the corresponding schema file (axl.xsd) in the parent schema folder must be referred and must implement the string class that these classes can inherit.
Using the AXL API in a .NET Environment
To integrate the AXL API with a .NET client, you must modify the Cisco-provided WSDL and XSD files.
Cisco provides the associated schema file, AXLSoap.xsd, only for code generation. Cisco has modified this file to minimize the backwards compatibility impact of future changes in the database schema. Use the WSDL and the schema files in the parent directory for reference and for validation of responses.
The inability of .NET to handle complex schemas necessitates some of the changes that are described below.
Required Changes to the Generated Code
After running WSDL.exe, you must make several changes to the generated code. Run WSDL.exe by using the following command:
wsdl.exe AXLAPI.wsdl axlsoap.xsdThis command generates the file AXLAPIService.cs. The class AXLAPIService in AXLAPIService.cs requires at least three changes:
1.
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.
public AXLAPIService(string ccmIp, string user, string password){System.Net.ServicePointManager.CertificatePolicy = new BruteForcePolicy();this.Url = "https://" + ccmIp + ":8443/axl/";this.Credentials = new System.Net.NetworkCredential(user, password);}3.
a.
protected override System.Net.WebRequest GetWebRequest(Uri uri){System.Net.HttpWebRequest request = base.GetWebRequest (uri) asSystem.Net.HttpWebRequest;request.ProtocolVersion = System.Net.HttpVersion.Version10;return request;}b.
this.Credentials = new System.Net.NetworkCredential(user, password);from the constructor that is provided in point 2 earlier in this section.
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.
Resolving JIT Errors
When you compile and attempt to instantiate the AXLAPIService class, you should expect one error to appear while the types are inspected and loaded.
Class XUserUserGroup includes a field that was generated incorrectly. You must remove one of the `[]' from the two `[][]' brackets after the XUserUserGroupUserRolesUserRole field:
public XUserUserGroupUserRolesUserRole[] userRoles;Backward Compatibility Issues
When you add the definitions for new Cisco Unified IP Phone devices to the Unified CM database, the original WSDL that was sent out for that Unified CM becomes outdated. For example, the XModel enumeration in Cisco CallManager Release 4.1.3 does not contain the Cisco Unified IP Phone 7961G-GE.
However, if you install the latest device pack that contains that device information into your release 4.1.3 environment, that value will be returned if you use the listAllDevices or getPhone commands for that device name. This causes .NET to throw an exception when it encounters the new model because the definition does not contain the mode.
More generally, almost all enumerations in AXLEnums.xsd could change in some future release, which in turn might create backward incompatibility with your code. To address this issue, Cisco has changed the type of all of the tags that use any of these enumerations to String and added an annotation to that tag that specifies where to look for the correct value (AXLEnums.xsd).
Tag Serialization Issues
If you generate the client stub by using wsdl.exe, you may find that some fields that have default values that are defined in the schema would not work if passed in the AXL request. For example, in the updatePhoneReq class of the generated client stub, a field named "ignorePresentationIndicators" has a default value of "False" defined in the schema.
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://www.cisco.com/AXL/7.0")]public class UpdatePhoneReq : APIRequest {.. .[System.Xml.Serialization.XmlElementAttribute(Form=System.Xml.Schema.XmlSchemaForm.Unquali fied)][System.ComponentModel.DefaultValueAttribute(false)]public bool ignorePresentationIndicators = false;..}When this tag is sent with a value of false, XmlSerializer does not serialize this tag because of a design restriction in Microsoft .NET Framework 1.0. Refer to http://support.microsoft.com/kb/325691.
To work around this problem, comment out all instances of
[System.ComponentModel.DefaultValueAttribute(XXX)]in the generated client stub as shown:
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://www.cisco.com/AXL/7.0")]public class UpdatePhoneReq : APIRequest {.. .[System.Xml.Serialization.XmlElementAttribute(Form=System.Xml.Schema.XmlSchemaForm.Unquali fied)]// Comment this line below//[System.ComponentModel.DefaultValueAttribute(false)]public bool ignorePresentationIndicators = false; ..}A second issue that is found when you are using the version of wsdl.exe that comes with .NET 1.0 is that some tags, including fkcallingsearchspace_autoregistration, do not get updated to null/none in the database.
This appears to be an issue in which .NET does not serialize tags that are defined as nillable=true in the schema.
For example, to work around this limitation for the tag callingSearchSpace in updatePhoneReq in the generated stub, you can remove the "Form=System.Xml.Schema.XmlSchemaForm.Unqualified" from
[System.Xml.Serialization.XmlElementAttribute("name", typeof(string), Form=System.Xml.Schema.XmlSchemaForm.Unqualified)][System.Xml.Serialization.XmlElementAttribute("uuid", typeof(string), Form=System.Xml.Schema.XmlSchemaForm.Unqualified)][System.Xml.Serialization.XmlChoiceIdentifierAttribute("ItemElementName")]public string Item;With this change, the serializer will serialize the tags. Passing the tag value as "" will set the callingSearchSpace to null/None. The same workaround applies to other such tags.
Names Containing Special Characters
Using the version of wsdl.exe that comes with .NET 1.0, Cisco has found that when attempting to add elements like gatewayEndpoint,MGCPEndpoint or CSS where the name contains special characters, the elements do not get updated in the database properly.
For example, a gatewayEndpoint with name="AALN@SAA000011114444" sent as name="AALN_x0040_SAA000011114444" in the AXL request.
This appears to be a limitation in .NET serialization of tags that are defined as type xsd:Name in the schema.
In the XML specification, the type xsd:name is defined as a token that begins with a letter or one of a few punctuation characters and continues with letters, digits, hyphens, underscores, colons, or periods, together known as name characters. Thus, xsd:name does not allow any special characters such as '@' or '/'.
One workaround involves changing the data type from "Name" to "string" in the generated stub:
Original Code
public class XDevice {[System.Xml.Serialization.XmlElementAttribute (Form=System.Xml.Schema.XmlSchemaForm.Unqualified,DataType="Name")]public string name;Modified Code
public class XDevice {[System.Xml.Serialization.XmlElementAttribute(typeof(string),Form=System.Xml.Schema.XmlSchemaForm.Unqualified)]public string name;With this modification, the special characters in the name will be updated in the database without any conversion.
Returned Namespace for AXIS and .NET Applications
By default, the AXLAPI.wsdl carries the namespace http://www.cisco.com/AXL/API/7.0. The generated client stubs also have this namespace. In some situations, you must change the namespace in AXLAPI.wsdl before creating the client stubs.
The namespace that is returned in the AXL response depends on two factors:
1.
2.
If the SOAPAction attribute in the HTTP header has the value "CUCM:DB ver=7.0":
•
•
•
If the SOAPAction attribute has any other value, the AXL response will have the namespace http://www.cisco.com/AXL/API/1.0 or http://www.cisco.com/AXL/1.0, depending on the value of the service parameter.
Example AXL Requests
No platform considerations exist in Cisco Unified Communications Manager Release 7.0(1). The client must be able to send an HTTPS request to the AXL endpoint.
The following examples describe how to make an AXL request and read back the response to the request.
Ensure each SOAP request is sent to the web server via an HTTPS POST. The endpoint URL represents the AXL web service that is running on a Cisco Unified Communications Manager server. The following list contains the only four required HTTPS headers:
•
The first header specifies that this particular POST is intended for the Cisco AXL Web Service. The AXL API only responds to the POST method.
•
The second header confirms that the data that is being sent to AXL is XML. If this header is not found, the system returns an HTTP 415 error to the client.
•
The third header gives the Base64 encoding of the user name and password for the administrator of the AXL Server. Because Base64 encoding takes three 8-bit bytes and represents them as four printable ASCII characters, if the encoded header does not contain an even multiple of four ASCII characters (16, 20, 24, and so on), you must add padding characters (=) to complete the final group of four as in the following examples.
If authentication of the user fails, the system returns an HTTP 401 Access Denied error to the client.
•
The fourth header specifies the length (in bytes) of the AXL request.
Note
The following example contains an HTTPS header for an AXL SOAP request:
POST :8443/axl/Host: axl.myhost.com:8443Accept: text/*Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==Content-type: text/xmlSOAPAction: "CUCM:DB ver=7.0"Content-length: 613The following AXL request gets used in the code examples that display in the following sections. This example shows a getPhone request:
POST :8443/axl/Host: axl.myhost.com:8443Accept: text/*Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==Content-type: text/xmlSOAPAction: "CUCM:DB ver=7.0"Content-length: 613<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:getPhone xmlns:axl="http://www.cisco.com/AXL/7.0" xsi:schemaLocation="http://www.cisco.com/AXL/7.0 http://ccmserver/schema/axlsoap.xsd" sequence="1234"><phoneName>SEP222222222245</phoneName></axl:getPhone></SOAP-ENV:Body></SOAP-ENV:Envelope>C or C++ Example
This code example uses a hard-coded AXL request and sends it to the AXL server that is running on the local system (localhost). It then reads the response and outputs the response to the screen:
#include <sys/socket.h>#include <sys/types.h>#include <stdlib.h>#include <openssl/ssl.h>#include <stdio.h>#include <unistd.h>#include <netinet/in.h>#include <arpa/inet.h>#include <strings.h>#include <openssl/x509.h>#include <openssl/crypto.h>#include <iostream>#include <string>using namespace std;typedef unsigned char byte;void encodeBase64( const string& inBuf, string &outBuf ){unsigned int i;unsigned int j;bool hiteof = false;byte dtable[256];outBuf.erase();for(i= 0;i<9;i++){dtable[i]= 'A'+i;dtable[i+9]= 'J'+i;dtable[26+i]= 'a'+i;dtable[26+i+9]= 'j'+i;}for(i= 0;i<8;i++){dtable[i+18]= 'S'+i;dtable[26+i+18]= 's'+i;}for(i= 0;i<10;i++){dtable[52+i]= '0'+i;}dtable[62]= '+';dtable[63]= '/';j = 0;while(!hiteof){byte igroup[3],ogroup[4];int c,n;igroup[0]= igroup[1]= igroup[2]= 0;for(n= 0;n<3;n++){if( j < inBuf.size() ){c = inBuf[j++];} else{hiteof = true;break;}igroup[n]= (byte)c;}if(n> 0){ogroup[0]= dtable[igroup[0]>>2];ogroup[1]= dtable[((igroup[0]&3)<<4)|(igroup[1]>>4)];ogroup[2]= dtable[((igroup[1]&0xF)<<2)|(igroup[2]>>6)];ogroup[3]= dtable[igroup[2]&0x3F];if(n<3){ogroup[3]= '=';if(n<2){ogroup[2]= '=';}}for(i= 0;i<4;i++){outBuf += ogroup[i];}}}}string getAuthorization(){string m_encode64,name;//You should change name to your own axl server user name and passwd//in this example, "CCMAdministrator" is the user name and "cisco_cisco" is the passwd.name="CCMAdministrator:cisco_cisco";encodeBase64(name,m_encode64);return m_encode64;}voidBuildDeviceNameSQL(string &buf, // Buffer to build AXLstring& deviceNumber, // DNstring& seqNum ){const int BUFSIZE = 2048;char buff[BUFSIZE]; // Temp bufferstring strHTTPHeader; // HTTP/AXL Headerstring strAXLRequest; // AXL RequeststrAXLRequest = "<SOAP-ENV:Envelope xmlns:SOAP-ENV=";strAXLRequest += "\"http://schemas.xmlsoap.org/soap/envelope/\"";strAXLRequest += " xmlns:SOAP-ENC=\"http://schemas.xmlsoap.org/soap/encoding/\"";strAXLRequest += " xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"";strAXLRequest += " xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"> ";strAXLRequest += "<SOAP-ENV:Body> ";strAXLRequest += "<m:executeSQLQuery xmlns:m=\"http://www.cisco.com/AXL/API/7.0\"sequence=\"" + seqNum + "\"> ";strAXLRequest += "<m:sql> ";strAXLRequest += "SELECT * FROM Device ";strAXLRequest += "</m:sql> ";strAXLRequest += "</m:executeSQLQuery> ";strAXLRequest += "</SOAP-ENV:Body> ";strAXLRequest += "</SOAP-ENV:Envelope>";strHTTPHeader = "POST /axl/ HTTP/1.1\r\n";strHTTPHeader += "Host: localhost:8443\r\n";strHTTPHeader += "Accept: text/*\r\n";strHTTPHeader += "Authorization: Basic ";strHTTPHeader += getAuthorization() + "\r\n";strHTTPHeader += "Content-type: text/xml\r\n";strHTTPHeader += "SOAPAction: \"CUCM:DB ver=7.0\"\r\n";strHTTPHeader += "Content-length: ";// temporarily use the buffer to store the length of the requestsprintf( buff, "%d", strAXLRequest.length() );strHTTPHeader += buff;strHTTPHeader += "\r\nConnection: Keep-Alive";strHTTPHeader += "\r\n\r\n";// put the HTTP header and SOAP XML togetherbuf = strHTTPHeader + strAXLRequest;return;}int main(int argc, char** argv){struct sockaddr_in saddr;SSL_METHOD *meth;SSL_CTX *sslctx;SSL *ssl;X509* server_cert;string buff,line,seqnum;char buffer[2048];int status,error;char *str;if( argc!=3 ){printf("Usage : ssltest <ip> <port> \n");printf("Usage : the default port is 8443 \n");printf("Usage : the ip is the ip of ccm5.0 \n");printf("Example: ssltest 10.77.31.168 8443 \n");exit(2);}int sock=socket(AF_INET,SOCK_STREAM,IPPROTO_TCP);if(sock<0){printf("create socket failed\n");exit(1);}saddr.sin_family=AF_INET;saddr.sin_port=htons(atoi(argv[2]));saddr.sin_addr.s_addr =inet_addr(argv[1]);status=connect(sock,(struct sockaddr *)&saddr,sizeof(saddr));if(status<0){printf("connect to %s failed\n",argv[1]);exit(2);}SSL_library_init();meth=TLSv1_client_method();sslctx=SSL_CTX_new(meth);if(!sslctx){printf("SSL_CTX_new failed\n");close(sock);exit(3);}SSL_CTX_set_verify(sslctx,SSL_VERIFY_NONE,NULL);ssl =SSL_new(sslctx);if(!ssl){printf("SSL_new failed\n");close(sock);exit(4);}status=SSL_set_fd(ssl,sock);if(!status){printf("SSL_set_fd failed\n");close(sock);exit(5);}SSL_set_mode(ssl,SSL_MODE_AUTO_RETRY);status=SSL_connect(ssl);error=SSL_get_error(ssl,status);switch(error){case SSL_ERROR_NONE:printf("connect successful\n");break;case SSL_ERROR_ZERO_RETURN:printf("peer close ssl connection \n");break;default:printf("connect error is %d\n",error);}server_cert = SSL_get_peer_certificate (ssl);if(!server_cert){printf("get server certificate failed!\n");SSL_shutdown(ssl);close(sock);exit(6);}str= X509_NAME_oneline(X509_get_subject_name (server_cert),0,0);if(str){printf("subject :%s\n",str);}elseprintf("subject is empty\n");str = X509_NAME_oneline (X509_get_issuer_name (server_cert),0,0);if(!str)printf("issuer name is :%s\n",str);elseprintf("issuer name is empty \n");line="12";seqnum="1234";BuildDeviceNameSQL(buff,line,seqnum);SSL_write(ssl,buff.c_str(),buff.length());printf("\n");printf("\n");printf("Request sent is:\n");printf(buff.c_str());printf("\n");printf("\n");SSL_read(ssl,buffer,sizeof(buffer));printf("Response from server is: \n%s\n",buffer);status=SSL_shutdown(ssl);if(status==1)printf("shutdown successful\n");elseprintf("\nshutdown error code is %d\n",status);close(sock);}Java Example
This code example uses a hard-coded AXL request and sends it to the AXL server that is running on the local system (localhost). It then reads the response and outputs the response to the screen.
import java.io.*;import java.net.*;import javax.net.ssl.*;import java.security.cert.CertificateException;import java.security.cert.X509Certificate;public class AXLJavaClient {public static void main(String[] args) {byte[] bArray = null; // buffer for reading response fromSocket socket = null; // socket to AXL serverOutputStream out = null; // output stream to serverInputStream in = null; // input stream from serverString sAXLSOAPRequest = "";// HTTPS header and SOAP payloadString sAXLRequest = null; // will hold only the SOAP payload//username=CCMAdministrator and password=cisco_ciscoString authorization = "CCMAdministrator" + ":" + "cisco_cisco";// base64 encoding of the username and passwordauthorization = new sun.misc.BASE64Encoder().encode(authorization.getBytes());// Form the http headersAXLSOAPRequest = "POST /axl/ HTTP/1.0\r\n";sAXLSOAPRequest += "Host:localhost:8443\r\n";sAXLSOAPRequest += "Authorization: Basic " + authorization + "\r\n";sAXLSOAPRequest += "Accept: text/*\r\n";sAXLSOAPRequest += "Content-type: text/xml\r\n";sAXLSOAPRequest += "SOAPAction: \"CUCM:DB ver=7.0\"\r\n";sAXLSOAPRequest += "Content-length: ";// Build the SOAP payloadsAXLRequest = "<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\" ";sAXLRequest += "xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"> ";sAXLRequest += "<SOAP-ENV:Body> <axl:getPhone xmlns:axl=\"http://www.cisco.com/AXL/7.0\" ";sAXLRequest += " xsi:schemaLocation=\"http://www.cisco.com/AXL/7.0 http:// ccmserver/schema/axlsoap.xsd\" ";sAXLRequest += "sequence=\"1234\"> <phoneName>SEP000000000009</phoneName>";sAXLRequest += "</axl:getPhone> </SOAP-ENV:Body> </SOAP-ENV:Envelope>";// finish the HTTPS HeadersAXLSOAPRequest += sAXLRequest.length();sAXLSOAPRequest += "\r\n\r\n";// now add the SOAP payload to the HTTPS header, which completes the AXL// SOAP requestsAXLSOAPRequest += sAXLRequest;try {AXLJavaClient axl = new AXLJavaClient();// Implement the certificate-related stuffs required for sending request via httpsX509TrustManager xtm = axl.new MyTrustManager();TrustManager[] mytm = { xtm };SSLContext ctx = SSLContext.getInstance("SSL");ctx.init(null, mytm, null);SSLSocketFactory sslFact = (SSLSocketFactory) ctx.getSocketFactory();socket = (SSLSocket) sslFact.createSocket("10.77.31.203", Integer.parseInt("8443"));in = socket.getInputStream();// send the request to the server// read the response from the serverStringBuffer sb = new StringBuffer(2048);bArray = new byte[2048];int ch = 0;int sum = 0;out = socket.getOutputStream();out.write(sAXLSOAPRequest.getBytes());while ((ch = in.read(bArray)) != -1) {sum += ch;sb.append(new String(bArray, 0, ch));}socket.close();// output the response to the standard outputSystem.out.println(sb.toString());} catch (UnknownHostException e) {System.err.println("Error connecting to host: " + e.getMessage());return;} catch (IOException ioe) {System.err.println("Error sending/receiving from server: " + ioe.getMessage());// close the socket} catch (Exception ea) {System.err.println("Unknown exception " + ea.getMessage());return;}finally{try {if (socket != null)socket.close();} catch (Exception exc) {exc.printStackTrace();System.err.println("Error closing connection to server: "+ exc.getMessage());}}}public class MyTrustManager implements X509TrustManager {MyTrustManager() {// create/load keystore}public void checkClientTrusted(X509Certificate chain[], String authType)throws CertificateException {}public void checkServerTrusted(X509Certificate chain[], String authType)throws CertificateException {}public X509Certificate[] getAcceptedIssuers() {return null;In addition to these examples, refer to the AXL SQL Toolkit, which is available for download from the Cisco Unified Communications Manager server at https://ccmserver:8443/plugins/axlsqltoolkit.zip.
Using executeSQLUpdate
This example illustrates the use of the executeSQLUpdate request:
POST :8443/axl/Host: axl.myhost.com:8443Accept: text/*Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==Content-type: text/xmlSOAPAction: "CUCM:DB ver=7.0"Content-length: 613<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Body><axlapi:executeSQLUpdate sequence="1" xmlns:axlapi="http://www.cisco.com/AXL/API/7.0" xmlns:axl="http://www.cisco.com/AXL/7.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.cisco.com/AXL/API/7.0 axlsoap.xsd"><sql>insert into device (fkPhoneTemplate,fkDevicePool,tkclass, tkpreemption, tkdeviceprofile, tkmodel, tkdeviceprotocol, tkproduct, description, tkstatus_mlppindicationstatus, name, pkid) values ('Standard 7941 SCCP','default',1, 2, 2, 115, 0, 115, '', 0, 'Cisco 7941', newid())</sql></axlapi:executeSQLUpdate></SOAP-ENV:Body></SOAP-ENV:Envelope>Using executeSQLQuery
This example illustrates the use of the executeSQLQuery request:
POST :8443/axl/Host: axl.myhost.com:8443Accept: text/*Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==Content-type: text/xmlSOAPAction: "CUCM:DB ver=7.0"Content-length: 613<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Body><axlapi:executeSQLQuery sequence="1" xmlns:axlapi="http://www.cisco.com/AXL/API/7.0" xmlns:axl="http://www.cisco.com/AXL/API/7.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.cisco.com/AXL/API/7.0 axlsoap.xsd"><sql>SELECT * from numplan</sql></axlapi:executeSQLQuery></SOAP-ENV:Body></SOAP-ENV:Envelope>AXL Error Codes
If an exception occurs on the server, or if any other error occurs during the processing of an AXL request, the system returns an error in the form of a SOAP Fault message. For example:
<SOAP-ENV:Envelope xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><SOAP-ENV:Fault><faultcode>SOAP-ENV:Client</faultcode><faultstring>Device not found with name SEP003094C39708.</faultstring><detail xmlns:axl="http://www.cisco.com/AXL/7.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.cisco.com/AXL/API/7.0http://myhost/CCMApi/AXL/V1/axlsoap.xsd"><axl:error sequence="1234"><code>0</code><message><![CDATA[Device not found with name SEP003094C39708.]]></message><request>doDeviceLogin</request></axl:error></detail></SOAP-ENV:Fault></SOAP-ENV:Body></SOAP-ENV:Envelope>SOAP Fault messages can also contain more detailed information. The following example depicts a detailed SOAP Fault:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><SOAP-ENV:Body><SOAP-ENV:Fault><faultcode>SOAP-ENV:Client</faultcode><faultstring>Device not found with name SEP003094C39708.</faultstring><detail xmlns:axl="http://www.cisco.com/AXL/7.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.cisco.com/AXL/7.0http://myhost/CCMApi/AXL/V1/axlsoap.xsd"><axl:error sequence="1234"><code>0</code><message><![CDATA[Device not found with name SEP003094C39708.]]></message><request>doDeviceLogin</request></axl:error></detail></SOAP-ENV:Fault></SOAP-ENV:Body></SOAP-ENV:Envelope>The <detail> element of a SOAP Fault includes error codes. The axl:Error elements represent the errors. If a response to a request contains an <error> element, the user agent can determine the cause of the error by looking at the subelements of the <error> tag.
The user agent uses the <code> element, a numerical value, to find what type of error occurred.
The following table explains the error codes that the <code> tag might have:
message
The system provides the <message> element, so the user agent gets a detailed error message that explains the error.
request
The system provides the <request> element, so the user agent can determine the type of request that generated this error. Because this element is optional, it may not always appear.
