Cisco Unified Communications Manager XML Developers Guide, Release 9.0(1)
Overview
Downloads: This chapterpdf (PDF - 165.0KB) The complete bookPDF (PDF - 14.37MB) | 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 Media 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 9.0(1) API

Administrative XML API

New APIs

Changed APIs

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 9.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 , 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 , 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 Media Driver

Cisco JTAPI

Cisco Web Dialer

Cisco TAPI and Media 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 Media 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 Media Driver is beyond the scope of this guide. For information of Cisco TAPI and Media 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 Media 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 , 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 , 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 9.0(1) API

This section gives information on the changes in the following APIs in the Unified CM release 9.0(1):

Administrative XML API

Serviceability XML API

Extension Mobility API

Web Dialer API

Routing Rules API


Note Information on changes in Cisco JTAPI and Cisco TAPI and Media Driver API are beyond the scope of this guide.
For information of Cisco TAPI and Media 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 the Administrative XML API in Unified CM release 9.0(1).

New APIs

Changed APIs

New APIs

Table 1-1 provides information on the new APIs in Unified CM release 9.0.

Table 1-1 New APIS in Unified CM Release 9.0

API
Operation
Added Tags

Announcement

AddAnnouncement

GetAnnouncement

UpdateAnnouncement

RemoveAnnouncement

ListAnnouncement

name

description

announcementFile

AudioCodecPreferenceList

AddAudioCodecPreferenceList

UpdateAudioCodecPreferenceList

GetAudioCodecPreferenceList

RemoveAudioCodecPreferenceList

ListAudioCodecPreferenceList

Name

Description

CodecsInlist

codecNames

LbmGroup

addLbmGroup

updateLbmGroup

removeLbmGroup

listLbmGroup

name

description

ProcessnodeActive

ProcessnodeStandby

BillingServer

addBillingServer

updateBillingServer

getBillingServer

removeBillingServer

hostName

userId

password

directory

resendOnFailure

billingServerProtocol

uuid

SIPNormalizationScript

addSIPNormalizationScript

removeSIPNormalizationscript

listSIPNormalizationscript

getSIPNormalizationscript

updateSIPNormalizationscript

Name

Description

Content

ScriptExecutionErrorRecoveryAction

SystemResourceErrorRecoveryAction

maxMemoryThreshold

maxLuaInstructionsThreshold

isStandard

CalledPartyTracing

addCalledPartyTracing

listCalledPartyTracing

removeCalledPartyTracing

Directory Number

Description

Search Criteria

Return Tags

Uuid

GatewaySccpEndpoints

addGatewaySccpEndpoints

updateGatewaySccpEndpoints

getGatewaySccpEndpoints

removeGatewaySccpEndpoints

domainName

gatewayuuid

unit

subunit

endpoint

name

uuid

ServiceProfile

addServiceProfile

updateServiceProfile

getServiceProfile

name

description

isDefault

ServiceProfileInfos

ServicePofileInfo

listServiceProfile

removeServiceProfile

name

description

isDefault

name

uuid

SNMPCommunityString

addSNMPCommunityString

getSNMPCommunityString

removeSNMPCommunityString

updateSNMPCommunityString

communityName

accessPrivilege

ArrayOfHosts

SNMPUser

addSNMPUser

getSNMPUser

removeSNMPUser

updateSNMPUser

userName

User

authRequired

authPassword

authProtocol

privacyRequired

privacyPassword

privacyProtocol

accessPrivilege

snmpEngineID

ArrayOfHosts

SNMPMIB2List

getSNMPMIB2List

updateSNMPMIB2List

sysLocation

sysContact

SyslogConfiguration

updateSyslogConfiguration

getSyslogConfiguration

Uuid

serverName

serviceGroup

service

enable

AlarmLevelEvent

RemoteServerName1

RemoteServerName 2

RemoteServerName 3

RemoteServerName 4

RemoteServerName 5

monitor

enable

remoteAlarmLevelEvent

remoteServerName

localAlarmLevelEvent

UcService

AddUcService

GetUcService

ListUcService

RemoveUcService

serviceType

productType

name

description

hostnameorip

PhoneTypeDisplayInstance

