Cisco Unified CallManager Developers Guide
Chapter 3. Extension Mobility Service API Programming
Downloads: This chapterpdf (PDF - 362.0KB) The complete bookPDF (PDF - 3.65MB) | Feedback

Extension Mobility Service API Programming

Table Of Contents

Extension Mobility Service API Programming

Cisco Unified CallManager Extension Mobility Architecture

Cisco Unified CallManager Extension Mobility Service Components

How Cisco Unified CallManager Extension Mobility Works

Cisco Unified CallManager Extension Mobility Service Module

Authentication

Pre-Conditions

Automatic Logout

Device Profiles

Logout Device Profile

Using the Cisco Extension Mobility API

New and Changed Information

Dial Plan on SIP Phones

Survivable Remote Site Telephony (SRST) Mode

Credentials for SIP Digest Authentication

EMApp Now a Separate Deployable Service

Failover Support

Clearing Call Logs

Last Login Stored in Database

Enhanced Service URL Generation

Localization Changes

Enhanced Error Codes

Change Notification Enhancements

Performance Counter Enhancements

SIP Phones

Configuration

Messages

Login 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

Application and Service Error Codes


Extension Mobility Service API Programming


Cisco Unified CallManager Extension Mobility (EM) service, a feature of Cisco Unified CallManager, 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 Cisco Unified CallManager Extension Mobility service works by downloading a new configuration file to the phone. Cisco Unified CallManager dynamically generates this new configuration file based on information about the user who is logging in.

Each EM user is associated with a "device profile" through configuration. When a user logs in to a phone, the phone temporarily embodies the device profile for that user. The two primary functions of the EM feature are authenticating the user who is logging in and generating the right configuration file based on the user information.

You can view the device profile as a template for a physical device. The device profile defines the attributes of a device, but it is not associated with a physical phone. A device profile includes information such as the phone template, user locale, services to which the device is subscribed, and so on. Because it is not associated with a physical phone, it does not have information such as MAC address, location, and region. When a phone downloads a device profile, the phone retains its physical attributes such as MAC address, device location information, device CSS, and so on.

The Cisco Unified CallManager support for the Extension Mobility service comprises the Unified CM Extension Mobility Application (EMApp) and the Unified CM Extension Mobility Service (EMService) modules. The application and service modules, along with other Cisco Unified CallManager infrastructure such as the Database Layer (DBL), User directory (either internal or an external LDAP directory), and TFTP server provide the CiscoUnified CallManager Extension Mobility feature.

You can use the XML-based EMService API with your applications, so they can take advantage of Cisco Unified CallManager Extension Mobility service functionality. For details about how to use the Cisco Extension Mobility service API, see the "Using the Cisco Extension Mobility API" section.

To successfully develop an application that uses the Cisco Unified CallManager Extension Mobility service, you need to understand how the service operates and how your application fits into the Cisco Unified CallManager Extension Mobility service. This chapter includes the high-level concepts that are important in understanding the Cisco Unified CallManager Extension Mobility service:

Cisco Unified CallManager Extension Mobility Architecture

Cisco Unified CallManager Extension Mobility Service Components

How Cisco Unified CallManager Extension Mobility Works

Cisco Unified CallManager Extension Mobility Service Module

Device Profiles

Cisco Unified CallManager Extension Mobility Architecture

This section explains the Cisco Unified CallManager Extension Mobility service components and how they work with your application. Figure 3-1 provides a functional diagram of the different EM modules that is followed by a brief description of each module.

Figure 3-1 Cisco Unified CallManager Extension Mobility Functional Diagram

Cisco Unified CallManager Extension Mobility Service Components

The Cisco Unified CallManager Extension Mobility service comprises three basic architectural components. The following paragraphs provide a brief description of each component:

Cisco Unified CallManager Extension Mobility Application—A software module in Cisco Unified CallManager that receives XML requests (via HTTP post) for login and logout of users from the phones. It interacts with other components in the system and responds with a HTTP response message to the phone. The application module validates the "user ID" and PIN in the login request by consulting either a local user directory or an external directory like LDAP. If the "user ID" and PIN are valid, it interacts with the Cisco Unified CallManager EM service module on behalf of the phones. After the interaction with the service module is successful, it notifies the phone to restart with a new configuration.

