Administrative XML (AXL) > Learn > How To

How to ... Work with AXL Data Throttling

The Developer can make powerful modifications to 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 AXL 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 obejcts: Standard methods which provide backward compatibility between releases (e.g. Get User) and direct access through the ExecuteSQLQuery and ExecuteSQLUpdate methods, which do not provide backward compatibility.

The AXL service dynamically throttles 'write' requests (add/update/remove requests, and executeSqlUpdate) based on the current size of the UCM database transaction queue. Note that the UCM database transaction queue can contain pending updates arising from recent administrative actions, bulk administration tasks, other AXL applications, etc. 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 re-try rejected requests, however re-tries should be attempted after a reasonable delay (e.g. 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 who use 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
  • The maximum total data set size AXL can process for all concurrent queries never exceeds 16 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/out of EM via the AXL interface.

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

Scenario 1: AXL Query request that tries to fetch more than 8MB of data.

Request

1
2
3
4
5
6
7
8
<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>

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
    <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 2: Too many concurrent ExecuteSQLQuery requests.

Request (repeated 3 times at the same time)

1
2
3
4
5
6
7
8
<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>

Response - Two requests are processed. The third one gives an error response.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
    <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>