Cisco Unified Communications Manager XML Developers Guide Release 7.1(2)
Administrative XML API
Downloads: This chapterpdf (PDF - 544.0KB) The complete bookPDF (PDF - 7.76MB) | Feedback

Administrative XML Programming

Table Of Contents

Administrative XML Programming

Overview

New and Changed Information

New Information for Cisco Unified Communications Manager 7.1(2)

New APIs

Changed Operations

New Information for Cisco Unified Communications Manager 7.0(1)

New APIs

Changed Operations

Dynamic Throttling of Requests

New Information for Cisco Unified Communications Manager 6.1 (1)

New Information for Cisco Unified Communications Manager 6.0(1)

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

New Information for Cisco Unified Communications Manager 5.1(1)

New Information for Cisco Unified Communications Manager 5.0(1)

New Information for Cisco Unified Communications Manager 4.2(2)

Changed API Calls

New Service Parameter

New Information for Cisco Unified Communications Manager 4.1(2)

AXL Schema Documentation

AXL Versioning Support

Authentication

Data Encryption

Dynamic Throttling of Requests

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

AXL Versioning Support

Data Encryption

Dynamic Throttling of Requests

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 (Unified CM) 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://www.cisco.com/pcgi-bin/dev_support/access_level/product_support.

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 describe the major changes in the AXL APIs for Release 7.1(2) and for previous releases:

New Information for Cisco Unified Communications Manager 7.1(2)

New Information for Cisco Unified Communications Manager 7.0(1)

New Information for Cisco Unified Communications Manager 6.1 (1)

New Information for Cisco Unified Communications Manager 6.0(1)

New Information for Cisco Unified Communications Manager 5.1(1)

New Information for Cisco Unified Communications Manager 5.0(1)

New Information for Cisco Unified Communications Manager 4.2(2)

New Information for Cisco Unified Communications Manager 4.1(2)

For information about new, changed, or deprecated AXL API methods from the interface library, see Chapter 3, "Administrative XML Operations by Release".

New Information for Cisco Unified Communications Manager 7.1(2)

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

The following sections describe API updates that were made in Cisco Unified Communications Manager 7.1(2):

New APIs

Changed Operations

New APIs

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

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

Operation
Purpose
Added Tags

addGeoLocation

updateGeoLocation

getGeoLocation

removeGeoLocation

Added for logical partitioning feature.

name(mandatory)
country
description
nationalSubdivision
district
communityName
cityDivision
neighbourhood
street
leadingStreetDirection
trailingStreetSuffix
streetSuffix
houseNumber
houseNumberSuffix
landmark
location
floor
occupantName
postalCode

addGeoLocationPolicy

updateGeoLocationPolicy

getGeoLocationPolicy

removeGeoLocationPolicy

Added for logical partitioning feature.

name(mandatory)
country
description
nationalSubdivision
district
communityName
cityDivision
neighbourhood
street
leadingStreetDirection
trailingStreetSuffix
streetSuffix
houseNumber
houseNumberSuffix
landmark
location
floor
occupantName
postalCode
relatedPolicies, relatedPolicy,
geoLocationPolicyA
geoLocationPolicyAName
geoLocationDeviceA
geoLocationPolicyB
geoLocationPolicyBName
geoLocationDeviceB
logicalPartitionPolicy

addGeoLocationFilter

updateGeoLocationFilter

getGeoLocationFilter

removeGeoLocationFilter

Added for logical partitioning feature.

name
description
useCountry
useNationalSubDivision
useDistrict
useCommunityName
useCityDivision
useNeighbourhood
useStreet
useLeadingStreetDirection
useTrailingStreetSuffix
useStreetSuffix
useHouseNumber
useHouseNumberSuffix
useLandmark
useLocation
useFloor
useOccupantName
usePostalCode

addCommonPhoneConfig

updateCommonPhoneConfig

getCommonPhoneConfig

removeCommonPhoneConfig

Added for phone support feature.

