Cisco Unified Communications Manager XML Developers Guide Release 8.0(1)
Overview
Downloads: This chapterpdf (PDF - 199.0KB) The complete bookPDF (PDF - 12.51MB) | Feedback

Overview

Table Of Contents

Overview

Cisco Unified Communications Manager Interfaces

Provisioning Interfaces

Administrative XML

Cisco Extension Mobility

Device Monitoring and Call Control Interfaces

Cisco TAPI and Wave Driver

Cisco JTAPI

Cisco Web Dialer

Serviceability Interfaces

Serviceability XML

SNMP/MIBs

Routing Rules Interface

Development Guidelines

What is New in Cisco Unified Communications Manager 8.0 (1) API

Administrative XML API

Serviceability XML API

Extension Mobility API

Web Dialer API

Routing Rules API


Overview


Cisco Unified Communications Manager (Unified CM) is the powerful call-processing component of the Cisco Unified Communications Solution. It is a scalable, distributable, and highly available enterprise IP telephony call-processing solution. Unified CM acts as the platform for collaborative communication and as such supports a wide array of features. In order to provision, invoke the features, monitor, and control such a powerful system, Unified CM supports different interface types.

This chapter gives an introduction to the different interfaces of Unified CM and includes the following sections:

Cisco Unified Communications Manager Interfaces

Development Guidelines

What is New in Cisco Unified Communications Manager 8.0 (1) API

Cisco Unified Communications Manager Interfaces

The interface types supported by Unified CM are divided into the following types:

Provisioning Interfaces

Device Monitoring and Call Control Interfaces

Serviceability Interfaces

Routing Rules Interface

Provisioning Interfaces

The following are the provisioning interfaces of Unified CM:

Administration XML

Cisco Extension Mobility service

Administrative XML

The Administration XML (AXL) API provides a mechanism for inserting, retrieving, updating and removing data from the Unified CM configuration database using an eXtensible Markup Language (XML) Simple Object Access Protocol (SOAP) interface. This allows a programmer to access Unified CM provisioning services using XML and exchange data in XML form, instead of using a binary library or DLL. The AXL methods, referred to as requests, are performed using a combination of HTTP and SOAP. SOAP is an XML remote procedure call protocol. Users perform requests by sending XML data to the Unified CM Publisher server. The publisher then returns the AXL response, which is also a SOAP message.

This guide gives detailed information on the AXL API see Part 1, Administrative XML.

For more information, see the Administrative XML Tech Center on the Cisco Developer Network at http://developer.cisco.com/web/axl/home

Cisco Extension Mobility

The Cisco Extension Mobility (Extension Mobility) service, a feature of Unified CM, allows a device, usually a Cisco Unified IP Phone, to temporarily embody a new device profile, including lines, speed dials, and services. It enables users to temporarily access their individual Cisco Unified IP Phone configuration, such as their line appearances, services, and speed dials, from other Cisco Unified IP Phones. The Extension Mobility service works by downloading a new configuration file to the phone. Unified CM dynamically generates this new configuration file based on information about the user who is logging in. You can use the XML-based Extension Mobility service API with your applications, so they can take advantage of Extension Mobility service functionality.

This guide gives detailed information on the Extension Mobility APIs, see Part 3, Extension Mobility Service API.

For more information, see the Extension Mobility API Tech Center on the Cisco Developer Network at http://developer.cisco.com/web/emapi/home

Device Monitoring and Call Control Interfaces

The following are the device monitoring and call control interfaces of Unified CM:

Cisco TAPI and Wave Driver

Cisco JTAPI

Cisco Web Dialer

Cisco TAPI and Wave Driver

Unified CM exposes sophisticated call control of IP telephony devices and soft-clients via the Computer Telephony TAPI interface. Cisco's Telephone Service Provider (TSP) and Wave Driver interface enables custom applications to monitor telephony-enabled devices and call events, establish first- and third-party call control, and interact with the media layer to terminate media, play announcements, record calls.

Information on Cisco TAPI and Wave Driver is beyond the scope of this guide. For information of Cisco TAPI and Wave Driver, see Cisco Unified TAPI Developers Guide for Cisco Unified Communications Manager for relevant release of Unified CM at the following location:

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

For more information, see the TAPI and Wave Driver Tech Center on the Cisco Developer Network at http://developer.cisco.com/web/tapi/home