Cisco Unified CallManager Extension Mobility Service—A software module in Cisco Unified CallManager that receives XML/HTTP requests from the application module to build a new configuration file. The application module provides information such as identity of the device and the device profile for the user who is logging in. It invokes the Database Layer (DBL) via the Java Native Interface (JNI) to write the appropriate configuration file to the TFTP server.

Database Layer (DBL)—Receives a request from the EM service module and generates a new configuration file. The device profile corresponding to the user who is logging in and the physical attributes of the phone provide the basis for the new configuration file. After the new configuration file is generated, it is pushed to the Cisco Unified CallManager database and a change notification is generated to the call-processing module. This notification ultimately results in the new configuration file being pushed to the TFTP server.

The Cisco Unified CallManager Extension Mobility service comprises your application, the EMApp module, the EMService module, the Database Layer (DBL), and the ancillary items that are listed in Table 3-1.

Table 3-1 Additional Cisco Unified CallManager Extension Mobility Service Components 

Component
Description

DBL Monitor

Database Layer Monitor service notifies other processes of changes in the Cisco Unified CallManager database.

LDAP Directory

Lightweight Directory Access Protocol Directory (LDAP) stores information for Cisco Unified CallManager.

CallProcessing

CallProcessing is a Cisco Unified CallManager process that maintains device connections.

CTI

Computer Telephony Interface (CTI) comprises the set of processes that expose programmable APIs for call control.

TAPI/JTAPI

TAPI and JTAPI programmatic interfaces support call control.


How Cisco Unified CallManager Extension Mobility Works

This section describes what happens when your application sends a message to the EMService to use Cisco Unified CallManager Extension Mobility functionality.

Figure 3-1 also illustrates how the Cisco Unified CallManager Extension Mobility components communicate with each other. The high-level message flow between different EM components remains the same as in previous releases.

Your login application submits an XML message to the EMService servlet by using the Hypertext Transfer Protocol (HTTP). The EMService uses the LDAP directory to check the UserID and PIN in the message from the login application. If the UserID and PIN are valid, the EMService executes the request by communicating with the database layer (DBL) through JNI. For more details about how the EMService module works, see the "Cisco Unified CallManager Extension Mobility Service Module" section that follows.

If the DBL changes the device profile for a login or logout request, it tells the DBL Monitor, which passes this information on to the CallProcessing and CTI components. CallProcessing, in turn, tells the Cisco IP Phone that it needs to restart itself to load the new device profile. For more information about device profiles, see the "Device Profiles" section.

The CTI layer notifies JTAPI and TAPI applications that are monitoring the device or user that the application control list has changed.

If the DBL completes a transaction successfully, it tells the EMService. The EMService then sends an XML response that the transaction was successful to your login application by using HTTP.

If the transaction is not successful, the EMService sends your login application an appropriate error message.

Cisco Unified CallManager Extension Mobility Service Module

Your login application communicates with the Cisco Unified CallManager Extension Mobility service through the Cisco Unified CallManager Extension Mobility Service (EMService) component.

Only a single user can log in at a time on a particular device. Subsequent attempts by users to log in on a device before the previous user has logged out will fail. You also cannot log out of a device to which no user is currently logged in. These conditions generate error messages.

When the EMService component receives an HTML message from your login application, it uses HTTP to send an XML response message. The response to a request serves as success or failure message, and the response to a query serves as a query result message.

For more detailed information about these messages, see Messages

Figure 3-2 illustrates more details of the operation of the EMService module.

Figure 3-2 Cisco Unified CallManager Extension Mobility EMService Module

The EMService component sends an appropriate XML error response to your login application if

Authentication fails

A precondition is not met

It cannot contact the DBL

The DBL returns an error

Authentication

The Cisco Unified CallManager Extension Mobility service allows authentication by proxy. That is, a user with Cisco Unified CallManager Extension Mobility proxy rights can log in any user to any device.

