Vous êtes sur la page 1sur 62
DEVELOPER COOKBOOK FOR THE PRESENCE WEB SERVICE FOR CISCO UNIFIED PRESENCE RELEASE 8.5 Last Updated:

DEVELOPER COOKBOOK FOR THE PRESENCE WEB SERVICE FOR CISCO UNIFIED PRESENCE RELEASE 8.5

Last Updated: 26/01/2011

CISCO UNIFIED PRESENCE RELEASE 8.5 Last Updated: 26/01/2011 A ll contents are Copyright © 2011 Cisco

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

Presence Web Service for Cisco Unified Presence Release 8.5 Table of Contents Introduction 3 WSDL Defi
Presence Web Service for Cisco Unified Presence Release 8.5 Table of Contents Introduction 3 WSDL Defi

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

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.

Web Service

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

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.

Service

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

user configuration screen on Cisco Unified Presence Note: The Application User must be added to the

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 2.

Start and stop Tomcat. The following directory is created:

<CATALINA_HOME>\webapps\refApp

Step 3.

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

Step 4.

Restart Tomcat.

Configuring the Web XML File

securityConfig Servlet

axisConfig Servlet

restConfig Servlet

genericConfig Servlet

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

securityConfig Servlet

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

Table 1.

securityConfig servlet parameters

Parameter Name

Parameter Description

java_keystore_file

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

java_keystore_password

The password to access the Java keystore.

axisConfig Servlet

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

Table 2.

axisConfig parameters

Parameter Name

Parameter Description

cup_presence_path

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

cup_config_soap_path

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

cup_config_soapversion

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

cup_presence_soapversion

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

cup_config_disablesoapaction

This parameter disables the soap action header when connecting to the Client Configuration Web Service. The valid values are true and false.

cup_presence_disablesoapacti

This parameter disables the soap action header when connecting to the Presence Web Service. The valid values are true and false.

on

Note:

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

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

restConfig Servlet

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

Table 3.

restConfig parameters

Parameter Name

Parameter Description

cup_rest_presence_path

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

cup_configsoap_path

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

genericConfig Servlet

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

Table 4.

genericConfig parameters

Parameter Name

Parameter Description

Application_username

The username of the application user.

Application_password

The password of the application user.

callback_url

The URL on which the Reference Application will receive notifications

from Cisco Unified Presence. Set the

REFAPP_WEBSERVER_HOSTNAME value to the address of the

machine that the Reference Application is running on.

handler_factory_clas

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

spath

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

Application connections to Cisco Unified Presence server Note: The security procedures described in this section must

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 SecurityCertificate Management.

Στεπ 4.

Click Find. The list of certificates is displayed.

Στεπ 5.

Click on the link cup.der and click Download.

Στεπ 6.

Save the certificate cup.der to the local directory C:\certs\.

Στεπ 7.

Navigate back to the Certificate Find/List page, click on the link tomcat.der and click Download.

Στεπ 8.

Save the certificate tomcat.der to the local directory C:\certs\.

Create a Keystore and Import the Certificates

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

Procedure:

Step 1.

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

Step 2.

Open a command prompt/ shell on the Application server, navigate to c:\certs and run the following command (using the parameter definitions in Table 5):

keytool -import -alias cup -file cup.der -keystore c:\certs\refapp.keystore -storepass ciscoRefApp

Step 3.

You are asked if you want to trust the certificate, enter Yes.

Step 4.

From the command prompt/ shell on the Application server, run the following command (using the parameter definitions in Table 5):

keytool -import -alias tomcat -file tomcat.der -keystore C:\certs\refapp.keystore -storepass ciscoRefApp

Step 5.

You are asked if you want to trust the certificate, enter Yes.

Step 6.

To ensure that the certificates have been imported (from the C:\certs\ directory) print out the contents of the Java keystore using the command:

keytool -list -keystore refapp.keystore -storepass ciscoRefApp

Note:

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

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

Table 5.

Import keytool parameter descriptions

Parameter Name

Parameter Description

alias

The name that is used to identify the certificate in the keystore.

file

