DEVELOPER COOKBOOK FOR THE PRESENCE WEB SERVICE FOR CISCO UNIFIED PRESENCE RELEASE 8.

5
Last Updated: 26/01/2011

All contents are Copyright 2011 Cisco Systems, Inc. All rights reserved.

Page 1 of 62

Developer Cookbook for the Presence Web Service for Cisco Unified Presence Release 8.5

Table of Contents
Introduction ....................................................................................................................................... 3 WSDL Definitions ......................................................................................................................... 3 Terminology .................................................................................................................................. 4 References .............................................................................................................................. 5 Installing the Reference Application .................................................................................................. 5 Requirements ............................................................................................................................... 5 Copying the WAR File .................................................................................................................. 6 Configuring the Web XML File ...................................................................................................... 7 Verify Installation ..................................................................................................................... 9 Debugging ............................................................................................................................... 9 Security Configuration .................................................................................................................. 9 Downloading the Certificates ................................................................................................. 10 Create a Keystore and Import the Certificates ....................................................................... 10 Configure the Reference Application to use the Keystore ..................................................... 11 Using the Reference Application GUI .............................................................................................. 12 Viewing Presence ....................................................................................................................... 14 Managing Groups ....................................................................................................................... 15 Managing Contacts..................................................................................................................... 15 Viewing a Contacts Presence Details ........................................................................................ 17 Using the Eventing Tutorial ........................................................................................................ 18 Building the Reference Application.................................................................................................. 20 src Folder ................................................................................................................................... 20 build Folder ................................................................................................................................. 21 web folder ................................................................................................................................... 21 clientstubs Folder ....................................................................................................................... 21 Build.xml Script ........................................................................................................................... 22 Reference Application Structure ...................................................................................................... 23 Architecture ................................................................................................................................ 23 Web Application.......................................................................................................................... 24 Getting Presence Updates ..................................................................................................... 25 Action Classes ............................................................................................................................ 26 Cisco Unified Presence Handlers ............................................................................................... 27 Example: ContactAction Class............................................................................................... 28 Implementation Information ............................................................................................................. 30 System Startup ........................................................................................................................... 30 Login/Logout ............................................................................................................................... 31 Multi-node .............................................................................................................................. 32 Context Objects .......................................................................................................................... 33 Handler Internals ........................................................................................................................ 34 registerEndPoint Axis Example........................................................................................... 34 registerEndPoint REST Example ........................................................................................ 35 Event Notifications ...................................................................................................................... 37 Expiration ............................................................................................................................... 37 Endpoints ............................................................................................................................... 39 Subscriptions ......................................................................................................................... 40 NotifyAction............................................................................................................................ 41 Polling for Presence ................................................................................................................... 41 Setting Presence ........................................................................................................................ 42 Presence Override ................................................................................................................. 43 Error Handling ............................................................................................................................ 43 Third Party API FAQ........................................................................................................................ 44 Appendix 1 ...................................................................................................................................... 49 Error Codes ................................................................................................................................ 49 Appendix 2 ...................................................................................................................................... 54 PIDF Documents ........................................................................................................................ 54 Sample PIDF .............................................................................................................................. 55 Appendix 3 ...................................................................................................................................... 58 Importing the Eclipse Project ...................................................................................................... 58 Rebuild the Eclipse Project ......................................................................................................... 61

All contents are Copyright 2011 Cisco Systems, Inc. All rights reserved.

Page 2 of 62

Introduction
Presence exchange and user preference information (presence rules, contact list, etc) on Cisco Unified Presence have been made available to Third Party Applications through two web services, the Presence Web Service and the Client Configuration Web Service. The Presence Web Service provides the functionality to manage user presence on a Cisco Unified Presence server. Users can set their own presence states and receive notifications of changes to the presence states of their contacts; the client application registers a HTTP endpoint and sets up a subscription for presence notifications. The Client Configuration Web Service is an interface that allows client applications to manage user preference information on Cisco Unified Presence. The Client Configuration Web Service provides the functionality to provision information such as contacts, contact groups, presence rules, access control lists, and calendaring options. Both these interfaces are described in detail in the Developer Guide for Cisco Unified Presence. This document describes what methods are in the API, and the contents of method requests and responses.
Note:

The term Third Party Interface is used throughout this document and refers to the

combined functionality provided by both web services, the Presence Web Service and the Client Configuration Web Service. A Reference Application is provided with the web services to demonstrate the functionality opened up by the web services. The objective of the Reference Application is not to be of production quality, but to aid developer understanding of how best to use the interfaces. The Reference Application also provides a method for testing that the web services have been correctly set up, and are fully operational. This document describes the functionality of the Reference Application, and outlines how it is built and configured. It also describes implementation, includes source code examples, and provides guidelines on the using the web services.
Note:

The Presence Web Service can also be accessed over REST. Cisco sees REST as being

the interface mechanism of choice in the future. This functionality is an early adopter REST interface and future development and enhancements in the interface mean that compatibility with previous releases of the API is not guaranteed.

WSDL Definitions
The WSDL definition of the SOAP-based web services can be found (on a Cisco Unified Presence server) at:

Presence Web Service (HTTP): http://<cup-hostname>:8082/presenceservice/soap?wsdl Presence Web Service (HTTPS): https://<cup-hostname>:8083/presenceservice/soap?wsdl

 Client Configuration Web Service (HTTPS): https://<cuphostname>:8443/EPASSoap/service/v70?wsdl The Client Configuration WSDL uses two .xsd files. These files are located at:

https://cup-hostname:8443/EPASSoap/presence-rules.xsd https://cup-hostname:8443/EPASSoap/ epas-soap-interface.xsd

Note:

The WSDL will only load in Mozilla Firefox (non-version specific) or Microsoft Internet

Explorer v7.X and above.

Terminology
Name Application User Description An application user is a logical entity that represents a Third Party Application that can log in to Cisco Unified Presence. The primary functionality associated with an application user is the ability to log end users in to Cisco Unified Presence. Setting up the Reference Application involves configuring an application user. An application user is created under the User Management option in the Cisco Unified Presence Administration GUI. Axis Axis is a Java-based implementation of both the client and server sides of the Web services specification. The Reference App uses Axis2 to:

Send SOAP messages Receive and process SOAP messages Create implementation client stub classes using WSDL

The Reference Application uses an Axis2 client library to interact with the Third Party Interface. As the Third Party Interface has two elements, with the Presence and Configuration interfaces served on different ports, the Reference Application must interact with two end points. Client Configuration The Client Configuration Web Service is an interface to Cisco Unified Presence Web Service that allows client applications to manage user preference information such as contacts, contact groups, access control lists, and calendaring options. This web service is available via a SOAP interface. CUP Handler The CUP Handler is the layer of code (in the Reference Application) which communicates with Cisco Unified Presence. There are two Handler implementations available within the Reference Application - a REST implementation, which sends HTTP Requests to Cisco Unified Presence, and an Axis SOAP implementation. Endpoint The Reference Application has an endpoint, which Cisco Unified Presence uses to send presence notifications back to the Reference Application. Any application using the sub/notify feature of Cisco Unified Presence must provide such an end point.

Presence Web Service

The Presence Web Service is an open interface that allows client applications to share user presence information with Cisco Unified Presence. This interface is used by developers to build client applications that can send and receive updates to a user's presence state. The web service is available via a SOAP interface and a REST (HTTP/XML) interface.

REST

REST, is short for Representational State Transfer can be seen as a lightweight alternative to SOAP. Rest relies on accessing resources by using different URIs and putting the XML data in the message body.

References

AJAX Programming - http://en.wikipedia.org/wiki/Ajax_(programming) Apache Struts - http://struts.apache.org/) Axis - http://ws.apache.org/axis2/index.html Eclipse Development Platform - http://www.eclipse.org/ Jakarta Commons HTTP Client library (http://commons.apache.org/httpclient RFC 3863 - Presence Information Data Format (PIDF) RFC4480 - RPID: Rich Presence Extensions to the Presence Information Data Format (PIDF)

Installing the Reference Application

Requirements Copying the WAR File Configuring the Web XML File Security Configuration This section describes how to install and configure the Reference Application. The Reference Application is delivered as a J2EE Web Application; the configuration information for the Reference Application is stored in a web.xml file. The Reference Application can be downloaded as an Eclipse Project. This download includes a WAR file (refApp.war file) in the build\ear folder. If you have not been provided with this file, please contact your Cisco representative.

Requirements
This section assumes that you are running Apache Tomcat version 6.X and have Java2SE version 6. To download this software, go to http://tomcat.apache.org/.

This section also assumes that you have created an application user for the Reference Application on Cisco Unified Presence server, and that you have added your end users to the Cisco Unified Presence server. The application user is created in the Cisco Unified Presence Administration GUI via User Management > Application User > New. Figure 1
Figure 1.

Application user configuration screen on Cisco Unified Presence

Note:

The Application User must be added to the Admin-3rd Party API Group for use with the

3rd Party API.

Copying the WAR File

Procedure:
Step 1.

Copy the refApp.war file into the <CATALINA_HOME>\webapps folder, where CATALINA_HOME is the Tomcat installation directory.

Step 2.

Start and stop Tomcat. The following directory is created: <CATALINA_HOME>\webapps\refApp

Step 3.

Edit the servlet parameters in the <CATALINA_HOME>\webapps\refApp\WEBINF\web.xml file as described in section Configuring the Web XML File.

Step 4.

Restart Tomcat.

Configuring the Web XML File

securityConfig Servlet axisConfig Servlet restConfig Servlet genericConfig Servlet On application startup, certain servlets are invoked to configure the Reference Application. You must define parameters for these servlets during installation; the servlets are configured in the web.xml file.

