developer cookbook for cisco unified presence 8.5

All contents are Copyright © 2011 Cisco Systems, Inc. All rights reserved. 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. 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


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


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


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


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


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


Configuration

CupContext This class represents a user session with Cisco

Unified Presence.

NA

GroupHandler This class allows for the managing of groups on


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


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.


110 The presence type

is not valid

Presence type must be

either BASIC_PRESENCE

or RICH_PRESENCE.


111 The password is

not valid

The password must not be

empty.


112 The login type is

not valid

Follow the required format

for either application user

login or end user login.


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.


115 Basic presence

parameter

specified is

either null or

empty

Specify a basic presence

status.


120 Failed to set

presence data

Ensure the presence data is

valid.


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.


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.


123 Endpoint URL

specified in

endpoint

registration

update

Only expiry times are

updated in endpoint

registration. Ensure that the

endpoint URL field is empty.


124 An invalid contact

URI was provided

Ensure that all contact URIs

are correctly formatted.


125 An invalid

override parameter

was provided

Ensure that the override

parameter is specified as

either true or false (case

sensitive).


130 The endpoint URL

is null or empty

An endpoint URL is required

when registering an

endpoint.


131 The expiry value

must be between

3600 and 86400

seconds

The value must not be less

than 3600 or greater than

86400 seconds.


132 The endpoint id

does not exist

Ensure the value is not less

than 0 or that the endpoint

was not previously

unregistered.


133 The subscription

id does not exist

Ensure the value is not less

than 0 or that the id was not

previously unsubscribed.


134 The subscription

type is not valid

Subscription was expecting

to receive a type of

PRESENCE_NOTIFICATIO

N.


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.


136 You do not have

permission to

access this

endpoint

Ensure the session key

associated with this endpoint

is used.


137 You do not have

permission to

access this

subscription

Ensure the session key

associated with this

subscription is used.


138 There are no free

endpoints

available

Unregister any unused

endpoints.


139 There are no free

subscriptions

available

Unsubscribe from any

unused subscriptions.


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.


143 A null or empty

contact was

provided

Ensure that all contacts are

valid.


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.


145 No expiry value or

contacts provided

An expiry value or a list of

contacts must be specified.


146 No contact list

provided

A list of contacts must be

specified.


147 Invalid element in

contact list

Ensure the contact list

consists of valid elements.


148 Invalid contact

attribute

Specify a valid contact

attribute.


150 Could not read the

message body of

the http request

Ensure the http body is

correctly formed.


160 User is already

logged in

Log the user out from their

session or enable the force

option when logging in.

200 OK 409 Conflict

161 Invalid override

tuple-id specified

in rich presence

document

To set override or persistent

presence, the tuple-id must

be 'pws-override' or 'pws-

persistent'.


162 Invalid source

element in rich

presence document

Place a 'Presence Web

Service' source element in

the device tuple.


200 Server error

occurred

Consult the application

server logs.

200 OK 500 Internal Server Error

201 Failed to

unregister

endpoint


server logs.


202 Failed to

subscribe to

contact’s presence


server logs.


203 Failed to

unsubscribe to



server logs.


204 Failed to set


status


server logs.


205 Failed to logout

user


server logs


206 Failed to acquire

endpointID


server logs


207 Failed to acquire

subscriptionID


server logs


208 Failed to login

user


server logs


209 Failed to register

endpoint


server logs


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)