GetPhoneTypeDisplayInstance

productName

protocol


Changed APIs

Table 1-2 provides information on the changed APIs in Unified CM release 9.0.

Table 1-2 Changed APIs in Unified CM Release 9.0

API
New Tags
Deprecated Tags

AddLine

UpdateLine

GetLine

allowCtiControlflag

directoryNumberURI

-

AddUserPhoneAssosiation

DirectoryNumberURI

DirectoryNumberURIPartition

 

AddSipProfile

UpdateSipProfile

DeleteSipProfile

ListSipProfile

scriptParameters

isScriptTraceEnabled

sipNormalizationScript

dialStringInterpretation

acceptAudioCodecPreferences

videoCallTrafficClass

sipBandwidthModifier

enableUriOutdialSupport

userAgentServerHeaderInfo

allowPresentationSharingUsingBfcp

-

AddSipTrunk

UpdateSipTrunk

DeleteSipTrunk

ListSipTrunk

callingAndCalledPartyInfoFormat

requestUriDomainName

-

GetMohAudioSource

UpdateMohAudioSource

initialAnnouncement

periodicAnnouncement

periodicAnnouncementInterval

localeAnnouncement

initialAnnouncementPlayed

 

AddHuntpilot

GetHuntpilot

maxCallersInQueue

queueFullDestination

callingSearchSpacePilotQueueFull

maxWaitTimeInQueue

maxWaitTimeDestination

callingSearchSpaceMaxWaitTime

noAgentDestination

callingSearchSpaceNoAgent

networkHoldMohAudioSourceID

 

AddRegion

UpdateRegion

GetRegion

UpdateRegionMatrix

codecPreference

lossyNetwork

AddPhone

GetPhone

ListPhone

UpdatePhone

requireThirdPartyRegistration

blockIncomingCallsWhenRoaming

homeNetworkId

requireOffPremiseLocation

subsribeCallingSearchSpaceName

SIPTrunkSecurityProfile

SipV150SdpOfferFiltering

-

getCallManager

ListCallManager

UpdateCallManager

lbmGroup

 

addRoutePattern

getRoutePattern

updateRoutePattern

enableDccEnforcement

blockedCallPercentage

 

ConferenceBridge

userName

password

httpPort

useHttps

-

AddLdapDirectoryHandler

GetLdapDirectoryHandler

directoryUri

 

User

homeCluster

imAndPresenceEnable

serviceProfile

laapAssociate

laapProductType

laapDeviceName

laapDirectory

laapPartition

laapDescription

directoryUri

-


For more information on the changes in the Administrative XML API, see the New and Changed Information in Unified CM Release 9.0 section in the Chapter 2 "Administrative XML Programming".

Serviceability XML API

The following changes were made to the Serviceability XML API in Unified CM release 9.0(1).

SelectCmDevice API returns device information for a maximum of 1000 devices instead of the earlier 200 devices.
For more information, see the section Maximum Devices Specification and Example Request (RPC/Encoded Format).

SelectCmDevice API for Ipv6 devices returns device information for a maximum of 1000 devices instead of the earlier 200 devices.
For more information, see the section MaxReturnedDevices.

SelectCtiItem API returns device information for a maximum of 1000 devices instead of the earlier 200 devices.
For more information, see the section Maximum Device Information.

SelectCtiDevice API for Ipv6 devices returns device information for a maximum of 1000 devices instead of the earlier 200 devices.
For more information, see the section MaxReturnedItems.

SelectCmDeviceSIP API returns device information for a maximum of 1000 devices instead of the earlier 200 devices.
For more information, see the section State Info.

The device query response in large Unified CM clusters returns device information for a maximum of 1000 devices instead of the earlier 200 devices.
For more information, see the section Device Query Support for Large Clusters.

For Unified CM release 9.0 and later, Serviceability XML APIs provide remote procedure call (RPC) as well as doc/literal style operations for clients.

Extension Mobility API

There are no changes in the Extension Mobility API in Unified CM release 9.0(1).

Web Dialer API

There are no changes in the Web Dialer API in Unified CM release 9.0(1).

Routing Rules API

There are no changes in the Routing Rules API in Unified CM release 9.0(1).