securityConfig Servlet
The securityConfig servlet is used to define the security configuration for the Reference Application; the configuration parameters are described in Table 1.
Table 1.

securityConfig servlet parameters

Parameter Description

Parameter Name

java_keystore_file

The full path to the Java keystore (including the keystore filename) that contains trusted certificates for establishing TLS connections between the Reference Application and the Cisco Unified Presence server. Path should include keystore filename.

java_keystore_password The password to access the Java keystore.

axisConfig Servlet
The axisConfig servlet is used to point the Reference Application to the REST services on Cisco Unified Presence; the configuration parameters are described in Table 2. The parameters cup_presence_path and cup_config_soap_path must be defined as part of the Reference Application installation; the remaining parameter values can remain as the default values.
Table 2.

axisConfig parameters
Parameter Description

Parameter Name

cup_presence_path

The endpoint where the SOAP-based Presence Web Service is hosted. The CUP_HOSTNAME value should be set to the IP address of the Cisco Unified Presence server

cup_config_soap_path

The endpoint where the SOAP-based Client Configuration Web Service. The CUP_HOSTNAME value should be set to the IP address of the Cisco Unified Presence server.

cup_config_soapversion

The SOAP version used to connect to the Client Configuration Web Service on the Cisco Unified Presence server; only SOAP 1.2 is supported. The syntax is V1_2,

cup_presence_soapversion

The SOAP version used to connect to the Presence Web Service on the Cisco Unified Presence server; SOAP 1.1 and 1.2 are supported. The syntax is V1_1 or V1_2.

cup_config_disablesoapaction This parameter disables the soap action header when connecting to the Client Configuration Web Service. The valid values are true and false. cup_presence_disablesoapacti This parameter disables the soap action header when on connecting to the Presence Web Service. The valid values are true and false.
Note:

SOAP 1.2 messages have an action field in the Content Type header e.g. Content-Type:

application/soap+xml; charset=UTF-8; action="urn:cisco:epas:soap/login"; Disabling the parameters cup_config_disablesoapaction and cup_presence_disablesoapaction removes the action from the header.

restConfig Servlet
The restConfig servlet is used to point the Reference Application to the REST-based Presence Web Service; the configuration parameters are described in Table 3. The cup_rest_presence_path and cup_configsoap_path parameters must be defined as part of the Reference Application installation.
Table 3.

restConfig parameters
Parameter Description

Parameter Name

cup_rest_presence_path

The URL where the REST-based Presence Web Service is hosted. The

CUP_HOSTNAME should be set to the IP address of the

Cisco Unified Presence server. cup_configsoap_path The endpoint where the REST-based Client Configuration Web Service is hosted. The CUP_HOSTNAME should be set to the IP address of the Cisco Unified Presence server.

genericConfig Servlet
The genericConfig servlet has configuration parameters common to both the REST and SOAP interfaces; the relevant parameters are described in Table 4.

Table 4.

genericConfig parameters
Parameter Description

Parameter Name

Application_username The username of the application user. Application_password The password of the application user. callback_url The URL on which the Reference Application will receive notifications from Cisco Unified Presence. Set the

REFAPP_WEBSERVER_HOSTNAME value to the address of the

machine that the Reference Application is running on. handler_factory_clas spath The location of handler class to use when communicating with Cisco Unified Presence. There are two possible settings for the REST and Axis SOAP implementations of the Handler Interface respectively: com.cisco.cup.webservices.refapp.handler.rest.RestHandlerFactory or com.cisco.cup.webservices.refapp.handler.axis.AxisHandlerFactory

Verify Installation
To verify that the Reference Application has installed correctly, in your browser go to Error! Hyperlink reference not valid.http://localhost:<port>/refApp, assuming the Reference Application is installed on your local machine. The login page for the Reference Application is displayed.

Debugging
To help debug any Reference Application installation problems, look at the log file(s) in <CATALINA_HOME>\bin\logs\refApp.log*.

Security Configuration
Downloading the Certificates Create a Keystore and Import the Certificates Configure the Reference Application to use the Keystore This section describes how to configure the Reference Application to use secure transport (TLS v1) between the Application server and the Cisco Unified Presence server; the process involves downloading certificates from Cisco Unified Presence and creating a keystore for the certificates. Figure 2 shows the connections between the Application server, hosting the Reference Application, and the Cisco Unified Presence server.

Figure 2.

Reference Application connections to Cisco Unified Presence server

Note:

The security procedures described in this section must be repeated for any Cisco Unified

Presence server that you wish to connect to the Reference Application.

Downloading the Certificates

The following certificates need to be downloaded from the Cisco Unified Presence server: Presence Interface (cup.der) Configuration Interface (tomcat.der)

Procedure: 1. Create the local directory, e.g. if using Windows create C:\certs\. 2. Login to the Cisco Unified Presence Operating System Administration using your administrator username and password. 3. Navigate to Security Certificate Management. 4. Click Find. The list of certificates is displayed. 5. Click on the link cup.der and click Download. 6. Save the certificate cup.der to the local directory C:\certs\. 7. Navigate back to the Certificate Find/List page, click on the link tomcat.der and click Download. 8. Save the certificate tomcat.der to the local directory C:\certs\.

Create a Keystore and Import the Certificates

A Java keystore is used to store trusted certificates for a Java application; you must set up a Java keystore for the Reference Application. Procedure:

Step 1.

On the Application server (where you installed the Reference Application) you have a Java Runtime Environment installed for the J2EE container you are using. Ensure that the java bin directory is in your path environment variable. Run the command keytool from the command prompt/ shell and it should print out a list of commands as help information.

Step 2.

Open a command prompt/ shell on the Application server, navigate to c:\certs and run the following command (using the parameter definitions in Table 5): keytool -import -alias cup -file cup.der -keystore c:\certs\refapp.keystore -storepass ciscoRefApp

Step 3. Step 4.

You are asked if you want to trust the certificate, enter Yes. From the command prompt/ shell on the Application server, run the following command (using the parameter definitions in Table 5): keytool -import -alias tomcat -file tomcat.der -keystore C:\certs\refapp.keystore -storepass ciscoRefApp

Step 5. Step 6.

You are asked if you want to trust the certificate, enter Yes. To ensure that the certificates have been imported (from the C:\certs\ directory) print out the contents of the Java keystore using the command: keytool -list -keystore refapp.keystore -storepass ciscoRefApp

Note:

When you run the keytool import command, a new Java keystore will be created with the

specified filename and password if this keystore does not already exist.
Table 5.

Import keytool parameter descriptions

Parameter Description

Parameter Name

alias file

The name that is used to identify the certificate in the keystore. The path to the certificate file that was downloaded from Cisco Unified Presence

keystore

The path to the Reference Application keystore. It can be located in a folder of your choice on your local disk.

storepass

The password used to access the keystore.

Configure the Reference Application to use the Keystore

This section describes how to configure the Reference Application to use the newly created Java keystore.

Procedure:

Step 1. Step 2. Step 3. Step 4.

Open the <TOMCAT_HOME>\webapps\refApp\WEB-INF\web.xml file for the Reference Application. Edit the java_keystore_file property so that it contains the full path to the Java keystore created in previous section. Edit the java_keystore_password property so that it contains the password used when creating the Java keystore in previous section. Ensure the URLs configured in the following web.xml properties have a https:// prefix and use the ports listed below:

(axisConfig Servlet) cup_presence_path cup_configsoap_path port : 8083 port : 8443

(restConfig Servlet) cup_rest_presence_path cup_configsoap_path port : 8083 port : 8443

Below are example values for a Cisco Unified Presence server with hostname cupserver: cup_presence_path cup_configsoap_path https://cupserver:8083/presence-service/soap https://cupserver:8443/EPASSoap/service

cup_rest_presence_path https://cupserver:8083/presence-service cup_configsoap_path https://cupserver:8443/EPASSoap/service

Step 5. Step 6.

Restart Tomcat to ensure that all properties are updated. To verify that the certificates were downloaded correctly and the Reference Application is using HTTPS, check the refApp.log in the Tomcat/logs folder for the following: 200 OK message from https://<IP>:8443/EPASSoapDev/service 200 OK message from https://<IP>:8083/presence-service/soap 200 OK message from https://<IP>:8083/presence-service

Using the Reference Application GUI

Viewing Presence Managing Groups Managing Contacts Using the Eventing Tutorial

This section describes the functions that are available using the Reference Application GUI. There are two sets of screens available in the Reference Application, the User Presence Application and the Eventing Tutorial.

To access the Reference Application GUI, in your browser go to Error! Hyperlink reference not valid.http://localhost:<port>/refApp, assuming the Reference Application is installed on your local machine. The login page for the Reference Application is displayed.

User Presence Application These screens use a subset of the Client Configuration Web Service functionality in conjunction with the Presence Web Service; the following operations can be performed: Maintain a contact list View presence of your contacts Set a users presence View the devices a contact is using (an example of rich presence) Block other users from seeing your presence

Eventing Tutorial These screens provide a tutorial on using the presence notification feature provided by the Presence Web Service. It walks the user through setting up and tearing down subscriptions, and viewing notifications associated with a subscription. You select the set of screens you wish to view at login; from the login screen (Figure 3) simply select the screen set, enter your user ID and press the login button.

Figure 3.

Login screen

Viewing Presence
On logging in to the User Presence Application, you are presented with a management screen that allows you to set your presence state, and manage your contact list (Figure 4). You can set your own presence by selecting a presence state from the drop down menu. The following presence states are available: Available Busy (translated to Away on the server) DND (Do Not Disturb) Away Unavailable Vacation (translated to Away on the server)