Cisco JTAPI

Unified CM exposes sophisticated call control of IP telephony devices and soft-clients via the Computer Telephony JTAPI interface. Cisco's JTAPI enables custom applications to monitor telephony-enabled devices and call events, as well as establish first- and third-party call control.

Information on Cisco JTAPI is beyond the scope of this guide. For information on Cisco JTAPI, see Cisco Unified JTAPI Developers Guide for Cisco Unified Communications Manager for relevant release of Unified CM at the following location:

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

For more information, see the JTAPI Tech Center on the Cisco Developer Network at http://developer.cisco.com/web/jtapi/home

Cisco Web Dialer

The Web Dialer, which is installed on a Unified CM server, allows Cisco Unified IP Phone users to make calls from web and desktop applications. For example, the Web Dialer uses hyper linked telephone numbers in a company directory to allow users to make calls from a web page by clicking the telephone number of the person that they are trying to call. The two main components of Web Dialer comprise the Web Dialer Servlet and the Redirector Servlet.

This guide gives detailed information on the Web Dialer API, see Part 4, Web Dialer API.

For more information, see the Web Dialer Tech Center on the Cisco Developer Network at http://developer.cisco.com/web/wd/home

Serviceability Interfaces

The following are the serviceability interfaces of Unified CM:

Serviceability XML

SNMP/MIBs

Serviceability XML

A collection of services and tools designed to monitor, diagnose, and address issues specific to Unified CM. Serviceabiltiy XML interface:

Provides platform, service and application performance counters to monitor the health of Unified CM hardware and software

Provides real-time device and CTI connection status to monitor the health of phones, devices, and applications connected to Unified CM.

Enables remote control (Start/Stop/Restart) of Unified CM services.

Collects and packages Unified CM trace files and logs for troubleshooting and analysis.

Provides applications with Call Detail Record files based on search criteria.

Provides management consoles with SNMP data specific to Unified CM hardware and software.

This guide gives detailed information on the Serviceability XML APIs, see Part 2, Serviceability XML.

For more information, see the Serviceability XML Tech Center on the Cisco Developer Network at http://developer.cisco.com/web/sxml/home

SNMP/MIBs

SNMP interface allows external applications to query and report various Unified CM entities. It provides information on the connectivity of the Unified Communication Manager to other devices in the network, including syslog information.

The MIBs supported by Unified CM includes:

Cisco-CCM-MIB, CISCO-CDP-MIB, Cisco-syslog-MIB

Standard MIBs like MIB II, SYSAPPL-MIB, HOST RESOURCES-MIB

Vendor MIBs

For more information, see the SNMP/MIB Tech Center on the Cisco Developer Network at http://developer.cisco.com/web/sxml/home

Routing Rules Interface

Cisco Unified Communication Manager 8.0(1) supports the external call control (ECC) feature, which enables an adjunct route server to make call-routing decisions for Cisco Unified Communications Manager by using the 8.0(1) Cisco Unified Routing Rules Interface. When you configure external call control, Cisco Unified Communications Manager issues a route request that contains the calling party and called party information to the adjunct route server. The adjunct route server receives the request, applies appropriate business logic, and returns a route response that instructs Cisco Unified Communications Manager on how the call should get routed, along with any additional call treatment that should be applied.

For more information, see the Routing Rules Interface Tech Center on the Cisco Developer Network at http://developer.cisco.com/web/curri/home

Development Guidelines

Cisco maintains a policy of interface backward compatibility for at least one previous major release of Cisco Unified Communications Manager (Cisco Unified CM). Cisco still requires Cisco Technology Developer Program member applications to be retested and updated as necessary to maintain compatibility with each new major release of Cisco Unified CM.

The following practices are recommended to all developers, including those in the Cisco Technology Developer Program, to reduce the number and extent of any updates that may be necessary:

The order of events and/or messages may change. Developers should not depend on the order of events or messages. For example, where a feature invocation involves two or more independent transactions, the events or messages may be interleaved. Events related to the second transaction may precede messages related to the first. Additionally, events or messages can be delayed due to situations beyond control of the interface (for example, network or transport failures). Applications should be able to recover from out of order events or messages, even when the order is required for protocol operation.

