6 OCMS Parlay X Web Services

This chapter describes OCMS support for the Parlay X 2.0 Presence Web services interfaces for developing applications. The Web service functions as a Presence Network Agent which can publish, subscribe, and listen to notifies on behalf of the users of the Web service. This chapter consists of the following sections:

• "Introduction"

• "Installing the Web Services"

• "Installing the Aggregation Proxy"

• "Configuring Web Services with the Aggregation Proxy"

• "Presence Web Services Interface Descriptions"

• "Using the Presence Web Services Interfaces"

• "OCMS Parlay X Presence Custom Error Codes"

Introduction

OCMS provides support for Part 14 of the Parlay X Presence Web Service as defined in the Open Service Access, Parlay X Web Services, Part 14, Presence ETSI ES 202 391-14 specification. The OCMS Parlay X Web service maps the Parlay X Web service to a SIP/IMS network according to the Open Service Access, Mapping of Parlay X Web Services to Parlay/OSA APIs, Part 14, Presence Mapping, Subpart 2, Mapping to SIP/IMS Networks, ETSI TR 102 397-14-2 specification.

Note:

Due to the synchronous nature of the Web service, to receive a callback from the Web service the client must implement the Web service callback interface. For presence, the required interface is the PresenceNotification interface described in Open Service Access, Parlay X Web Services, Part 14, Presence ETSI ES 202 391-14.

Because this implementation is not common or practical for most Web service architectures, the PresenceNotification interface is not currently supported.

The presence Web service communicates directly with IMS presence network elements using the SIP/SIMPLE protocol interface, and uses the JSR-32 UAC framework to communicate with the SIP network.

The HTTP server that hosts the presence Web service is a Presence Network Agent or a Parlay X to SIP gateway.

Installing the Web Services

The Web services are packaged as a standard .ear file and can be deployed the same as any other Web services through Enterprise Manager. The .ear file contains two .war files that implement the two interfaces. If the Web services are deployed on the same server as the presence server, they must be a child application of the Presence server.

Installing the Aggregation Proxy

The aggregation proxy is packaged as a standard .ear file and can be deployed through Enterprise Manager. There are two requirements:

• The application name must be "aggregationproxyear".

• The parent application must be "subscriberdataservices". The aggregation proxy uses the authentication functions of subscriberdataservices to authenticate Web services.

Configuring Web Services with the Aggregation Proxy

The Web services operate within a trusted domain where another entity performs authentication. To authenticate Web services and identify the user of the services, OCMS uses the aggregation proxy to insert the HTTP X-3GPP-ASSERTED-IDENTITY header as defined in 3GPP TS 33.222 Generic Authentication Architecture (GAA); Access to network application functions using Hypertext Transfer Protocol over Transport Layer Security (HTTPS).

To define a Web services deployment server:

1. Open the Enterprise Manager page for the aggregation proxy.

2. Configure the WebServiceHost and WebServicePort to the host and port of the Web services deployment server.

3. Configure the XCAPHost, XCAPPort, and XCAPRoot to the location and parameters of the XDMS.

Presence Web Services Interface Descriptions

The presence Web services consist of three interfaces:

• PresenceConsumer: The watchers use these methods to obtain presence data (Table 6-1).

• PresenceNotification: The presence consumer interface uses the client callback defined in this interface to send notifications. OCMS does not currently support PresenceNotification (Table 6-2).

• PresenceSupplier: The presentity uses these methods to supply presence data and manage access to the data by its watchers (Table 6-3).

Table 6-1 PresenceConsumer Interface

Operation	Description
subscribePresence	The Web Services send a SUBSCRIBE to the presence server.
getUserPresence	Returns the cached presence status because the status changes of the presentity are asynchronously sent to the Web services through a SIP NOTIFY. The Web services actually have the subscription, not the Web services client.
startPresenceNotification	Not supported.
endPresenceNotification	Not supported.

Table 6-2 PresenceNotification Interface

Operation	Description
statusChanged	Not supported.
statusEnd	Not supported.
notifySubscription	Not supported.
subscriptionEnded	Not supported.

Table 6-3 PresenceSupplier Interface

Operation	Description
publish	Maps directly to a SIP PUBLISH.
getOpenSubscriptions	Called by the presentity (supplier) to check if any watcher wants to subscribe to its presence data. No SIP message maps to this method. Returns pending subscriptions currently in the Web services server.
updateSubscriptionAuthorization	The supplier uses this method to answer any open pending subscriptions. An XCAP PUT message is sent to the XDMS server to update the presence-rule document.
getMyWatchers	Retrieves the local list of watchers from the Web services server.
getSubscribedAttributes	Retrieves the local list of subscribed attributes from the Web services server. Currently, only returns Activity.
blockSubscription	Causes the Web services server to end a watcher subscription by modifying the XCAP document on the XDMS server (i.e., putting the watcher on the block list).

Using the Presence Web Services Interfaces

This section describes how to use each of the operations in the interfaces, and includes code examples.

Interface: PresenceConsumer, Operation: subscribePresence

This is the first operation the application must call before using another operation in this interface. It serves two purposes:

• It allows the Web services to associate the current HTTP session with a user.

• It provides a context for all the other operations in this interface by subscribing to at least one presentity (SUBSCRIBE presence event).

Code Example

// Setting the attribute to activityPresenceAttributeType pa = PresenceAttributeType.Activity;PresenceAttributeType[] pat = new PresenceAttributeType[]{pa};
// These inputs are required but not used. SimpleReference sr = new SimpleReference();sr.setCorrelator("unused_correlator");sr.setInterfaceName("unused_interfacename");sr.setEndpoint(new URI ("http://unused.com"));
// Calling the web service consumer.subscribePresence (new URI ("[e-mail]") , pat, "unused", sr);