When users log in, their presence states are automatically set to Available. When users log out, their presence states are set to Unavailable. You can also view the presence state of your contacts from the management screen; an icon displayed to the right of the contact name indicates the presence state. The color code for showing presence is: Green - Available Red - Away, DND

 Grey - Unavailable

If the presence state is none of the above, the presence icon displayed is a grey question mark.
Figure 4.

Presence Management Screen

Managing Groups
You can manage your contact groups by clicking on the My Groups link on the Presence Management screen (Figure 4). The following group management functions are available: Modify a group name In the Select Group drop-down menu, select the group you wish to modify. Enter a new group name and press the Modify button. Delete a group In the Select Group drop-down menu, select the group you wish to delete. Press the Delete button.

Managing Contacts
You can manage the contacts in a group by clicking on the group name link (for example General in Figure 5). The following contact management functions are available: Add a Contact - In the Select Contact drop-down menu, select New. Enter a user ID, domain and a Nickname, and press the Add option. This contact (user) should be provisioned in Cisco Unified Presence. Modify a contact - In the Select Contact drop-down menu, select the contact you wish to modify. You cannot modify the User ID or the Domain associated with a contact. The NickName of the contact can be changed, and the contact can be moved to a new or existing group using the Group dropdown. To move the contact to a new Group - select the Other option in the Group drop down.

 Delete a Contact - In the Select Contact drop-down menu, select the contact you wish to delete. Press the Delete button.

Figure 5.

Managing Contacts

The following screen shows the User moving the contact devtest1 to a New Group Friends. This is done by selecting Other in the Group dropdown and then updating the New Group text field.

Viewing a Contacts Presence Details

You can view more information on a contacts presence by clicking on a contact name. This screen demonstrates retrieving Rich Presence in PIDF format from Cisco Unified Presence. The following presence information is available for a contact: The overall presence state of the contact. The device(s) the contact is using. The privacy status defined for the contact. This facility allows you to block the contact from viewing your presence state.

Figure 6.

Viewing a Contact

Using the Eventing Tutorial

This tutorial demonstrates to a developer the steps involved in setting up the presence notification feature offered by the Presence Web Service. On logging in to the Eventing Tutorial, you are presented with the notification tutorial screen (Figure 7). This screen allows you to perform the following functions: Register the endpoint that is configured in the web.xml file; the end point ID is then displayed on the screen. Subscribe to the presence of some, or all, of the contact list. You can only subscribe to the presence of contacts that have been added to the Cisco Unified Presence database. Remove contact(s) from the subscription. Unregister an endpoint. All presence notifications for a subscription are shown in the Notifications text area. To generate a notification, log in to another instance of the Reference Application as one of the contacts in the subscription. When a subscription is created, a presence notification is immediately generated by Cisco Unified Presence. All of the requests on this screen (with the exception of logout) are serviced by the following class:

com.cisco.cup.webservices.refapp.action.EventingAction
Figure 7.

Notification Tutorial

Building the Reference Application

The Reference Application is available as an Eclipse Project. This section describes the content of the Project, and provides information on building the Reference Application. See Appendix 3 for information on importing the Reference Application into Eclipse. The Project contains the following items: src Contains all the Reference Application source code. build Contains build scripts used to build the Reference Application. The WAR files are located in build\ear. web Contains the jsp and JavaScript files that make up the Web Application. In addition the Java libraries used by the Reference Application are stored in here at WEB-INF\LIB clientStubs WSDL and client stubs for the Third Party SOAP Interface. docs Javadocs describing the Reference Application source code.

src Folder
The src folder contains the following packages: com.cisco.cup.webservices.refapp.action The struts action classes and associated forms that service the UI. com.cisco.cup.webservices.refapp.config Four servlets that run at system start-up, and configure the Reference Application based on the web.xml file. com.cisco.cup.webservices.refapp.endpoint Classes used to manage and cache subscription information. com.cisco.cup.webservices.refapp.handler The handler classes that interact with the Cisco Unified Presence Third Party Interfaces. com.cisco.cup.webservices.refapp.log RefApp logger. The RefApp uses log4j to write to <CATALINA_HOME>\logs\refApp.log* log files. com.cisco.cup.webservices.refapp.ssl Classes for setting up the TLS Connections with Cisco Unified Presence.

build Folder
The build folder contains two ant scripts, build.xml and deploy.xml. The WAR file for the Reference Application is located in the build\ear\refApp.war.

web folder
The web folder contains the following subfolders: images pages Contains the gifs used to represent presence in the contacts tree. Contains the JSP files used to generate the HTML/Javascript that make up the Reference Application UI. tiles WEB-INF Contains the Template.jsp which dictates where a JSP is placed on screen. Contains the tag libraries used by the Reference Application. The strutsconfig.xml is used to configure struts, tiles-defs.xml manages the tiles set up and web.xml configures the Reference Application itself. The build process bundles all these files in to RefApp.war.

(lib)

Contains jar file needed by the Reference Application. These jars include the Axis2, struts and xml handling binaries. Other jar of note is the axisstruts.jar created during the stubs process above. All the jars in the lib directory are put in the RefApp.war file.

clientstubs Folder
The clientstubs folder contains the following files: client-configuration.wsdl Contains the interface definition for the Client Configuration Web Service. presence.wsdl presence-rules.xsd Contains the interface definition for the Presence Web Service. Contains the schema definition of a PresenceRule. It is used by the client-configuration.wsdl file. Epas-soap-interface.xsd generateClientStubs.sh Contains type used by the client-configuration.wsdl. Shows how to generate axis client stubs from the WSDL definitions. Running the file has the effect of creating two jars client-config.jar and presence.jar (one for each WSDL file) and placing them in the lib directory. This script only runs on a Unix/Linux platform.

The WSDL definition for the Client Configuration Web Service is found at:

https://cup:8443/EPASSoap/service?wsdl

The WSDL definition for the Presence Web Service is found at https://cup:8083/presence-service/soap?wsdl

Note:

It is recommended that you always get the latest WSDL from the above URLs for any

application development.

Build.xml Script
The build.xml script, located in the build folder, contains the following targets of note: the all target, the stubs target and the doc tag. The default tag, all, builds the application into a RefApp.war file, and places it in the build/ear folder. The stubs target is used to generate axis client stubs for interacting with the Third Party web services soap interfaces. This target calls the generateClientStubs.sh script in the clientstubs folder, which creates two jars (client-config.jar and presence.jar) in the lib directory. Axis2 provides several options when it comes to mapping WSDL to objects when generating clients. The model used in the Reference Application is XMLBeans which has a powerful schema compiler; however be aware that it generates a huge number of files. The stub generation build files are included only as an example and require an Axis2 installation.
Note:

Generating stubs has only been tested on a Linux platform.

The doc tag generates the Javadoc documentation associated with the Reference Application. In addition another ant file, deploy.xml, can be used to deploy the Reference Application to a Tomcat Server. To run this an environment variable, TOMCAT_HOME needs to be set. The ant script simply copies the RefApp.war, to a webapps folder in Tomcat.

Reference Application Structure

Architecture Web Application Action Classes CUP Handlers

Architecture
An overview of the Reference Application architecture is outlined in Figure 8; the Reference Application is written as a Web Application following a three-tiered-architecture.

Figure 8.

Reference Application architecture

Browser IE and Mozilla

HTML/Javascript/Ajax

HTTP

Action Classes

Servlet Container Tomcat Axis Impl

Hander Interface Rest Impl

Axis Stubs

HttpClient

HTTP XML/HTTP Presence REST API CUP

SOAP/HTTP

Presence CUP Third Party APIs

Configuration SOAP API

The Presentation Layer (web application) is written using HTML. The HTML pages are generated by JSPs. JavaScript and AJAX are embedded in the HTML pages to make UI behavior more dynamic. The Middle Tier contains the Reference Application business logic. There are two layers to the middle tier, a set of Struts action classes that service HTTP requests from Reference Application clients, and a set of handler classes that interact with the Third Party Web Services on Cisco Unified Presence. As mentioned previously there are two implementations of the handler layer, REST and Axis SOAP; these layers make calls to the REST and SOAP Web Services provided by Cisco Unified Presence. There are two interfaces exposed on Cisco Unified Presence, a SOAP interface which provides Presence and Configuration services and a REST interface, which provides Presence capabilities only.
Note:

The Presentation Layer (web application) has been tested on Mozilla Firefox 2 and

Internet Explorer 6.0. The Reference Application is deployed as a WAR file to a Servlet Engine, such as Tomcat. The Java code that makes up the Reference Application uses JDK 5.0.

Web Application
The JSPs that make up the Reference Application User Interface are described in Table 6. The JSP files are located in the web/pages folder in the Eclipse project, with the exception of index.jsp (the welcome page) which is in the web folder.
Table 6.

Reference Application JSPs

Name index.jsp

Screen Login Page

Description This JSP manages user login authorization and application type selection. Submitting the login form calls the LoginAction class.

eventing.jsp

Eventing Tutorial

This JSP demonstrates how to register endpoints and set up a subscription for event notifications. All form submission is handled by the EventingAction class. This JSP uses Ajax to poll the Reference Application for event notifications.

Contact.jsp

Contact Page

This JSP displays rich presence and manages the functionality for blocking a users presence. This JSP Interacts with the UserAction class.

ContactList.jsp

Contact Tree

This JSP receives contact information that it uses to draw the contact tree. This JSP uses Ajax to poll for presence updates; polling and setting of presence results in calls to Presence Action.