The order of elements within the interface event or message may change, within the constraints of the protocol specification. Developers must avoid unnecessary dependence on the order of elements to interpret information.

New interface events, methods, responses, headers, parameters, attributes, other elements, or new values of existing elements, may be introduced. Developers must disregard or provide generic treatments where necessary for any unknown elements or unknown values of known elements encountered.

Previous interface events, methods, responses, headers, parameters, attributes, and other elements, will remain, and will maintain their previous meaning and behavior to the extent possible and consistent with the need to correct defects.

Applications must not be dependent on interface behavior resulting from defects (behavior not consistent with published interface specifications) since the behavior can change when defect is fixed.

Use of deprecated methods, handlers, events, responses, headers, parameters, attributes, or other elements must be removed from applications as soon as possible to avoid issues when those deprecated items are removed from Cisco Unified CM.

Application Developers must be aware that not all new features and new supported devices (for example, phones) will be forward compatible. New features and devices may require application modifications to be compatible and/or to make use of the new features/devices.

What is New in Cisco Unified Communications Manager 8.0 (1) API

This section gives information about the changes in the following APIs for the Unified CM release 8.0 (1):

Administrative XML API

Serviceability XML API

Extension Mobility API

Web Dialer API

Routing Rules API


Note Information on Cisco JTAPI and Cisco TAPI and Wave Driver API changes are beyond the scope of this guide.
For information of Cisco TAPI and Wave Driver, see Cisco Unified TAPI Developers Guide for Cisco Unified Communications Manager and for information on Cisco JTAPI, see Cisco Unified JTAPI Developers Guide for Cisco Unified Communications Manager for relevant release of Unified CM at the following location:
http://www.cisco.com/en/US/products/sw/voicesw/ps556/products_programming_reference_guides_list.html


Administrative XML API

The following are the changes in Administrative XML APIs for Unified CM release 8.0(1):

The following new APIs are added:

add UserPhoneAssociation

add/get/remove/update AppDialRules

add/get/remove/update ApplicationServer

add/get/remove/update ApplicationUserCapfProfile

add/get/remove/update AppServerInfo

add/get/remove/update CallingPartyTransformationPattern

add/get/remove/update CcdAdvertisingService

add/get/remove/update CcdHostedDN

add/get/remove/update CcdHostedDNGroup

add/get/remove/update CcdRequestingService

add/get/remove/update CiscoCatalyst600024PortFXSGateway

add/get/remove/update CiscoCatalyst6000E1VoIPGateway

add/get/remove/update CiscoCatalyst6000T1VoIPGatewayPri

add/get/remove/update CiscoCatalyst6000T1VoIPGatewayT1

add/get/remove/update CiscoCatalyst6000T1VoIPGatewayT1

add/get/remove/update CumaServerSecurityProfile

add/get/remove/update DateTimeGroup

add/get/remove/update DefaultDeviceProfile

add/get/remove/update DirectoryLookupDialRules

add/get/remove/update EndUserCapfProfile

add/get/remove/update ExternalCallControlProfile

add/get/remove/update FallbackProfile

add/get/remove/update Gateway

add/get/remove/update GatewayEndpointAnalogAccess

add/get/remove/update GatewayEndpointDigitalAccessBri

add/get/remove/update GatewayEndpointDigitalAccessPri

add/get/remove/update GatewayEndpointDigitalAccessT1

add/get/remove/update ImeClient

add/get/remove/update ImeE164Transformation

add/get/remove/update ImeEnrolledPattern

add/get/remove/update ImeEnrolledPatternGroup

add/get/remove/update ImeExclusionNumber

add/get/remove/update ImeExclusionNumberGroup

add/get/remove/update ImeFirewall

add/get/remove/update ImeRouteFilterElement

add/get/remove/update ImeRouteFilterGroup

add/get/remove/update ImeServer

add/get/remove/update IpPhoneServices

add/get/remove/update LdapDirectory

add/get/remove/update MessageWaiting

add/get/remove/update MlppDomain

add/get/remove/update Mtp

add/get/remove/update PhoneNTP

add/get/remove/update PhoneSecurityProfile

add/get/remove/update PresenceGroup

add/get/remove/update RemoteCluster

add/get/remove/update SafCcdPurgeBlockLearnedRoutes

add/get/remove/update SafCcdPurgeBlockLearnedRoutes

