Cisco Unified Communications Manager Express System Administrator Guide - Configuring the XML API [Cisco Unified Communications Manager Express]

Table Of Contents

Configuring the XML API

Contents

Information About XML API

XML API Definition

XML API Provision Using IXI

How to Configure XML API

Defining XML Transport Parameters

Defining XML Application Parameters

Defining Authentication for XML Access

Defining XML Event Table Parameters

Troubleshooting the XML Interface

Configuration Examples for XML API

XML Transport Parameters: Example

XML Application Parameters: Example

XML Authentication: Example

XML Event Table: Example

Where to Go Next

Additional References

Related Documents

Technical Assistance

Feature Information for XML API

Configuring the XML API

Last Updated: March 3, 2008

This chapter describes the eXtensible Markup Language (XML) Application Programming Interface (API) support available in Cisco Unified Communications Manager Express (Cisco Unified CME).

Finding Feature Information in This Module

Your Cisco Unified CME version may not support all of the features documented in this module. For a list of the versions in which each feature is supported, see the "Feature Information for XML API" section.

Contents

•Information About XML API

•How to Configure XML API

•Configuration Examples for XML API

•Where to Go Next

•Additional References

•Feature Information for XML API

Information About XML API

To enable XML API, you should understand the following concepts:

•XML API Definition

•XML API Provision Using IXI

XML API Definition

An XML API provides an interface to Cisco Unified CME that allows an external network management system (NMS) to configure and monitor Cisco Unified CME operations.

XML API Provision Using IXI

In previous versions of Cisco Unified CME, the XML interface provided configuration and monitoring functions using the HTTP port. The XML interface ran under the HTTP server process, simultaneously parsing incoming XML requests on demand and processing them.

In Cisco Unified CME 4.0 and later versions, the XML interface is provided through the Cisco IOS XML Infrastructure (IXI), in which the parser and transport layers are separated from the application. This modularity provides scalability and enables future XML support to be developed. In Cisco Unified CME 4.0 and later versions, all Cisco Unified CME features have XML support.

How to Configure XML API

This section contains the following tasks:

•Defining XML Transport Parameters

•Defining XML Application Parameters

•Defining Authentication for XML Access

•Defining XML Event Table Parameters

•Troubleshooting the XML Interface

Note The following Cisco IOS commands that were previously used with the XML interface are no longer valid: log password, xmltest, xmlschema, and xmlthread.

Defining XML Transport Parameters

To define the XML transport method and associated parameters, perform the following steps.

SUMMARY STEPS

1. enable

2. configure terminal

3. ip http server

4. ixi transport http

5. response size fragment- size

6. request outstanding number

7. request timeout seconds

8. no shutdown

9. end

DETAILED STEPS

Command or Action

Purpose

Step 1

enable
Example:

Router> enable

Enables privileged EXEC mode.

•Enter your password if prompted.

Step 2

configure terminal
Example:

Router# configure terminal

Enters global configuration mode.

Step 3

ip http server
Example:

Router(config)# ip http server

Enables the Cisco web browser user interface on the local Cisco Unified CME router.

Step 4

ixi transport http
Example:

Router(config)# ixi transport http

Specifies the XML transport method and enters XML-transport configuration mode.

•http—HTTP transport.

Step 5

response size fragment-size
Example:

Router(conf-xml-trans)# response size 8

Sets the response buffer size.

•fragment-size—Size of fragment in the response buffer, in kilobytes. Range is constrained by the transport type and platform. See the CLI help for the valid range of values.

Step 6

request outstanding number
Example:

Router(conf-xml-trans)# request outstanding 2

Sets the maximum number of outstanding requests allowed for the transport type.

•number—Number of requests. Range is constrained by the transport type and platform. See the CLI help for the valid range of values.

Step 7

request timeout seconds
Example:

Router(conf-xml-trans)# request timeout 30

Sets the number of seconds to wait, while processing a request, before timing out.

