5.4 Administrative XML (AXL) API & Dial-Plan Troubleshooting Tools
Key Takeaways
The Administrative XML (AXL) API provides programmatic SOAP-over-HTTPS web services on TCP port 8443, enabling Create, Read, Update, and Delete (CRUD) provisioning and direct SQL execution against the CUCM Informix engine.
The Cisco Real-Time Monitoring Tool (RTMT) tracks real-time performance counters (CallsActive, CallsAttempted, CallsInProgress), monitors system alerts, and centralizes trace log collection across all cluster nodes.
The Dialed Number Analyzer (DNA) executes offline digit analysis simulations using the live database to evaluate Calling Search Spaces, partitions, translation patterns, and egress route lists without placing physical calls or seizing trunk channels.
CallManager SDI traces show digit analysis decisions and full SIP messages, while SDL (Signal Distribution Layer) traces record the internal messages between CUCM processes; collect both with RTMT Trace & Log Central.
ISDN Q.931 Disconnect Cause Codes provide authoritative diagnostic identification of call failures, distinguishing between unassigned numbers (Cause 1), normal clearing (Cause 16), user busy (Cause 17), and circuit congestion (Cause 34).
5.4 Administrative XML (AXL) API & Dial-Plan Troubleshooting Tools
Operating enterprise collaboration networks requires automated provisioning tools alongside diagnostic instruments capable of troubleshooting complex dial plans. Cisco Unified Communications Manager provides the Administrative XML (AXL) API for programmatic database manipulation, complemented by the Real-Time Monitoring Tool (RTMT), Dialed Number Analyzer (DNA), and Signaling Distribution Layer (SDL) trace analysis to isolate call routing anomalies.
1. Administrative XML (AXL) API Architecture & Operations
The Administrative XML (AXL) API is an enterprise management interface allowing external scripts, orchestration platforms, and third-party provisioning engines to configure and query the CUCM Informix database.
Architectural Specifications
- Protocol: Simple Object Access Protocol (SOAP 1.1) wrapped in XML payloads.
- Transport: Encrypted HTTPS over TCP port 8443 (or port 443 with reverse-proxy redirection).
- Authentication: HTTP Basic Authentication over TLS, requiring an Application User or End User assigned the Standard AXL API Access role.
- Database Target: Interacts directly with the Informix Dynamic Server (IDS) database engine running on the Publisher node.
+--------------------------------------------------------------------------------+
| AXL API ARCHITECTURE |
| |
| +--------------------+ |
| | Provisioning App | |
| | (Python / Ansible) | |
| +---------+----------+ |
| | |
| |=== 1. HTTPS POST SOAP/XML (Port 8443) ==================> |
| | Auth: Basic (AXL Application User) |
| | Payload: <updateLine> or <addPhone> |
| | |
| | +---------------------------+ |
| | | CUCM Publisher Node | |
| | | - Tomcat Web Server | |
| | | - AXL Web Service | |
| | +-------------+-------------+ |
| | | |
| | v |
| | +---------------------------+ |
| | | Informix IDS Database | |
| | | (Read / Write Access) | |
| | +-------------+-------------+ |
| | | |
| |<== 2. SOAP XML Response (200 OK) <===============+ |
| | <return>{UUID}</return> |
+--------------------------------------------------------------------------------+
Core AXL CRUD Operations
AXL models configuration entities through standard Create, Read, Update, and Delete methods:
addPhone: Provisions a new physical IP phone or softphone, specifying MAC address, product model, device pool, phone button template, and line associations.getPhone: Queries configuration attributes and line associations for a specific device.updateLine: Modifies line parameters, including directory number, route partition, alert name, and Call Forward All (CFA) destinations.removeUser: Deletes an End User account or disassociates assigned extensions.executeSQLQuery/executeSQLUpdate: Executes direct Informix SQL statements against the CUCM database for high-performance bulk reporting or complex data manipulation.
Example AXL SOAP Request
The following XML payload illustrates an AXL updateLine operation configuring Call Forward All to voicemail for extension 5001:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns="http://www.cisco.com/AXL/API/14.0">
<soapenv:Header/>
<soapenv:Body>
<ns:updateLine>
<pattern>5001</pattern>
<routePartitionName>Internal_PT</routePartitionName>
<callForwardAll>
<forwardToVoiceMail>true</forwardToVoiceMail>
<callingSearchSpaceName>Internal_CSS</callingSearchSpaceName>
</callForwardAll>
</ns:updateLine>
</soapenv:Body>
</soapenv:Envelope>
Other Unified CM APIs (Blueprint 3.5)
Objective 3.5 asks you to describe each API's type, authentication, and capabilities. For Unified CM the main interfaces are:
| API | Type | Authentication | Capabilities |
|---|---|---|---|
| AXL | SOAP/XML over HTTPS (TCP 8443) | HTTP Basic; the account needs the Standard AXL API Access role | Add, get, update, and remove configuration objects; SQL queries |
| User Data Services (UDS) | REST (XML responses) over HTTPS | Directory queries can be anonymous; user-specific calls use the end user's credentials or an OAuth token | Directory search, user and device lookups, home-cluster discovery for Jabber and Webex App |
| Serviceability XML (SXML) | SOAP over HTTPS | HTTP Basic with a serviceability-enabled account | RisPort70 real-time registration status, PerfMon counters, Control Center service start and stop, log collection |
| CTI (JTAPI/TAPI) | Java or Windows libraries talking to CTIManager (TCP 2748) | An application or end user with Standard CTI Enabled (or Allow Control of All Devices) | Call control, monitoring, and recording of associated devices |
A provisioning script therefore uses AXL to build a phone, RisPort70 to confirm the phone registered, and UDS or CTI only when a client or application needs runtime user data or call control.
2. Real-Time Monitoring Tool (RTMT) & Performance Telemetry
The Cisco Unified Real-Time Monitoring Tool (RTMT) is an administrator client application that monitors system health, tracks performance counters, and manages diagnostic logs across all cluster nodes.
Core Telemetry Counters
Administrators monitor live telephony performance through the Cisco CallManager object counters:
CallsActive: Instantaneous number of active voice and video sessions currently established across the cluster node.CallsAttempted: Cumulative count of call setup attempts initiated since the CallManager service last started.CallsInProgress: Number of calls currently in setup, digit analysis, or teardown phases.CallsCompleted: Number of successfully completed and normally cleared calls.PartiallyRegisteredPhone: SIP phones that are registered but have one or more lines that failed to register.
Alert Central & Trace Collection
- Alert Central: Tracks real-time threshold conditions (for example,
CallProcessingNodeCpuPegging,MediaListExhausted,RouteListExhausted,DBReplicationFailure, andLowActivePartitionAvailableDiskSpace). When thresholds are exceeded, RTMT generates visual alerts and dispatches SNMP traps or email notifications. - Trace & Log Central: Provides a centralized utility to collect diagnostic logs across all cluster nodes simultaneously. Administrators can query, download, and zip traces for
Cisco CallManager,Cisco IP Voice Media Streaming App, andCisco Extension Mobilityservices without requiring command-line SSH access.
3. Dialed Number Analyzer (DNA)
Dialed Number Analyzer (DNA) is a specialized diagnostic simulation tool embedded within CUCM Serviceability. It allows engineers to test and validate complex dial plans offline.
+--------------------------------------------------------------------------------+
| DNA SIMULATION PIPELINE |
| |
| INPUT PARAMETERS: |
| Calling Device: SEP001122334455 |
| Line DN: 2001 (Line CSS: Internal_CSS) |
| Dialed Digits: 912145551212 |
| Time of Day: Monday 14:00 |
| |
| DIGIT ANALYSIS ENGINE (Offline Simulation): |
| Step 1: Check Translation Patterns in Line/Device CSS |
| -> Match 9.1[2-9]XX[2-9]XXXXXX (Discard: PreDot) |
| Step 2: Check Egress Route Patterns |
| -> Match 1[2-9]XX[2-9]XXXXXX in [PSTN_PT] |
| Step 3: Route List Resolution |
| -> Traverses RL_PSTN -> RG_LocalGateway |
| Step 4: Egress Device Selection |
| -> Target: CUBE_SIP_Trunk (192.168.10.50) |
| |
| OUTPUT: Full resolution tree; ZERO physical calls or trunk circuits seized! |
+--------------------------------------------------------------------------------+
Advantages of DNA Simulation
- Zero Impact on Production Trunks: DNA runs against the live Informix configuration database but does not initiate signaling or seize B-channels/SIP sessions.
- Granular Transformation Tracing: Exposes every transformation step: pattern matching, discard digit instructions (e.g.,
PreDot), prefixing, route list filter application, and gateway selection. - Line vs. Device CSS Disambiguation: Visualizes exactly whether a pattern was matched via the Line CSS or Device CSS partition list.
4. SDL Trace Analysis & ISDN Q.931 Disconnect Codes
When diagnosing intermittent call failures, one-way audio, or unexpected disconnects, engineers analyze the Cisco CallManager SDI traces (ccm*.txt.gz), which show digit analysis results such as the matched pattern and the CSS used, together with SDL (Signal Distribution Layer) traces, which record the internal messages between CUCM processes.
Structure of SDL Traces
- SDL traces live in
/var/log/active/cm/trace/ccm/sdl/(files named likeSDL001_100_000123.txt.gz) and SDI traces in/var/log/active/cm/trace/ccm/sdi/; collect both with RTMT Trace & Log Central rather than browsing the file system. - SDL records internal message exchanges between CUCM state-machine processes (for example, StationD for SCCP phones, digit analysis, the SIP handlers, and route list control).
- Engineers search for the GlobalCallId or CallID to trace a call leg from ingress signaling (a SIP
INVITEor an SCCP off-hook message) through digit translation, route selection, and egress alerting (180 Ringing).
Authoritative Q.931 Disconnect Cause Codes
When a call terminates, CUCM logs the authoritative ISDN Q.931 Disconnect Cause Code (which directly maps to corresponding SIP response status codes):
| Q.931 Cause Code | Diagnostic Name | SIP Response Mapping | Technical Meaning & Diagnostic Action |
|---|---|---|---|
| Cause 1 | Unallocated (unassigned) number | 404 Not Found | The dialed number does not exist in the dial plan or route table. Check for missing directory numbers or route patterns. |
| Cause 16 | Normal call clearing | 200 OK (to BYE) | The call was terminated normally by either the calling or called party hanging up. Indicates successful session completion. |
| Cause 17 | User busy | 486 Busy Here | The called party is engaged on an active call and has reached their maximum call appearance limit, or sent a busy status. |
| Cause 28 | Invalid number format (address incomplete) | 484 Address Incomplete | Insufficient digits were dialed before interdigit timeout expired. Check overlap dialing or variable-length route pattern syntax. |
| Cause 34 | Circuit / channel congestion | 503 Service Unavailable | All PSTN B-channels, trunk channels, or WAN Call Admission Control bandwidth pools are completely exhausted. |
| Cause 41 | Temporary failure | 503 Service Unavailable | An internal network outage, SIP signaling timeout, or transient gateway malfunction occurred. |
An automation developer is building a Python integration to automatically provision IP phones on CUCM using the Administrative XML (AXL) API. Which architectural protocol, transport port, and user privilege are required to execute AXL operations?
gRPC over TCP on port 50051 authenticated with a mutual TLS client certificate.
SOAP/XML over HTTPS on port 8443 authenticated with a user assigned the Standard AXL API Access role.
REST over HTTP on port 8080 authenticated with an End User assigned the Standard CTI Enabled role.
SNMPv3 over UDP on port 161 authenticated with an MD5/DES privacy profile.
During a dial-plan migration, users report that calls to a specific department are failing. The collaboration engineer wants to trace the digit analysis path, translation patterns, and egress route lists for a dialed number without placing physical calls or seizing trunk channels. Which tool within CUCM provides this offline simulation capability?
Cisco IP Voice Media Streaming Application
Cisco Unified Dialed Number Analyzer (DNA)
Cisco Real-Time Monitoring Tool (RTMT) Alert Central
Signaling Distribution Layer (SDL) Trace Collection Utility
While analyzing an SDL call trace file in RTMT for a failed outbound call to the PSTN, an engineer observes an ISDN Q.931 disconnect message containing 'Cause 34'. What is the technical meaning of this disconnect code?
No circuit or channel available; no B-channel or trunk capacity can complete the call.
Normal call clearing; the remote party answered the call and subsequently hung up normally.
Unallocated or unassigned number; the dialed destination does not exist.
User busy; the called endpoint is actively engaged on another call.
Sections you finish are checked off in the contents.