add/get/remove/update SipDialRules

add/get/remove/update Srst

add/get/remove/update TransformationProfile

add/get/remove/update VpnGateway

add/get/remove/update VpnGroup

add/get/remove/update VpnProfile

add/get/remove/update LdapFilter

add/get/remove/update SafForwarder

add/get/remove/update SafSecurityProfile

add/remove GatewaySubunits

add/remove UnitsToGateway

get/remove/update MohAudioSource

get/update FixedMohAudioSource

get/update InterClusterServiceProfile

get/updateAnnunciator

list RoutePlan

The following APIs are updated:

AarGroup

AarGroupMatrix

AppUser

CalledPartyTransformationPattern

CallerFilterList

CallManager

CallManagerGroup

CallPark

CallPickupGroup

CmcInfo

CommonDeviceConfig

CommonPhoneConfig

ConferenceBridge

CredentialPolicy

Css

CtiRoutePoint

Ddi

DeviceMobility

DeviceMobilityGroup

DevicePool

DeviceProfile

DhcpServer

DhcpSubnet

DialPlan

DialPlanTag

DirectedCallPark

FacInfo

Gatekeeper

GeoLocation

GeoLocationFilter

GeoLocationPolicy

H323Gateway

H323Phone

H323Trunk

HuntList

HuntPilot

IvrUserLocale

LicenseCapabilities

Line

LineGroup

Location

MediaResourceGroup

MediaResourceList

MeetMe

MobileSmartClientProfile

MobileVoiceAccess

MohServer

Phone

PhoneButtonTemplate

PhysicalLocation

ProcessNode

ProcessNodeService

RecordingProfile

Region

RegionMatrix

RemoteDestination

RemoteDestinationProfile

ResourcePriorityNamespace

ResourcePriorityNamespaceList

RouteFilter

RouteGroup

RouteList

RoutePattern

RoutePartition

ServiceParameter

SipProfile

SipRealm

SipRoutePattern

SipTrunk

SipTrunkSecurityProfile

SoftKeyTemplate

TimePeriod

TimeSchedule

TodAccess

Transcoder

TransPattern

User

UserGroup

Vg224

VoiceMailPilot

VoiceMailPort

VoiceMailProfile

For detailed description of the changes in Administrative XML APIs, see New Information for Unified CM 8.0(1) section in Chapter 2, "Administrative XML Programming".

Serviceability XML API

The following are the changes in Serviceability XML APIs for Unified CM release 8.0(1):

The following new alarms are added:

VAPTLSConnectionFailed

VAPOverQuota

CMVersionMismatch

VAPInvalidCredentials

VAPTCPSetupFailed

InsufficientFallbackIdentifiers

SAFInvalideMethodReceived

VAPDHTInactive

DbInfoCorrupt

DbInfoTimeout

DbInfoError

SAFPublishRevoke

EndPointTransientConnection

ConflictingDataIE

EndPointUnregistered

ViPRQualityProblem

ErrorParsingDirectiveFromPDP

VAPPublishFailedOverQuota

ConnectionFailureToPDP

CCDRequestingServiceReceivedDuplicationPatterns

CCDPSTNFailOverDurationTimeOut

FailureResponseFromPDP

SAFUnknownSubscription

SAFUnknownService

CCDAgeOutDurationTimeOut

SafFwdError

ConnectionToSaffBroke

SAFBadFilter

SAFResponderError

InvalidVAPSubscription

DigitAnalysisTimeoutAwaitingResponse

FailedToFulfillDirectiveFromPDP

VAPRejectedRoutes

ErrorParsingResponseFromPDP

VAPPublishFailed

CallAttemptBlockedByPolicy

DbInsertValidatedDIDFailure

EndPointRegistered

CCDLearnedPatternExceededLimits

VAPPublicationRunCompleted

EndPointRestartInitiated

EndPointResetInitiated

RouteRemoved

ConnectionToPDPInService

The following alarms are modified:

NoFeatureLicense

DBLException

CUCMOverallInitTimeExceeded

SDLLinkOOS

BChannelOOS

CodeYellowEntry

MaxCallsReached

DChannelOOS

CallManagerFailure

StationTCPInitError

CodeRedEntry

MGCPGatewayLostComm

TimerThreadSlowed