•seconds—Number of seconds. Range is 0 to 60.

Step 8

no shutdown
Example:

Router(conf-xml-trans)# no shutdown

Enables HTTP transport.

Step 9

end
Example:

Router(config-xml-app)# end

Returns to privileged EXEC mode.

Defining XML Application Parameters

To set a response timeout for communication with the XML application that overrides the setting in transport configuration mode, perform the following steps.

SUMMARY STEPS

1. enable

2. configure terminal

3. ixi application cme

4. response timeout {-1 | seconds}

5. no shutdown

6. end

DETAILED STEPS

Command or Action

Purpose

Step 1

enable
Example:

Router> enable

Enables privileged EXEC mode.

•Enter your password if prompted.

Step 2

configure terminal
Example:

Router# configure terminal

Enters global configuration mode.

Step 3

ixi application cme
Example:

Router(config)# ixi application cme

Enters XML-application configuration mode for configuring Cisco IOS XML infrastructure parameters for the Cisco Unified CME application.

Note This command defines URL of Cisco Unified CME XML server as http://<routerIPaddress>/ios_xml_app/cme.

Step 4

response timeout {-1 | seconds}
Example:

Router(config-xml-app) response timeout 30

Sets a timeout for responding to the XML application and overwrites the IXI transport level timeout.

•-1—No application-specific timeout is specified. This is the default.

•seconds—Length of timeout, in seconds. Range is 0 to 60.

Step 5

no shutdown
Example:

Router(conf-xml-app)# no shutdown

Enables XML communication with the application.

Step 6

end
Example:

Router(config-xml-app)# end

Returns to privileged EXEC mode.

Defining Authentication for XML Access

To authenticate users for XML access, perform the following steps:

SUMMARY STEPS

1. enable

2. configure terminal

3. telephony-service

4. xml user user-name password password privilege-level

5. end

DETAILED STEPS

Command or Action

Purpose

Step 1

enable
Example:

Router> enable

Enables privileged EXEC mode.

•Enter your password if prompted.

Step 2

configure terminal
Example:

Router# configure terminal

Enters global configuration mode.

Step 3

telephony-service
Example:

Router(config)# telephony-service

Enters telephony-service configuration mode.

Step 4

xml user user-name password password privilege-level
Example:

Router(config-telephony)# xml user user23 password 3Rs92uzQ 15

Defines an authorized user.

•user-name—Unique alphanumeric string that is authorized user name. Maximum length of string is 19 characters.

•password—Alphanumeric string to use for access. Maximum length of string is 19 characters.

•privilege-level—Level of access to Cisco IOS commands to be granted to this user. Only the commands with the same or a lower level can be executed via XML. Range is 0 (lowest) to 15 (highest).

Step 5

end
Example:

Router(config-telephony)# end

Returns to privileged EXEC mode.

Defining XML Event Table Parameters

The XML event table is an internal buffer that stores captured and time-stamped events, such as phones registering and unregistering and extension status. One event equals one entry in the table. To set the maximum number of events or entries that can be stored in the XML event table and the length of time that events are retained before they are deleted from the table, perform the following steps.

SUMMARY STEPS

1. enable

2. configure terminal

3. telephony-service

4. log table max-size number

5. log table retain-timer minutes

6. end

7. show fb-its-log

8. clear telephony-service xml-event-log

DETAILED STEPS

Command or Action

Purpose

Step 1

enable
Example:

Router> enable

Enables privileged EXEC mode.

•Enter your password if prompted.

Step 2

configure terminal
Example:

Router# configure terminal

Enters global configuration mode.

Step 3

telephony-service
Example:

Router(config)#

Enters telephony-service configuration mode.

Step 4

log table max-size number
Example:

Router(config-telephony)# log table max-size 100

Sets the number of entries in the XML event table.

•number—Number of entries. Range is 0 to 1000. Default is 150.

Step 5

log table retain-timer minutes
Example:

Router(config-telephony)# log table retain-timer 30

