Feedback
Table Of Contents
AXL APIs Added for Cisco Unified Communications Manager 6.0(1)
AXL APIs Changed for Cisco Unified Communications Manager 6.0(1)
Service Parameters Added or Changed
AXL APIs Added for Cisco Unified Communications Manager 5.1(1)
Integration Considerations and Interoperability
Impact on Backward Compatibility
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
AXL Configuration Programming
The Administrative XML Layer (AXL) Application Programming Interface (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 allows a programmer to access the database by using XML and receive the data in XML form, instead of 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. Users perform requests by sending XML data to the Cisco Unified Communications Manager server. The server then returns the AXL response, which is also a SOAP message.
The AXL-SOAP web service is enabled by default on all Cisco Unified Communications Manager servers. It requires no other installation or configuration.
To access all AXL SOAP API downloads and AXL requests and responses that are found in this chapter, refer to http://www.cisco.com/cgi-bin/dev_support/access_level/product_support.
This chapter assumes the developer has knowledge of a high-level programming language such as C++, Java, or an equivalent language.
Developers must also have knowledge or experience in the following areas:
•
TCP/IP Protocol
•
•
•
Tip
For more information on XML Schema, refer to http://www.w3.org/TR/xmlschema-0/.
For more information on XML syntax/grammar, refer to http://www.w3.org/TR/rdf-syntax-grammar/.
Caution
This chapter contains the following sections:
•
•
•
•
•
New and Changed Information
Release 6.0(1) makes the following major changes in the AXL APIs for :
•
•
–
–
–
•
•
•
•
•
•
AXL Versioning Support
To improve backward compatibility, Cisco Unified Communications Manager Release 6.0(1) introduces AXL schema versioning. The system duplicates the previous AXL 1.0 schema as the AXL 6.0(1) schema, and, in upcoming releases, the AXL schema will be numbered the same as the corresponding Cisco Unified Communications Manager release. This approach maintains AXL backward compatibility for one full release cycle.
Developers have the option in Cisco Unified Communications Manager Release 6.0(1) to request a specific AXL schema version (either 1.0 or 6.0(1)); however, both these schema versions are identical. If a specific schema version is not requested, the AXL 1.0/6.0(1) schema automatically gets used and an appropriate response gets returned, which will have no backward compatibility issues for several releases.
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 updateSQLquery, changes have occurred to the Cisco Unified Communications Manager 6.0(1) database schema that affect the direct SQL query approach. Refer to the Cisco Unified Communications Manager Database Dictionary, Release 6.0(1), which describes the specific changes in the database schema.
To help developers plan for AXL versioning, Table 1-1 provides the approach that Cisco will follow in supporting upcoming releases.
•
•
The following a sample AXL request carries version information:
POST /axl/ HTTP/1.0Host:10.77.31.194:8443Authorization: Basic Q0NNQWRtaW5pc3RyYXRvcjpjaXNjb19jaXNjbw==Accept: text/*Content-type: text/xmlSOAPAction: "CUCM:DB ver=6.0"Content-length: 427<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:getUser xmlns:axl="http://www.cisco.com/AXL/1.0" xsi:schemaLocation="http://www.cisco.com/AXL/1.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=950805DE5E10F32C5788AE164EEC4955; Path=/Set-Cookie: JSESSIONID=151CF94ACF20728B1D47CC5C3BECC401; Path=/axl; SecureSOAPAction: "CUCM:DB ver=6.0"Content-Type: text/xml;charset=utf-8Content-Length: 728Date: Mon, 22 Jan 2007 06:51:42 GMTConnection: closeAXL APIs Added for Cisco Unified Communications Manager 6.0(1)
The following list provides AXL API calls that are new in 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.
AXL APIs Changed for Cisco Unified Communications Manager 6.0(1)
The following AXL API calls changed since the previous release. These changes might require changes to existing user code that is making use of them:
•
•
•
•
•
•
•
•
•
•
•
–
–
•
–
–
•
–
–
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
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.
Service Parameters Added or Changed
The Cisco Unified Communications Manager 6.0(1) release 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.
The Cisco Unified Communications Manager 5.1(1) release 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.
AXL APIs Added for Cisco Unified Communications Manager 5.1(1)
The following list provides AXL API calls that were added in Release 5.1(1):
•
•
•
•
These APIs add and update credentials (passwordreserve) in siprealm.
AXL API
Request methods represent XML structures that are passed to the AXL API server. The server receives the XML structures and executes the request. If the request completes successfully, the system returns the appropriate AXL response. All responses get 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 gets returned wrapped inside a SOAP Fault structure (see the "AXL Error Codes" section).
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.
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:
<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><![CDATA[An error occurred during parsingMessage: End element was missing the character '>'.Source = Line : 41, Char : 6Code : c00ce55f, Source Text : </re]]></faultstring></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/1.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.cisco.com/AXL/1.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 following list describes the <error> elements:ws The user agent uses the <code> element, a numerical value, to find what type of error occurred.
The error codes follow:
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.
Example AXL Requests
No platform considerations exist in Cisco Unified Communications Manager Release 6.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=6.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=6.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/1.0" xsi:schemaLocation="http://www.cisco.com/AXL/1.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/1.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=6.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=6.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/1.0\" ";sAXLRequest += " xsi:schemaLocation=\"http://www.cisco.com/AXL/1.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 executeSQLUpdateAXL
This example illustrates the use of the executeSQLUpdateAXL request:
POST :8443/axl/Host: axl.myhost.com:8443Accept: text/*Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==Content-type: text/xmlSOAPAction: "CUCM:DB ver=6.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/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 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=6.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/1.0" xmlns:axl="http://www.cisco.com/AXL/API/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.cisco.com/AXL/API/1.0 axlsoap.xsd"><sql>SELECT * from numplan</sql></axlapi:executeSQLQuery></SOAP-ENV:Body></SOAP-ENV:Envelope>Throttling of Requests
The side effects of updating the Cisco Unified Communications Manager database can adversely affect system performance; therefore, the system administrator can control how many AXL requests are allowed to update the database per minute. You can control this value by using the Database Layer Monitor advanced service parameter "MaxAXLWritesPerMinute."
AXL accommodates all requests until the "MaxAXLWritesPerMinute" value is reached. The system rejects subsequent attempts to modify the database with AXL by sending an HTTPS 503 Service Unavailable response. Every minute, AXL resets its internal counter and begins to accept AXL update requests until the limit is reached again.
The following AXL requests, which are considered "Reads," do not count against the preset "MaxAXLWritesPerMinute" service parameter value. All other AXL requests that are not in the following list count against the service parameter value:
•
•
•
•
The execSQLUpdate request is throttled.
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 and 6.0.
You can obtain complete documentation of all available AXL messages from the Cisco Developer Services web site: http://www.cisco.com/cgi-bin/dev_support/access_level/product_support. This website requires a Cisco.com login.
From the Cisco Unified Communications Manager server administration interface, you can use the Application > Plugins > Cisco Unified Communications Manager AXL SQL Toolkit command to obtain
•
See also AXL Schema Documentation.
•
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.
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.
If AXL is determined to be using too much CPU time, consider lowering the Database Layer Monitor advanced service parameter MaxAXLWritesPerMinute (see the "Throttling of Requests" section). If this does not solve the problem, consider employing an additional server to be used only by applications that are using AXL.
Note
Impact on Backward Compatibility
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. Necessary changes in the Cisco Unified Communications Manager 6.0(1) database schema make this true.
•
•
Note
•
1.
2.
•
For further details about the Cisco Unified Communications Manager database schema changes, refer to the Cisco Unified Communications Manager Data Dictionary for Release 6.0(1).
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://system-name:port/axl/ (port is 8443).
•
Step 2
•
•
Step 3
Step 4
1.
For instance, enter https://system-name:8443/axl/ in the address text box.
2.
3.
This verifies functionality and user access.
Step 5
•
•
•
Step 6
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/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 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/1.0 xmlns:xsi="http://www.cisco.com/AXL/1.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
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, such as in the following 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><![CDATA[An error occurred during parsingMessage: End element was missing the character '>'.Source = Line : 41, Char : 6Code : c00ce55f, Source Text : </re]]></faultstring></SOAP-ENV:Fault></SOAP-ENV:Body></SOAP-ENV:Envelope>SOAP Fault messages can also contain more detailed information. The following example shows a detailed SOAP Fault message:
<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/1.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.cisco.com/AXL/1.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 contains the error codes. The <axl:Error> element represents 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 following list describes the <error> element.
•
•
•
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._6_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._6_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 Cisco Unified Communication Manager database, the original WSDL that was sent out for that Cisco Unified Communication Manager 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/6.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/6.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/6.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=6.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.