NumDevRegExceeded

ICTCallThrottlingStart

DeviceTypeMismatch

DeviceCloseMaxEventsExceeded

ConnectionFailure

DeviceInitTimeout

MultipleSIPTrunksToSamePeerAndLocalPort

InvalidIPNetPattern

H323Stopped

StationEventAlert

DevicePartiallyRegistered

MaliciousCall

UserUserPrecedenceAlarm

MediaResourceListExhausted

NotEnoughChans

SIPStopped

DaTimeOut

RouteListExhausted

DeviceTransientConnection

SIPLineRegistrationError

DeviceUnregistered

BeginThrottlingCallListBLFSubscriptions

AnnunciatorNoMoreResourcesAvailable

ConferenceNoMoreResourcesAvailable

MtpNoMoreResourcesAvailable

SIPStarted

SDLLinkISV

H323Started

ICTCallThrottlingEnd

CodeYellowExit

MaxCallDurationTimeout

BChannelISV

DChannelISV

CallManagerOnline

MGCPGatewayGainedComm

DeviceRegistered

EndThrottlingCallListBLFSubscriptions

DeviceApplyConfigInitiated

CUCMTotalInitializationStateTime

MaxHoldDurationTimeout

PktCapServiceStarted

PktCapOnDeviceStarted

StationConnectionError

DatabaseDefaultsRead

PktCapServiceStopped

DeviceDnInformation

StationAlarm

DeviceResetInitiated

PktCapOnDeviceStopped

DeviceRestartInitiated

CUCMInitializationStateTime

The following new perform classes are added:

CCM_VIPR_SERVICE_OBJECT

EXTERNALCALLCONTROL_OBJ

CCM_SAFCLIENT_OBJECT

ViPR

The following perform classes are modified:

CCM_PRESENCE_OBJECT

CCM_MGCPFXO_OBJECT

CCM_DUAL_MODE_MOBILITY_OBJECT

CCM_VCB_OBJECT

CCM_PHONE_OBJECT

CcmSIPObject

CCM_LOCATIONS_OBJECT

CCM_WSM_CONNECTOR_OBJECT

CcmQSIGFeatureObject

CCM_SIP_STATION_OBJECT

UCB_SW_DEVICE_OBJECT

MGCP_GATEWAY_OBJECT

MOH_DEVICE_OBJECT

CCM_LINES_OBJECT

CCM_MGCPBRI_OBJECT

CCM_MGCPT1CAS_OBJECT

CCM_HUNTLISTS_OBJECT

CcmAnnunciatorObject

CcmSIPStackObject

MTP_DEVICE_OBJECT

CCM_SDL_OBJECT

CCM_SIGNALING_OBJECT

CCM_ANALOGACCESS_OBJECT

UCB_HW_DEVICE_OBJECT

CCM_H323_OBJECT

CISCO_CALL_RESTRICTION

CCM_MGCPFXS_OBJECT

CCM_MGCPPRI_OBJECT

GATEKEEPER_OBJECT

CCM_MOBILITY_OBJECT

CCM_CM_OBJECT

XCODE_DEVICE_OBJECT

PRFOBJ_EMAPP

Changes are made in the CISCO-CCM-MIB and the Cisco Syslog-MIB.

Changes are made in Serviceability API Cipher support.

For detailed description of the changes, see New and Changed Information section in Chapter 4, "Serviceability XML Programming".

Extension Mobility API

The following are the changes in Extension Mobility APIs for Unified CM release 8.0(1):

DeviceProfileQuery

LogoutAll

For detailed description of the changes in Extension Mobility APIs, see New and Changed Information section in Chapter 6, "Cisco Extension Mobility Service API".

Web Dialer API

A new service parameter, called Maximum Concurrent Call Requests, is added for modifying the throttle value of Web Dialer requests. This value was previously hard-coded. The throttle limits the number of CTI requests from Web Dialer. The minimum and maximum values for this throttle are one and six, and the recommended values for 7825 and 7845 servers are three and six respectively.

For detailed description of the changes, see New and Changed Information section in Chapter 8, "Cisco Web Dialer API Programming"

Routing Rules API

This interface is introduced in Unified CM release 8.0(1). For detailed description of this interface, see Chapter 10, "Cisco Unified Routing Rules Interface,".