Sets the number of minutes to retain entries in the event table before they are deleted.

•minutes—Number of minutes. Range is 2 to 500. Default is 15.

Step 6

end
Example:

Router(config-telephony)# end

Returns to privileged EXEC mode.

Step 7

show fb-its-log
Example:

Router# show fb-its-log

Displays the event logs.

Step 8

clear telephony-service xml-event-log
Example:

Router# clear telephony-service xml-event-log

Clears XML event logs.

Troubleshooting the XML Interface

Step 1 Use the debug cme-xml command to view debug messages for the Cisco Unified CME XML interface.

Configuration Examples for XML API

This section contains the following examples:

•XML Transport Parameters: Example

•XML Application Parameters: Example

•XML Authentication: Example

•XML Event Table: Example

XML Transport Parameters: Example

The following example selects HTTP as the XML transport method:
ip http server 
ixi transport http
 response size 8
 request outstanding 2
 request timeout 30
 no shutdown
XML Application Parameters: Example

The following example sets the application response timeout to 30 seconds.
ixi application cme
 response timeout 30
 no shutdown
XML Authentication: Example

The following example selects HTTP as the XML transport method. It allows access for user23 with the password 3Rs92uzQ, and sets up access list 99 that accepts requests from the IP address 192.168.146.72.

ixi transport http
ip http server
!
telephony-service
xml user user23 password 3Rs92uzQ 15

XML Event Table: Example

The following example sets the maximum number of entries in the XML event table to 100 and the number of minutes to retain entries at 30:

telephony-service
log table max-size 100
 log table retain-timer 30
Where to Go Next

For developer information on the XML API, see the XML Provisioning Guide for Cisco CME/SRST.

Additional References

The following sections provide references related to Cisco Unified CME features.

Related Documents

Related Topic

Document Title

Cisco Unified CME configuration

•Cisco Unified CME Command Reference

•Cisco Unified CME Documentation Roadmap

Cisco IOS commands

•Cisco IOS Voice Command Reference

•Cisco IOS Software Releases 12.4T Command References

Cisco IOS configuration

•Cisco IOS Voice Configuration Library

•Cisco IOS Software Releases 12.4T Configuration Guides

Phone documentation for Cisco Unified CME

•User Documentation for Cisco Unified IP Phones

Technical Assistance

Description

Link

The Cisco Support website provides extensive online resources, including documentation and tools for troubleshooting and resolving technical issues with Cisco products and technologies.

To receive security and technical information about your products, you can subscribe to various services, such as the Product Alert Tool (accessed from Field Notices), the Cisco Technical Services Newsletter, and Really Simple Syndication (RSS) Feeds.

Access to most tools on the Cisco Support website requires a Cisco.com user ID and password.

http://www.cisco.com/techsupport

Feature Information for XML API

Table 13 lists the features in this module and enhancements to the features by version.

To determine the correct Cisco IOS release to support a specific Cisco Unified CME version, see the Cisco Unified CME and Cisco IOS Software Version Compatibility Matrix at http://www.cisco.com/en/US/docs/voice_ip_comm/cucme/requirements/guide/33matrix.htm.

Use Cisco Feature Navigator to find information about platform support and software image support. Cisco Feature Navigator enables you to determine which Cisco IOS software images support a specific software release, feature set, or platform. To access Cisco Feature Navigator, go to http://www.cisco.com/go/cfn. An account on Cisco.com is not required.

Note Table 13 lists the Cisco Unified CME version that introduced support for a given feature. Unless noted otherwise, subsequent versions of Cisco Unified CME software also support that feature.

Table 13 Feature Information for XML API

Feature Name

Cisco Unified CME
Version

Feature Information

Call Blocking Based on Date and Time

4.0

The XML API was modified and is now provided through the Cisco IOS XML infrastructure. It supports all Cisco Unified CME features. The log password, xmltest, xmlschema, and xmlthread commands were made obsolete.

3.0

The XML API was introduced.