Cisco CallManager Extension Mobility API Developer Guide, Release 4.1(3)
Using the Cisco Extension Mobility API
Downloads: This chapterpdf (PDF - 231.0KB) The complete bookPDF (PDF - 617.0KB) | Feedback

Using the Cisco Extension Mobility API

Table Of Contents

Using the Cisco Extension Mobility API

Configuration

Messages

Login Requests

Logout Requests

Device-User Queries

User-Devices Queries

Message Document Type Definitions

Request DTD

Login or Logout Response DTD

Query DTD

Query Response DTD

Message Examples

Request Examples

Request Response Examples

Query Examples

Query Response Examples

Login Service Error Codes


Using the Cisco Extension Mobility API


The Cisco Extension Mobility API gets exposed as an Extensible Markup Language (XML) interface via HTTP. The administrator of the system designates a website as the entry point to the API, and all requests and queries are made through those URLs. This website also provides the document type definitions (DTDs) that define the XML for requests, queries, and responses. This document includes the DTDs, along with examples.

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

This chapter includes the following sections:

Configuration

Messages

Message Document Type Definitions

Message Examples

Login Service Error Codes

Configuration

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

To use Cisco Extension Mobility, create a device profile for the user logging in and for the target device.

Use the following steps to configure Cisco Extension Mobility service:

Create a User Device Profile.

Assign a User Device Profile to a User.

Assign authentication proxy rights to a UserID.

Assign a Logout Device Profile to a target device.

Configure the System Parameters.


NoteTechnically, no need exists to assign a profile to a user. The device profile may be specified at login time.

System Parameters use defaults if they are 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, Cisco CallManager Extended Services Administrator Guide, or Cisco CallManager Features and Services Guide.

Messages

You communicate between your login application and the Cisco Extension Mobility Login service by sending and receiving messages that are written in XML. The XML messages that you send must follow the rules set by the Message DTDs that are described in the "Message Document Type Definitions" section.

The default URL for login and logout requests and system queries follows:

http://<server>/emservice/EMServiceServlet

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

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

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

Login Requests

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

Logout Requests

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

Device-User Queries

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

User-Devices Queries

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

Message Document Type Definitions

A Message Document Type Definition (DTD) designates 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 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.

Request DTD

The Request DTD defines the login and logout messages that your application can send to the Cisco 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>

Login or Logout Response DTD

Login or Logout Response DTD defines the messages that your application receives from the Cisco 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>

Query DTD

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

<!-- 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)>

Query Response DTD

The Query Response DTD defines the messages that your application receives from the Cisco 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 Extension Mobility service. Table 2-1 lists each example 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 that specifies the RyanTravelPhone profile and limits 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 displays.

Example 2-5

Request Response

Failure response with error indicates an incorrect appID or password.

Example 2-6

Device-User Query

Query asks what user is logged in to device SEP003094C25B15.

Example 2-7

User-Devices Query

Query asks to which devices user rknotts and fwragge are logged in.

Example 2-8

Device-User Response

Response displays that rknotts is the user who is logged in to device SEP003094C25B15.

Example 2-9

User-Devices Response

Response displays that rknotts is logged in to devices SEP003094C25B15 and SEP003094C25B49, and fwragge is logged in to 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 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 That Specifies 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 That Specifies 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 that indicates 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 that an application sent to the Cisco Extension Mobility service.

Example 2-7 Device-User Query

<query>

<appInfo>

<appID>applicationName</appID>

<appCertificate>password</appCertificate>

</appInfo>

<deviceUserQuery>

<deviceName>SEP003094C25B15</deviceName>

</deviceUserQuery>

</query>

Example 2-8 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 that the Cisco Extension Mobility service sent to the login application after the login application has sent a Device-User query message or a User-Devices query message.

Example 2-9 Device-User Response

<results>

<deviceUserResults>

<device name="SEP003094C25B15">

<userID>rknotts</userID>

</device>

<deviceUserResults>

</results>

<results>

Example 2-10 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 Extension Mobility Login service returns and describes what each error code means.

Table 2-2 Cisco Extension Mobility Login Service Error Codes 

Error Code
Description

0

Unknown Error

1

XML Validation Error: Because the request or query was incorrectly formed, it cannot be properly processed.

2

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

3

Invalid Authentication: The appID and/or appPassword that were provided are incorrect.

4

Policy Validation Error: Some generic issue exists regarding determination whether the request is allowed.

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: The system could not communicate with the AutoLogout service.

8

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

9

DirUser Creation Error: Directory integration error occurred.

10

Proxy Authentication Not Allowed: the appID that is specified does not have rights to log in or log out 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 that does not exist or no Logout Device Profile was configured for the specified user.

18

Device Already Logged In: The system could not log in to the specified device because a user is already logged in.

19

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

20

Get Device Hoteling Flag Error: The system could not determine whether the device allows Cisco Extension Mobility (also called "hoteling").

21

Get Device Hoteling Status Error: The system could not determine whether these is a user currently is logged in.

22

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

23

User Does Not Exist: The userID that was entered for login does not exist in the system.

25

User Already Logged In Elsewhere: The system denied the0 login because the specified user is already logged in to a different device.