Developer Cookbook for Cisco Unified Presence 8.5
Click here to load reader
-
Upload
perico-eldelospilotes -
Category
Documents
-
view
372 -
download
3
Transcript of Developer Cookbook for Cisco Unified Presence 8.5
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
Last Updated: 26/01/2011
Developer Cookbook for the Presence Web Service for Cisco Unified Presence Release 8.5
All contents are Copyright © 2011 Cisco Systems, Inc. All rights reserved. Page 2 of 62
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 Contact’s 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
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/presence-
service/soap?wsdl
● Presence Web Service (HTTPS): https://<cup-hostname>:8083/presence-
service/soap?wsdl
● Client Configuration Web Service (HTTPS): https://<cup-
hostname>: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 Description
Application User 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
Web Service
The Client Configuration Web Service is an interface to Cisco Unified Presence
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\WEB-
INF\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 Name Parameter Description
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 Name Parameter Description
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
on
This parameter disables the soap action header when
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 Name Parameter Description
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 Name Parameter Description
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_classpath
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. You are asked if you want to trust the certificate, enter Yes.
Step 4. 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. You are asked if you want to trust the certificate, enter Yes.
Step 6. 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 Name Parameter Description
alias The name that is used to identify the certificate in the keystore.
file 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. Open the <TOMCAT_HOME>\webapps\refApp\WEB-INF\web.xml file for the
Reference Application.
Step 2. Edit the java_keystore_file property so that it contains the full path to the Java
keystore created in previous section.
Step 3. Edit the java_keystore_password property so that it contains the password used
when creating the Java keystore in previous section.
Step 4. 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 port : 8083
cup_configsoap_path port : 8443
(restConfig Servlet)
cup_rest_presence_path port : 8083
cup_configsoap_path port : 8443
Below are example values for a Cisco Unified Presence server with hostname “cupserver”:
cup_presence_path https://cupserver:8083/presence-service/soap
cup_configsoap_path https://cupserver:8443/EPASSoap/service
cup_rest_presence_path https://cupserver:8083/presence-service
cup_configsoap_path https://cupserver:8443/EPASSoap/service
Step 5. Restart Tomcat to ensure that all properties are updated.
Step 6. 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 user’s 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 Contact’s Presence Details
You can view more information on a contact’s 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 Contains the gifs used to represent presence in the contacts tree.
pages Contains the JSP files used to generate the HTML/Javascript that make up
the Reference Application UI.
tiles Contains the Template.jsp which dictates where a JSP is placed on screen.
WEB-INF
(lib)
Contains the tag libraries used by the Reference Application. The struts-
config.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.
Contains jar file needed by the Reference Application. These jars include
the Axis2, struts and xml handling binaries. Other jar of note is the axis-
struts.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 Contains the interface definition for the Presence Web Service.
presence-rules.xsd Contains the schema definition of a PresenceRule. It is used by the
client-configuration.wsdl file.
Epas-soap-interface.xsd Contains type used by the client-configuration.wsdl.
generateClientStubs.sh 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
HTML/Javascript/Ajax
CUP
Action Classes
SOAP API
Hander Interface
Axis Stubs
Axis Impl Rest Impl
HttpClient
Presence Configuration
REST API
Presence
HT
TP
HT
TP
SOAP/HTTPXML/HTTP
BrowserIE and Mozilla
Servlet ContainerTomcat
CUPThird Party APIs
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 Screen Description
index.jsp Login Page 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
user’s 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.
Contacts-
Maintainance.jsp
Manage Contacts Screen This JSP interacts with ContactAction
class for adding/updating/deleting
contacts.
Group-
Maintainance.jsp
Manage Groups Screen This JSP Interacts with GroupAction
class for adding/updating/deleting
contacts.
errorPage.jsp 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 user’s 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 Functionality
EventingAction Provides examples on using the event methods e.g. on setting up and
tearing down, registering subscriptions and endpoints.
ContactAction Add/modify/delete a contact.
GroupAction Add/modify/delete a group
LoginAction Log an end user in to Cisco Unified Presence.
LogoutAction Log an end user out of Cisco Unified Presence.
NotifyAction Handling a presence notification.
PresenceAction Setting a user’s presence, and retrieving cached presence.
UserAction Getting (polled) rich presence of a contact, and blocking a contact
from seeing a user’s 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 Purpose Type
HandlerFactoryGenerator This class determines which HandlerFactory
implementation (Axis or REST) is used.
NA
HandlerFactory This class is the gateway to handler logic, acting as
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.
Presence
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
setting presence rules.
Configuration
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. SecurityConfigServlet reads the keystore information.
2. 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 user’s 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 user’s id and the application user’s
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
user’s 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
Node 1a
Node 1b
CUP Sub Cluster1
Node 2a
Node 2b
CUP Sub Cluster2
End User1
End User2
Third Party Application
Application User
End User1End
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 user’s session key.
● The TPA will maintain a record of what nodes an end user is logged into. In the event of a
user’s primary node failing, the TPA will forward end user requests to the user’s 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 don’t use SOAP to engage with the Presence Web Service, the
RestCupContext doesn’t 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 it’s
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 Time-
To-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 Application’s 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 user’s 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
Presence State Definition
Available The user is available.
Away The user has logged in but presence is set to AWAY.
Do Not Disturb (DND) The user has logged in but Presence is set to DND.
Unavailable 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 user’s basic presence state. Rich presence contains an end user’s
“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 user’s 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 user’s overall reachability and overrides the
presence of an end user’s devices. When an end user set’s 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 user’s 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
user’s 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 subscription’s
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 user’s 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 definitions
Error Code Error Message Error Fix HTTP Status Code
SOAP REST
100 Session key not
present in request
A session key is required to
authenticate the request. It is
obtained by logging in.
200 OK 401 Unauthorized
101 Invalid session
key
Ensure the user is logged in
or try logging in the user
again.
200 OK 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
element is invalid
Ensure that the XML root
element corresponds to the
root element expected for
this type of request.
200 OK 400 Bad Request
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.
200 OK 400 Bad Request
112 The login type is
not valid
Follow the required format
for either application user
login or end user login.
200 OK 400 Bad Request
113 The username is
not valid
The username must not be
empty.
200 OK 404 Not Found
114 Failed to login
user
Ensure the login data is
valid.
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
valid.
200 OK 400 Bad Request
121 User’s presence
status cannot be
set to AVAILABLE
in override mode.
To set the presence status to
AVAILABLE, the override
flag must be false.
200 OK 400 Bad Request
122 User’s presence
status cannot be
set to DND in non-
override mode
To set the presence status to
DND, the override flag must
be true.
200 OK 400 Bad Request
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
URI was provided
Ensure that all contact URIs
are correctly formatted.
200 OK 400 Bad Request
125 An invalid
override parameter
was provided
Ensure that the override
parameter is specified as
either true or false (case
sensitive).
200 OK 400 Bad Request
130 The endpoint URL
is null or empty
An endpoint URL is required
when registering an
endpoint.
200 OK 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
than 0 or that the endpoint
was not previously
unregistered.
200 OK 400 Bad Request
133 The subscription
id does not exist
Ensure the value is not less
than 0 or that the id was not
previously unsubscribed.
200 OK 400 Bad Request
134 The subscription
type is not valid
Subscription was expecting
to receive a type of
PRESENCE_NOTIFICATIO
N.
200 OK 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
user to perform
this task
Log in as end user. 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.
Remove any spaces.
200 OK 400 Bad Request
143 A null or empty
contact was
provided
Ensure that all contacts are
valid.
200 OK 400 Bad Request
144 At least one of
the contacts
provided is not
part of the
subscription
Ensure that all contacts are
valid and exist as part of this
subscription.
200 OK 400 Bad Request
145 No expiry value or
contacts provided
An expiry value or a list of
contacts must be specified.
200 OK 400 Bad Request
146 No contact list
provided
A list of contacts must be
specified.
200 OK 400 Bad Request
147 Invalid element in
contact list
Ensure the contact list
consists of valid elements.
200 OK 400 Bad Request
148 Invalid contact
attribute
Specify a valid contact
attribute.
200 OK 400 Bad Request
150 Could not read the
message body of
the http request
Ensure the http body is
correctly formed.
200 OK 400 Bad Request
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
tuple-id specified
in rich presence
document
To set override or persistent
presence, the tuple-id must
be 'pws-override' or 'pws-
persistent'.
200 OK 400 Bad Request
162 Invalid source
element in rich
presence document
Place a 'Presence Web
Service' source element in
the device tuple.
200 OK 400 Bad Request
200 Server error
occurred
Consult the application
server logs.
200 OK 500 Internal Server Error
201 Failed to
unregister
endpoint
Consult the application
server logs.
200 OK 500 Internal Server Error
202 Failed to
subscribe to
contact’s presence
Consult the application
server logs.
200 OK 500 Internal Server Error
203 Failed to
unsubscribe to
contact’s presence
Consult the application
server logs.
200 OK 500 Internal Server Error
204 Failed to set
contact’s presence
status
Consult the application
server logs.
200 OK 500 Internal Server Error
205 Failed to logout
user
Consult the application
server logs
200 OK 500 Internal Server Error
206 Failed to acquire
endpointID
Consult the application
server logs
200 OK 500 Internal Server Error
207 Failed to acquire
subscriptionID
Consult the application
server logs
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
endpoint
Consult the application
server logs
200 OK 500 Internal Server Error
210 Max CPU
utilization
reached
Wait before sending another
request
503 Service
Unavailable
503 Service Unavailable
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
request
503 Service
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 user’s 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 user’s 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 user’s 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 user’s 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 “pws-
override”.
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 Definition
<person> This element contains information on the “overall reachability” of the
contact.
<tuple id> This element identifies the device.
<contact> 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> This element contains model information for the device.
<status> 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:[email protected]" 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:[email protected]</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:[email protected]" 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:[email protected]</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. Open Eclipse to your local workspace.
Step 7. Go to File Import.
Step 8. 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. Right click on build.xml in the build folder and choose Run As Ant Build.
Step 11. 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)