What this means is that an application can be responsible for authenticating a user in whatever way that the designer of the application sees fit: by using a password, PIN, hardware key, biometrics, and so on. The application must provide valid credentials for itself, so the Cisco Unified CallManager Extension Mobility Service knows the application is provisioned in the system and allowed to log users in and out.

To this end, you must ensure that a special user that corresponds to the application is configured in the Directory. This user, representing the application, has a standard LDAP UserID and PIN. The application must send a valid UserID and PIN to log a user in or log out from a device.


Note This mechanism requires configuring a UserID and PIN for the application; you can do this by using Cisco Unified CallManager Administration, User Configuration.


Pre-Conditions

The EMService Java Object's Policy Validation engine checks the preconditions.

Only a single user can log in at a time on a particular device. Subsequent attempts by users to log in on a device before the previous user has logged out will fail. You also cannot log out of a device to which no user is currently logged in. These conditions generate error messages.

Automatic Logout

The Logout Scheduler in the EMService module times all login occurrences if you have specified a system maximum login time. If you have not set the login duration, the automatic logout period for that device defaults to the system maximum time.

Device Profiles

Device profiles act as the basic unit of transaction for the Cisco Unified CallManager Extension Mobility service. A device profile contains all the configuration information, such as line appearances, speed dials, and services, for a particular device. You can think of it as a "virtual device." It has all the properties of a device except physical characteristics such as a Media Access Control (MAC) address and a directory URL.

When a user logs in, the User device profile replaces the current device configuration. When a user logs out, the Logout device profile replaces the User device profile.

Logout Device Profile

Cisco Unified CallManager Extension Mobility requires a Logout Device Profile for each configured device. Cisco Unified CallManager Extension Mobility uses the Logout Device Profile, which can be either an Auto-Generated or User Device Profile, as the "logged out" configuration of the device.

Two types of device profiles exist: Auto-Generated device profiles and User device profiles:

Auto-Generated device profile—Can be used only as a Logout device profile. This provides a snapshot of the existing device's configuration. You cannot associate it with a user.

User device profile—It is generated by an administrator and associated with a user in the same manner as any other device.


Note To create an Auto-Generated Device Profile, the system configures a device and a snapshot of the device is taken and saved as a device profile with the prefix ADP (Auto-Generated Device Profile) and the MAC address of the device. For example, the Auto-Generated Device Profile for the device SEP000011112222 specifies ADP000011112222.



Note Cisco Extension Mobility fully supports the Cisco Unified IP Phone 7960 and the Cisco Unified IP Phone 7940 but not the Cisco IP Phone model 7910 and preceding devices.


Using the Cisco Extension Mobility API

The Cisco Unified CallManager Extension Mobility service provides a fairly rich API, which enables extension mobility on Cisco Unified IP phones and allows application control over authentication, scheduling, and availability.

An application that uses Cisco Unified CallManager Extension Mobility service represents an IP phone service that allows a user to enter a userID and PIN at the phone itself and log into the phone. The architecture and implementation of Extension Mobility make many other applications possible; some examples follow:

An application that automatically activates phones for employees when they reserve a particular desk for a particular time (the scheduling application)

A lobby phone that does not have a line appearance until a user logs in

The Cisco Unified CallManager 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 section includes the following topics:

New and Changed Information

Configuration

Messages

Message Document Type Definitions

Message Examples

Application and Service Error Codes

New and Changed Information

This section describes new features and or changes that are pertinent to the Cisco Unified CallManager Extension Mobility Service in Cisco Unified CallManager Release 5.0 for API developers.

Dial Plan on SIP Phones

SIP phones will have dial plan information pushed to them via a configuration file. This dial plan exists as an unordered list of dial maps. One dial plan corresponds to each Calling Search Space (CSS).

In the case of Extension Mobility, the effective list of CSSs for a phone combines "Device CSS" and "Line CSS." Device CSS is tied to the physical attributes of the phone like location, region, and so on, and does not change across the login and logout of users. Line CSS is tied to the lines and changes when users login or logout.