ContactsMaintainance.jsp GroupMaintainance.jsp errorPage.jsp

Manage Contacts Screen

This JSP interacts with ContactAction class for adding/updating/deleting contacts.

Manage Groups Screen

This JSP Interacts with GroupAction class for adding/updating/deleting contacts.

Error Page

This JSP will be displayed if an exception is thrown by any other JSP page

Presence.jsp

This JSP carries Ajax call back information for the contact tree.

Notification.jsp

This JSP carries Ajax call back information for the eventing screen.

Tiles are used to control what part of a HTML pages a JSP will write to. Tiles are configured using the Web-Inf/tiles-def.xml page.

Getting Presence Updates

The process for directing a presence update to a users screen is described, and illustrated in Figure 9. Cisco Unified Presence notifications are dealt in detail later in the document, but this section gives an overview of the process on the client side. The contactList JSP and eventing JSP use AJAX to poll the Reference Application for server updates. The contactList.jsp updates the buddy list tree every 5 seconds (see the triggerPull(5) call) by an Ajax call to getTreePresence in the PresenceAction. Cisco Unified Presence sends a PresenceNotification to the Third Party Application. The NotifyAction handle the notification by putting the presence update in a SubscriptionCache. The UI make a call to the getTreePresence method on the PresenceAction over Ajax. The PresenceAction checks the cache for updates and returns an XML snippet for any updates to the UI. The UI uses Javascript to change the color code of a contact in the tree to reflect the change.

Figure 9.

Getting presence updates for the contact tree

Action Classes
The Reference Application uses Apache Struts, an open-source framework for creating Java Web Applications. To see how HTTP Requests are forwarded to the correct struts action, refer to the Web-Inf/struts-config.xml file. Submitting a HTML form in the Reference Application results in a call to one of the struts action classes in the com.cisco.cup.webservices.refapp.action package. The Action classes are quite lightweight, typically performing the following functions: Converting form variables to handler parameters Calling the appropriate hander Storing any information returned from the handler in the request or session Forwarding to next screen The Action classes and the functionality they illustrate are described in Table 7.
Table 7.

Reference Application action classes

Action EventingAction

Functionality Provides examples on using the event methods e.g. on setting up and tearing down, registering subscriptions and endpoints.

ContactAction GroupAction LoginAction LogoutAction NotifyAction PresenceAction UserAction

Add/modify/delete a contact. Add/modify/delete a group Log an end user in to Cisco Unified Presence. Log an end user out of Cisco Unified Presence. Handling a presence notification. Setting a users presence, and retrieving cached presence. Getting (polled) rich presence of a contact, and blocking a contact from seeing a users presence. Code for parsing PIDF to get Device and Privacy Information.

Cisco Unified Presence Handlers

The Cisco Unified Presence Handlers are the classes that interact with Cisco Unified Presence. The interfaces that Cisco Unified Presence Handlers must implement are at: com.cisco.cup.webservices.refapp.handler Table 8 lists the Cisco Unified Presence handler classes and interfaces, and indicates whether they use configuration or presence information from Cisco Unified Presence. There are currently two implementations of the handler interfaces, one for Axis and one for REST.
Table 8.

Cisco Unified Presence Handler descriptions

Class HandlerFactoryGenerator

Purpose This class determines which HandlerFactory implementation (Axis or REST) is used.

Type NA

HandlerFactory

This class is the gateway to handler logic, acting as Presence a Factory for creating handler objects. There are two implementation of this factory, one for returning Axis Handlers, another for returning REST Handlers. In addition the login/logout functionality is available here.

ACLHandler

This class determines the methods that can be carried out on a Rule ACL.

Configuration

CalendarHandler

This class is used to access the calendaring logic available on Cisco Unified Presence.

Configuration

ContactHandler

This class allows for managing the contacts on Cisco Unified Presence.

Configuration

CupContext

This class represents a user session with Cisco Unified Presence.

NA

GroupHandler

This class allows for the managing of groups on Cisco Unified Presence.

Configuration

PresenceHandler

This class allows for getting and setting of Presence.

Presence

ApplicationHandler

This class interacts with the Subscribe/Notify capabilities of the Presence Web Service.

Presence

PresenceRulesHandler

This class determines the methods for getting and Configuration setting presence rules.

The two implementations of the handler interfaces are: An Axis Soap implementation at.

com.cisco.cup.webservices.refapp.handler.axis which make calls to the Third Party Interfaces over SOAP. This implementation has implementation of all the handler interfaces (both Configuration and Presence) A REST implementation at com.cisco.cup.webservices.refapp.handler.rest that extends the SOAP implementation. This package has separate implementations of the HandlerFactory ,PresenceHandler and ApplicationHandlers making calls to the RESTful Presence Interface; the REST Implementation still needs to use SOAP to interact with the Client Configuration Web Service, but uses REST to exchange presence data.

Example: ContactAction Class

The ContactAction class is a good example of an action class interacting with Cisco Unified Presence handlers. It is called by the Reference Application GUI when any contact information needs to be maintained. To access the contact functionality on Cisco Unified Presence, the ContactAction class uses a ContactHandler implementation, as illustrated in Figure 10.

Figure 10.

ContactAction class

There are two steps in getting a ContactHandler: Call the HandlerGeneratorFactory to get the HandlerFactory being used. In Figure 10 an AxisHandlerFactory is returned. Get the required Handler call the appropriate method in the HandlerFactory. In Figure 10 calling getContactHandler, will see an AxisContactHandler object being returned.

The action class then calls the appropriate method on the ContactHandler, which will result in a SOAP call (over Axis stubs) to Cisco Unified Presence. Following is a code snippet for fetching a contact list.

CupContext context = endUser.getCupContext();

HandlerFactory

handlerFactory =

HandlerFactoryGenerator.getHandlerFactory().

ContactHandler contacthandler = handlerFactory.getContactHandler(context);

List<ContactGroup> contactList = contacthandler.getContactList();

Implementation Information
System Startup Login/Logout Context Objects Handler Internals Event Notifications Polling for Presence Setting Presence

System Startup
The application web.xml is configured to run the init method of the servlets that appear in the com.cisco.cup.webservices.refapp.config package at system startup. The init functionality of each servlet, and the order in which they run, is as follows: 1. 2. SecurityConfigServlet reads the keystore information. AxisConfigServlet points the Reference Application to the SOAP interfaces on Cisco Unified Presence. 3. RestConfigSerlvet points the Reference Application to the Rest interface on Cisco Unified Presence. 4. GenericConfigServlet loads other configurations parameters such as the Application User name and password, the callback URL, and what handler implementation is being used by the Reference Application. The GenericConfigServlet also has the following lines in its init method:

HandlerFactoryGenerator.getHandlerFactory() .login(APPLICATION_USERNAME, APPLICATION_PASSWORD, true, true); if(cupContext != null) { ApplicationUser.getInstance().setCupContext(cupContext); ApplicationUser.getInstance().setUserID(APPLICATION_USERNAME); } CupEndPoint.getInstance().register();

This code snippet sets up two important singletons within the Reference Application:

 The application user that is logged into Cisco Unified Presence; this object will in turn be used to log in end users to Cisco Unified Presence, and An endpoint which will be used to receive presence notifications from Cisco Unified Presence.

Login/Logout
As noted in previous section, on start-up the Reference Application creates an application user and logs the application user in to Cisco Unified Presence. Once an application users credentials (user name and password) are verified by Cisco Unified Presence, the application user can log in end users to Cisco Unified Presence. As the Reference Application uses only one application user, the class com.cisco.cup.webservices.refapp.endpoint.ApplicationUser which models the Application User, is a singleton. When a user (application user or end user) logs onto Cisco Unified Presence via the Third Party Interface, they are granted a session ID. This session ID must be passed back in all subsequent calls to the interface. In SOAP requests the session ID is passed in SOAP header as follows: <soapenv:Header> <session-key xmlns="urn:cisco:cup:tpi:soap"> beb3bb70-1be2-4d73-90f8-e8b3929af58c </session-key> </soapenv:Header>

With the REST interface, the session ID is passed as a request header as follows:

Presence-Session-Key:

beb3bb70-1be2-4d73-90f8-e8b3929af58c

Thus all handlers must be passed a session ID (contained in CUPContext) to enable them to communicate with Cisco Unified Presence. Logging out involves passing the session key back to Cisco Unified Presence, where all the resources associated with the session will be destroyed. A user can be logged in/logged out over REST or SOAP interfaces, so both the RestHandlerfactory and the AxisHandlerFactory have login/logout methods. The login methods for either interface are similar. For example when logging in an end user, the end users id and the application users session key are passed to Cisco Unified Presence for both interfaces. Cisco Unified Presence acknowledges a successful login by returning a session ID. This session ID is used to create a CUPContext object which is then passed as a parameter to all Handler objects. The Handlers need the CUPContext so they can extract the session ID when communicating with Cisco Unified Presence. In summary the HandlerFactories logs an application user in to Cisco Unified Presence with a user name and password combination. End users are logged in with their user name and the application users session ID. A successful login results in the creation of CupContext objects which are stored with the EndUser in the HTTP Session object.

Multi-node
Cisco Unified Presence can be distributed across a series of clusters. Figure 11 shows a deployment with two sub clusters, each with two Cisco Unified Presence nodes. End User 1 is configured to have Node 1a as its primary node, while End User 2 has Node 2b as its primary node. Both end users are logged on to a Third Party Application which has an associated application user.
Figure 11.

Clustered Cisco Unified Presence deployment

End User1

Node 1a

Node 2a

Node 1b

Node 2b

End User2

