Cisco Unified Communications Manager XML Developers Guide Release 7.0(1)
Chapter 1. Administrative XML (AXL) Programming
Downloads: This chapterpdf (PDF - 430.0KB) The complete bookPDF (PDF - 8.87MB) | Feedback

Administrative XML (AXL) Programming

Table Of Contents

Administrative XML (AXL) Programming

Overview

New and Changed Information

AXL Versioning Support

Dynamic Throttling of Requests

New and Changed AXL APIs for Cisco Unified Communications Manager 7.0(1)

New APIs

Changed Operations

Changed AXL APIs for Cisco Unified Communications Manager 6.1(1)

Changed AXL APIs for Cisco Unified Communications Manager 6.0(1)

Changed Service Parameter for Cisco Unified Communications Manager 6.0(1)

New AXL APIs for Cisco Unified Communications Manager 5.1(1)

Changed AXL APIs for Cisco Unified Communications Manager 5.0(1)

Changed AXL APIs for Cisco Unified Communications Manager 4.2

Changed API Calls

New Service Parameter

Changed AXL APIs for Cisco Unified Communications Manager 4.1(2)

AXL Schema Documentation

Authentication

Data Encryption

Integration Considerations and Interoperability

Post-Installation Steps and Troubleshooting on the Linux Platform

Post-Installation Steps

Starting the AXL Service

Setting AXL API Access Permissions

Post-Installation Troubleshooting Checklist

AXL Trace Logs

Using the AXL API with AXIS

Using the AXL API in a .NET Environment

Required Changes to the Generated Code

Resolving JIT Errors

Backward Compatibility Issues

Tag Serialization Issues

Names Containing Special Characters

Returned Namespace for AXIS and .NET Applications

Example AXL Requests

C or C++ Example

Java Example

Using executeSQLUpdate

Using executeSQLQuery

AXL Error Codes


Administrative XML (AXL) Programming


This chapter describes the Administrative XML Layer (AXL) Application Programming Interface (API). It contains the following sections:

Overview

New and Changed Information

AXL Schema Documentation

Authentication

Data Encryption

Integration Considerations and Interoperability

Post-Installation Steps and Troubleshooting on the Linux Platform

Using the AXL API with AXIS

Using the AXL API in a .NET Environment

Returned Namespace for AXIS and .NET Applications

Example AXL Requests

AXL Error Codes

Overview

The AXL 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 approach allows a programmer to access the database by using XML and receive the data in XML form, instead of by 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. The server receives the XML structures and executes the request. If the request completes successfully, the system returns the appropriate AXL response. All responses are 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 is returned, wrapped inside a SOAP Fault structure (see the "AXL Error Codes" section).

The AXL-SOAP web service is disabled by default on all Cisco Unified Communications Manager servers that are running version 5.x or later. You should start the service before using the AXL APIs.

To access all AXL SOAP API downloads and AXL requests and responses that are found in this chapter, refer to http://developer.cisco.com/web/axl/documentation

This chapter assumes that the developer has knowledge of a high-level programming language such as C++, Java, or an equivalent language, and has knowledge of SOAP.

Developers must also have knowledge or experience in the following areas:

TCP/IP Protocol

Hypertext Transport Protocol (specifically HTTPS)

Socket programming

XML

Users of the AXL API must have a firm grasp of XML syntax and Schema, which is used to define the 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/.


Caution The AXL API allows you to modify the Cisco Unified Communications Manager system database. Use caution when using AXL because each API call affects the system. Misuse of the API can lead to dropped calls and slower performance. AXL should act as a provisioning and configuration API, not as a real-time API.

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.

New and Changed Information

The following sections describes the major changes in the AXL APIs for Release 7.0(1) and for previous releases:

AXL Versioning Support

Dynamic Throttling of Requests

New and Changed AXL APIs for Cisco Unified Communications Manager 7.0(1)

Changed AXL APIs for Cisco Unified Communications Manager 6.1(1)

Changed AXL APIs for Cisco Unified Communications Manager 6.0(1)

New AXL APIs for Cisco Unified Communications Manager 5.1(1)

Changed AXL APIs for Cisco Unified Communications Manager 5.0(1)

Changed AXL APIs for Cisco Unified Communications Manager 4.2

Changed AXL APIs for Cisco Unified Communications Manager 4.1(2)

For information about new, changed, or deprecated AXL API methods from the interface library, see "Administrative XML (AXL) Operations by Release." For related information, refer to Cisco Configuration XML Interface Specification (zip archive), which is available at this URL:

http://www.cisco.com/en/US/products/sw/voicesw/ps556/products_programming_reference_guides_
list.html

AXL Versioning Support

To improve backward compatibility, Cisco Unified Communications Manager introduced AXL schema versioning in Release 6.0(1). This feature is included in all subsequent Cisco Unified Communications Manager releases. Beginning with Release 6.0(1), the system duplicates the previous AXL 1.0 schema as the AXL 6.0(1) schema and numbers the AXL schema the same as the corresponding Cisco Unified Communications Manager release. This approach maintains AXL backward compatibility for one full release cycle.

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 executeSQLUpdate, changes have occurred to the Cisco Unified Communications Manager database schema that affect the direct SQL query approach. Refer to the Cisco Unified Communications Manager Database Dictionary for the release that you are using. That document 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.

Cisco will support AXL requests without version information for only three releases following the 6.0(1) release; after that, requests without version information will be rejected.

AXL requests with version information will have the corresponding schema applied for up to three subsequent releases; after that, the specified version may not be available.

Table 1-1 AXL Versioning and Schema Plan for Future Releases

   
AXL Request no version specified
AXL Request with Version Specified
   
Release 6.0
Release 6.1(0)
Release 7.0(1)
Plus 1 releases
Plus 2 releases
Cisco Unified Communications Manager Release
Release 6.0

6.0 schema applied

6.0 schema applied

 
Release 6.1(0)

6.0 schema applied

6.0 schema applied

6.1(0) schema applied

Not Applicable
Release 7.0(1)

6.0 schema applied

6.0 schema applied

6.1(0) schema applied

7.0(1) schema applied

 
Plus 1 releases

6.0 schema applied

6.0 schema applied

6.1(0) schema applied

7.0(1) schema applied

Plus 1 schema applied

 
Plus 2 releases
Request rejected
 

6.1(0) schema applied

7.0(1) schema applied

Plus 1 schema applied

Plus 2 schema applied