The database layer (DBL) generates the appropriate list of dialmaps when login/logout operations are performed. Because each CSS has a dial map that is linked with it, the DBL module extracts dial map information for each line in the device profile, appends this information to the dial map corresponding to the device CSS, and the resulting dial map list is pushed to the configuration file.

Survivable Remote Site Telephony (SRST) Mode

In SRST mode, the extension mobility behavior remains the same as in previous releases. Users cannot perform login and logout operations when a phone is in SRST mode. Call processing proceeds as normal, given that the SRST gateway is configured appropriately.

Credentials for SIP Digest Authentication

Credentials for SIP digest authentication are configured in the "user directory" window. All the device profiles that are associated with that user must use this set of credentials. For phones that read this information from the configuration file, DBL populates the configuration file with the appropriate credential set.

For phones that do not support digest credentials in the configuration file, digest authentication can break. For extension mobility, the SIP digest credentials change when a user logs in and out. The user must enter the credentials when placing a call.

EMApp Now a Separate Deployable Service

The Extension Mobility Application module (EMApp) remained as a servlet that was automatically started whenever the Cisco Tomcat service was running until the previous release of Cisco CallManager. This service acted as an interface between the phone and the EMService module, the component that updates the database to perform the actual login and logout.

In this release, EMApp is now a separate deployable service. This change occurred to address the serviceability assumption that each service has only one servlet. The administrator must activate/deploy the service before performing start/stop operations from the control center. The upgrade of Cisco Unified CallManager from Windows to Linux takes care of automatically activating this service.

EMApp depends on EMService and is automatically activated when EMService is activated.

The following comprise the necessary changes in the files to implement this feature:

TypeService.csv : ccm_sw\Projects\DBL\DBLInstallCSV—This file updates the database with the correct values. A new entry for "Cisco Extension Mobility Application" is added with the service enum value of 41.

ActiveConf.xml : ccm_sw\Common\XML\ServiceManager—This file is used by service manager and serviceability. A new entry for "Cisco Extension Mobility Application" is added and made a dependent service of EMService.

ActiveW3C.xsd : ccm_sw\Common\XML\ServiceManager—This file is changed to include "Cisco Extension Mobility Application" in the schema.

cm-em.spec : ccm_sw\Projects\CMAppServices\rpm—This file executes during rpm installation. Instead of webapps directory, emapp.war is copied to the appropriate location.

ServicesConf.xml : ccm_sw\Common\XML\ServiceManager—Because EMApp has become a deployable service, the entry is removed from this file.

ServicesW3C.xsd : ccm_sw\Common\XML\ServiceManager—EMApp entry is also removed from the schema.


Note The autologout function of Extension Mobility does not work when the user is logged in/out of EM via the AXL interface. The AXL interface is not intended to be used as a real-time API.


Failover Support

This change addresses the nonavailability of EM when a failure occurs in a node in a cluster. This restriction exists primarily because the Services button on the phone is configured to Unified CM CIP in only one node and, if that node is down, the Services button does not work.

This solution takes advantage of the fact that multiple IP addresses can be configured for a DNS entry. A new DNS entry is created with all the IP addresses of the nodes in a cluster. This new name is not related to any of the Cisco Unified CallManagers. When a failure occurs in a node, the phone contacts Unified CM CIP on the next node to get the list of services. When a user selects a service from this list, the phone will contact EM on that node.

You must make the following configuration changes to provide this support:


Step 1 Create a new hostname with more than one IP address in the DNS entry.

For example, CLUSTER with the IP address IP1, IP2, IP3 for nodes N1, N2, N3, respectively.

Unified CM CIP must run on all the nodes in the cluster. The IP phones must handle multiple IP addresses that the DNS server returns. This release enhances the way phones handle multiple IP addresses.

Step 2 Modify the URL for the IP phone service that is configured for EM:

http:// CLUSTER:8080/emapp/EMAppServlet?device=#DEVICENAME#

Step 3 Change the services URL in the enterprise parameters:

http:// CLUSTER:8080/ccmcip/getservicesmenu.jsp


Figure 3-3 provides a diagram that shows the different failover support components. The dotted lines represent the connections after a failover. The shaded boxes represent required configuration changes.