CUP Sub Cluster1 Application User

CUP Sub Cluster2

Third Party Application End User1 End User2

The key points to note are: The application user is not tied to any sub-cluster or any node in a sub-cluster; it can log in an end user to any node. End User 1 has Node 1a as its primary node, so on logging on to the Third Party Application (TPA), the TPA will use the application user to log the end user onto Node 1a. Once an end user is logged on to a node, all end user requests will be routed to that node, with the end users session key.

 The TPA will maintain a record of what nodes an end user is logged into. In the event of a users primary node failing, the TPA will forward end user requests to the users backup server.

Context Objects
There are the extensions of the CupContext class for REST and Axis: com.cisco.cup.webservices.refapp.handler.axis.AxisCupContext and com.cisco.cup.webservices.refapp.handler.rest.RestCupContext with RestCupContext extending AxisCupContext.

There are two service stub objects in the class AxisCupContext, which are used to invoke SOAP API methods. The stub objects are generated from the WSDL as part of the client stub generation. There is one stub object generated for each service element defined in the WSDL, configStub and presenceStub. There is a default constructor for each that uses the relevant service endpoint defined in the WSDL. However, in the Reference Application, the instances of the stub objects are created using the constructor that take an endpoint URL as the argument (the endpoints are passed to the AxisCupContext constructor). A number of client options can be set for the stubs. In the AxisCupContext constructor the following client options are set: HTTP Chunking is turned off on the PresenceSoapServiceStub; this is required to call the Presence Interface web service. REUSE_HTTP_CLIENT is used to configure Axis to re-use one instance of the HTTPClient object for each stub The SOAP version to be used is set. Setting of action fields in the Content Type Header is disabled. The HTTP Header Connection : Keep-Alive is added to the stub properties to request a persistent connection from the server As the REST handlers dont use SOAP to engage with the Presence Web Service, the RestCupContext doesnt initialize the PresenceStub. Instead the object HTTPClient is created, which is used for fire requests at the REST Interface. RestCupContext uses HTTPClient objects created by the class: com.cisco.cup.webservice.refApp.ssl.ConnectionManager
Note:

The HTTP client objects are set up to allow concurrent requests.

The ConnectionManager registers a custom Protocol Socket Factory for handling HTTPS requests; this is to ensure HTTPS requests will always used the TLSv1 protocol as required by the Presence Web Service. The custom Protocol Socket Factory that is registered is the AuthSSLProtocolSocketFactory class which can be obtained as part of the HTTPClient contrib package.

Handler Internals
To illustrate the contents of Handler objects, a REST and an Axis example of the registerEndPoint method is provided in this section. This method is used as part of the Presence Eventing model, this model is discussed in detail in the section Presence Eventing.

registerEndPoint Axis Example

This section describes the registerEndPoint method for Axis, AxisApplicationHandler.registerEndPoint(). The AxisHandler is passed an AxisCupContext in its constructor. The handler gets a stub from the context object in order to invoke a registerEndPoint request on the Third Party SOAP Interface. The method builds the parameters needed by the stub method and is an example of using the classes generated during the WSDL generation exercise. The RegisterEndPoint and RegisterEndPointDocument classes for example, were generated (by axis) from the WSDL, and can be found in the lib/presence.jar file.