name
description
unlockPwd
dndOption
dndAlertingType
backgroundImage
phonePersonalization
phoneServiceDisplay
sshUserId
sshPwd
alwaysUsePrimeLine
alwaysUsePrimeLineforVoiceMessage
vendorConfig


Changed Operations

Table 2-2 describes changed operations in Cisco Unified Communications Manager 7.1(2).

Table 2-2 Changed Operations in Cisco Unified Communications Manager 7.1(2) 

Operation
Change
Tags

addLine

updateLine

getLine

Added optional tags for park monitoring feature.

ParkMonForwardNoRetrieveDN
ParkMonForwardNoRetrieveIntDN
ParkMonForwardNoRetrieveIntVMEnabled
ParkMonForwardNoRetrieveVMEnabled
ParkMonForwardNoRetrieveCSS
ParkMonForwardNoRetrieveIntCSS
ParkMonReversionTimer

addLine

updateLine

getLine

Added optional tag for barge enchancement feature.

partyEntranceTone

addHuntPilot

updateHuntPilot

getHuntPilot

Added optional tags for park monitoring feature.

ParkMonForwardNoRetrieveDN
ParkMonForwardNoRetrieveCSS

addH323Gateway

updateH323Gateway

getH323Gateway

Added optional tags for H.235 - H.323 security: voice encryption profile with native H.235/H.245 key management feature.

AllowH235PassThrough

Added optional tags for logical partitioning feature.

geoLocationName
geoLocationFilterName
sendGeoLocation

Added optional tags for QSIG variant Per Trunk or Gateway feature.

ASN1ROSEOIDEncoding
QSIGVariant
tunneledProtocol

 

Added optional tags for more enhancements to CPN transformations.

nationalStripDigits
internationalStripDigits
unknownStripDigits
subscriberStripDigits
cgpnTransformationNationalCSS
cgpnTransformationInternationalCSS
cgpnTransformationUnknownCSS
cgpnTransformationSubscriberCSS
useDevicePoolCgpnTransformNationalCSS
useDevicePoolCgpnTransformInternationalCSS
useDevicePoolCgpnTransformUnknownCSS
useDevicePoolCgpnTransformSubscriberCSS

addH323Trunk

updateH323Trunk

getH323Trunk

Added optional tag for H.235 - H.323 security: voice encryption profile with native H.235/H.245 key management feature.

AllowH235PassThrough

Added optional tags for logical partitioning feature.

geoLocationName
geoLocationFilterName
sendGeoLocation

Added optional tags for QSIG variant per trunk or gateway feature.

ASN1ROSEOIDEncoding
QSIGVariant

Added optional tags for more enhancements to CPN transformations.

nationalStripDigits
internationalStripDigits
unknownStripDigits
subscriberStripDigits
cgpnTransformationNationalCSS
cgpnTransformationInternationalCSS
cgpnTransformationUnknownCSS
cgpnTransformationSubscriberCSS
useDevicePoolCgpnTransformNationalCSS
useDevicePoolCgpnTransformInternationalCSS
useDevicePoolCgpnTransformUnknownCSS
useDevicePoolCgpnTransformSubscriberCSS

addCommonDeviceConfig

updateCommonDeviceConfig

getCommonDeviceConfig

Added optional tags for IPv6 feature.

IPAddressingMode
IPAddressingModePreferenceControl allowAutoConfigurationForPhones

addSIPProfile

updateSIPProfile

getSIPProfile

Added optional tag for IPv6 feature.

enableAnatForEarlyOfferCalls

Added optional tag called to enhance Clear Channel (G.clear) support feature.

gClear

addProcessNode

updateProcessNode

getProcessNode

Added optional tag for IPv6 feature.

IPv6Name

addSIPRoutePattern

updateSIPRoutePattern

getSIPRoutePattern

Added optional tag for IPv6 feature.

dnOrPatternIPv6

addPhone

updatePhone

getPhone

Added optional tags for logical partitioning feature.

geoLocationName
geoLocationFilterName
sendGeoLocation