Figure 3-3 Cisco Unified CallManager Extension Mobility Failover Support Components

Clearing Call Logs

The call log (missed calls, received calls, placed calls) is cleared only during manual EM login and manual EM logout. If EM logout is from ccmadmin, due to automatic logout, or from sampleloginapp, then the log is not cleared. This practice ensures privacy by preventing other users of the same phone from seeing the call logs of the previous user.

In the previous release, EM sent a "login/logout successful" message to the phone after a successful login/logout, and the phone would reset immediately. This message stays on the screen for a maximum of 10 seconds or until the phone does a reset, whichever happens first. If a reset happens sooner, the user might miss seeing this message on the screen.

In this release, lack of enough time to clear the log and send the message before the phone resets means that the call logs are cleared during both login/logout, but no message displays to show that login/logout was successful; however, in the case of failure, appropriate error messages display.


Note Call logs are cleared only during manual EM login and manual EM logout. If EM logout is from ccmadmin, due to automatic logout, or from sampleloginapp, the log is not cleared.


Last Login Stored in Database

In earlier releases, EM preserved the last login UserID of the EM user, so future logins need not enter the same user every time. This change was implemented by saving the last UserID in a local file on the hard disk. In this release, the Cisco Unified CallManager database stores this field either in the device table or in a separate table, which makes this feature more robust and secure.

The algorithm follows:

When EMApp gets a EM login request, it sends an XML request to EMService to query the current device status.

EMService responds to this request by returning the device status and the last logged in user for the device, if there is one.

When there is successful EM login, EMApp sends the last login user id in the login request to EMService so that this field can be updated in the database.

Enhanced Service URL Generation

In the previous release, the services URL was queried based on the activation of the node and not the service. Node activation does not mean that the node is up and running.

In this release, EM queries the service activation table to build the list of EM services that are activated in the cluster. EM also listens to change notification whenever a new node is activated or deactivated.

When a new EM login request is sent to EMApp, it looks at the list of active EM services in the list of service URLs and sends an HTTP request to the first one. Because activation of EM services does not necessarily mean that the EMService module is actually running, the HTTP request might not reach the EMService module, and an HTTP timeout results. In this case, EMApp sends the login request to the next URL in the list of service URLs.

Localization Changes

A recent field addition to the Cisco Unified CallManager table "typeUserLocale" called "alternativeScript" contains the name of an alternative script that can be utilized to allow an endpoint to use a localized file that contains the same language but with a different written script. This change was implemented for Japanese with "kanji" as the alternative to "katakana." Some devices can display only kanji script while some can display only katakana. Because applications can send text information to the phone, they need to know if the phone can support just the default language, or both the default languange and the alternate script. If the phone can support an alternate script, applications need to know what the alternate script is.

EM can get this information for each device model from the database or from an HTTP request. You need to make sure that the HTTP request contains this information. Based on this information, EM will send appropriate strings to the phone.

The "ProductSupportsFeature" table includs a field "useAlternateScript." This table includes entries based on the phone model. If this field is set to 1, the "TypeUserLocale" table contains the actual script that must be used as the alternate script. Because the tables are quite small, EM could load this information and keep it in its cache or look for this information and the phone model in the HTTP request and then decide which to use.

Enhanced Error Codes

In this release the extension mobilitty feature presents the user with enhanced error codes to indicate the nature of the problem. Prior to this release, only a few error codes were displayed on the phone user interface with a description and, for others, only error codes were given. This arrangement lead to difficulties in interpreting the nature of the problem. Overlapping error codes existed between the extension mobility application and the extension mobility service. In this release, separate error codes for extension mobility application and service exist with different ranges specified. EM service error codes range from 0-199 while EM application error codes begin at 200 and range upward. These changes minimize the learning curve for the user with respect to the older error codes.

For detailed information on the new EM error codes, see the "Application and Service Error Codes" section.

Change Notification Enhancements

The extension mobility feature now provides change notification capability to EMApp, which previously did not have change notification for the service parameters. It also provides the capability to listen for change notifications with respect to activation and deactivation of extension mobility service on any node.

