Overview

Administrative XML (AXL) is a powerful provisioning API to extend the Cisco Unified Communications Manager 11.0 (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:

• add data
• apply data
• get data
• list data
• lockPhone
• remove data
• reset devices
• restart devices
• update data
• wipePhone

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:

• TCP/IP Protocol
  
• Hypertext Transport Protocol, specifically HTTPS
  
• Socket programming
  
• XML
  
• SOAP

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.

Development Guidelines

Recommendations for Developers

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

• Developers should never depend on the order of events or messages. The order of events and/or messages may change. For example:
  • For a feature invocation involving two or more independent transactions, the events or messages may be interleaved.
  • In such cases, events related to the second transaction may precede messages related to the first.
  • Events or messages may be delayed due to situations beyond control of the interface, for example network or transport failures.
  • Applications should be able to recover from out-of-order events or messages, even when the order is required for protocol operation.
    
• Developers must avoid unnecessary dependence on the order of elements to interpret information. The order of elements within the interface event or message may change, within the constraints of the protocol specification.
• Developers must disregard or provide generic treatments for any unknown elements or unknown values of known elements encountered. New interface events, methods, responses, headers, parameters, attributes, other elements, or new values of existing elements may be introduced.
  
• Previous interface events, methods, responses, headers, parameters, attributes, and other elements will remain and maintain their previous stated meaning and behavior in every way possible. They will remain consistent even when defects with them need to be corrected.
  
• Applications must never be dependent on interface behavior resulting from defects. That is, not consistent with the published interface specifications. Application behavior might change when a defect is fixed.
  
• Remove deprecated methods, handlers, events, responses, headers, parameters, attributes, or other elements from applications as soon as possible to avoid issues when those deprecated items are removed from Cisco Unified CM.
  
• Application developers must be aware that not all new features or new supported devices will be forward compatible. New features and devices (for example, phones) may require application modifications to work properly.

New and Changed Information

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

• New and Change Information for Unified CM 11.5(1)
• New and Changed Information for Unified CM 11.0(1)
• New and Changed Information for Unified CM 10.5(1)
• New and Changed Information for Unified CM 10.0(1)
  
• New and Changed Information for Unified CM 9.1(1)
• New and Changed Information for Unified CM 9.0(1)
• New and Changed Information for Unified CM 8.6(1)
  

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 and Changed Information for Unified CM Release 11.5(1)

New Features:

• AXL Read-Only Role

The AXL user can now be assigned a read-only role, allowing the application to read (but not add/update/remove) AXL data. Refer to AXL Authentication for more details.

• User Rank access control support

CUCM can be configured by the administrator to control the ability of users, including AXL API users, to access or update certain CUCM data, via the User Rank feature. The CUCM user account used by an application to authenticate to AXL is also subject to the access control restrictions of the User Rank feature, which may affect certain types of AXL requests. See User Rank Interactions for more details.

• 11.5 schema added

• New APIs

• Changed APIs

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

• 11.0 schema added
• New APIs
  

• Changed APIs

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

• 10.5 schema added
  
• New API LicensedUser added.
  

• Existing SipProfile API, from 10.0(1), changed.

AXL Versioning Policy for Unified CM Release 10.5(1)

The versioning mechanism 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 for Unified CM Release 10.5(1)

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 for Unified CM Release 10.5(1)

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.

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.

See the AXL vs. CUCM version compatibility matrix for details.

Sample AXL 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

The sample AXL request (in the right-hand panel) shows how to use the SOAPAction Header to specify the schema version. The sample shows the typical required HTTP headers (above) and the XML content in the HTTP body (below.)

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.

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

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.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 AXL API access permissions
        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 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 a getPhone API request to the CUCM Publisher.

Refer to the Java example in the right-hand panel for how to use the getPhone API.

Authentication

Refer to AXL Authentication.

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:

• Standard methods which provide backward compatibility between releases, such as GetUser
  
• Direct access through the ExecuteSQLQuery and ExecuteSQLUpdate methods, which do not provide backward compatibility.
  

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:

• Applications should break up all SQL queries so that the data returned is always less than 8 MB
• Use the Unified CM Data Dictionary to help determine the maximum allowable size of any field in the database
• ASCII characters are stored as 1-byte
• i18n characters (UTF-8) are stored as 3-bytes
• DB has a mix of ASCII and UTF-8 characters
• While Unified CM is processing a large query, concurrent queries should not result in data sets larger than 2 MB
• Applications should wait to receive a response before issuing subsequent queries
• Applications should not submit duplicate queries
  

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 (via HTTP 1.1 persistent connection) 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, AXL will continue to use the same session, thus reducing the stress on the server when compared to opening new AXL sessions with every request.

Note: you can re-use the AXL authentication session via JSESSIONID either within the same HTTP persistent connection session, or in separate HTTP connection requests

The JSESSIONID has a default timeout of 30 minutes in AXL, 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

Data Change Notification

Overview

Administrative XML (AXL) clients may be dependent upon up-to-date Unified Cisco CM data to function properly. While apps can periodically request updated data from CUCM via AXL in a pull/polling model, the AXL Change Notification Feature (CNF) is designed to help keep AXL applications informed when CUCM data changes via a more push/notification-type mechanism. This section is intended to show AXL Developers how to add change notification functionality to their applications. Change notification features are applicable to Cisco Unified CM 10.0 and above.

How It Works

AXL will record changes for objects exposed within the AXL interface into an internal tracking cache. CUCM database changes are 'transformed', as they occur, from the raw table/column update data to their corresponding AXL object names, and a summary of the type of change (e.g. add, update, remove) is then stored in the cache. The AXL client can then periodically retrieve the list of change summaries by calling the listChange interface which returns all of the changes in the cache.

If an application is interested in the full details of a particular change, it may be necessary to perform the corresponding <getXXX> request on the specific changed object. For example, if a change response indicates a change type of phone and action of u the application may want to perform a <getPhone> request to ensure it has the latest, complete details for the device in question.

Details

Sample First Request

sample first request

<!--sample first 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:listChange>
            <objectList> (optional)
                <object>Phone</object>
                <object>User</object>
            </objectList>
        </ns:listChange>
    </soapenv:Body>
</soapenv:Envelope>

Refer to the right hand panel for a sample of a first request.

The first time the client calls the listChange API, AXL returns all of the change notifications in the cache. AXL clients interested in changes for a specific set of objects should always specify the objectList. Use of the objectList tailors the response and reduces the overall load on the Publisher. There is no limit to the number of objects which can be specified in the objectList. If the objectList is not specified, AXL will return the list of changes for all objects in the cache.

Sample First Response

sample response

<!--sample response-->
<queueInfo>
    <firstChangeId>154</firstChangeId>
    <lastChangeId>10000</lastChangeId>
    <nextStartChangeId>10001</nextStartChangeId>
    <queueId>093249823498</queueId>
</queueInfo>
<changes>
    <change type='physicalLocation' >uuid='8h58f047-7b40-4547-a8c2-fc5b2b668b7f'>                      
        <id>1</id>
        <action>u</action>
        <doGet>false</doGet>
        <changedTags>
            <changedTag name='description'>A__V3.Dx.3 w_p6.</changedTag>
        </changedTags>
    </change>
</changes>

The sample response in the right hand panel shows AXL returned changes 1 to 10,000. The client is expected to ask for change 10,001 the next time it makes a request. Additionally, the queueID must also be submitted. queueID helps the client detect if changes may have been lost between sync intervals. Note that changes 2-10,000 are not shown in this example.

Each time a client calls listChange, the response contains two sections. The first section is called queueInfo which contains: firstChangeID, lastChangeID, nextStartChangeID, and queueID. The second section identifies the change.

Queue Info tags

• firstChangeId The first (or oldest) change available in the cache
• lastChangeId The last (or newest) change available in the cache
• nextStartChangeId The next change record ID clients should specify in subsequent listChange requests
• queueId A unique cache identifier which changes every time the AXL service is restarted
  

Change Type tags

• changes Indicates what changed
  
• id The change identifier AXL assigned
  
• action Indicates the type change: u is update, a is add, r is remove
  
• doGet Boolean which indicates when the client should perform a Get operation for the object, typically because the object is new or when multiple attributes of the object were changed.
• changedTags Indicates the details of the change
  

Sample Subsequent Request

sample subsequent request

<!--sample subsequent 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:listChange>
            <startChangeId queueId='093249823498'>10001</startChangeId>
            <objectList> (optional)
                <object>Phone</object>
                <object>User</object>
            </objectList>
        </ns:listChange>
    </soapenv:Body>
</soapenv:Envelope>  

The first time the client calls the listChange API, the startChangeId is not included. However, every subsequent listChange request should include both a startChangeID and queueID. The nextStartChangeId value received in the first response should be submitted as the startChangeId in subsequent requests. Additionally, the queueId received in the first response must also be included to help the client detect if changes may have been lost between sync intervals. Anytime the AXL service is restarted, a new queueID is generated.

Sample Subsequent Response

sample subsequent response

<!--sample subsequent response-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.cisco.com/AXL/API/10.0">
    <soapenv:Body>
        <ns:listChangeResponse>
            <queueInfo>
                <firstChangeId>10001</firstChangeId>
                <lastChangeId>20000</lastChangeId>
                <nextStartChangeId>20001</nextStartChangeId>
                <queueId>093249823498</queueId>
            </queueInfo>
            <changes>
                <change type='Phone' uuid='4c48f047-7b40-4547-a8c2-fc5b2b668bda'>
                    <id>10001</id>
                    <action>a</action>
                    <doGet>true</doGet>
                </change>
                <change type='PhysicalLocation' uuid='8h58f047-7b40-4547-a8c2-fc5b2b668b7f'>
                    <id>10002</id>
                    <action>u</action>
                    <doGet>false</doGet>
                    <changedTags>
                        <changedTag name = 'description'>A__V3.Dx.3 w_p6.</changedTag>
                    </changedTags>
                </change>
                <change type='PhysicalLocation' uuid='8h58f047-7b40-4547-a8c2-fc5b2b668b7f'>
                    <id>10003</id>
                    <action>r</action>
                    <doGet>false</doGet>
                </change>
                <change type='Phone' uuid='8g48f047-7b40-4547-a8c2-fc5b2b668b8d'>
                    <id>10004</id>
                    <action>u</action>
                    <doGet>false</doGet>
                    <changedTags>
                        <changedTag name='name'>SEP00000001</changedTag>
                        <changedTag name='description'>A__V.x.3 w_p6.</changedTag>
                        <changedTag name='versionStamp'>815abf2-1c0e-4</changedTag>
                    </changedTags>
                </change>
            </changes>
        </ns:listChangeResponse>
    </soapenv:Body>
</soapenv:Envelope>

The sample response in the right hand panel shows AXL returned changes from 10,001 to 20,000 for queueID 093249823498. The client should ask for change 20,001 with the same queueID the next time it makes a request. Note that changes 10,005-20,000 are not shown in this example.

The <doGet> tag indicates when the client needs to perform a get <object> operation, typically when the object is newly added or when too many attributes for the object changed. In this example the client should perform a getPhone request for uuid='4c48f047-7b40-4547-a8c2-fc5b2b668bda'.

Note: There may be multiple results for the same object. In this example the PhysicalLocation attribute for phone with uuid='8h58f047-7b40-4547-a8c2-fc5b2b668b7f' was updated, then removed.

Pagination Example

pagination example

<!--pagination example-->
<queueInfo>
<firstChangeId>100</firstChangeId>
<lastChangeId>10000</lastChangeId>
<nextStartChangeId>1001</nextStartChangeId>
<queueId>093249823498</queueId>
</queueInfo>

The client should always ask for the nextStartChangeId whether or not the request was paged, so the client doesn't really need to detect if the request was paged. If lastChangeId is greater than or equal to nextStartChangeId, then the request was paged. The client can immediately request the nextStartChangeId.

Polling Interval

The new AXL CNF has no restrictions on polling intervals. Requests are still subject to existing AXL throttles which limit each response to 8MB and all concurrent responses to 16MB.

The change queue cache is stored in memory and is limited to 100,000 changes. The cache can fill quickly depending on the types of changes performed. For example, if an XSI (IP Phone) Service has been configured for 10,000 phones and the service is deleted, the cache will include one entry representing the deletion of the service plus 10,000 phone updates indicating the service was removed from each device.

For a typical cluster, Cisco recommends AXL clients request listChange every 1-15 minutes. On a very busy system, AXL clients should request changes often (between 1-5 minutes) to ensure all changes are communicated while still in the cache. If the client waits too long and the changeID requested is no longer in the queue, AXL will return an error.

Error Conditions

Given the following queueInfo, here are some common error conditions:

queueInfo

<queueInfo>
<!--queueInfo-->
    <firstChangeId>154</firstChangeId>
    <lastChangeId>10000</lastChangeId>
    <nextStartChangeId>10001</nextStartChangeId>
    <queueId>093249823498</queueId>
</queueInfo>

Asking for a change that is no longer in the queue:

a change that is no longer in the queue

<!--a change that is no longer in the queue-->
<ns:listChange>
    <startChangeId queueId='093249823498'>153</startChangeId>
</ns:listChange>

Asking for a change that is greater than the nextStartChangeId in the queue:

a change that is greater than the nextStartChangeId in the queue

<!--a change that is greater than the nextStartChangeId in the queue-->
 <ns:listChange>
    <startChangeId queueId='093249823498'>10002</startChangeId>
</ns:listChange>

Using an invalid or old queueId:

invalid or old queueId

<ns:listChange>
<!--invalid or old queueId-->
    <startChangeId queueId='foobar'>10001</startChangeId>
</ns:listChange>  

User Rank Interactions

Overview

Cisco Unified CM can be configured by the administrator to control the ability of users, including AXL API users, to access or update certain CUCM data, via the User Rank feature. The administrator may create and assign User Rank values to individual end-users, application-users, or user-groups, then restrict only certain User Ranks from updating specific CUCM data types. These User Ranks can be created and assigned with values ranging from 1-10, with 1 being the 'default' rank which has the highest level of access.

Note: User Rank is a feature that first appears in CUCM v11.5(1)SU1. More details can be found in the Documentation Supplement for Cisco Unified Communications Manager and IM and Presence Service, Release 11.5(1)SU1 and System Configuration Guide for Cisco Unified Communications Manager for releases later than v11.5(1).

The CUCM user account used by an application to authenticate to AXL is also subject to the access control restrictions of the User Rank feature, which may affect certain types of AXL requests.

Interaction Scenarios

If the administrator has configured a User Rank for the AXL user that is higher than 1 (non-default), for example a Rank of 2-10, keep in mind the following possible interactions when performing operations on the controlled object types of End Users, Application Users, User Groups, and LDAP Directories:

• Add requests will result in the new object having the same User Rank as the AXL user.
  
• Remove requests will fail if the User Rank of the AXL user is greater than the User Rank of the target object.
• Update requests which attempt to modify the User Group(s) associated to an object will fail if the User Rank of the AXL user is greater than the User Rank of the target object.
• executeSqlUpdate operations which attempt to modify database fields related to User Rank, or User Group Association, are only allowed if the AXL User Rank is 1, the 'default' value.

Compatibility Notes

Upon upgrade to v11.5(1)SU1, User Rank of all objects and users will default to 1, which means no restrictions due to the User Rank Feature will occur. This should mean all AXL users and applications will be unaffected by the User Rank feature unless the CUCM administrator intentionally increases the User Rank of the AXL user or target controlled objects.

However, as of CUCM v11.5(1)SU1, User Rank is not exposed by any requests or elements in the AXL schema. Exposing User Rank is planned for a later release. As a result, applications may have difficulty ascertaining the User Rank of the AXL user itself or the User Rank of objects on which operations are to be performed, making it hard to avoid attempting restricted operations. Applications should be prepared to sanely handle requests which fail due to User Rank restrictions, see Error Messages.

Note, it is possible to read the User Rank value of controlled objects via SQL, using the executeSqlQuery request. See the Cisco Unified Communications Manager Data Dictionary for details on the tables and fields of the CUCM configuration database.

Error Messages

Requests which fail due to User Rank access restrictions will return a HTTP 500 Internal Server Error status code response with an explanatory <faultstring> element. See the example on the right of a error response where an AXL user having a User Rank of 3 attempts a <removeUser> operation on an end user having User Rank of 1:

HTTP/1.1 500 Internal Server Error
Set-Cookie: JSESSIONIDSSO=BADDF16BEBAFE335A63E2E9A8FAE89C4; Path=/; Secure; HttpOnly
Set-Cookie: JSESSIONID=480237656C63A166A88934CE54528E54; Path=/axl/; Secure; HttpOnly
X-Frame-Options: SAMEORIGIN
Strict-Transport-Security: max-age=31536000; includeSubdomains
Content-Type: text/xml;charset=UTF-8
Content-Length: 534
Date: Thu, 11 Aug 2016 17:46:51 GMT
Connection: close

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
     <soapenv:Fault>
        <faultcode>soapenv:Server</faultcode>
        <faultstring>You do not have the privilege to remove this End User as you have lower User Rank</faultstring>
        <detail>
           <axlError>
              <axlcode>5003</axlcode>
              <axlmessage>You do not have the privilege to remove this End User as you have lower User Rank</axlmessage>
              <request>removeUser</request>
           </axlError>
        </detail>
     </soapenv:Fault>
  </soapenv:Body>
</soapenv:Envelope>