Plus 3 releases
Request rejected

Schema no longer available

7.0(1) schema applied

Plus 1 schema applied

Plus 2 schema applied


The following sample AXL request carries version information:

Host:10.77.31.194:8443
Authorization: Basic Q0NNQWRtaW5pc3RyYXRvcjpjaXNjb19jaXNjbw==
Accept: text/*
Content-type: text/xml
SOAPAction: "CUCM:DB ver=7.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/7.0" 
si:schemaLocation="http://www.cisco.com/AXL/API/7.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 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONIDSSO=12E52A7F9B34107BA6147096878E00F9; Path=/
Set-Cookie: JSESSIONID=7B94F17D61C6A91B04C5C76A6E3F905E; Path=/axl; Secure
SOAPAction: "CUCM:DB ver=7.0"
Content-Type: text/xml;charset=utf-8
Content-Length: 1936
Date: Mon, 03 Mar 2008 10:17:38 GMT
Connection: close
<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:getUserResponse xmlns:axl="http://www.cisco.com/AXL/API/7.0" 
xmlns:xsi="http://www.cisco.com/AXL/API/7.0" sequence="1234">
    <return>
      <user>
        <firstname/>
        <lastname>tttt</lastname>
        <userid>tttt</userid>
        <password/>
        <pin/>
        <telephoneNumber/>
        <department/>
        <manager/>
        <associatedDevices>
          <device>SEPA88888888888</device>
        </associatedDevices>
        <primaryExtension/>
        <associatedPC/>
        <associatedGroups>
          <userGroup uuid="{6B126A13-8F47-B78D-13D4-9555D664F634}">
     <name>test</name>
       <userRoles>
         <userRole uuid="{A6BAE213-AAB5-F794-B71C-98EE94129C9B}">Standard AXL API 
Access</userRole>
       </userRoles>
          </userGroup>
        </associatedGroups>
        <enableCTI>true</enableCTI>
        <digestCredentials/>
        <enableMobility>false</enableMobility>
        <enableMobileVoiceAccess>false</enableMobileVoiceAccess>
        <maxDeskPickupWaitTime>10000</maxDeskPickupWaitTime>
        <remoteDestinationLimit>4</remoteDestinationLimit>
        <passwordCredentials>
          <pwdCredPolicyName>Default Credential Policy</pwdCredPolicyName>
          <pwdCredUserCantChange>false</pwdCredUserCantChange>
          <pwdCredUserMustChange>false</pwdCredUserMustChange>
          <pwdCredDoesNotExpire>false</pwdCredDoesNotExpire>
          <pwdCredTimeChanged>February 14, 2008 16:10:12 IST</pwdCredTimeChanged>
          <pwdCredTimeAdminLockout/>
          <pwdCredLockedByAdministrator>false</pwdCredLockedByAdministrator>
        </passwordCredentials>
        <pinCredentials>
          <pinCredPolicyName>Default Credential Policy</pinCredPolicyName>
          <pinCredUserCantChange>false</pinCredUserCantChange>
          <pinCredUserMustChange>false</pinCredUserMustChange>
          <pinCredDoesNotExpire>false</pinCredDoesNotExpire>
          <pinCredTimeChanged>February 14, 2008 16:10:12 IST</pinCredTimeChanged>
          <pinCredTimeAdminLockout/>
          <pinCredLockedByAdministrator>false</pinCredLockedByAdministrator>
        </pinCredentials>
      </user>
    </return>
  </axl:getUserResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Dynamic Throttling of Requests

Cisco Unified Communications Manager releases earlier than 7.0 included the AXL service parameter MaxAXLWritesPerMinute, which has a default value of 50 and maximum value of 999. This service parameter designates the maximum number of write requests that AXL can encounter and process in one minute. Cisco Unified Communications Manager 7.0 includes a new throttling mechanism. The MaxAXLWritesPerMinute service parameter has been deprecated.

The new throttling mechanism takes into account the dynamic state of Cisco Unified Communications Manager. It considers the number of outstanding change notifications across the Cisco Unified Communications Manager cluster at any given time. If a node has more than 1,500 outstanding change notifications, AXL stops processing write requests until the outstanding change notifications are below 1,500. During throttling, HTTPS Status-Code: 503 Service Unavailable response and sets AXL performance counters which can be viewed using RTMT. When a 503 Service Unavailable response is returned, Cisco recommends that the application sleep for a number of seconds or milliseconds (as determined by the developer) to allow pending write requests to be processed. The application should then continue submitting requests.

There are two AXL performance counters:

ThrottleCount—Determines number of times Administrative AXL throttling has been engaged.

ThrottleState—Determines the state of AXL throttling. That is, whether AXL throttling is currently active (throttling is engaged).

The AXL error message for throttling remains same as in earlier versions of Cisco Unified Communications Manager. There is no change required to AXL applications.

For example, consider an application that makes 1,000 phone insertions in 30 seconds. Assume that these insertions cause 2,000 change notifications to various applications such as Cisco Unified Communications Manager and Cisco TFTP, and that within 10 seconds all change notifications are consumed. In this situation, by the 40th second, the number of outstanding change notifications is zero and the throttling mechanism does not take effect. However, if these change notifications are not consumed, the throttling mechanism does take effect and write requests are throttled until the outstanding change notification value falls below 1,500.

The throttling mechanism considers the capacity of the Cisco Unified Communications Manager cluster to consume the change notifications that generated from all the write activities to the Cisco Unified Communications Manager database. In this way, it is dynamic. As long as all change notifications are consumed at a rate that is equal to or higher than the rate at which change notifications are generated, throttling does not take effect.


NoteRead requests are never throttled and pass through even when write requests are throttled.

The MaxAXLWritesPerMinute service parameter has been deprecated and is no longer available.


New and Changed AXL APIs for Cisco Unified Communications Manager 7.0(1)

Cisco Unified Communications Manager Release 7.0(1) APIs are compatible with all previous releases of Cisco Unified Communications Manager. For additional details about the Cisco Unified Communications Manager database schema changes, refer to the Cisco Unified Communications Manager Data Dictionary for Release 7.0(1).

The following sections describe API updates that were made in Cisco Unified Communications Manager Release 7.0(1):

New APIs

Changed Operations

Changed AXL APIs for Cisco Unified Communications Manager 6.1(1)

New APIs

Table 1-2 describes new operations in Cisco Unified Communications Manager 7.0(1).

Table 1-2 New Operations in Cisco Unified Communications Manager 7.0(1) 

Operation
Purpose
Added Tags

addCalledPartyTransformationPattern

removeCalledPartyTransformationPattern

updateCalledPartyTransformationPattern

getCalledPartyTransformationPattern

Added for Local Route Group feature

pattern (mandatory)

usage (mandatory)

routePartition

description

numberingPlan

routeFilter

patternUrgency (read only)

discardDigits

calledPartyTransformationMask

prefixDigitsOut

calledPartyNumberType

calledPartyNumberingPlan

addSIPTrunkSecurityProfile

updateSIPTrunkSecurityProfile

removeSIPTrunkSecurityProfile

getSIPTrunkSecurityProfile

Added for SRTP support for SIP Trunk feature

name (mandatory)

description

securityMode

incomingTransport

outgoingTransport

digestAuthentication

noncePolicyTime

x509SubjectName

incomingPort

applLevelAuthentication

acceptPresenceSubscription

acceptOutOfDialogRefer

allowReplaceHeader

acceptUnsolicitedNotification

transmitSecurityStatus

addResourcePriorityNamespace

updateResourcePriorityNamespace

removeResourcePriorityNamespace

getResourcePriorityNamespace

Added for AS-SIP feature

namespace

addResourcePriorityNamespaceList

updateResourcePriorityNamespaceList

getResourcePriorityNamespaceList

removeResourcePriorityNamespaceList

Added for AS-SIP feature

name (mandatory)

members (mandatory)

resourcePriorityNamespace / resourcePriorityNamespaceName

addResourcePriorityDefaultNamespace

updateResourcePriorityDefaultNamespace

getResourcePriorityDefaultNamespace

removeResourcePriorityDefaultNamespace

Added for AS-SIP feature

resourcePriorityNamespace

addSIPProfile

updateSIPProfile

getSIPProfile

removeSIPProfile

Added for AS-SIP feature

resourcePriorityNamespaceList

addTODAccess

updateTODAccess

getTODAccess

removeTODAccess

Added for Mobility - TOD Access List feature

name (mandatory)

description

ownerId (mandatory)

members > member > [timeSchedule (mandatory), isActionAllowed (mandatory), accessList (mandatory)]

associatedRemoteDestination (read only)

getMobileSmartClientProfile

Added for Cisco Unified Communications Manager New Device Typ

MobileSmartClient

Name

EnableSNRUri

EnableCFAUri

HandoffUri

addVG224

updateVG224

removeVG224

getVG224

Added for adding VG224 gateway

domainName, description, product, protocol, model, callManagerGroup, callManagerGroupName, units, unit, product, subunits, subunit, endpoints, endpoint, name, description, product, productInfo, model, modelInfo, class, protocol, protocolSide, callingSearchSpace, callingSearchSpaceName, devicePool, devicePoolName, commonDeviceConfig, commonDeviceConfigName, commonPhoneConfig, commonPhoneConfigName, networkLocation, location, locationName, mediaResourceList, mediaResourceListName, networkHoldMOHAudioSourceId, userHoldMOHAudioSourceId, automatedAlternateRoutingCSS, automatedAlternateRoutingCSSName, aarNeighborhood, aarNeighborhoodName, loadInformation, vendorConfig, versionStamp, traceFlag, mlppDomainId, mlppIndicationStatus, preemption, useTrustedRelayPoint, retryVideoCallAsAudio, securityProfile, securityProfileName, sipProfile, sipProfileName, cgpnTransformationCSS, cgpnTransformationCSSName, useDevicePoolCgpnTransformCSS, lines, packetCaptureMode, packetCaptureDuration, transmitUTF8, ports, userLocale, networkLocale, isActive, unattendedPort, subscribeCallingSearchSpace, subscribeCallingSearchSpaceName, allowCtiControlFlag, remoteDevice, phoneTemplate, phoneTemplateName, presenceGroup, presenceGroupName, ignorePresentationIndicators, deviceMobilityMode, hlogStatus, ownerUserId, vendorConfig, versionStamp

addApplicationUser

Added for creating new application users

userid

password

passwordCredentials

presenceGroup

presenceGroupName

acceptPresenceSubscription

acceptOutOfDialogRefer

acceptUnsolicitedNotification

alloReplaceHeader

isStandard

associatedDevices

associatedGroups

associatedCAPFProfiles

updateApplicationUser

Added for updating application users

removeApplicationUser

Added for removing existing application users

getApplicationUser

Added for obtaining details about application users


Changed Operations

Table 1-3 describes changed operations in Cisco Unified Communications Manager 7.0(1).

Table 1-3 Changed Operations in Cisco Unified Communications Manager 7.0(1) 

Operation
Change
Tags

addDevicePool

updateDevicePool

getDevicePool

Added tags for CPN and E.164 Dialing feature

cgpnTransformationCSS

nationalPrefix

internationalPrefix

unknownPrefix

subscriberPrefix

Added tags for Local Route Group feature

cdpnTransformationCSS

useDevicePoolCdpnTransformCSS

addMGCPEndPoint

Added tags for Local Route Group feature

cdpnTransformationCSS

useDevicePoolCdpnTransformCSS

Added tags for CPN and E.164 Dialing feature

cgpnTransformationCSS

useDevicePoolCgpnTransformCSS

Added tag for Network Virtualization feature

useTrustedRelayPoint

Added tag for Secure-Indication Tone feature

enableProtectedFacilityIE

addSIPTrunk

updateSIPTrunk

getSIPTrunk

Added tags for CPN and E.164 Dialing feature

cgpnTransformationCSS

useDevicePoolCgpnTransformCSS

unknownPrefix

Added tags for Local Route Group feature

cdpnTransformationCSS

useDevicePoolCdpnTransformCSS

Added tags for Network Virtualization feature

useTrustedRelayPoint

Added tags for SRTP support feature

srtpAllowed

srtpFallbackAllowed

Added tags for SIP PAI feature

isPaiEnabled

sipPrivacy

isRpidEnabled

sipAssertedType

Added tag for Trunk Licensing feature

licensedCapacity

addH323Phone

updateH323Phone

getH323Phone

Added tag for Network Virtualization feature

useTrustedRelayPoint

addH323Trunk

updateH23Trunk

getH323Trunk

Added tags for CPN and E.164 Dialing feature

cgpnTransformationCSS

useDevicePoolCgpnTransformCSS

nationalPrefix

internationalPrefix

unknownPrefix

subscriberPrefix

Added tags for Local Route Group feature

cdpnTransformationCSS

useDevicePoolCdpnTransformCSS

Added tags for Network Virtualization feature

useTrustedRelayPoint

Added tags for Trunk Licensing feature

licensedCapacity

addH323Gateway

updateH323Gateway

getH323Gateway

Added tags for CPN and E.164 Dialing feature

cgpnTransformationCSS

useDevicePoolCgpnTransformCSS

nationalPrefix

internationalPrefix

unknownPrefix

subscriberPrefix

Added tags for Local Route Group feature

cdpnTransformationCSS

useDevicePoolCdpnTransformCSS

Added tag for Network Virtualization feature

useTrustedRelayPoint

Added tag for Trunk Licensing feature

licensedCapacity

addRoutePattern

updateRoutePattern

getRoutePattern

Added tags for CPN and E.164 Dialing feature

callingPartyNumberingPlan

callingPartyNumberType

Added tags for Local Route Group feature

calledPartyNumberingPlan

calledPartyNumberType

Added tag for AS-SIP feature

resourcePriorityNamespace

addHuntPilot

updateHuntPilot

getHuntPilot

Added tags for CPN and E.164 Dialing feature.

callingPartyNumberingPlan

callingPartyNumberType

Added tags for Local Route Group feature

calledPartyNumberingPlan

calledPartyNumberTyp

addTransPattern

updateTransPattern

getTransPattern

Added tags for CPN and E.164 Dialing feature

callingPartyNumberingPlan

callingPartyNumberType

Added tags for Local Route Group feature

calledPartyNumberingPlan

calledPartyNumberType

Added tag for AS-SIP feature

resourcePriorityNamespace

addConferenceBridge

updateConferenceBridge

getConferenceBridge

Added tag for Network Virtualization feature

useTrustedRelayPoint

addCTIRoutePoint

updateCTIRoutePoint

getCTIRoutePoint

Added tagsAdded tag for CPN and E.164 Dialing feature

cgpnTransformationCSS

useDevicePoolCgpnTransformCSS

Added tag for Network Virtualization feature

useTrustedRelayPoint

addPhone

updatePhone

getPhone

Added tags for CPN and E.164 Dialing feature

cgpnTransformationCSS

useDevicePoolCgpnTransformCSS

Added tags for BLF CallPickup feature

associatedBLFSDFeatures

ringSettingIdleBLFAudibleAlert

ringSettingBusyBLFAudibleAlert

Added tags for Enhanced IP Phone Services Provisioning feature

phoneService

vendor

version

priority

phoneServiceDisplay

requirePKIAuthForHTTPS

Added tag for Secure-Indication Tone feature

isProtected

Added tag for new CUCM Device type feature

MobileSmartClientProfile

Added tags for complete phone API support

requireDTMFReception

RFC2833Disabled

phoneLoadName

authenticationMode

keySize

addGatewayEndpoint

updateGatewayEndpoint

getGatewayEndpoint

Added tags for CPN and E.164 Dialing feature

gpnTransformationCSS

useDevicePoolCgpnTransformCSS

nationalPrefix

internationalPrefix

unknownPrefix

subscriberPrefix

Added tags for Local Route Group feature

cdpnTransformationCSS

useDevicePoolCdpnTransformCSS

Added tag for Network Virtualization feature

useTrustedRelayPoint

Added tag for VoSIP/DVX G.Clear feature

GClearEnable

addMOHServer

updateMOHServer

getMOHServer

Added tag for Network Virtualization feature

useTrustedRelayPoint

addVoiceMailPort

getVoiceMailPort

addCommonDeviceConfig

updateCommonDeviceConfig

getCommonDeviceConfig

addTranscoder

updateTranscoder

getTranscoder

Added tag for Network Virtualization feature

isTrustedRelayPoint

addRemoteDestinationProfile

updateRemoteDestinationProfile

getRemoteDestinationProfile

Added tags for DND Reject feature

dndStatus

dndOption

Added tag for new CUCM Device type feature

MobileSmartClientProfile

addTransformationPattern

updateTransformationPattern

getTransformationPattern

Added tags for CPN and E.164 Dialing feature

callingPartyNumberingPlan

digitDiscardInstruction

callingPartyNumberTyp

addTimePeriod

updateTimePeriod

getTimePeriod

Added tags for Mobility - TOD Access List feature

description

isPublished

todOwnerId

dayOfMonthEnd

monthOfYearEnd

addTimeSchedule

updateTimeSchedule

getTimeSchedule

Added tags for Mobility - TOD Access List feature

description

isPublished

timeScheduleCategory

todOwnerId

addRemoteDestination

Added tags for Mobility - TOD Access List feature

timeZone

clientApplicationModel

todAccess

Removed tags for Mobility - TOD Access List feature

allowedAccessList

blockedAccessList

smartClientInstalled

Added tag for new CUCM Device type feature

MobileSmartClient

Deprecated tag

clientAppModelxxx

updateRemoteDestination

getRemoteDestination

Added tags for Mobility - TOD Access List feature

timeZone

clientApplicationModel

todAccess

Removed tags for Mobility - TOD Access List feature

allowedAccessList

blockedAccessList

smartClientInstalled

Added tag for new CUCM Device type feature

MobileSmartClient

Added tag for new CUCM Device type feature

clientAppModelxxx

addUser

updateUser

getUser

Added tag for Mobility - TOD Access List feature

associatedTodAccess

Removed tag for addUser API for Mobility - TOD Access List feature

associatedAccessLists

addRouteList

updateRouteList

getRouteList

Added tags for CPN and E.164 Dialing feature

callingPartyNumberingPlan

callingPartyNumberType

calledPartyNumberingPlan

calledPartyNumberType


Changed AXL APIs for Cisco Unified Communications Manager 6.1(1)

Table 1-4 describes the API calls that changed in Cisco Unified Communications Manager 6.1(1). These changes might require updates to existing user code in which a changed feature is used.

Table 1-4 Changed API Calls in Cisco Unified Communications Manager 6.1(1) 

API Call
Change
Tags

addLine

Added tag for Intercom CTI Support feature

defaultActivatedDevice

updateLine

Added tag for Intercom CTI Support feature

defaultActivatedDevice

getLine

Added tag for Intercom CTI Support feature

defaultActivatedDevice

addUser

Added tag for Mobility user feature

primaryDevice

updateUser

Addedtag for Mobility user feature

primaryDevice

getUser

Added tag for Mobility user feature

primaryDevice

addDeviceProfile

Added tags for SingleButtonBarge and JoinAcrossLines features

singleButtonBarge

joinAcrossLines

updateDeviceProfile

Added tags SingleButtonBarge and JoinAcrossLines features

singleButtonBarge

joinAcrossLines

getDeviceProfile

Added tags for SingleButtonBarge and JoinAcrossLines features

singleButtonBarge

joinAcrossLines

addDevicePool

Added tags for SingleButtonBarge and JoinAcrossLines features

singleButtonBarge

joinAcrossLines

updateDevicePool

Added tags for SingleButtonBarge and JoinAcrossLines features

singleButtonBarge

joinAcrossLines

getDevicePool

Added tags for SingleButtonBarge and JoinAcrossLines features

singleButtonBarge

joinAcrossLines

addPhone

Added tags and joinAcrossLines for SingleButtonBarge and JoinAcrossLines features

singleButtonBarge

joinAcrossLines

Added tag for BAT/TAPS Licensing Allowance feature

isActive

updatePhone

Added tags and joinAcrossLines for SingleButtonBarge and JoinAcrossLines features

singleButtonBarge

joinAcrossLines

Added tag for BAT/TAPS Licensing Allowance feature

isActive

getPhone

Added tags and joinAcrossLines for SingleButtonBarge and JoinAcrossLines features

singleButtonBarge

joinAcrossLines

Added tag for BAT/TAPS Licensing Allowance feature

isActive


Be aware that all Cisco Unified Communications Manager 6.0 AXL methods, with the exception of ExecuteSQLQuery and ExecuteSQLupdate, are backward compatible with Cisco Unified Communications Manager 6.1. By default, the interface automatically uses the 6.0 AXL schema. Developers should specify SOAPAction: "CUCM:DB ver=6.1" in the HTTP header to use any new 6.1 methods.

Changed AXL APIs for Cisco Unified Communications Manager 6.0(1)

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.

Release 6.0(1) splits some of the tables in the Cisco Unified Communications Manager database. Feature-related information moved to the corresponding dynamic tables. If the direct SQL query to which the 'executeSQLQuery' API referred uses any of the changed tables, you may need to rewrite the query according to the new database schema.

The columns enduser.password and enduser.pin from the enduser table and the applicationuser.password column from the applicationUser table moved to the credential table as credential.credentials. A direct SQL query that refers to these columns will not work in Cisco Unified Communications Manager Release 6.0(1).


Note Be aware that Cisco Unified Communications Manager password and pin fields are encrypted. Applications should not write to those fields using <executeSQLUpdate>. Instead, update passwords and pins by using the appropriate <updateXXXUser> request.


The phone API for extension mobility-related parameters has the new tag CurrentConfig. This tag is valid only for the getPhone response. The tag lets AXL provide the original device configuration and the logged-in profile information:

If a user has logged in to a device by using a device profile, the CurrentConfig tag contains the values for the extension mobility-related parameters from that device profile.

If no user has logged in, the CurrentConfig tag contains the values of the extension mobility-related parameters for the actual device.

Schema changes for the CMCInfo and FACInfo APIs help maintain consistency with other AXL APIs.

For further details about the Cisco Unified Communications Manager database schema changes, refer to Cisco Unified Communications Manager Data Dictionary for Release 6.0(1).


Note The getCCMVersion API will return the Cisco Unified Communications Manager Version based on the Node Name that is specified in the request. If no Node Name is specified, you will get the Cisco Unified Communications Manager Version of the lowest node ID Cisco Unified Communications Manager.

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.


The following AXL API calls changed in Cisco Unified Communications Manager Release 6.0(1). These changes might require changes to existing user code that is making use of them:

updateAppUser

addCallPickupGroup

updateCallPickupGroup

getCallPickupGroup

addConferenceBridge

updateConferenceBridge

getConferenceBridge

addCSS

updateCSS

getCSS

addDevicePool

In axl.xsd, the tag name aarNeighborhood and the annotation for the revertPriority tag in XDevicePool changed to match the AXL response.

In axlsoap.xsd, the tag name aarNeighborhood and the annotation for the revertPriority tag in updateDevicePoolReq changed.

updateDevicePool

In axl.xsd, the tag name aarNeighborhood and the annotation for the revertPriority tag in XDevicePool changed to match the AXL response.

In axlsoap.xsd, the tag name aarNeighborhood and the annotation for the revertPriority tag in updateDevicePoolReq changed.

getDevicePool

In axl.xsd, the tag name aarNeighborhood and the annotation for the revertPriority tag in XDevicePool changed to match the AXL response.

In axlsoap.xsd, the tag name aarNeighborhood and the annotation for the revertPriority tag in updateDevicePoolReq changed.

addDeviceProfile

updateDeviceProfile

getDeviceProfile

addGatewayEndpoint

updateGatewayEndpoint

getGatewayEndpoint

addH323Phone

updateH323Phone

getH323Phone

addH323Trunk

updateH323Trunk

getH323Trunk

addLine

updateLine

getLine

addMGCP

getMGCP

addPhone

updatePhone

getPhone

addRegion

updateRegion

getRegion

updateRegionMatrix

addRoutePartition

updateRoutePartition

getRoutePartition

addSIPTrunk

updateSIPTrunk

getSIPTrunk

addUser

updateUser

getUser

addVoiceMailPort

updateVoiceMailPort

getVoiceMailPort

doAuthenticateUser

getCMCInfo, removeCMCInfo, and updateCMCInfo

In axlsoap.xsd

A new option tag "code" along with the "uuid" tag for these three requests exists. The user can send either the uuid or code tag.

This release renames the existing tag "code" to "newCode" in the updateCMCInfo request. Users can send the new code to be updated as the "newCode" tag instead of "code" in update CMCInfo requests.

This release removes the invalid authorizationLevel tag in the updateCMCInfo request.

addFACInfo, getFACInfo, updateFACInfo, and removeFACInfo

In axl.xsd

The existing tag "description" changed to "name." This makes the addFACInfo, getFACInfo, and updateFACInfo request match the database. In previous releases, the value that was supplied for the "description" tag updated "name" in the database.

In axlsoap.xsd

A new option tag "name" along with the "uuid" tag for getFACInfo, updateFACInfo, and removeFACInfo exist.

The existing tag "description" changed to "newName" in the updateFACInfo request.

Users can send either uuid or name in the getFACInfo, updateFACInfo, and removeFACInfo requests.

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.

Changed Service Parameter for Cisco Unified Communications Manager 6.0(1)

Cisco Unified Communications Manager 6.0(1) 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.

Cisco Unified Communications Manager 5.1(1) 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.

When this parameter is True, Cisco Unified Communications Manager sends the valid namespace (https://www.cisco.com/AXL/API/1.0) in the AXL response, so the namespace matches the AXL schema specification.

If the parameter is False, Cisco Unified Communications Manager sends an invalid namespace (https://www.cisco.com/AXL/1.0) in the AXL response, which does not match the AXL schema specification.

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.

New AXL APIs for Cisco Unified Communications Manager 5.1(1)

The following list provides AXL API calls that are new in Cisco Unified Communications Manager 5.1:

addSIPRealm

updateSIPRealm

getSIPRealm

removeSIPRealm

These APIs add and update credentials (passwordreserve) in siprealm.

In addition, Cisco Unified Communications Manager Administration 5.1 release adds a new service parameter, "Send Valid Namespace in AXL Response," under the Cisco Database Layer Monitor service. This parameter determines the namespace that gets sent in the AXL response from Cisco Unified Communications Manager.

When this parameter specifies True, Cisco Unified Communications Manager sends the valid namespace (that is, http://www.cisco.com/AXL/API/1.0) in the AXL response so the namespace matches the AXL schema specification.

If the parameter specifies False, Cisco Unified Communications Manager sends an invalid namespace (that is, http://www.cisco.com/AXL/1.0) in the AXL response, which does not match the AXL schema specification.

The default service parameter value specifies False to maintain backward compatibility with the AXL response in the Cisco Unified Communications Manager 5.0 release. Cisco recommends that you set this parameter to True so Cisco Unified CallManager sends the valid namespace.

Changed AXL APIs for Cisco Unified Communications Manager 5.0(1)

The following AXL API calls are new in Cisco Unified Communications Manager 5.0:

executeSQLUpdate

doAuthenticateUser

updateAppUser

addUserGroup

updateUserGroup

removeUserGroup

getUserGroup

The following AXL API calls have been changed in Cisco Unified Communications Manager 5.0:

addPhone

updatePhone

getPhone

addGatewayEndpoint

updateGatewayEndpoint

getGatewayEndpoint

addMGCPEndpoint

updateMGCP

addSIPTrunk

updateSIPTrunk

getSIPTrunk

addCallManager

updateCallManager

getCallManager

addCallPark

addRoutePattern

updateRoutePattern

updateTransPattern

updateHuntPilot

addHuntList

updateHuntList

getHuntList

addPilotPoint

updatePilotPoint

getPilotPoint

addH323Gateway

updateH323Gateway

updateH323Phone

getH323Gateway

getH323Trunk

addUser

updateUser

getUser

updateProcessNodeService

getProcessNodeService

doDeviceLogout

listUserByName

updateServiceParameter

updateGatekeeper

updateConferenceBridge

updateAttendantConsoleHuntGroup

updateDeviceProfile

updateLine

updateLineGroup

addDevicePool

updateDevicePool

doDeviceReset

The following API calls that have been deprecated in Cisco Unified Communications Manager 5.0:

addDDI

updateDDI

removeDDI

addDialPlan

updateDialPlan

removeDialPlan

addDialPlanTag

updateDialPlanTag

removeDialPlanTag

Changed AXL APIs for Cisco Unified Communications Manager 4.2

This section describes the new or changed API calls for Cisco Unified Communications Manager 4.2(2) and a new service parameter for Cisco Database Layer Monitor. No new or changed API calls exist for Cisco Unified Communications Manager 4.2(3).

Changed API Calls

Changes to the following API calls in Cisco Unified Communications Manager 4.2(2) support the Hold Reversion feature:

addDevicePool (adds revertPriority to this request)

updateDevicePool (adds revertPriority to this request)

addLine (adds hrDuration and hrInterval to this request)

updateLine (adds hrDuration and hrInterval to this request)

Because these new tags are disabled by default, these changes are backward-compatible with existing user code.

New Service Parameter

A new service parameter, EnableAXLEncodingInfo, has been added to Cisco Unified Communications Manager Administration under the Cisco Database Layer Monitor service. This parameter enables the user to decide if AXL responses should contain encoding information. Encoding information is important if an AXL request has non-English characters in it.

Changed AXL APIs for Cisco Unified Communications Manager 4.1(2)

The following AXL API calls are new in Cisco Unified Communications Manager 4.1(2):

addTimePeriod

updateTimePeriod

removeTimePeriod

getTimePeriod

addTimeSchedule

updateTimeSchedule

removeTimeSchedule

getTimeSchedule

addCMCInfo

updateCMCInfo

removeCMCInfo

getCMCInfo

addFACInfo

updateFACInfo

removeFACInfo

getFACInfo

The following AXL API calls have been changed in Cisco Unified Communications Manager 4.1(2):

addPhone

updatePhone

getPhone

addLine

updateLine

addUser

removeUser

updateUser

getUser

addDeviceProfile

updateDeviceProfile

getDeviceProfile

addRoutePattern

updateRoutePattern

getRoutePattern

addRouteList

updateRouteList

getRouteList

addGatewayEndpoint

updateGatewayEndpoint

getGatewayEndpoint

addH323Trunk

updateH323Trunk

removeH323Trunk

getH323Trunk

addHuntPilot

updateHuntPilot

removeHuntPilot

getHuntPilot

addProcessNode

updateProcessNode

removeProcessNode

getProcessNode

listAllProcessNodes

listProcessNodesByService

addRoutePartition

updateRoutePartition

removeRoutePartition

getRoutePartition

addH323Gateway

updateH323Gateway

removeH323Gateway

getH323Gateway

addH323Phone

updateH323Phone

removeH323Phone

getH323Phone

addHuntList

updateHuntList

removeHuntList

getHuntList

AXL Schema Documentation

The axlsqltoolkit.zip plug-in contains the following five AXL schema files:

AXLAPI.wsdl

AXLEnums.xsd

axlmessage.xsd

axlsoap.xsd

axl.xsd

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:

WSDL-AXIS

WSDL-NET

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, 6.0, 6.1, and 7.0.

You can obtain complete documentation of all available AXL messages from the Cisco Developer Services web site: http://developer.cisco.com/web/axl/documentation. This website requires a Cisco.com login.

You can use the Application > Plugins > Cisco Unified Communications Manager AXL SQL Toolkit command from the Cisco Unified Communications Manager server administration interface to obtain:

AXL schema (.xsd) files

See also AXL Schema Documentation.

The WSDL file

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 The two "equals" characters (=) at the end of the string act as padding characters for Base64 encoding.


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.

The AXL interface provides Developers with direct access to the Cisco Unified Communications Manager database via the ExecuteSQLQuery and ExecuteSQLUpdate methods. While the Dynamic Throttling mechanism protects system resources when multiple update (write) requests are received, by returning a "503: Service Unavailable" error message, there is no mechanism to guard system resources when large read requests are received.

Queries issued using the ExecuteSQLQuery method that result in a data sets greater than 8 MB may place Cisco Unified Communications Manager resources at risk. Cisco recommends developers using ExecuteSQLQuery method to follow these guidelines:

Applications should break up all SQL queries so that the data returned is always less than 8 MB

Use the Cisco Unified Communications Manager 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 UCMgr 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 autologout function of extension mobility does not work when the user is logged in/out of EM via the AXL interface.


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 From the Cisco Unified Communications Manager Administration window, choose Navigation > Cisco Unified Communications Manager Serviceability.

Step 2 Choose Tools > Service Activation.

Step 3 From the Server box, choose the server and click GO.

Step 4 From Database and Admin Services, select Cisco AXL Web Service and save the changes.

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 From the Cisco Unified Communications Manager Administration window, choose User Management > UserGroup > Add New.

Step 2 To add AXP API access for the new UserGroup

a. Choose User Management > User Group.

b. Choose Role > Assign Role to Group.

c. Select Standard AXL API Access.

d. Click Add Selected.

e. On the main page, click Save.

Step 3 To add a user to the new UserGroup

a. Choose User Management > User Group.

b. Choose UserGroup > Add End Users to Group.

c. Select the user and click Add Selected.


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 If the AXL client application cannot connect to the AXL service, check the following

Is the AXL application configured with the correct IP address for the AXL server?

Is the AXL application configured with the appropriate AXL user credentials?

Does the application server have HTTPS connectivity to the AXL server?

Use this URL for accessing AXL: https://server-name:port/axl/ (port is 8443).

Is HTTPS (secure) configured for AXL?

Step 2 Verify basic AXL functionality by performing the procedure that follows:

1. Go to the AXL API URL via a web browser.

For instance, enter https://server-name:8443/axl/ in the address text box.

2. When prompted for user name and password, use the standard administrator login, or use the user name that is associated with a user group that is assigned the AXL role.

3. Look for a plain page that states the AXL listener is working and accepting requests but only communicates via POST.

This procedure verifies functionality and user access.

Step 3 If the AXL functions or requests are failing with error as User Authorization error: "Access to the requested resource has been denied," check whether the user has the permission to the Standard AXL API Access. You can check this from the Permission Information section of the EndUser configuration window.

Step 4 If the AXL functions or requests are failing, check the following

AXL logs for AXL or SOAP error responses. See the "AXL Error Codes" section.

For further debugging, you can view the AXL log files with the RTMT application.

Step 5 Check that applications in a cluster configuration are connected to the AXL service only on the Cisco Unified Communications Manager Publisher server if the application needs to modify the database.


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 If an AXL login request contains a <password> tag with an xmlns attribute value, versions of the AXL API prior to 6.0(1) or 5.1(2) log the password in clear text. In later versions of the API, the system replaces the password with an "*" character.

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,

Determine which log file is currently active by timestamp.

Look for Exception traces that indicate processing errors.

If no traces are being added, verify that Tomcat is running, AXL is currently activated, and a client application is attempting to communicate with the AXL API.

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.203
2007-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/7.0" 
xmlns:axl="http://www.cisco.com/AXL/7.0" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.cisco.com/AXL/API/7.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 initializing
2007-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/7.0 
xmlns:xsi="http://www.cisco.com/AXL/7.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 356ms
 
   

The AXL trace log contains:

Time that the request was received - 05:32:26,512

Client IP address - IP 10.77.31.203

Client user ID - CCMAdministrator

Request ID number - 1173323669700

Request contents - addGatekeeper, <gatekeeper>, <name>, and so on

Response contents - <name>

Time taken for the response - 356 ms

Follow these steps to set the AXL trace level from the Serviceability window:


Step 1 From the Cisco Unified Communications Manager Administration window, choose Application > Cisco Unified Communications Manager Serviceability.

Step 2 Choose Trace > Configuration.

Step 3 From the Servers column, select the server and click GO.

Step 4 From the Service Group box, select Database And Admin Services and click GO.

Step 5 From the Services box, select the Cisco AXL Web Service and click GO.

Step 6 Check the Trace On check box.

Step 7 If you want the trace to apply to all Cisco Unified Communications Manager servers in the cluster, select the Apply to All Nodes check box.

Step 8 From the Debug Trace Level field, select Debug.

Step 9 You can set trace output options from the same window.



Note You should enable AXL logs only on request from Cisco TAC or Cisco Developer Services.


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._7_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._7_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 constructor
	public 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.xsd
 
   

This command generates the file AXLAPIService.cs. The class AXLAPIService in AXLAPIService.cs requires at least three changes:

1. Create an ICertificatePolicy-derived class, which will later be associated with our service. This class represents a brute-force approach to policy and certificate management. You need to use this method in 5.x and 6.x AXL due to the use of HTTPS.

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. Modify the service constructor to take username/password credentials, with the Cisco Unified Communications Manager IP address as an argument, and associate the BruteForcePolicy class with the static CertificatePolicy manager.

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. The .NET framework uses the expects header differently (http://issues.apache.org/bugzilla/show_bug.cgi?id=31567). Several possible workarounds exist to this problem:

a. Override the GetWebRequest method to use HTTP 1.0 due to an error between TOMCAT/AXIS and the .NET HTTP 1.1 Web Service request mechanism.

protected override System.Net.WebRequest GetWebRequest(Uri uri)
{
	System.Net.HttpWebRequest request = base.GetWebRequest (uri) as 
		System.Net.HttpWebRequest;
	request.ProtocolVersion = System.Net.HttpVersion.Version10; 
 
   
	return request;
}

b. Override the GetWebRequest method to manually embed the authentication string. If you do this, do not use the line

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. If you use wsdl2wse (WSE library) instead of wsdl.exe, you cannot override the HTTP version or supply HTTP headers manually. To use WSE, you must set the keepalive header to false for the generated class, or set the user-agent to restricted. This technique will work as an alternative to steps a and b.

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/7.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/7.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/7.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. Whether the SOAPAction attribute in the HTTP header had the value "CUCM:DB ver=7.0."

2. The value of the "Send Valid Namespace in AXL Response" service parameter in the Cisco Unified Communications Manager Administration Service Parameter window.

If the SOAPAction attribute in the HTTP header has the value "CUCM:DB ver=7.0":

The AXL response will have the namespace value that the "Send Valid Namespace in AXL Response" service parameter specifies: either http://www.cisco.com/AXL/API/7.0 or http://www.cisco.com/AXL/7.0.

If you set the service parameter "Send Valid Namespace in AXL Response" to true, the namespace that is returned in the AXL response will be http://www.cisco.com/AXL/API/7.0, which will match the namespace that is specified in AXLAPI.wsdl.

If you set this service parameter to False, the namespace that is returned in the AXL response will be http://www.cisco.com/AXL/7.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.

Example AXL Requests

No platform considerations exist in Cisco Unified Communications Manager Release 7.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.

POST :8443/axl/

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.

content-type: text/xml

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.

Authorization: Basic <some Base 64 encoded string>

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.

content-length: <a positive integer>

The fourth header specifies the length (in bytes) of the AXL request.


Note If a request that is greater than 40 kilobytes is received, the system returns an HTTP 413 error message.


The following example contains an HTTPS header for an AXL SOAP request:

POST :8443/axl/
Host: axl.myhost.com:8443
Accept: text/*
Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==
Content-type: text/xml
SOAPAction: "CUCM:DB ver=7.0"
Content-length: 613
 
   

The 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:8443
Accept: text/*
Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==
Content-type: text/xml
SOAPAction: "CUCM:DB ver=7.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/7.0" 
xsi:schemaLocation="http://www.cisco.com/AXL/7.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;
}
 
   
void
BuildDeviceNameSQL(string &buf,  // Buffer to build AXL
                                   string& deviceNumber, // DN
                                   string& seqNum )
{
    const int BUFSIZE = 2048;
    char buff[BUFSIZE];           // Temp buffer
    string strHTTPHeader;         // HTTP/AXL Header
    string strAXLRequest;         // AXL Request
 
   
    strAXLRequest = "<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/7.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=7.0\"\r\n";
    strHTTPHeader += "Content-length: ";
 
   
    // temporarily use the buffer to store the length of the request
    sprintf( buff, "%d", strAXLRequest.length() );
 
   
    strHTTPHeader += buff;
    strHTTPHeader += "\r\nConnection: Keep-Alive";
    strHTTPHeader += "\r\n\r\n";
 
   
    // put the HTTP header and SOAP XML together
    buf = 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);
   }
   else
     printf("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);
   else
     printf("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");
   else
     printf("\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 from
		Socket socket = null; // socket to AXL server
		OutputStream out = null; // output stream to server
		InputStream in = null; // input stream from server
 
   
		String sAXLSOAPRequest = "";
		// HTTPS header and SOAP payload
		String sAXLRequest = null; // will hold only the SOAP payload
		//username=CCMAdministrator and password=cisco_cisco
		String authorization = "CCMAdministrator" + ":" + "cisco_cisco";
		// base64 encoding of the username and password
		authorization = new sun.misc.BASE64Encoder().encode(authorization.getBytes());
		// Form the http header
		sAXLSOAPRequest = "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=7.0\"\r\n";
		sAXLSOAPRequest += "Content-length: ";
 
   
		// Build the SOAP payload
		sAXLRequest = "<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/7.0\" ";
		sAXLRequest += " xsi:schemaLocation=\"http://www.cisco.com/AXL/7.0 http:// 
ccmserver/schema/axlsoap.xsd\" ";
		sAXLRequest += "sequence=\"1234\"> <phoneName>SEP000000000009</phoneName>";
		sAXLRequest += "</axl:getPhone> </SOAP-ENV:Body> </SOAP-ENV:Envelope>";
 
   
 
   
		// finish the HTTPS Header
		sAXLSOAPRequest += sAXLRequest.length();
		sAXLSOAPRequest += "\r\n\r\n";
 
   
		// now add the SOAP payload to the HTTPS header, which completes the AXL
		// SOAP request
		sAXLSOAPRequest += sAXLRequest;
		try {
			AXLJavaClient axl = new AXLJavaClient();
			// Implement the certificate-related stuffs required for sending request via https
			X509TrustManager 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 server
			StringBuffer 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 output
			System.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 executeSQLUpdate

This example illustrates the use of the executeSQLUpdate request:

POST :8443/axl/ 
Host: axl.myhost.com:8443
Accept: text/*
Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==
Content-type: text/xml
SOAPAction: "CUCM:DB ver=7.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/7.0" xmlns:axl="http://www.cisco.com/AXL/7.0" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.cisco.com/AXL/API/7.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:8443
Accept: text/*
Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==
Content-type: text/xml
SOAPAction: "CUCM:DB ver=7.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/7.0" 
xmlns:axl="http://www.cisco.com/AXL/API/7.0" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.cisco.com/AXL/API/7.0 axlsoap.xsd">
            <sql>SELECT * from numplan</sql>
        </axlapi:executeSQLQuery>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
 
   

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. For 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>Device not found with name SEP003094C39708.</faultstring> 
            <detail xmlns:axl="http://www.cisco.com/AXL/7.0" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xsi:schemaLocation="http://www.cisco.com/AXL/API/7.0 
            http://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>
 
   

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/7.0" 
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
                     xsi:schemaLocation="http://www.cisco.com/AXL/7.0 
                    http://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 user agent uses the <code> element, a numerical value, to find what type of error occurred.

The following table explains the error codes that the <code> tag might have:

Error Code
Description
5000

Unknown Error—An unknown error occurred while the request was processed. This can occur due to a problem on the server but can also be due to errors in the request.

5002

Unknown Request Error—The user agent submitted a request that is unknown to the API.

5003

Invalid Value Exception—The API detected an invalid value in the XML request.

5007

Item Not Valid Error—The system identified the specified item as invalid, which means that it does not exist or that it was specified incorrectly at input.


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.