Table of Contents

Introduction
Configuration
Messages

Login Requests
Logout Requests
Device-User Queries
User-Devices Queries

Securing Cisco CallManager Extension Mobility Messages
Message Document Type Definitions

The Request DTD
The Login or Logout Response DTD
The Query DTD
The Query Response DTD

Message Examples

Request Examples
Request Response Examples
Query Examples
Query Response Examples

Login Service Error Codes

Using the Cisco CallManager Extension Mobility API

Introduction

The Cisco CallManager Extension Mobility API is exposed as an Extensible Markup Language (XML) interface via HTTP. A website is designated by the administrator of the system as the entry point to the API, and all requests and queries are made through those URLs. The Document Type Definitions (DTDs) which define the XML for requests, queries, and responses are also made available at this website. The DTDs are included in this document, along with examples.

The XML input is submitted via an HTTP POST. A field named "xml" contains the XML string which defines the request or query. The response to this HTTP POST is a pure XML response with either a success or failure indicator for a request or the response to a query.

This chapter is organized as follows:

• Configuration
  
  
• Messages
  
  
• Message Document Type Definitions
  
  
• Message Examples
  
  
• Login Service Error Codes
  
  
• 
  
  

Configuration

Cisco CallManager Extension Mobility is an application designed to accompany Cisco CallManager Release 3.1. As such, all necessary Cisco CallManager Extension Mobility API components are installed with the standard Cisco CallManager installation.

To use Cisco CallManager Extension Mobility, a device profile must be created for the user logging in and for the target device.

These are the steps necessary to configure Cisco CallManager Extension Mobility:

• Create a User Device Profile.
  
  
• Assign a User Device Profile to a User.
  
  
• Assign authentication proxy rights to an appID.
  
  
• Assign a Logout Device Profile to a target device.
  
  
• Configure the System Parameters.
  
  

Note

• Technically, it is not necessary to assign a profile to a user. The device profile may be specified at login time.

• System Parameters use defaults if not manually configured.
  
  
• Extension Mobility must be enabled on a device-by-device basis.
  
  

For details on how to configure the User Device Profile, refer to the Cisco CallManager Administration Guide or the Cisco CallManager Extended Services Administrator's Guide.

Messages

You communicate between your login application and the Cisco CallManager Extension Mobility Login Service by sending and receiving messages written in Extensible Markup Language (XML). The XML messages you send must follow the rules set by the Message Document Type Definitions (DTDs) described in the "Message Document Type Definitions" section.

The two different kinds of messages which can be sent to the Cisco CallManager Extension Mobility API must be sent to distinct URLs. The default URLs are:

• Login/Logout requests: http://<machine-address>/LoginService/login.asp
  
  
• System queries: http://<machine-address>/LoginService/query.asp
  
  

Since there are two types of requests, Login and Logout, and there are two different types of queries, Device-User and User-Devices, the Cisco CallManager Extension Mobility API supports four distinct types of messages.

The application sends authentication information, including an Application ID and an Application Certificate, at the start of message.

The only type of certificate which is currently supported is a password. All messages must include a valid appID and appPassword, or they will not be processed.

For examples of legal Cisco CallManager Extension Mobility messages, see the "Message Examples" section.

Login Requests

Login requests are the cornerstone of this service, and currently they are the most flexible and complex message type. The information required to process a login request must include the device which is to be logged into and the userid of the user logging into that device. If a device profile other than the default Device Profile which has been associated with the user is to be used, that profile name can be specified optionally. If the system is to log the user out automatically after a particular period of time, that can also be specified optionally.

Logout Requests

To Log out, you only need to provide the device name in the message.

Device-User Queries

A Device-User query is a query wherein the application specifies a list of one or more devices, and the system returns the userid of the user currently logged on to each device.

User-Devices Queries

A User-Devices query is a query in which the application specifies a list of one or more users, and the system returns the list of devices for each user that the particular user is currently logged into.

Securing Cisco CallManager Extension Mobility Messages

There is a security mechanism which can be taken advantage of in order to prevent the appID and password from being sent in cleartext over the HTTP connection in the request or query. This mechanism uses a public-key encryption system which is relatively safe, but will slow down response time and increase processor load as the requests must be decrypted before being serviced.

In order to take advantage of this mechanism, these two steps must be taken:

1. The request or query XML string must be encrypted.

2. The request or query must be POSTed to loginSecure.asp or querySecure.asp rather than login.asp or query.asp, respectively.

To encrypt the XML string, use either the EMEncoder.dll or EMEncoder.jar, both of which may be obtained from the Cisco CallManager server which supplies the Cisco CallManager Extension Mobility service at:

http://<Cisco CallManager ip-address>/LoginService/Tools/EMEncoder.dll

and

http://<Cisco CallManager ip-address>/LoginService/Tools/EMEncoder.jar