The path to the certificate file that was downloaded from Cisco Unified Presence

keystore

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

storepass

The password used to access the keystore.

Configure the Reference Application to use the Keystore

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

Procedure:

Step 1.

Open the <TOMCAT_HOME>\webapps\refApp\WEB-INF\web.xml file for the Reference Application.

Step 2.

Edit the java_keystore_file property so that it contains the full path to the Java keystore created in previous section.

Step 3.

Edit the java_keystore_password property so that it contains the password used when creating the Java keystore in previous section.

Step 4.

Ensure the URLs configured in the following web.xml properties have a “https://” prefix and use the ports listed below:

(axisConfig Servlet)

cup_presence_path

port : 8083

cup_configsoap_path

port : 8443

(restConfig Servlet)

cup_rest_presence_path

port : 8083

cup_configsoap_path

port : 8443

Below are example values for a Cisco Unified Presence server with hostname “cupserver”:

cup_presence_path

cup_configsoap_path

cup_rest_presence_path https://cupserver:8083/presence-service

https://cupserver:8443/EPASSoap/service

https://cupserver:8083/presence-service/soap

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

Figure 3. Login screen Viewing Presence On logging in to the User Presence Application, you are

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

a grey question mark. Figure 4. Presence Management Screen Managing Groups You can manage your contact

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

Press the Delete button. Figure 5. Managing Contacts The following screen shows the User m oving

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

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

Figure 6. Viewing a Contact Using the Eventing Tutorial This tutorial demonstrates to a developer the

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

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

com.cisco.cup.webservices.refapp.config

com.cisco.cup.webservices.refapp.endpoint

com.cisco.cup.webservices.refapp.handler

com.cisco.cup.webservices.refapp.log

com.cisco.cup.webservices.refapp.ssl

The struts action classes and associated forms that service the UI.

Four servlets that run at system start-up, and configure the Reference Application based on the web.xml file.

Classes used to manage and cache subscription information.

The handler classes that interact with the Cisco Unified Presence Third Party Interfaces.

RefApp logger. The RefApp uses log4j to write to <CATALINA_HOME>\logs\refApp.log* log files.

Classes for setting up the TLS Connections with Cisco Unified Presence.

build Folder

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

web folder

The web folder contains the following subfolders:

images

Contains the gifs used to represent presence in the contacts tree.

pages

Contains the JSP files used to generate the HTML/Javascript that make up the Reference Application UI.

tiles

Contains the Template.jsp which dictates where a JSP is placed on screen.

WEB-INF

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.

(lib)

Contains jar file needed by the Reference Application. These jars include the Axis2, struts and xml handling binaries. Other jar of note is the 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

Browser IE and Mozilla

Servlet Container

Tomcat

CUP Third Party APIs

HTML/Javascript/Ajax Action Classes Hander Interface Axis Impl Rest Impl Axis Stubs HttpClient XML/HTTP SOAP/HTTP
HTML/Javascript/Ajax
Action Classes
Hander Interface
Axis Impl
Rest Impl
Axis Stubs
HttpClient
XML/HTTP
SOAP/HTTP
Presence
Configuration
Presence
SOAP API
REST API
CUP
HTTP
HTTP

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-

Manage Contacts Screen

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

Maintainance.jsp

Group-

Manage Groups Screen

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

Maintainance.jsp

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

Figure 9. Getting presence updates for the contact tree Action Classes The Reference Application uses Apache
Figure 9. Getting presence updates for the contact tree Action Classes The Reference Application uses Apache
Figure 9. Getting presence updates for the contact tree Action Classes The Reference Application uses Apache
Figure 9. Getting presence updates for the contact tree Action Classes The Reference Application uses Apache

Action Classes

The Reference Application uses Apache Struts, an open-source framework for creating Java Web Applications. To see how HTTP Requests are forwarded to the correct struts action, refer to the Web-Inf/struts-config.xml file.

Submitting a HTML form in the Reference Application results in a call to one of the struts action classes in the com.cisco.cup.webservices.refapp.action package. The Action classes are quite lightweight, typically performing the following functions:

Converting form variables to handler parameters