public int registerEndPoint(String url, int endPointID, int expiration) throws HandlerException {

int result = 0;

// Using the Generated classes RegisterEndPoint regEPointObj = RegisterEndPoint.Factory.newInstance();

regEPointObj.setUrl(url); regEPointObj.setEndPointID(endPointID); regEPointObj.setExpiration(expiration);

//set up RegisterEndPointDocument used in the SOAP request RegisterEndPointDocument regEPointReq = RegisterEndPointDocument.Factory.newInstance();

regEPointReq.setRegisterEndPoint(regEPointObj);

RegisterEndPointResponseDocument regEPointResp = null;

try { AxisCupContext context = getAxisCupContext();

// invoke the web service regEPointResp = context.getPresenceStub().registerEndPoint( regEPointReq, context getPresenceSessionKeyDocument() ); } catch(RemoteException re) { throw new HandlerException(re); }

if(regEPointResp!= null)

{
result = regEPointResp.getRegisterEndPointResponse() .getEndPointID(); }

return result; }

registerEndPoint REST Example

This section describes the registerEndPoint method for REST, RestApplicationHandler.registerEndPoint(). The purpose of this method is to create a HTTP request in the format below and send the request to the REST Interface of the Presence Web Service on Cisco Unified Presence.

POST /presence-service/endpoints HTTP/1.1 Presence-Session-Key: {app-user-session-key}

<?xml version="1.0" ?> <endpoint> <url>{callback-url}</url> <expiration>{expiration}</expiration> </endpoint>

Cisco Unified Presence will respond with a HTTP response in the format shown below, from which the endpoint is read:
HTTP/1.1 201 CREATED Location: http://{hostname}/presence-service/endpoints/{endpointId}

The method uses the Jakarta Commons HTTP Client library (http://commons.apache.org/httpclient) to create and send the HTTP requests. DOM Parsers are use to formulate the body of the POST method and to parse the returned response. See the embedded comments on the code below to understand method contents.

// If it a new endpoint uses a PostMethod otherwise use PutMethod. Refer to interface definition as to what HTTP Method should be used. if(endPointID == 0) { method = new PostMethod(uri); } else { method = new PutMethod(uri + "/" + endPointID); } // The Session ID is passed as a HTTP Header RestUtils.addSessionKeyHeader(method, restCupContext.getSessionId()); // Build the Request Body String request = "<?xml version=\"1.0\"?>\n" + "<endpoint>\n" + " <url>" + callbackUrl + "</url>\n" + " <expiration>" + expiration + "</expiration>\n" + "</endpoint>"; RequestEntity entity = new StringRequestEntity(request, "text/xml", "UTF-8"); // Configure the form parameters method.setRequestEntity(entity); // Execute the method on the HttpClient object on the RestCupContext int statusCode = restCupContext.getPresenceHttpClient().executeMethod(method); if (statusCode != HttpStatus.SC_CREATED) { log.log(LEVEL.Error, "registerEndPoint Method failed: " + method.getStatusLine()); throw new HandlerException("Error Registering REST End Point"); } Header locationHeader = method.getResponseHeader("Location");

// Extract the EndPoint ID and return return RestUtils.getResourceIDAsInt(locationHeader.getValue());

Note: The call to the REST Interface on the Presence Web Service will have a Session ID set as a HTTP header. Different HTTP methods are used depending on the service being invoked in the Presence Web Service. Please refer to the Developer Guide for Cisco Unified Presence for a description of the methods and parameters that are used for each call to the Presence Web Service. Data can be passed to the Presence Web Service in the URI, as a HTTP header, or in the XML message body. The example above returned an end point in the message body.

Event Notifications
The sequence flow in Figure 12 shows the methods used in the Presence Web Service to exchange presence data, using the eventing model. On start up the Reference Application registers an endpoint with Cisco Unified Presence and is passed back an endPointID. This endPointID is stored in the CupEndPoint class and is made available to the Reference Application when a subscription is created. The Reference Application sets up a subscription and is returned a subscription ID. When a subscription is created, the endpoint is one of the parameters passed to Cisco Unified Presence, along with the contacts whose presence will be watched by the subscription. When Cisco Unified Presence needs to notify the Reference Application of an event, it sends an HTTP notification to the Reference Application specifying the subscriptionID and the eventType. This alerts the Reference Application that an event of the specified type has occurred and that it should retrieve it. The Reference Application calls the appropriate method to retrieve the event.

A client application should respond to a notification of type PRESENCE_NOTIFICATION by calling getSubscribedPresence on the Presence Web Service. The client application can call the unsubscribe and unregisterEndPoint methods to terminate the subscription and to un-register the end point respectively.

Expiration
An important point concerns the prevention of endpoint registrations from timing out. An expiration (or Time-To-Live) is passed as a parameter to Cisco Unified Presence for endpoint registration. This parameter reflects how long the endpoint is registered with Cisco Unified Presence. The expiration interval for endpoint registration can be refreshed by invoking the registerEndPoint method on the Presence Web Service and passing in the endpointID and the updated expiration interval.

This is done in the Reference Application by a TimerTask in the CupEndPoint class.

Figure 12.

Event Notification Message Flow

Endpoints
In order to use the Event notification feature of the Presence Web Service, the Reference Application must expose an endpoint to Cisco Unified Presence; this endpoint is used by Cisco Unified Presence to send event notifications. The management of this end point is performed by the class: com.cisco.cup.webservices.refapp.endpoint.CupEndPoint This class has methods for registering and unregistering endpoints. It also prevents the endpoint registration from expiring. Registering an endpoint involves sending a call back URL and an

expiration interval to Cisco Unified Presence. The Reference Application is configured to use the following action class to handle incoming notifications: com.cisco.cup.webservices.refapp.action.NotifyAction The CupEndPoint, a singleton, is set up in conjunction with the ApplicationUser at system startup. As can be seen from the CupEndPoint class, an ApplicationHandler is used to set up and tear down endpoints. There are Rest and Axis implementations of the ApplicationHandler.

Subscriptions
In addition to setting up endpoints the ApplicationHandler also manages subscriptions through its subscribe and unsubscribe methods. The following is the subscribe method signature:
public int subscribe(List<ContactURI> contactList, EventType eventType, int expiration, int endPointID, int subscriptionID) throws HandlerException

This method takes in an ad-hoc list of contact URI, an eventtype (the only supported eventtype is PRESENCE_NOTIFICATION), an expiration interval (in seconds) an endpointID, and a subscriptionID. The endPointID is retrieved from the CupEndPoint singleton. There are two possible ways of using the subscriptionID parameter. You can pass in a subscriptionID value of zero which instructs Cisco Unified Presence to create a new subscription, the subscribe method will return the ID of the new subscription. To add contacts to an existing subscription, pass in the relevant subscriptionID value and the additional contacts. An important point concerns the prevention of subscriptions from timing out. An expiration (or TimeTo-Live) is passed as a parameter to Cisco Unified Presence for a subscription. This parameter reflects how long the subscription is valid for with Cisco Unified Presence. The expiration interval for a subscription can be refreshed by invoking the subscribe method on the Presence Web Service and passing in the subscriptionID, the endpointID and the updated expiration interval. This is done in the Reference Application by a TimerTask in the SubscriptionCache class. The unsubscribe method takes in a list of contacts to be removed from a subscription with the given subscriptionID. To remove all contacts from a subscription set the unsubscribeAll flag to true, or list all contacts to be removed from the subscription in the contactsList parameter. The unsubscribe method is as follows:
public void unsubscribe(List<ContactURI> contactList, int subscriptionID, boolean unsubscribeAll) throws HandlerException

NotifyAction
When a presence event of interest to a subscription takes place on Cisco Unified Presence, Cisco Unified Presence sends a notification back to the appropriate endPoint. The NotifyAction class is configured to be the Reference Applications endPoint. As this notification (or call back) is over an unsecure link, the notify message will not contain any security sensitive data. It will however include the ID of the subscription associated with the event. The NotifyAction then calls getSubscribedPresence on the PresenceHandler, which calls the Presence Web Service over a secure link to get the actual presence change. getSubscribedPresence is defined as follows:
public MultiUserPresence getSubscribedPresence(int subscriptionID, PresenceType presenceType) throws HandlerException;

There are two types of Presence_Type, BASIC_PRESENCE and RICH_PRESENCE. Passing in BASIC_PRESENCE will see a string such as AVAILABLE, BUSY, etc being returned, while specifying RICH_PRESENCE will see a PIDF document being returned. The PIDF document defines the end users overall reachability, and the status of each device associated with the end user. For detailed information on the content of a PIDF, and sample PIDF documents, refer to Appendix 2. The presence data is then cached on the WebServer for retrieval by a Reference Application client. The endpoint package contains a SubscriptionCache for caching details on a subscription. Some of the details cached include: The logged in End User who created the subscription. The contacts associated with the subscription. Any presence event associated with the subscription.

So typically the NotifyAction will place presence event data for an end user in the subscription cache. The PresenceAction, which is being continually polled by Reference Application clients, checks if there are any events in the cache associated with the end user, and returns any updates to the client.

Polling for Presence

The Presence Web Service provides a PolledPresence (or Snapshot) mechanism for providing presence information to a Third Party Application. This polling functionality can be seen in the Rest and Axis implementations of the getPolledPresence method in PresenceHandler Interface. The getPolledPresence method is defined as follows:
public MultiUserPresence getPolledPresence(List<ContactURI> contactList, PresenceType presenceType) throws HandlerException;

This interface is defined as taking an ad-hoc list of contacts and a Presence Type. There are two types of Presence_Type, BASIC_PRESENCE and RICH_PRESENCE. Passing in BASIC_PRESENCE will see a string such as AVAILABLE, BUSY, etc being returned, while specifying RICH_PRESENCE will see a PIDF document being returned.
Note:

This mechanism bypasses the eventing model to get presence. A Third Party Application

could continually use getPolledPresence to get presence updates; this alternative to eventing, while easier to implement, increases network traffic and increases the load on Cisco Unified Presence. The Presence Web Service is throttled to prevent an overload on Cisco Unified Presence.
Figure 13.

Presence Polling Message Flow

Setting Presence
The Presence Handler interface also has a method for allowing end users to set their presence states on Cisco Unified Presence. The setPresence interface is as follows:
public void setPresence(SingleUserPresence presenceInfo, int expiration ) throws HandlerException;

The presenceInfo parameter contains the presence information. The expiration value specifies how long this presence information is valid for; subsequent calls to setPresence are needed to maintain a presence state after the expiration time. The SingleUserPresence class can hold Rich Presence and Basic Presence. The setPresence method handles passing both rich and basic presence to the Third Party Interface. The setPresence method is on: com.cisco.cup.webservices.refapp.handler.axis.AxisPresenceHandler
Note:

Rich Presence is represented as a PIDF document, an example of which is included in

Appendix 2. Refer to this section for a description of the content of a PIDF document.
Note:

The Reference Application only has a use case for setting SIMPLE Presence, i.e. passing

down a String Representation (AVAILABLE, BUSY etc).

Table 9 lists the presence States on Cisco Unified Presence, and provides a definition for each state.
Table 9.

Presence state definitions

Definition

Presence State

Available Away Do Not Disturb (DND) Unavailable

The user is available. The user has logged in but presence is set to AWAY. The user has logged in but Presence is set to DND. This state is returned when a user is not logged in to Cisco Unified Presence through any UPC client (or the Presence Web Service).

Unknown

This state returned when Cisco Unified Presence is asked for the presence of a user that it does not know about.

Presence Override
Presence override is the concept of setting your presence state to override any other presence events. For example, you might be at your desk, but have set your presence to DND, in an override state. This means all other device initiated presence events (i.e. going on/off hook) will be overridden by the original DND presence event. Override is represented as a boolean on the SingleUserPresence class.
Note:

A state of Available can ONLY be set with override set to false. A state of DND can ONLY

be set with override set to true.

Error Handling
This is applicable to the SOAP Interface only. When the Presence Web Service on Cisco Unified Presence encounters an error condition, it generates a Fault. This results in an AxisFault being thrown in the Axis Handler Layer of the Reference Application. A definition of the AxisFault class is as follows: http://ws.apache.org/axis/java/apiDocs/org/apache/axis/AxisFault.html The Reference Application has a very basic exception (fault) handling procedure in that all exceptions are just written to the log\refApp.log file under the Tomcat Installation directory. The AxisSoapFaultUtils class contains an example of how to parse a SOAP fault. Appendix 1 lists the errors that can be generated by the SOAP-based Presence Web Service. Each error has a code, a message and a recommended fix. The errors covered in the Appendix are only returned by the Presence SOAP Interface.

Third Party API FAQ

Note:

In this section the term Third Party Interface refers to the web services that open up both

Presence exchange and user preference information (presence rules, contact list, etc) on Cisco Unified Presence, the Presence Web Service and the Client Configuration Web Service.

What Interfaces make up the Third Party API? The Third Party API consists of a Client Configuration Interface and a Presence Interface. Both interfaces are available as Web Services, though the Presence Interface can also be accessed over REST. The Presence and Client Configuration interfaces run on different components on Cisco Unified Presence and are available on different ports.

Why does interacting with the API involve using two certificates? What TLS Versions are supported? As mentioned above the Third Party API is split across two Cisco Unified Presence components. Interacting with SIP Proxy requires one certificate, and calling the Tomcat Config Servlet requires another certificate. These certificates are downloaded via the Cisco Unified Presence Operating System GUI. TLSv1 is supported.

What versions of SOAP are supported by the Third Party API? The Presence Interface supports SOAP V1.1 and V1.2. The Configuration Interface supports V1.2 only.

Can the Third Party API be accessed over HTTP? The Presence Interface is available over HTTP. The Client Configuration Interface cannot be accessed over HTTP.

What is the difference between RICH and BASIC Presence? Rich Presence is in a PIDF format (for a sample PIDF, refer to Appendix 2) and contains information beyond an end users basic presence state. Rich presence contains an end users overall reachability status and the status of each device associated with the end user. The Reference Application for example, shows retrieving device information over PIDF. Basic Presence involves sending one of the seven basic presence states in a string format i.e. Available, Busy, etc. The basic presence states are defined in Table 9.

How do I read a PIDF document? The PIDF document is made up of a persona section, and a tuple section per device associated with the end user. The persona section identifies the end user and defines the end users overall

reachability. The tuple section identifies an associated end user device and contains information on the status of the device. Note that the status of a device can either be open or closed. For more detailed information on the content of the PIDF, refer to Appendix 2.

What is the purpose of the override flag when setting Presence? When setting presence, a presence status and an override flag are passed to Cisco Unified Presence. Setting override to true sets an end users overall reachability and overrides the presence of an end users devices. When an end user sets their presence to DND (DND must have an associated override of true), their presence will be still DND, even if they go on a call. Normally going on a call, would see Call Manager publishing a BUSY Event to Cisco Unified Presence. The event will be ignored if the users presence is a DND state, because of the override session. When using the override flag for rich presence, the tuple ID should be set to pws-override or pws-persistent. How does setPresence with override set to false affect my overall presence status? A presence rules for a user dictate how setPresence requests are handled by Cisco Unified Presence when override is false. The user is actually setting their presence for a particular client and the presence rules decide how that change affects their overall status. With default presence rules, setting the status of a user to 'Available', 'Away', 'Busy' or 'Vacation' on a PWS client will also update the overall status for a user; but this is not guaranteed for 'Unavailable'. A overall status for a user will only be set to 'Unavailable' when they are unavailable on all their clients. Note: A presence rule for a user may be modified to change this default behavior.

How do I set up an Application User? An application user is set up using the user management option in the Cisco Unified Presence Administration GUI. When setting the application user, keep a note of the user name and password as you will need these values for configuring the web.xml file in the Reference Application.

Why must HTTP Chunking be disabled when using the Presence Interface? Presence Interface is rendered by a GSOAP Web Service stack which has a requirement that HTTP chunking be disabled.

What are the presence eventing models, and why would I use one over the other? There are two presence eventing models supported, polling and eventing. Polling is easier to implement on the client, but may cause increased network traffic and load on the Cisco Unified Presence. This is the method to use for getting a quick presence snapshot. However, to monitor a users presence over time, the eventing model is more efficient and will give presence updates in real time as distinct from having a polling interval lag.

What are the issues around maintaining an endpoint? When an endpoint is created, an endpointID is returned by Cisco Unified Presence which is used to manage the endpoint. When an endpoint is created, an expiration interval must be passed as a parameter. This timeout is absolute and is NOT an inactivity timeout, meaning the timer starts as soon as the endpoint is created. The interval can be refreshed by calling registerEndPoint (via SOAP or REST) and passing the new expiration interval and the endpointID.

What are the issues around maintaining a subscription? When a subscription is created, a subscriptionID is returned by Cisco Unified Presence. An application can add contacts to the subscription by passing the additional contacts, the endpointID and the subscriptionID to the subscribe call. As with endpoints, the expiration interval on a subscription is absolute. The subscription can be refreshed by invoking the subscribe call and passing the subscriptionID, the endpointID, and the updated expiration interval.

What are the defaults expiration values around setting up subscriptions and endpoints? Both expiration values have a maximum expiration time of twenty-four hours. If the expiration time is non zero the interval must be at least one hour or the request will be rejected. An expiration of zero is an error case for RegisterEndPoint, but for subscribe, you can pass an expiration value of zero when adding contacts to an existing subscription; without refreshing the subscriptions expiration time. If I am using the Presence Web Service, and the Client Configuration Web Service, do I need to log in separately to both interfaces?

No, if your application intends to use both interfaces, you should just log in over the Presence Web Service interface. The session key returned may be used in requests to both the Presence Web Service and Client Configuration Web Service. If the application is just using Client Configuration Web Service, then it can use the Client Configuration Web Service login method.

What happens when the Primary (Cisco Unified Presence) Node I am logged into fails? When an Application/End user is logged in, the login response includes the IP address of a backup server. In the event of a primary failure, any User can login to the backup server, the presence resources such as endpoints and subscriptions will have to be recreated on the backup server. This requires calling the registerEndPoint method and the subscribe method to set up endpoints and subscriptions

Do you support viewing presence of Federated users through the Presence Web Service? Yes, for Cisco Unified Presence to Cisco Unified Presence federation. However, for Cisco Unified Presence to Microsoft OCS federation, BASIC presence is not supported. RICH presence must be retrieved to view a federated OCS users presence.

I am getting errors trying to generate stubs with the Client Configuration WSDL due to missing types. What can I do? Make sure presence-rules.xsd and the epas-soap-interface.xsd files are in the same directory as the Client Configuration. Then (in a .NET environment) run the command "wsdl.exe <service.wsdl> presence-rules.xsd epas-soap-interface.xsd". The xsd files are located at: https://cup-hostname:8443/EPASSoap/presence-rules.xsd https://cup-hostname:8443/EPASSoap/ epas-soap-interface.xsd

I am having problems connecting to the Presence Service using CXF Soap Stack using HTTPS. What is the issue?
The Proxy Component that runs the Presence Web Service only accepts connection requests using TLSv1. CXF version 2.0.5+ does not support TLSv1. CXF will use SSLV2, even for connection setup requests, leading to the connection being rejected by the Cisco Unified Presence.

What ports are the Presence and Client Configuration Web Services available on by default?
The Presence Web Service is available on port 8082 (HTTP) and 8083 (HTTPS). The Client Configuration Web Service is available on 8443 (HTTPS) only.

What is the format of a presence notification (callback) generated by Cisco Unified Presence? http://<Call Back Address>?id=10&eventType=PRESENCE_NOTIFICATION The Call back Address is passed as the URL parameter to the registerEndPoint method. Note that Cisco Unified Presence sets two parameters in the call back. The id (subscription id) for which a present event has occurred and the eventType. The client application would typically then call getSubscribedPresence passing in the subscription id to get the Presence update.

I am getting an invalid session key response when I attempt to log out of the Presence Web Service using a Cisco Unified Personal Communicator session key with the logout method. What is the issue? The Presence Web Service can only log in or log out any third party user. It is unable to log in or log out a Cisco Unified Personal Communicator or Cisco Unified Mobile Communicator user. This is applicable to both SOAP and REST. Note that the Client Configuration Web Service can distinguish between a third party user and an application user. Therefore it is possible to log in and log out a third party user, a Cisco Unified Personal Communicator user and a Cisco Unified Mobile Communicator user from the Client Configuration Web Service.

When using the Third Party API over HTTPS, what is the best connection handling approach? We recommend that you reuse a secure connection when interacting with Cisco Unified Presence due to the CPU overhead used to create these secure connections. The Reference Application. provides an example for doing this with the Keep-Alive Http Header. Using this header Cisco Unified Presence maintains a secure connection for several hours even if there is no activity on the connection.

Appendix 1
Error Codes
The error codes for the Presence Web Service are defined in Error! Reference source not found..

Table 10. Error Code

Error code definitions

Error Message Error Fix HTTP Status Code SOAP REST

100

Session key not

A session key is required to 200 OK obtained by logging in.

401 Unauthorized

present in request authenticate the request. It is

101

Invalid session key

Ensure the user is logged in 200 OK or try logging in the user again.

401 Unauthorized

102

Unable to parse XML request

Ensure that the XML in the request is well formed and the required data is provided.

200 OK

400 Bad Request

103

The XML root

Ensure that the XML root root element expected for this type of request.

200 OK

400 Bad Request

element is invalid element corresponds to the

110

The presence type is not valid

Presence type must be either BASIC_PRESENCE or RICH_PRESENCE.

200 OK

400 Bad Request

111

The password is not valid

The password must not be empty. Follow the required format for either application user login or end user login.

200 OK

400 Bad Request

112

The login type is not valid

200 OK

400 Bad Request

113

The username is not valid

The username must not be empty. Ensure the login data is valid.

200 OK

404 Not Found

114

Failed to login user

200 OK

400 Bad Request

115

Basic presence parameter specified is either null or empty

Specify a basic presence status.

200 OK

400 Bad Request

120

Failed to set presence data

Ensure the presence data is 200 OK valid. To set the presence status to 200 OK AVAILABLE, the override flag must be false.

400 Bad Request

121

Users presence status cannot be set to AVAILABLE in override mode.

400 Bad Request

122

Users presence status cannot be

To set the presence status to 200 OK DND, the override flag must

400 Bad Request

set to DND in non- be true. override mode

123

Endpoint URL specified in endpoint registration update

Only expiry times are updated in endpoint registration. Ensure that the endpoint URL field is empty.

200 OK

400 Bad Request

124

An invalid contact Ensure that all contact URIs 200 OK URI was provided

400 Bad Request

are correctly formatted. Ensure that the override either true or false (case sensitive). 200 OK 400 Bad Request

125

An invalid

override parameter parameter is specified as was provided

130

The endpoint URL is null or empty

An endpoint URL is required 200 OK when registering an endpoint.

400 Bad Request

131

The expiry value must be between 3600 and 86400 seconds

The value must not be less than 3600 or greater than 86400 seconds.

200 OK

400 Bad Request

132

The endpoint id does not exist

Ensure the value is not less 200 OK than 0 or that the endpoint was not previously unregistered.

400 Bad Request

133

The subscription id does not exist

Ensure the value is not less 200 OK than 0 or that the id was not previously unsubscribed.

400 Bad Request

134

The subscription type is not valid

Subscription was expecting 200 OK to receive a type of PRESENCE_NOTIFICATIO N.

400 Bad Request

135

The number of contacts must be between 0 and 5000.

Ensure that the number of contacts is greater than 0 but not greater than 5000.

200 OK

400 Bad Request

136

You do not have permission to access this endpoint

Ensure the session key associated with this endpoint is used.

200 OK

400 Bad Request

137

You do not have permission to access this subscription

Ensure the session key associated with this subscription is used.

200 OK

400 Bad Request

138

There are no free endpoints available

Unregister any unused endpoints.

200 OK

400 Bad Request

139

There are no free subscriptions available

Unsubscribe from any unused subscriptions.

200 OK

400 Bad Request

140

You must be an end Log in as end user. user to perform this task

200 OK

400 Bad Request

141

You must be an application user to perform this task

Log in as application user.

200 OK

400 Bad Request

142

The endpoint URL contains spaces

The endpoint URL is invalid. 200 OK Remove any spaces. Ensure that all contacts are 200 OK valid.

400 Bad Request

143

A null or empty contact was provided

400 Bad Request

144

At least one of the contacts provided is not part of the subscription

Ensure that all contacts are 200 OK valid and exist as part of this subscription.

400 Bad Request

145

No expiry value or An expiry value or a list of contacts provided

200 OK

400 Bad Request

contacts must be specified.

146

No contact list provided

A list of contacts must be specified.

200 OK

400 Bad Request

147

Invalid element in Ensure the contact list contact list

200 OK

400 Bad Request

consists of valid elements. Specify a valid contact attribute. 200 OK 400 Bad Request 200 OK 400 Bad Request

148

Invalid contact attribute

150

Could not read the Ensure the http body is message body of the http request

correctly formed.

160

User is already logged in

Log the user out from their session or enable the force option when logging in.

200 OK

409 Conflict

161

Invalid override

To set override or persistent 200 OK be 'pws-override' or 'pwspersistent'. Place a 'Presence Web Service' source element in the device tuple. Consult the application server logs. Consult the application server logs. 200 OK 200 OK 200 OK

400 Bad Request

tuple-id specified presence, the tuple-id must in rich presence document

162

Invalid source element in rich presence document

400 Bad Request

200

Server error occurred

500 Internal Server Error

201

Failed to unregister endpoint

500 Internal Server Error

202

Failed to subscribe to contacts presence

Consult the application server logs.

200 OK

500 Internal Server Error

203

Failed to unsubscribe to contacts presence

Consult the application server logs.

200 OK

500 Internal Server Error

204

Failed to set

Consult the application

200 OK

500 Internal Server Error

contacts presence server logs. status

205

Failed to logout user

Consult the application server logs Consult the application server logs Consult the application server logs

200 OK

500 Internal Server Error

206

Failed to acquire endpointID

200 OK

500 Internal Server Error

207

Failed to acquire subscriptionID

200 OK

500 Internal Server Error

208

Failed to login user

Consult the application server logs

200 OK

500 Internal Server Error

209

Failed to register Consult the application endpoint

200 OK

500 Internal Server Error

server logs Wait before sending another 503 Service request Unavailable 503 Service Unavailable

210

Max CPU utilization reached

211

No free SIP Subscriptions available

Reduce the number of contacts being viewed to reduce the number of underlying SIP subscriptions

200 OK

503 Service Unavailable

212

Max number of requests per second reached

Wait before sending another 503 Service request Unavailable

503 Service Unavailable

Appendix 2
PIDF Documents
Rich presence for an end user is sent in a PIDF document. The PIDF contains the following information: The end users overall presence state or reachability. The status of each device associated with the end user.

Each device associated with an end user reports its status and reachability to Cisco Unified Presence. Using this device status information and the presence rules defined, Cisco Unified Presence determines an overall presence state for the end user, also known as overall reachability. The overall reachability, and the status of each device associated with the end user, form the rich presence information that is defined for an end user in the PIDF document. The PIDF document contains a person section, that defines the end users overall reachability, and a tuple section for each device associated with the end user. The tuple identifies the device type and contains information on the status of the device. Note that the status of a device can either be open or closed. A definition of the elements in the PIDF is provided in Table 11. Each time the client application sets basic presence, the Presence Web Service generates a PIDF document (on behalf of the client). This PIDF document will contain the end users overall reachability and a tuple entry for the Presence Web Service. This is illustrated in sample PIDF below where the tuple ID is cisco-pws which represents the Presence Web Service. When the client application sets rich presence, a PIDF document is built by the client and passed to the Third Party API. It is up to the client to ensure that the PIDF is well formed. The client can set the overall reachability and the set the tuple to whatever they wish; they are not tied to using the cisco-pws tuple.

The override flag allows the client application to override the overall reachability state and set an end users overall presence state directly on Cisco Unified Presence. Note that if the override flag is set to true, the tuple entry for the Presence Web Service will have the tuple id value pwsoverride. When rich presence is retrieved, multiple tuple entries may be present in the PIDF for each end user device. See section Sample PIDF for a sample PIDF document showing multiple tuple entries.

Table 11.

PIDF element definitions

Element <person>

Definition This element contains information on the overall reachability of the contact.

<tuple id> <contact>

This element identifies the device. This element identifies the contact SIP address.

<audio>

This element is used to indicate whether the class of service of audio (e.g. phone) is available. The value of true in this field is used to indicate that the state being published is that of a phone device. Note that it is possible for multiple classes of services to be published from the same device.

<text>

This element is used to indicate whether the class of service of text (e.g. IM) is available. The value of true in this field is used to indicate that the state being published is that of an IM device. Note that it is possible for multiple classes of services to be published from the same device.

<video>

This element is used to indicate whether the class of service of video is available. Note that it is possible for multiple classes of services to be published from the same device.

<user-input>

This element is used to indicate activity on a device e.g. voice, keyboard, pointing device)

<model> <status>

This element contains model information for the device. This element indicates the status of the device. This value is either open or closed.

Sample PIDF
This example shows a PIDF document with a Presence setting of available.

<presence entity="sip:brmaguir@cisco.com"

xmlns="urn:ietf:params:xml:ns:pidf">

<person xmlns="urn:cisco:params:xml:ns:pidf:rpid" id="brmaguir"> <activities> <available/> <phone-status>unavailable</phone-status> <im-status>available</im-status> </activities> </person> <display-name xmlns="urn:ietf:params:xml:ns:pidf:cipid"> Brendan Maguire </display-name> <tuple xmlns="urn:ietf:params:xml:ns:pidf" id="cisco-upc"> <contact priority="0.6">sip:brmaguir@cisco.com</contact>

<note xml:lang="en"/> <sc:servcaps xmlns:sc="urn:ietf:params:xml:ns:pidf:servcaps"> <sc:audio>false</sc:audio> <sc:text>true</sc:text> <sc:type>text/plain</sc:type> <sc:type>application/x-cisco-cupc+xml</sc:type> </sc:servcaps> <user-input>active</user-input> <status> <basic>open</basic> </status> </tuple> </presence>

This example shows a PIDF with multiple tuple entries,. <presence entity="sip:brmaguir@cisco.com" xmlns="urn:ietf:params:xml:ns:pidf"> <person xmlns="urn:cisco:params:xml:ns:pidf:rpid" id="brmaguir"> <activities> <user-input>idle</user-input> <available/> <phone-status>unavailable</phone-status> <im-status>available</im-status> </activities> </person> <display-name xmlns="urn:ietf:params:xml:ns:pidf:cipid"> Brendan Maguire </display-name> <tuple xmlns="urn:ietf:params:xml:ns:pidf" id="cisco-upc"> <contact priority="0.6">sip:brmaguir@cisco.com</contact> <note xml:lang="en"/> <sc:servcaps xmlns:sc="urn:ietf:params:xml:ns:pidf:servcaps"> <sc:video>false</sc:video>

<sc:audio>false</sc:audio> <sc:text>true</sc:text> <sc:type>text/plain</sc:type> <sc:type>application/x-cisco-cupc+xml</sc:type> </sc:servcaps> <user-input>idle</user-input> <status> <basic>open</basic> </status> </tuple> <tuple xmlns="urn:ietf:params:xml:ns:pidf" id="Jabbercup7"> <status> <basic>open</basic> </status> <servcaps xmlns="urn:ietf:params:xml:ns:pidf:servcaps"> <type>text/plain</type> <type>application/x-cisco-cupc+xml</type> <text>true</text> </servcaps> </tuple> </presence>

Appendix 3
Importing the Eclipse Project
This section describes how to import the Reference Application into Eclipse.

Step 5.

Download the Presence Web Service Reference Application. Contact your Cisco representative for the location to download the application. The filename for the Reference Application will be in the following format : cup_tpi_referenceApplication_<REF_APP_VERSION>.zip. Save this file to your local disk.

Step 6. Step 7. Step 8.

Open Eclipse to your local workspace. Go to File Import. Select the import source Existing Projects into Workspace and click Next. See Figure 14.

Figure 14.

Select Project Dialog Box

Step 9.

Choose Select archive file and browse to the location where you saved the Reference Application .zip file. Ensure the ReferenceApp Project is selected in the projects window, see Figure 15. Click Finish to start importing the project into the workspace.

Note:

It may take approx 10 minutes to import the project due to the large number of generated

client stub classes and javadocs

Figure 15.

Import Project dialog box

Note:

When imported the project may show HTML validation errors due to the nature of some

jsp files and javadocs. If this is the case you can disable HTML validation by right clicking on the ReferenceApp project and selecting Properties Validation. Then choose Override validation preferences and uncheck the required validators from the Build column as shown in Figure 16.

Figure 16.

Eclipse Project GUI

Rebuild the Eclipse Project

The structure of the Eclipse project is shown in Figure 17. To remove any validation errors that Eclipse may have been showing you will need to Clean the Project (Project Clean) and rebuild it (Project Build All) within Eclipse.
Figure 17.

Project structure

The pre-build Web Archive file (.WAR ) file is located in the folder : build \ ear \ refApp.war. The recommended way to build the Project is using the supplied Ant script; the procedure is described below.
Step 10. Step 11.

Right click on build.xml in the build folder and choose Run As Ant Build. To deploy the war file, copy the .WAR file from build \ ear to your J2EE webapps folder on Tomcat.

Note:

Alternatively you can use the deploy.xml ant script to deploy the .WAR file (Windows

only). To use this right click on deploy.xml in the build folder and choose Run As Ant Script.

CCDE, CCENT, Cisco Eos, Cisco Lumin, Cisco Nexus, Cisco StadiumVision, Cisco TelePresence, the Cisco logo, DCE, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn and Cisco Store are service marks; and Access Registrar, Aironet, AsyncOS, Bringing the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, CCVP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collaboration Without Limitation, EtherFast, EtherSwitch, Event Center, Fast Step, Follow Me Browsing, FormShare, GigaDrive, HomeLink, Internet Quotient, IOS, iPhone, iQ Expertise, the iQ logo, iQ Net Readiness Scorecard, iQuick Study, IronPort, the IronPort logo, LightStream, Linksys, MediaTone, MeetingPlace, MeetingPlace Chime Sound, MGX, Networkers, Networking Academy, Network Registrar, PCNow, PIX, PowerPanels, ProConnect, ScriptShare, SenderBase, SMARTnet, Spectrum Expert, StackWise, The Fastest Way to Increase Your Internet Quotient, TransPath, WebEx, and the WebEx logo are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries. All other trademarks mentioned in this document or Website are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0807R)