Cisco CallManager Extension Mobility API Developer Guide, Release 3.1
Using the Cisco CallManager Extension Mobility API
Downloads: This chapterpdf (PDF - 183.0KB) The complete bookPDF (PDF - 591.0KB) | Feedback

Using the Cisco CallManager Extension Mobility API

Table Of Contents

Using the Cisco CallManager Extension Mobility API

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.


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

Table 2-1 Message Examples

Message Example Type
Description
Example Reference

Login Request

The 7960LoginApp application requests that user rknotts be logged into device SEP003094C25B15

Example 2-1

Login Request

The WebLoginApp application makes a login request specifying the RyanTravelPhone profile and limiting the login time to 60 minutes.

Example 2-2

Login Request

WebLoginApp requests that user rknotts be logged in to the specified device for an unlimited duration.

Example 2-3

Logout Request

The 7960LoginApp application requests that the current user be logged out of device SEP003094C25B15

Example 2-4

Request Response

Response of Success to a login or logout request

Example 2-5

Request Response

Failure response with error indicating incorrect appID or password

Example 2-6

Device-User Query

Querying what user is logged into device SEP003094C25B15

Example 2-7

User-Devices Query

Querying which devices are user rknotts and fwragge logged into

Example 2-8

Device-User Response

Response saying that rknotts is the user logged into device SEP003094C25B15

Example 2-9

User-Devices Response

Response saying that rknotts is logged into devices SEP003094C25B15 and SEP003094C25B49 and fwragge is logged into device SEP003094C25B46

Example 2-10


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.

Example 2-1 A Simple Login Request

<request>

<appInfo>

<appID>7960LoginApp</appID>

<appCertificate>password</appCertificate>

</appInfo>

<login>

<deviceName>SEP003094C25B15</deviceName>

<userID>rknotts</userID>

</login>

</request>

Example 2-2 Login Request Specifying a Profile and a Time Restriction

<request>

<appInfo>

<appID>WebLoginApp</appID>

<appCertificate>password</appCertificate>

</appInfo>

<login>

<deviceName>SEP003094C25B15</deviceName>

<userID>rknotts</userID>

<deviceProfile>RyanTravelPhone</deviceProfile>

<exclusiveDuration>

<time>60</time>

</exclusiveDuration>

</login>

</request>

Example 2-3 Login Request Specifying an Unlimited Duration

<request>

<appInfo>

<appID>WebLoginApp</appID>

<appCertificate>password</appCertificate>

</appInfo>

<login>

<deviceName>SEP003094C25B15</deviceName>

<userID>rknotts</userID>

<exclusiveDuration>

<indefinite/>

</exclusiveDuration>

</login>

</request>

Example 2-4 Logout Request

<request>

<appInfo>

<appID>7960LoginApp</appID>

<appCertificate>password</appCertificate>

</appInfo>

<logout>

<deviceName>SEP003094C25B15</deviceName>

</logout>

</request>

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.

Example 2-5 Success Response

<response>

<success/>

</response>

Example 2-6 Failure Response

<response>

<failure>

<error code="3">Could not authenticate 'appid'</error>

</failure>

</response>

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.

Example 2-7 A Device-User Query

<query>

<appInfo>

<appID>applicationName</appID>

<appCertificate>password</appCertificate>

</appInfo>

<deviceUserQuery>

<deviceName>SEP003094C25B15</deviceName>

</deviceUserQuery>

</query>

Example 2-8 A User-Devices Query

<query>

<appInfo>

<appID>applicationName</appID>

<appCertificate>password</appCertificate>

</appInfo>

<userDevicesQuery>

<userID>rknotts</userID>

<userID>fwragge</userID>

</userDevicesQuery>

</query>

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.

Example 2-9 A Device-User Response

<results>

<deviceUserResults>

<device name="SEP003094C25B15">

<userID>rknotts</userID>

</device>

<deviceUserResults>

</results>

<results>

Example 2-10 A User-Devices Response

<userDevicesResults>

<user id="rknotts">

<deviceName>SEP003094C25B15</deviceName>

<deviceName>SEP003094C25B49</deviceName>

</user>

<user id="fwragge">

<deviceName>SEP003094C249A6</deviceName>

</user>

</userDeviceResults>

</results>

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.

Table 2-2 Cisco CallManager Extension Mobility Login Service Error Codes

Error Code
Description

0

Unknown Error

1

XML Validation Error: The request or query was incorrectly formed, and cannot be properly processed

2

Authentication Error: An error occurred in the authentication process, and the validity of the appID and appPassword submitted cannot be confirmed

3

Invalid Authentication: The appId and/or appPassword provided are incorrect

4

Policy Validation Error: Some generic issue regarding determination if the request is allowed or not

5

Request Denied: The request has been denied (failed Policy Validation) for one or more reasons

6

Database Error: The Extension Mobility Service received an error while trying to communicate with the database

7

AutoLogout Setup Error: Could not communicate with the AutoLogout service

8

Query Type Unknown: could not determine whether the query is Device-User or User-Devices

9

DirUser Creation Error: Directory integration error

10

Proxy Authentication Not Allowed: the appID specified does not have rights to login or logout other users

11

Device Does Not Exist: The specified device for login or logout does not exist in the system

12

Device Profile Does Not Exist: Either a profile was specified which does not exist or there is no Logout Device Profile configured for the specified user

13-17

Various Pipe Errors: Could not communicate with the AutoLogout service

18

Device Already Logged In: Could not log in to the specified device because there is already a user logged in

19

Device Not Logged In: Could not log out of the specified device because there is no user logged in

20

Get Device Hoteling Flag Error: Could not determine whether the device allows Cisco CallManager Extension Mobility (also called "hoteling") or not

21

Get Device Hoteling Status Error: Could not determine whether these is a user currently logged in or not

22

Device Does Not Allow Extension Mobility: The device specified is not configured for Extension Mobility

23

User Does Not Exist: The userid entered for login does not exist in the system

24

System Disabled: The Extension Mobility service has been disabled from the service parameters

25

User Already Logged In Elsewhere: The login is denied because the specified user is already logged into a different device