Calling the appropriate hander

Storing any information returned from the handler in the request or session

Forwarding to next screen

The Action classes and the functionality they illustrate are described in Table 7.

Table 7.

Reference Application action classes

Action

Functionality

EventingAction

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

ContactAction

Add/modify/delete a contact.

GroupAction

Add/modify/delete a group

LoginAction

Log an end user in to Cisco Unified Presence.

LogoutAction

Log an end user out of Cisco Unified Presence.

NotifyAction

Handling a presence notification.

PresenceAction

Setting a user’s presence, and retrieving cached presence.

UserAction

Getting (polled) rich presence of a contact, and blocking a contact from seeing a user’s presence. Code for parsing PIDF to get Device and Privacy Information.

Cisco Unified Presence Handlers

The Cisco Unified Presence Handlers are the classes that interact with Cisco Unified Presence. The interfaces that Cisco Unified Presence Handlers must implement are at:

com.cisco.cup.webservices.refapp.handler

Table 8 lists the Cisco Unified Presence handler classes and interfaces, and indicates whether they use configuration or presence information from Cisco Unified Presence. There are currently two implementations of the handler interfaces, one for Axis and one for REST.

Table 8.

Cisco Unified Presence Handler descriptions

Class

Purpose

Type

HandlerFactoryGenerator

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

NA

HandlerFactory

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

Presence

ACLHandler

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

Configuration

CalendarHandler

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

Configuration

ContactHandler

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

Configuration

CupContext

This class represents a user session with Cisco Unified Presence.

NA

GroupHandler

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

Configuration

PresenceHandler

This class allows for getting and setting of Presence.

Presence

ApplicationHandler

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

Presence

PresenceRulesHandler

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

Configuration

The two implementations of the handler interfaces are:

An Axis Soap implementation at.

com.cisco.cup.webservices.refapp.handler.axis which make calls to the Third Party Interfaces over SOAP. This implementation has implementation of all the handler interfaces (both Configuration and Presence)

A REST implementation at

com.cisco.cup.webservices.refapp.handler.rest that extends the SOAP implementation. This package has separate implementations of the HandlerFactory ,PresenceHandler and ApplicationHandlers making calls to the RESTful Presence Interface; the REST Implementation still needs to use SOAP to interact with the Client Configuration Web Service, but uses REST to exchange presence data.

Example: ContactAction Class

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

Figure 10.

ContactAction class

as illustrated in Figure 10. Figure 10. ContactAction class There are two steps in getting a

There are two steps in getting a ContactHandler:

Call the HandlerGeneratorFactory to get the HandlerFactory being used. In Figure 10 an AxisHandlerFactory is returned.

Get the required Handler call the appropriate method in the HandlerFactory. In Figure 10 calling getContactHandler, will see an AxisContactHandler object being returned.

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

CupContext context = endUser.getCupContext();

HandlerFactory handlerFactory = HandlerFactoryGenerator.getHandlerFactory().

ContactHandler contacthandler =

handlerFactory.getContactHandler(context);

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

Implementation Information

System Startup

Login/Logout

Context Objects

Handler Internals

Event Notifications

Polling for Presence

Setting Presence

System Startup

The application web.xml is configured to run the init method of the servlets that appear in the

com.cisco.cup.webservices.refapp.config package at system startup. The init functionality of each

servlet, and the order in which they run, is as follows:

1. SecurityConfigServlet reads the keystore information.

2. AxisConfigServlet points the Reference Application to the SOAP interfaces on

Cisco Unified Presence.

3. RestConfigSerlvet points the Reference Application to the Rest interface on Cisco Unified

Presence.

4. GenericConfigServlet loads other configurations parameters such as the Application User

name and password, the callback URL, and what handler implementation is being used by

the Reference Application.

The GenericConfigServlet also has the following lines in its init method:

HandlerFactoryGenerator.getHandlerFactory()

.login(APPLICATION_USERNAME,

APPLICATION_PASSWORD, true, true);

if(cupContext != null)

{

 

ApplicationUser.getInstance().setCupContext(cupContext);

ApplicationUser.getInstance().setUserID(APPLICATION_USERNAME);

}