Added optional tags for always-use- primeline feature.

alwaysUsePrimeLine alwaysUsePrimeLineforVoiceMessage

addH323Phone

updateH323Phone

getH323Phone

Added optional tags for logical partitioning feature.

geoLocationName
geoLocationFilterName
sendGeoLocation

addGatewayEndpoint

updateGatewayEndpoint

getGatewayEndpoint

Added optional tags for logical partitioning feature.

geoLocationName
geoLocationFilterName
sendGeoLocation

Added optional tags for QSIG variant per trunk or gateway feature.

ASN1ROSEOIDEncoding
QSIGVariant

Added optional tags to enhance the CPN transformations feature.

nationalStripDigits
internationalStripDigits
unknownStripDigits
subscriberStripDigits
cgpnTransformationNationalCSS
cgpnTransformationInternationalCSS
cgpnTransformationUnknownCSS
cgpnTransformationSubscriberCSS
useDevicePoolCgpnTransformNationalCSS
useDevicePoolCgpnTransformInternationalCSS
useDevicePoolCgpnTransformUnknownCSS
useDevicePoolCgpnTransformSubscriberCSS

addMGCP

updateMGCP

getMGCP

Added optional tags for logical partitioning feature.

geoLocationName
geoLocationFilterName
sendGeoLocation

addMGCPEndpoint

updateMGCPEndpoint

getMGCPEndpoint

Added optional tags for logical partitioning feature.

geoLocationName
geoLocationFilterName
sendGeoLocation

Added optional tags for QSIG variant per trunk or gateway feature.

ASN1ROSEOIDEncoding
QSIGVariant

Added optional tags for enhancements to CPN transformations.

nationalStripDigits
internationalStripDigits
unknownStripDigits
subscriberStripDigits
cgpnTransformationNationalCSS
cgpnTransformationInternationalCSS
cgpnTransformationUnknownCSS
cgpnTransformationSubscriberCSS
useDevicePoolCgpnTransformNationalCSS
useDevicePoolCgpnTransformInternationalCSS
useDevicePoolCgpnTransformUnknownCSS
useDevicePoolCgpnTransformSubscriberCSS

addSIPTrunk

updateSIPTrunk

getSIPTrunk

Added optional tags for logical partitioning feature.

geoLocationName
geoLocationFilterName
sendGeoLocation

Added optional tag for IPv6 feature.

destinationAddressIPv6

Added optional tags for enhancements to CPN transformations.

unknownStripDigits cgpnTransformationUnknownCSS
useDevicePoolCgpnTransformUnknownCSS

addVG224

updateVG224

getVG224

Added optional tags for logical partitioning feature.

geoLocationName
geoLocationFilterName
sendGeoLocation

addDevicePool

updateDevicePool

getDevicePool

Added optional tags for logical partitioning feature.

geoLocationName
geoLocationFilterName

Added optional tags for enhancements to CPN transformations.

nationalStripDigits
internationalStripDigits
unknownStripDigits
subscriberStripDigits
cgpnTransformationNationalCSS
cgpnTransformationInternationalCSS
cgpnTransformationUnknownCSS
cgpnTransformationSubscriberCSS

addCommonPhoneConfig

updateCommonPhoneConfig

getCommonPhoneConfig

Added optional tags for always-use- primeline feature.

alwaysUsePrimeLine
alwaysUsePrimeLineforVoiceMessage

addDeviceProfile

updateDeviceProfile

getDeviceProfile

Added optional tags for always-use- primeline feature.

alwaysUsePrimeLine
alwaysUsePrimeLineforVoiceMessage


New Information for Cisco Unified Communications Manager 7.0(1)

Cisco Unified Communications Manager 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 7.0(1):

New APIs

Changed Operations

New APIs

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

Table 2-3 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 type

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
digestCredentials
presenceGroup
presenceGroupName
acceptPresenceSubscription
acceptOutOfDialogRefer
acceptUnsolicitedNotification
allowReplaceHeader
isStandard
associatedDevices
associatedGroups
associatedCAPFProfiles

