NAV
Sample Code

Administrative XML (AXL) Developer Guide v10.5(1)

Overview

Administrative XML (AXL) is a powerful provisioning API to extend the Cisco Unified Communications Manager 10.5 (Unified CM). It can help businesses leverage their services to users by automating everyday communications tasks. The AXL API provides a mechanism for programmers to make several types of changes to the Cisco Unified CM Database using XML and the SOAP interface.

AXL is a provisioning and configuration API, not a real-time API. Beware that an attempt to make too many AXL requests in quick succession could be throttled. See Data Throttling and Performance.

Examples of AXL operations include:

AXL API methods, known as requests, use a combination of HTTPS and SOAP. Users perform requests by sending XML data to the Unified CM Publisher server. If the request completes successfully, the system returns the appropriate AXL response. All responses are named the same as associated requests, except the word Response is appended. For example, the XML response returned from an addPhone request is named addPhoneResponse.

Developers must 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 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/.

AXL service is now enabled by default on all nodes (Publisher and Subscribers.) It is recommended that developers always use AXL on the Publisher.

Note. The AXL API allows you to modify the Unified CM system database. Be careful not to delete or change objects unintentionally. AXL should not be used as a real-time API.

AXL Compliance

The Unified CM AXL implementation complies with XML Schema 1.0

The Unified CM AXL implementation also complies with SOAP 1.1 and HTTPS 1.1 as defined by the World Wide Web Consortium http://www.w3.org/. The AXL API runs as an independent service and can only be accessed via HTTPS.

Cisco Product Security Overview

This product contains cryptographic features and is subject to United States and local country laws governing import, export, transfer, and use.

Note: Delivery of Cisco cryptographic products does not imply third-party authority to import, export, distribute, or use encryption. Importers, exporters, distributors, and users are responsible for compliance with U.S. and local country laws. By using this product you agree to comply with applicable laws and regulations. If you are unable to comply with U.S. and local laws, return this product immediately.

A summary of U.S. laws governing Cisco cryptographic products may be found at: http://www.cisco.com/wwl/export/crypto/tool/stqrg.html. If you need further assistance, contact us by sending e-mail to export@cisco.com.

AXL Tutorials

For a tutuorial on AXL and PHP, see AXL PHP Primer.

For a tutuorial on AXL and PHP with Client Matter Codes (CMC) and Forced Authorization Codes (FAC), see Manage CMC and FAC with PHP and AXL.

Development Guidelines

Compatibility

Cisco Technology Developer Program member applications must be retested and updated with each new major release of Cisco Unified CM to ensure compatibility.

Recommendations for Developers

The following are recommendations for developers to reduce the number and extent of updates.

New and Changed Information

This section provides New and Changed Information for the Unified CM AXL Interface:

New and Changed Information for Unified CM Release 10.5(1)

AXL Versioning Policy

The versioning mechanism now supports three major releases of schemas to provide additional upgrade flexibility. For example, Unified CM release 10 supports AXL schemas 8.x, 9.x, and 10.x, while the 7.x schema is no longer available. Each major and minor release will include a new schema. Maintenance releases never include new schemas. Old schemas will be deprecated in the first release of each new major version, for example Release 7.0(1). Read the details here.

Change Notification Feature

Administrative XML (AXL) Clients depend on Cisco Unified CM data to work correctly. The AXL Change Notification Feature (CNF) is designed to help keep AXL applications informed when dependent data changes occur. Learn how to add Change Notification to your application here.

New Operations and Features

Apply, Reset, and Restart API Operations

Note: Reset operations should be used with extreme caution, especially when applied to device pools, where large numbers of users can be impacted. Resetting a device makes it unavailable to the user until the operation is completed, since it interrupts service and shuts down the device or service entirely. Applying changes to device pools or several concurrent users simultaneously should only be managed at scheduled maintenance periods.

getOptionsList

getOptionsList allows interrogation of devices to determine valid options for that device. SipProfileOptions, TransPatternOptions, LineOptions, PhoneOptions, and DeviceProfileOptions were provided as additional tools to help developers solve performance issues.

wipePhone

wipePhone allows Cisco’s newer Android-based devices like the Cisco DX650 to be remotely reset to factory defaults, removing user specific settings and data. This API is typically used when device ownership changes or when device access is compromised.

View a complete list of New APIs.

View a complete list of Changed APIs.

New APIs