Use the .dll or .jar to instantiate the EMEncoder object, which has a single method, encode(String). This method takes the XML string as input and returns the encrypted string, which is to be posted to the appropriate Cisco CallManager Extension Mobility service Active Server Page, either loginSecure.asp or querySecure.asp, exactly as its unencrypted counterpart would be posted to login.asp or query.asp.

The response is still in cleartext.

Message Document Type Definitions

A Message Document Type Definition (DTD) is an XML list that specifies precisely which elements can appear in a request, query, or response document. It also specifies the contents and attributes of the elements.

You communicate between your login application and the Cisco CallManager Extension Mobility Login Service by sending and receiving XML documents. These XML documents must follow the rules set by the Message DTDs.

For more details about messages, see the "Messages" section. For examples of how the Message DTDs are used, see the "Message Examples" section.

The Request DTD

The Request DTD defines the login and logout messages your application can send to the Cisco CallManager Extension Mobility Login Service.

<!-- login requests DTD -->

<!ELEMENT request (appInfo, (login | logout))>

<!ELEMENT appInfo (appID, appCertificate)>

<!ELEMENT appID (#PCDATA)>

<!ELEMENT appCertificate (#PCDATA)>

<!ELEMENT login (deviceName, userID, deviceProfile?, exclusiveDuration?)>

<!ELEMENT logout (deviceName)>

<!ELEMENT deviceName (#PCDATA)>

<!ELEMENT userID (#PCDATA)>

<!ELEMENT deviceProfile (#PCDATA)>

<!ELEMENT exclusiveDuration (time | indefinite)>

<!ELEMENT time (#PCDATA)>

<!ELEMENT indefinite EMPTY>

The Login or Logout Response DTD

Login or Logout Response DTD defines the messages your application receives from the Cisco CallManager Extension Mobility Login Service when it sends a login or logout request

message.

<!-- login response DTD -->

<!ELEMENT response (success | failure)>

<!ELEMENT success EMPTY>

<!ELEMENT failure (error)>

<!ELEMENT error (#PCDATA)>

<!ATTLIST error

code NMTOKEN #REQUIRED>

The Query DTD

The Query DTD defines the Device-User and User-Devices messages your application sends the Cisco CallManager Extension Mobility service to find out what user is logged into a device or what devices users are logged into.

<!-- login query DTD -->

<!ELEMENT query (appInfo, (deviceUserQuery | userDevicesQuery))>

<!ELEMENT appInfo (appID, appCertificate)>

<!ELEMENT appID (#PCDATA)>

<!ELEMENT appCertificate (#PCDATA)>

<!ELEMENT deviceUserQuery (deviceName+)>

<!ELEMENT userDevicesQuery (userID+)>

<!ELEMENT deviceName (#PCDATA)>

<!ELEMENT userID (#PCDATA)>

The Query Response DTD

The Query Response DTD defines the messages your application receives from the Cisco CallManager Extension Mobility service when it sends the service a Device-User or User-Devices query.

<!-- login query results DTD -->

<!ELEMENT response (deviceUserResults | userDevicesResults | failure)>

<!ELEMENT deviceUserResults (device+)>

<!ELEMENT userDevicesResults (user+)>

<!ELEMENT device (userID | none | doesNotExist)>

<!ATTLIST device

name NMTOKEN #REQUIRED>

<!ELEMENT user (deviceName+ | none | doesNotExist)>

<!ATTLIST user

id NMTOKEN #REQUIRED>

<!ELEMENT userID (#PCDATA)>

<!ELEMENT deviceName (#PCDATA)>

<!ELEMENT none EMPTY>

<!ELEMENT doesNotExist EMPTY>

<!ELEMENT failure (errorMessage)>

<!ELEMENT errorMessage (#PCDATA)>

Message Examples

This section provides examples of various types of messages to aid in understanding how to use the message DTDs to communicate between your application and the Cisco CallManager Extension Mobility service. Table 2-1 lists each example's type, a description of what the example message means, and a reference to that example. For more details about messages, see the "Messages" section. For details about the DTDs, see the "Message Document Type Definitions" section.

Request Examples

Request examples demonstrate three different login requests and one logout request. The login requests show a simple login message and two that specify options like using a particular device profile or setting a login duration.

Request Response Examples

The request response examples show a success message (for either login or logout) and a failure message indicating the type of error that the login or logout attempt generated.

Query Examples

Query examples show a typical Device-User Query message and a typical User-Devices Query message sent by an application to the Cisco CallManager Extension Mobility Service.

Query Response Examples

Query Response examples show messages sent to the login application by the Cisco CallManager Extension Mobility Service after the login application has sent a Device-User query message or a User-Devices query message.

Login Service Error Codes

Table 2-2 shows the current error codes that the Cisco CallManager Extension Mobility Login Service returns and describes what each error code means.

Posted: Wed Sep 18 06:38:03 PDT 2002
All contents are Copyright © 1992--2002 Cisco Systems, Inc. All rights reserved.
Important Notices and Privacy Statement.