EMApp listens for Service Parameter Change notifications and EM Service activation/deactivation on any node within the cluster. This release adds a new EMActivationListener to the Unified CM DBUtil Package. Unified CM Database exposes methods to add and remove the EMActivationListener objects. Finally, the actual notification part is appended to the listener notification mechanism of Unified CM Database.

The notification mechanism for EMActivationListener differs from the ServiceActivationListener. ServiceActivationListener is used primarily for listening for events regarding local service activation or deactivation. It does not propagate events regarding service activation on any other node. EMActivationListener notification mechanism actually sends all events regarding EMActivation on any node to the interested observer (EMApp).

EMApp listens for the activation/deactivation details of the EMService module and maintains a memory map on the activation status of all the EMService modules on different nodes. The system consults this memory map before actually sending a request to that particular EMService module on the node.

Performance Counter Enhancements

This change gives a more granular mechanism to measure extension mobility performance. This release adds four new counters:

EMAPP_ATTEMPTED_LOGIN_LOGOUT—Measures the total number of attempted login and logout requests. This counter includes both successful and failed requests. This counter does not measure the queries that are posted. Thus this count represents the total login and logout requests that were attempted on this node.

EMAPP_NO_OF_SUCESS_LOGIN—Captures the successful login requests.

EMAPP_NO_OF_SUCCESS_LOGOUT—Captures the successful logout requests (only coming through requests). This counter does not include autologouts.

EMAPP_NO_OF_THROTTLED_REQUESTS—Measures all throttled requests (throttling applies only to login/logout requests).

You can use these counters for calculating the success and failure rate of extension mobility logins:

Total Number of Successful Requests =
EMAPP_NO_OF_SUCESS_LOGIN + EMAPP_NO_OF_SUCCESS_LOGOUT

Total Request Failures (Only Login/Logout) =
EMAPP_ATTEMPTED_LOGIN_LOGOUT - Total Number of Successful Requests

Request Failures Other than Throttling =
Total Request Failures - EMAPP_NO_OF_THROTTLED_REQUESTS

EMPerfmon.xml (/Projects/serviceability/pi/xml/) contains all the perfmon object definitions for extension mobility. You can view the perfmon counters by using the RTMT tool.

SIP Phones

No basic design changes occurred from either the EMApp or EMService perspective as far as SIP phones are concerned. However, successful login through EM on SIP phones depends on several factors:

SIP phone support for XSI interfaces. SIP phones must support the following set of URI's to provide the basic functionality of EM through EMApp:

CiscoIPPhoneText

CiscoIPPhoneInput

CiscoIPPhoneExecute

CiscoIPPhoneMenu

Key:Services

SoftKey:Exit

Init:Services

Init:CallHistory

TFTP should be able to generate appropriate configuration files as described in the "TFTP Process Overview for Cisco SIP IP Phones" section in the "Cisco TFTP" chapter in the Cisco Unified CallManager System Guide for Release 5.0.


Note Legacy phones with SIP loads cannot support EM due to limitations with the XML object interface; however, SIP loads on Cisco Unified IP 7961 and 7970 phones are expected to support EM.


Configuration

The Extension Mobility service application accompanies Cisco Unified CallManager. As such, all necessary Cisco Unified CallManager Extension Mobility service API components get installed with the standard Cisco Unified CallManager installation.

To use the Cisco Unified CallManager Extension Mobility service, create a device profile for the user who is logging in and for the target device. Use the following steps to configure Cisco Unified CallManager Extension Mobility service:

Activate the service

Create EM IP phone service.

Create a user device profile.

Assign the user device profile to a user.

Assign authentication proxy rights to a UserID.

Assign userid to the Standard EM Authentication Proxy Rights user group.

Enable EM and configure the default device profile on the target device.
(You must enable EM on a device-by-device basis.)

Subscribe to EM IP phone service on the target device and the device profile.

Assign a logout device profile to a target device.

Configure the system parameters (defaults are used if parameters are not manually configured).


Note Technically, no need exists to assign a profile to a user. The device profile can be specified at login.