For a complete list of the AXL APIs and the versions of Cisco Unified Communications Manager in which they appear see the Operations by Release Matrix

New APIs in Unified CM Release 10.5(1)

API Operation Added Tags
LicensedUser get name, uuid, returnedTags

Changed APIs

For a complete list of the AXL APIs and the versions of Cisco Unified Communications Manager in which they appear see the Operations by Release Matrix.

Changed APIs in Unified CM Release 10.5(1)

API New Tags Deprecated Tags
SipProfile (SIPProfile pre 8.0) earlyOfferSuppVoiceCall earlyOfferSupportForVoiceCall

Versioning

The AXL interface supports multiple AXL schema versions which provide an abstraction layer between AXL Applications and the Unified CM database. Use of AXL Versioning enables developers to support multiple Unified CM releases and maintain backward compatibility during customer upgrades.

Developers can specify the schema that they wish to use in the SOAP Action Header of the request. If a schema version is not specified, the oldest supported schema will be used. The AXL versioning guidelines are illustrated in the following table and explained below.

AXL Request with Version Specified

No Version Specified in Request CUCM:DB ver=10.0 CUCM:DB ver=9.1 CUCM:DB ver=9.0 CUCM:DB ver=8.5 CUCM:DB ver=8.0 CUCM:DB ver=7.1
Release 10.5(1) 8.0 schema applied 10.0 schema applied 9.1 schema applied 9.0 schema applied 8.5 schema applied 8.0 schema applied
Release 10.0(1) 8.0 schema applied 10.0 schema applied 9.1 schema applied 9.0 schema applied 8.5 schema applied 8.0 schema applied
Release 9.1(1) 7.1 schema applied 9.1 schema applied 9.0 schema applied 8.5 schema applied 8.0 schema applied 7.1 schema applied
Release 9.0(1) 7.1 schema applied 9.0 schema applied 8.5 schema applied 8.0 schema applied 7.1 schema applied
Release 8.5(1) 7.0 schema applied 8.5 schema applied 8.0 schema applied 7.1 schema applied
Release 8.0(1) 6.1 schema applied 8.0 schema applied 7.1 schema applied
Release 7.1(2) 6.0 schema applied 7.1 schema applied

Release 8.6(x) did not include a new schema. Developers should use the 8.5 schema with Release 8.6(x). All new 8.6 database objects have been added to the 9.0 schema in Release 9.0(1).

AXL Guidelines (beginning with Unified CM 10.0)

AXL Guidelines (Unified CM 6.x through 9.x)

Sample AXL Request

The sample AXL request (in the right-hand panel) shows how to use the SOAPAction Header to specify the schema version.

The SoapAction header (SOAPAction: “CUCM:DB ver=8.5 getPhone”) specifies that the request uses the 8.5 AXL Schema and the getPhone API resource.

soapenv:Envelope xmlns:soapenv=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns=“http://www.cisco.com/AXL/API/8.5
specifies that the request uses the 8.5 AXL schema namespace.

The getPhone element from the specified namespace is used to specify the specific device used in this request.

Sample AXL Request:

Host:10.77.31.194:8443

Authorization: Basic Q0NNQWRtaW5pc3RyYXRvcjpjaXNjb19jaXNjbw==