CupEndPoint.getInstance().register();

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

The application user that is logged into Cisco Unified Presence; this object will in turn be used to log in end users to Cisco Unified Presence, and

An endpoint which will be used to receive presence notifications from Cisco Unified Presence.

Login/Logout

As noted in previous section, on start-up the Reference Application creates an application user and logs the application user in to Cisco Unified Presence. Once an application user’s credentials (user name and password) are verified by Cisco Unified Presence, the application user can log in end users to Cisco Unified Presence.

As the Reference Application uses only one application user, the class

com.cisco.cup.webservices.refapp.endpoint.ApplicationUser which models the Application User, is

a singleton.

When a user (application user or end user) logs onto Cisco Unified Presence via the Third Party Interface, they are granted a session ID. This session ID must be passed back in all subsequent calls to the interface. In SOAP requests the session ID is passed in SOAP header as follows:

<soapenv:Header>

<session-key xmlns="urn:cisco:cup:tpi:soap">

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

</session-key>

</soapenv:Header>

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

Presence-Session-Key: beb3bb70-1be2-4d73-90f8-e8b3929af58c

Thus all handlers must be passed a session ID (contained in CUPContext) to enable them to communicate with Cisco Unified Presence. Logging out involves passing the session key back to Cisco Unified Presence, where all the resources associated with the session will be destroyed.

A user can be logged in/logged out over REST or SOAP interfaces, so both the RestHandlerfactory

and the AxisHandlerFactory have login/logout methods. The login methods for either interface are similar. For example when logging in an end user, the end user’s id and the application user’s session key are passed to Cisco Unified Presence for both interfaces. Cisco Unified Presence acknowledges a successful login by returning a session ID. This session ID is used to create a CUPContext object which is then passed as a parameter to all Handler objects. The Handlers need the CUPContext so they can extract the session ID when communicating with Cisco Unified Presence.

In summary the HandlerFactories logs an application user in to Cisco Unified Presence with a user name and password combination. End users are logged in with their user name and the application user’s session ID. A successful login results in the creation of CupContext objects which are stored with the EndUser in the HTTP Session object.

Multi-node

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

Figure 11.

Clustered Cisco Unified Presence deployment

Node 2a Node 1a End User1 End Node 2b Node 1b User2 CUP Sub Cluster2
Node 2a
Node 1a
End User1
End
Node 2b
Node 1b
User2
CUP Sub Cluster2
CUP Sub Cluster1
Application
User
Third Party Application
End
End User1
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

Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature
Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature
Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature
Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature
Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature
Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature
Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature
Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature
Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature
Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature
Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature
Figure 12. Event Notification Message Flow Endpoints In order to use the Event notif ication feature

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

Unified Presence. Figure 13. Presence Polling Message Flow Setting Presence The Presence Handler interface also has

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.

Note:

Third Party API FAQ

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.

am getting errors trying to generate stubs with the Client Configuration WSDL due to missing types. What can I do?

I

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

200

OK

401

Unauthorized

authenticate the request. It is

   
 

obtained by logging in.

101

Invalid session

Ensure the user is logged in

200

OK

401

Unauthorized

key

or

try logging in the user

   

again.

102

Unable to parse XML request

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

200

OK

400

Bad Request

103

The XML root element is invalid

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

200

OK

400

Bad Request

110

The presence type is not valid

Presence type must be either BASIC_PRESENCE or RICH_PRESENCE.

200

OK

400

Bad Request

111

The password is not valid

The password must not be empty.

200

OK

400

Bad Request

112

The login type is not valid

Follow the required format for either application user login or end user login.

200

OK

400

Bad Request

113

The username is not valid

The username must not be empty.

200

OK

404

Not Found

114

Failed to login user

Ensure the login data is valid.

200

OK

400

Bad Request

115

Basic presence parameter specified is either null or empty

Specify a basic presence status.

200

OK

400

Bad Request

120

Failed to set presence data

Ensure the presence data is valid.

200

OK

400

Bad Request

121

User’s presence status cannot be set to AVAILABLE in override mode.