updateApplicationUser

Added for updating application users

userid
password
passwordCredentials
digestCredentials
presenceGroup
presenceGroupName
acceptPresenceSubscription
acceptOutOfDialogRefer
acceptUnsolicitedNotification
allowReplaceHeader
associatedDevices
associatedGroups

removeApplicationUser

Added for removing existing application users

userid

getApplicationUser

Added for obtaining details about application users

userid


Changed Operations

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

Table 2-4 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
allingPartyNumberType

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


Dynamic Throttling of Requests

Cisco Unified Communications Manager 7.0 includes a new throttling mechanism called dynamic throttling of request. The MaxAXLWritesPerMinute service parameter, used in earlier releases, has been deprecated. For more information see, Dynamic Throttling of Requests.

New Information for Cisco Unified Communications Manager 6.1 (1)

Table 2-5 describes the API calls that changed in Cisco Unified Communications Manager 6.1(1). These changes may require updates to the existing user-code that uses these APIs.

Table 2-5 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



Note All Unified CM 6.0 AXL methods, with the exception of ExecuteSQLQuery and ExecuteSQLupdate, are backward compatible with Unified CM 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.


New Information 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 may require changes to the existing user-code that uses these APIs:

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

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.

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 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 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 Information 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(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 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 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.

New Information for Cisco Unified Communications Manager 5.0(1)

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

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

New Information for Cisco Unified Communications Manager 4.2(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.

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.

New Information 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. 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

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, at http://www.cisco.com/en/US/products/sw/voicesw/ps556/products_programming_reference_guides_list.html, 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 2-6 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.

AXL Policy Under Consideration For Future Release

The following policies related to AXL versioning support is under consideration for future release:

AXL schema versioning will continue indefinitely.

AXL schemas will be available for two major Unified CM release cycles, such that AXL applications will require minor updates every two years.

Future release of Unified CM will have AXL schemas 8.0, 7.1, 7.0, and 6.1. The current AXL 6.0 schema will be removed.

The default AXL schema will change, in the next major Unified CM release, from the current 6.0 schema to the 6.1 schema.

Developers who do not request a specific AXL schema will always connect to the oldest schema available.

Developers can request other available AXL schemas by specifying the AXL schema version in the SOAP Action Header.

Table 2-6 AXL Versioning and Schema Plan

   
AXL Request no version specified
AXL Request with Version Specified
   

CUCM:DB ver=6.0(

CUCM:DB ver=6.1

CUCM:DB ver=7.0

CUCM:DB ver=7.1

Plus 1 release
Plus 2 release
Cisco Unified Communications Manager Release
Release 6.0(1)

6.0 schema applied

6.0 schema applied

 
Release 6.1(0)

6.0 schema applied

6.0 schema applied

6.1 schema applied

Not Applicable
Release 7.0(1)

6.0 schema applied

6.0 schema applied

6.1 schema applied

7.0 schema applied

   
Release 7.1(2)

6.0 schema applied

6.0 schema applied

6.1 schema applied

7.0 schema applied

7.1 schema applied

   
Plus 1 releases

6.1 schema applied

 

6.1 schema applied

7.0 schema applied

7.1 schema applied

Plus 1 schema applied

 
Plus 2 releases
7.0 schema applied
   

7.0 schema applied

7.1 schema applied

Plus 1 schema applied

Plus 2 schema applied

Plus 3 releases
7.1 schema applied

Schema no longer available

 

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

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.

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.

Table 2-7 AXL Query Limits

Writes Per Minute

Maximunm of 1500 Write requests

Reads Per Minute

No limit for Read requests.

Total Records

No limits for total number of records. But size of total recordes must be less than 8MB per request and 16MB is the maximum buffer allocated for parallel processing of requests.



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.


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 (http://www.cisco.com/en/US/products/sw/voicesw/ps556/products_programming_reference_guides_list.html) 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 Unified CM database, the original WSDL that was sent out for that Unified CM 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.