Interface: PresenceConsumer, Operation: getUserPresence

Call this operation to retrieve a subscribed presentity presence. If the person is offline, it returns ActivityNone and the hardstate note will be written to PresenceAttribute.note. If it returns ActivityOther, it returns the description in the form of OtherValue. It also returns the note on a device as an OtherValue with name = "DeviceNote".

Code Example

PresenceAttributeType pa = PresenceAttributeType.Activity;PresenceAttributeType[] pat = new PresenceAttributeType[]{pa};

//Calling the Web serviceURI Presentity = new URI("[e-mail]");PresenceAttribute[] resultPA = consumer.getUserPresence(presentity,pat);//Getting the result for (int i = 0; i < resultPA.length; i++){ PresenceAttribute attribute = resultPA[i]; String note = attribute.getNote(); if (attribute.getTypeAndValue().getUnionElement() == PresenceAttributeType.Activity){ String activity = attribute.getTypeAndValue().getActivity() .toString(); } if (attribute.getTypeAndValue().getUnionElement() == PresenceAttributeType.Other && attribute.getTypeAndValue().getOther().getName() == "DeviceNote"){ String deviceNote = attribute.getTypeAndValue().getOther().getValue(); }

}

Interface PresenceSupplier, Operation: publish and Oracle Specific "Unpublish"

This is the first operation the application must call before using another operation in this interface. It serves three purposes:

• It allows the Web services to associate the current HTTP session with a user.

• It publishes the user's presence status.

• It subscribes to watcher-info so that the Web services can keep track of any watcher requests.

Code Example

//publish String note = "From Web Service Client";PresenceAttributeType activity = ActivityValue.ActivityNone;PresenceAttribute pa = new PresenceAttribute();AttributeTypeAndValue typeValue = new AttributeTypeAndValue();typeValue.setActivity(activity);typeValue.setUnionElement(PresenceAttributeType.Activity);
//Fill up communication means to some default value CommunicationMeans mean = new CommunicationMeans();mean.setContact(new URI("sip:[e-mail]"));mean.setPriority(1);mean.setType(CommunicationMeanType.Chat);CommunicationValue commValue = new CommunicationValue();commValue.setMeans(new CommunicationMeans[]{mean});typeValue.setCommunication(commValue);
//Unpublish Functionality Implemented by OCMS //To perform an "Unpublish", set OtherValue to (Expires, 0) //OtherValue other = new OtherValue();//other.setName("Expires");//other.setValue(0);//typeValue.setOther(other);//typeValue.setUnionElement(PresenceAttributeType.Other);
//Set default values for other parameters typeValue.setPrivacy(PrivacyValue.PrivacyNone);typeValue.setPlace(PlaceValue.PlaceNone);typeValue.setSphere(SphereValue.SphereNone);pa.setTypeAndValue(typeValue);
//Set the note and time pa.setNote(note);Calendar dateTime = Calendar.getInstance();pa.setLastChange(dateTime);
//Calling the Web service publish(new PresenceAttribute[]{pa});

Interface: PresenceSupplier, Operation: getOpenSubscriptions

This operation retrieves a list of new requests to be on your watcher list.

Code Example

SubscriptionRequest[] srArray = getOpenSubscriptions();for (SubscriptionRequest sr:srArray) { System.out.println(sr.getWatcher() .toString());}

Interface: PresenceSupplier, Operation: updateSubscriptionAuthorization

This operation allows you to place a watcher on either the block or allow list.

Code Example

PresencePermission pp = new PresencePermission();pp.setDecision(true); //Put the user on the allow list //You always pass in Activity pp.set.PresenceAttribute(PresenceAttributeType.Activity);updateSubscriptionAuthorization(new URI("sip:[e-mail]"), new PresencePermission[]{pp});

Interface: PresenceSupplier, Operation: getMyWatchers

This operation retrievesthe list of watchers in your allow list.

Code Example

URI[] uris;uris = getMyWatchers();for (URI uri:uris) System.out.println(uri.toString());

Interface: PresenceSupplier, Operation: getSubscribedAttributes

This operation returns only a single item of PresenceTypeAttribute.Activity. An exception will be thrown if there is no existing subscription.

Code Example

PresenceAttributeType[] pat =getSubscriberdAttributes("sip:[e-mail]");

Interface: PresenceSupplier, Operation: blockSubscription

This operation places a watcher into the block list.

Code Example

blockSubscription(new URI("sip:[e-mail]"));

OCMS Parlay X Presence Custom Error Codes

OCMS introduces two extensions to the Parlay X standard exceptions:

• PresencePolicyException extends PolicyException, and

• PresenceServiceException extends ServiceException

Table 6-4 and Table 6-5 describe the error codes and their associated error message.

Table 6-4 OCMS Parlay X Presence Custom Error Codes: PresencePolicyException

Error Code	Error Message
OPOL0001	Watcher is on the block, polite-block or pending list.

Table 6-5 OCMS Parlay X Presence Custom Error Codes: PresenceServiceException

Error Code	Error Message
PRES0001	Invalid result from XDMS server.
PRES0002	Invalid HTTP session data.
PRES0003	Invalid URI.
PRES0004	Peer unavailable.
PRES0005	Unknown host.
PRES0006	Service unavailable.
PRES0007	Internal error.
PRES0008	User unauthenticated.