Accept: text/*

Content-type: text/xml

SOAPAction: "CUCM:DB ver=8.5 getPhone”

Content-length: 427 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.cisco.com/AXL/API/8.5">
   <soapenv:Header />
   <soapenv:Body>
      <ns:getPhone sequence="?">
         <name>SEPE8B7480316D6</name>
      </ns:getPhone>
   </soapenv:Body>
</soapenv:Envelope>

Next Steps

View the Latest Schema

Hello World

<!--Java Example-->  
// Here is a Java example of how to use the getPhone API call

import java.io.*;
import java.net.*;

public class AXLSample {
    public static void main(String[] args) throws Exception {
        //AXL service URL on UC Manager host ds-ucm851.cisco.com
        //Note this sample assumes the certificate for the host with subject
        //name 'host.com' has been imported into the Java keystore
        URL url = new URL("https://host.com:8443/axl/");
        //Create a java.net URLConnection object to make the HTTP request
        URLConnection conn = url.openConnection();
        //setDoOutput=true causes the URLConnection to perform a POST operation
        conn.setDoOutput(true);
        //HTTP Basic authorization string - a base64 encoded string with username:password, in this case 'Administrator:cisco!123'
        //This should be a UCM application user with Standard CCM Admin User and Standard AXL API Access roles
        String authorization = "QWRtaW5pc3RyYXRvcjpjaXNjbyExMjM=";
        conn.setRequestProperty("Authorization","Basic " + authorization);
        //Set the SOAPAction header to 'CUCM:DB ver=8.5' for use with a UCM 8.5(1) host, request is 'getPhone'
        conn.setRequestProperty("SOAPAction","\"CUCM:DB ver=8.5 getPhone\"");
        //The request body will be in XML format
        conn.setRequestProperty("Content-Type","text/xml");

        //Build a string containing the contents of the AXL XML request - here 'getPhone'
        String AXLRequest = "&lt;soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:ns=\"http://www.cisco.com/AXL/API/8.5\"&gt;";
        AXLRequest += "&lt;soapenv:Body&gt;&lt;ns:getPhone&gt;&lt;name&gt;SEP001B0CDBBE33&lt;/name&gt;&lt;/ns:getPhone&gt;&lt;/SOAP-ENV:Envelope&gt;";

        //Create an OutputStreamWriter for the URLConnection object and make the request
        OutputStreamWriter writer = new OutputStreamWriter(conn.getOutputStream());
        writer.write(AXLRequest);
        writer.flush();

        //Read the response
        BufferedReader reader = new BufferedReader(new InputStreamReader(conn.getInputStream()));

        //Output the response to the console
        String line;
        while ((line = reader.readLine()) != null) {
            System.out.println(line);
        }

        //Cleanup the stream objects
        writer.close();
        reader.close();
    }
}

To get started with using AXL, lets look at an API request for a simple example. The example scenario obtains information for a particular phone. For this task, make the getPhone API request to the CUCM Publisher.

Java Example

Refer to the Java example in the right-hand panel.

Refer to How to Create an AXL Client in JAVA with JAX-WS to learn how to setup a Java application.

CURL Example

Refer to How to Run AXL with CURL to get started with another AXL Web Services Hello World example.

Authentication

Overview

AXL limits access to its services through HTTP 1.0 Basic Access Authentication. It is a transaction scheme described in RFC 2617. The advantage of HTTP Basic Access Authentication is that it’s simple to implement. It uses only standard HTTP headers and, when using a Web browser, the browser implements and manages the login dialog.

Using Basic Authentication

HTTP Basic Access Authentication requires authorization credentials in the form of a user name and password before granting access to a specific URL. The client application can obtain the user name and password through a challenge dialog or it can use previously stored values. The user name and password are passed as Base64 encoded text in the header of a subsequent HTTP transaction.

The text to Base64 encode should be: “username:password” (without the quotes, but note the colon separating username and password). The header entry would then look similar to the line below, where “YXhsVXNlcjpjaXNjbw==” is the result of Base64 encoding of the “username:password”:

Authorization: Basic YXhsVXNlcjpjaXNjbw==

All AXL API requests require authentication for access. Use an end user account created by the CUCM administrator to make API calls that require authentication.

Service Activation and User/Group management is handled in Communications Manager Serviceability. Make sure the AXL services status is started:

AXL services started in Communications Manager

Create a dedicated user for AXL Access:

Dedicated User

Security considerations for AXL authorization:

Security

Cisco requires that all AXL transactions be conducted over a secure session, such as HTTPS. Any non-HTTPS requests will be redirected to the HTTPS port.

Depending on the connection technology used, you may need to manually install the Unified Communication Manager’s self-signed certificate into a local trust store for your application.

Authentication Best Practices

The client application must maintain the session by supplying a session cookie that the server sends when it makes subsequent requests. If the client fails to do so, it may receive a HTTP 503 Service Unavailable response to some of its requests.

Client sessions authenticating with AXL are given the JSESSIONID cookies.

A developer should configure the client to properly handle sessions. In most HTTP libraries, this is simple and usually involves only a few lines of code.

Data Throttling and Performance

The developer can make powerful modifications of the Unified CM System database using the AXL API. Caution should always be observed during implementation since every API call impacts the system. Requesting large amounts of data or performing multiple write operations may trigger the interface throttle to return an exception. The throttle protects system resources to ensure calls are processed before XML requests.

AXL acts as a provisioning and configuration API, not as a real-time API.

The AXL interface provides developers with two ways of accessing database objects:

The AXL service dynamically throttles write requests (add, update, and remove requests, and ExecuteSQLUpdate) based on the current size of the Unified CM database transaction queue. Note that the Unified CM database transaction queue can contain pending updates arising from recent administrative actions, bulk administration tasks, and other AXL applications. If the database transaction queue is too large, AXL may reject new write requests with a 503: Service Unavailable error message. In such cases, applications may retry rejected requests. However, retries should be attempted after a reasonable delay, for example several seconds.

Read requests are also dynamically throttled based on the size of the data set to be returned. Large queries issued using the List <object> and ExecuteSQLQuery methods that result in a data set greater than 8 MB will return Query request too large. Total rows matched: <Matched Rows>. Suggested row fetch: less than <Number of Rows>.

Cisco recommends developers using the ExecuteSQLQuery method follow these guidelines:

Note: Because AXL is not a real-time API, the auto-logout function of Extension Mobility (EM) does not work when the user is logged in or out of EM via the AXL interface.

Using JSESSIONID to Improve Performance

One way to streamline the performance of multiple sequential AXL operations is to reuse the JSESSIONID returned with the first request. This allows you to use a single HTTP session to Tomcat for making multiple AXL requests.

Here’s how it works. When you perform an AXL SOAP operation, it returns a JSESSIONID in the header as a cookie. For example (with the following all on one line):

Set-Cookie: JSESSIONID=3FC45B4CA24651208412AA73C162F164; Path=/axl/; Secure; HttpOnly

In order to continue to use the same HTTP connection to AXL instead of opening a new connection for each subsequent request, you should return the same JSESSIONID in a cookie header with the next request. As you continue using the same JSESSIONID, Tomcat will continue to use the same session, thus reducing the stress on the server when compared to opening new Tomcat sessions with every request.

The JSESSIONID has a default timeout of 30 minutes in Tomcat, but the timeout clock only starts ticking when the connection is idle. You could theoretically continue to use the same JSESSIONID indefinitely, or at least until you stop performing requests with that particular JSESSIONID for 30 minutes. If your JSESSIONID-based connection is idle for more than 30 minutes, make a new request without specifying a JSESSIONID. This new request should return a new JSESSIONID.

Below are some example request and response pairs that show what to expect in different throttling scenarios.

Scenario 1 

<!--Scenario 1 Request-->  
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.cisco.com/AXL/API/10.0">
   <soapenv:Header />
   <soapenv:Body>
      <ns:executeSQLQuery sequence="?">
         <sql>select * from enduser, device</sql>
      </ns:executeSQLQuery>
   </soapenv:Body>
</soapenv:Envelope>

<!--Scenario 1 Response-->  
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode>soapenv:Server</faultcode>
         <faultstring>Query request too large. Total rows matched: 2816 rows. Suggestive Row Fetch: less than 844 rows</faultstring>
         <detail>
            <axlError>
               <axlcode>-1</axlcode>
               <axlmessage>Query request too large. Total rows matched: 2816 rows. Suggestive Row Fetch: less than 844 rows</axlmessage>
               <request>executeSQLQuery</request>
            </axlError>
         </detail>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

Scenario 1
An AXL query request that tries to fetch more than 8 MB of data

Scenario 2 

<!--Scenario 2 Request: Too many concurrent ExecuteSQLQuery requests-->  
<!--Request (repeated 3 times at the same time)-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.cisco.com/AXL/API/10.0">
   <soapenv:Header />
   <soapenv:Body>
      <ns:executeSQLQuery sequence="?">
         <sql>select first 999 * from device, enduser</sql>
      </ns:executeSQLQuery>
   </soapenv:Body>
</soapenv:Envelope>

<!--Scenario 2 Response: Two requests are processed. The third request gives an error response.-->  
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <soapenv:Fault>
         <faultcode>soapenv:Server</faultcode>
         <faultstring>Maximum AXL Memory Allocation Consumed. Please retry once requests in progress have completed</faultstring>
         <detail>
            <axlError>
               <axlcode>-1</axlcode>
               <axlmessage>Maximum AXL Memory Allocation Consumed. Please retry once requests in progress have completed</axlmessage>
               <request>executeSQLQuery</request>
            </axlError>
         </detail>
      </soapenv:Fault>
   </soapenv:Body>
</soapenv:Envelope>

Scenario 2
Too many concurrent ExecuteSQLQuery requests

Sample Code