To set the presence status to AVAILABLE, the override flag must be false.

200

OK

400

Bad Request

122

User’s presence status cannot be set to DND in non- override mode

To set the presence status to DND, the override flag must be true.

200

OK

400

Bad Request

123

Endpoint URL

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

200

OK

400

Bad Request

specified in

   

endpoint

registration

update

 

124

An invalid contact URI was provided

Ensure that all contact URIs are correctly formatted.

200

OK

400

Bad Request

125

An invalid override parameter was provided

Ensure that the override parameter is specified as either true or false (case sensitive).

200

OK

400

Bad Request

130

The endpoint URL is null or empty

An endpoint URL is required when registering an endpoint.

200

OK

400

Bad Request

131

The expiry value must be between 3600 and 86400 seconds

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

200

OK

400

Bad Request

132

The endpoint id does not exist

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

200

OK

400

Bad Request

133

The subscription id does not exist

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

200

OK

400

Bad Request

134

The subscription type is not valid

Subscription was expecting to receive a type of PRESENCE_NOTIFICATIO

200

OK

400

Bad Request

N.

   

135

The number of contacts must be between 0 and

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

200

OK

400

Bad Request

5000.

   

136

You do not have permission to access this endpoint

Ensure the session key associated with this endpoint is used.

200

OK

400

Bad Request

137

You do not have permission to access this subscription

Ensure the session key associated with this subscription is used.

200

OK

400

Bad Request

138

There are no free endpoints available

Unregister any unused

200

OK

400

Bad Request

endpoints.

   

139

There are no free subscriptions available

Unsubscribe from any unused subscriptions.

200

OK

400

Bad Request

140

You must be an end user to perform this task

Log in as end user.

200

OK

400

Bad Request

141

You must be an application user to perform this task

Log in as application user.

200

OK

400

Bad Request

142

The endpoint URL contains spaces

The endpoint URL is invalid. Remove any spaces.

200

OK

400

Bad Request

143

A null or empty contact was provided

Ensure that all contacts are

200

OK

400

Bad Request

valid.

   

144

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

Ensure that all contacts are

200

OK

400

Bad Request

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.

200

OK

400

Bad Request

146

No contact list provided

A list of contacts must be specified.

200

OK

400

Bad Request

147

Invalid element in contact list

Ensure the contact list consists of valid elements.

200

OK

400

Bad Request

148

Invalid contact

Specify a valid contact attribute.

200

OK

400

Bad Request

attribute

   

150

Could not read the message body of the http request

Ensure the http body is correctly formed.

200

OK

400

Bad Request

160

User is already logged in

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

200

OK

409

Conflict

161

Invalid override tuple-id specified in rich presence document

To set override or persistent presence, the tuple-id must be 'pws-override' or 'pws- persistent'.

200

OK

400

Bad Request

162

Invalid source element in rich presence document

Place a 'Presence Web Service' source element in the device tuple.

200

OK

400

Bad Request

200

Server error

Consult the application server logs.

200

OK

500

Internal Server Error

occurred

   

201

Failed to

Consult the application server logs.

200

OK

500

Internal Server Error

unregister

   

endpoint

 

202

Failed to subscribe to contact’s presence

Consult the application server logs.

200

OK

500

Internal Server Error

203

Failed to unsubscribe to contact’s presence

Consult the application server logs.

200

OK

500

Internal Server Error

204

Failed to set contact’s presence status

Consult the application server logs.

200

OK

500

Internal Server Error

205

Failed to logout user

Consult the application server logs

200

OK

500

Internal Server Error

206

Failed to acquire endpointID

Consult the application server logs

200

OK

500

Internal Server Error

207

Failed to acquire subscriptionID

Consult the application server logs

200

OK

500

Internal Server Error

208

Failed to login user

Consult the application server logs

200

OK

500

Internal Server Error

209

Failed to register endpoint

Consult the application server logs

200

OK

500

Internal Server Error

210

Max CPU

Wait before sending another request

503

Service

503

Service Unavailable

utilization

Unavailable

 

reached

 

211

No free SIP Subscriptions available

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