For details on how to configure the User Device Profile, refer to the Cisco Unified CallManager Administration Guide or Cisco Unified CallManager Features and Services Guide.

Messages

You communicate between your login application and the Cisco Extension Mobility service by sending and receiving XML messages. 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 is:

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 do not get 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 in to 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 automatically log the user out after a particular time, you can also specify that. 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 login 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 login application specifies a list of one or more users, and the system returns the list of devices to 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 service by sending and receiving XML documents. These XML documents must follow the rules that the Message DTDs set. For examples of how 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 Exchange Mobility 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 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 in to 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 | lastlogin | none | doesNotExist)> 
<!ATTLIST device
          name NMTOKEN #REQUIRED>
<!ELEMENT user (deviceName+ | none | doesNotExist)>
<!ATTLIST user
          id NMTOKEN #REQUIRED>
<!ELEMENT userID (#PCDATA)>
<!ELEMENT lastlogin (#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 login application and the Cisco Extension Mobility service. Table 3-2 lists each example type, a description of the example, and a reference to the example.

Table 3-2 Message Examples 

Message Type
Description
Reference

Login Request

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

Example 3-1

Login Request

The WebLoginApp application makes a login request that specifies the RyanTravelPhone profile and limits the login time to 60 minutes.

Example 3-2

Login Request

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

Example 3-3

Logout Request

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

Example 3-4

Request Response

Response of Success to a login or logout request displays.

Example 3-5

Request Response

Failure response with error indicates an incorrect appID or password.

Example 3-6

Device-User Query

Message asks what user is logged into device SEP003094C25B15.

Example 3-7

User-Devices Query

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

Example 3-8

Device-User Response

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

Example 3-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 3-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 3-1 Simple Login Request

<request>
  <appInfo>
    <appID>7960LoginApp</appID>
    <appCertificate>password</appCertificate>
  </appInfo>
  <login>
    <deviceName>SEP003094C25B15</deviceName>
    <userID>rknotts</userID>
  </login>
</request>

Example 3-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 3-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 3-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 3-5 Success Response

<response>
  <success/>
</response>

Example 3-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 3-7 Device-User Query

<query>
  <appInfo>
    <appID>applicationName</appID>
    <appCertificate>password</appCertificate>
  </appInfo>
  <deviceUserQuery>
    <deviceName>SEP003094C25B15</deviceName>
  </deviceUserQuery>
</query>

Example 3-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 3-9 Device-User Response

Sample UserQuery Response

If you log in to the phone for the first time, the response is as follows:

<response>
<deviceUserResults>
<device name="SEP00016CEA6616">
<userID>one</userID>
<none/>
</device>
</deviceUserResults>
</response>

If you have previously logged in to the phone, the response is as follows:

<response>
<deviceUserResults>
<device name="SEP......">
<userID>one</userID>
<lastlogin>one</lastlogin>
</device>
</deviceUserResults>
</response>

Example 3-10 User-Devices Response

  <userDevicesResults>
    <user id="rknotts">
      <deviceName>SEP003094C25B15</deviceName>
      <deviceName>SEP003094C25B49</deviceName>
    </user>
    <user id="fwragge">
      <deviceName>SEP003094C249A6</deviceName>
    </user>
  </userDeviceResults>
</results>

Application and Service Error Codes

Table 3-3 shows the new error codes the Cisco Unified CallManager Extension Mobility Application module returns as well as the error code numbers for the previous release, and describes what each error code means.

Table 3-3 Cisco Unified CallManager Extension Mobility Application Error Codes 

New
Error Code
Previous Error Code
Message—Description

200

0

NO_ERROR—Successful.

201

1

Authentication error
AUTHENTICATION_ERROR—Authentication failed for user. Shows the user login page with error title.

202

2

Blank UserID or PIN
NULL_PARAM—Shows the user login page with error title.

203

3

Application UserID/Pwd null
APP_AUTHENTICATION_ERROR—Unable to find registry entry for AppUserID/Password.

204

6

Directory server error
DIR_SERV_ERROR—Exception occurred while performing diraccess.authenticateuserwithpin().

205

9

User Profile absent or null
DEV_PROF_ERROR—User profile absent or null.

206

12

No Device Profile associated with User
DEV_PROF_UNAVAILABLE—No Device profile associated with user.

207

100

Device name empty or absent
NULL_DEV_ERROR—Device name empty or absent.

208

101

Cannot connect to EM Service
LOGIN_SERVICE_CONN_ERROR—Unable to connect with EMService.


Table 3-4 shows the current (new) error codes that the Cisco Unified CallManager Extension Mobility Service module returns as well as the error code numbers for the previous release, and describes what each error code means. Shaded rows in this table represent error codes that are no longer used.

Table 3-4 Cisco Unified CallManager Extension Mobility Service Error Codes 

New Error Code
Previous Error Code
Message—Description

0

0

Unknown error
UNKNOWN_ERROR—Error due to some exception, largely unknown; scope for new error code when request type could not be determined.

1

1

Error occurred on parsing request/query
VALIDATION_ERROR—XML error occurred while parsing. Because the request or query was incorrectly formed, system cannot properly process it.

2

2

Error occurred on authenticating app user
AUTHENTICATION_ERRORCould not execute user authentication. Error occurred during the user authentication process, and the validity of the appID and appPassword that were submitted cannot be confirmed.

3

3

Invalid App User credentials
INVALID_AUTHENTICATION—The appID and/or appPassword that were provided are incorrect.

4

4

Policy validation error
POLICY_VALIDATION_ERROR—Exception occurred while doing policy validation. Some generic issue exists regarding the determination of whether the request is allowed.

5

5

Device does not allow logon
REQUEST_DENIED—The request has been denied (failed Policy Validation) for one or more reasons.

6

6

Database error occurred
DB_ERROR—The extension mobility service received an error while trying to communicate with the Cisco Unified CallManager database.

7

7

LOGOUT_REQUEST_ERROR—Not used.

8

8

Cannot determine query type
QUERY_TYPE_UNKNOWN—Could not determine query type (Device-User or User-Devices) for response generation.

9

9

Directory User information error
DIRUSER_ERROR—Directory User Information related error; could not integrate locales/ info / device profiles.

10

10

User does not have app proxy rights
PROXY_AUTHENT_NOT_ALLOWED—User does not have proxy authentication rights. The appID that is specified does not have rights to log in or log out other users.

11

11

Device does not exist
DEVICE_DOES_NOT_EXIST—Device ID is not present in the database. The specified device for login or logout does not exist in the system.

12

12

Device Profile does not exist
DEVICE_PROFILE_ERROR—Either a profile was specified that does not exist or no logout device profile was configured for the specified user.

13

13

PIPE_CREATE_FILE_ERROR—Unused

14

14

PIPE_ERROR—Unused

15

15

PIPE_BUSY—Unused

16

16

SET_PIPE_STATE_ERROR—Unused

17

17

PIPE_WRITE_ERROR—Unused

18

18

Another user logged in
DEVICE_ALREADY_LOGGED_IN—The system could not log in to the specified device because another user is already logged in.

19

19

No user logged in
DEVICE_NOT_LOGGED_IN—The system could not log out of the specified device because no user is logged in.

20

20

Hoteling flag error
GET_DEVICE_HOTELING_FLAG_ERROR—The system could not determine whether the device allows Cisco Extension Mobility (also called "hoteling").

21

21

Hoteling status error
GET_DEVICE_HOTELING_STATUS_ERROR—The system could not determine the current user status.

22

22

Device does not allow logon
DEVICE_DOES_NOT_ALLOW_HOTELING—The device that is specified is not configured for extension mobility ("hoteling").

23

23

User does not exist
USER_DOES_NOT_EXIST—The userID that was entered for login does not exist in the system.

24

24

System not enabled for login
SYSTEM_NOT_ENABLED—System login not allowed.

25

25

User logged in elsewhere
USER_LOGGED_IN_ELSEWHERE—The specified user is already logged in to a different device or is attempting to log in to a different device.

26

26

Busy, please try again
LOGIN_THROTTLED—User login not allowed. The server is busy.