# RESTful Application Development Guide

# Presence

## Operations

The RESTful Presence interfaces allow an application to act as either of two different parties to a presence interaction: as a presentity or as a watcher. A presentity agrees to have certain data (called attributes) such as current activity, available communication means, and contact addresses made available to others while a watcher is a consumer of such information. As a watcher, an application can request to subscribe to all or a subset of a presentity’s data, poll for that data, and start and end presence notifications. As a presentity, an application can publish presence data about itself, check to see if any new watchers wish to subscribe to its presence data, authorize those watchers it chooses to authorize, block those it wishes not to have access, and get a list of currently subscribed watchers.

In the listings below, bold indicates a required attribute, <> a descriptive comment.

Note: | An HTML version of this information is at `http://host:port/rest/presence/index.html` where host and port depend on the Oracle Communications Services Gatekeeper installation.

### Get Open Subscriptions

Polls for any watchers who want to subscribe to this presentity’s data.

#### Request

##### URI

`http://host:port/rest/presence/subscriptions?status=open`

##### HTTP Method

GET

#### Response

##### Response Content-Type

application/json

##### Body

`{"result": [{`

`` `"application"``: "String",`<A descriptive name for the application that operates on behalf of the watcher. Information only>

`"``attributes"``: ["Activity|Place|Privacy|Sphere|Communication|Other"],`<The attributes this watcher wishes to see. An empty array means all attributes. See Table 10-1 for more information.>

`` `"watcher"``: "URI"`<The address of the watcher whose request this is>

`}]}`

Table 10-1 Presence Attributes
Value | Meaning
--- | ---
`Activity` | The presentity’s activity (available, busy, lunch, etc.)
`Place` | The kind of place where the presentity is (home, office, etc.)
`Privacy` | The amount of privacy that the presentity wants (public, private, etc.)
`Sphere` | The presentity’s current environment (work, home,)
`Communication` | The presentity’s preferred means of communications (email, phone, etc.)
`Other` | A key-value pair to describe any arbitrary information

#### Error Response

Service Exception

Policy Exception

### Get My Watchers

Gets an array of current watchers

#### Request

##### URI

`http://host:port/rest/presence/subscriptions?filter=watcher`

##### HTTP Method

GET

#### Response

##### Response Content-Type

application/json

##### Body

{"result": ["URI"]}

The addresses of the current watchers

#### Error Response

Service Exception

Policy Exception

### Update Subscription Authorization

Used to add watchers who have recently asked for subscriptions or to change permissions for any current watchers.

#### Request

##### URI

`http://host:port/rest/presence/subscription/authorization`

##### Request Content-Type

application/json

##### Body

`{`

`` `"decisions"``: [{<`

`` `"decision"``: "Boolean",`<Whether to allow the watcher>

`` `"presenceAttribute"``: "Activity|Place|Privacy|Sphere|Communication|Other"`

`}],`<The attributes this watcher wishes to see. An empty array means all attributes. See Table 10-1 for more information.>

`"watcher": "URI"`<The watcher whose request is being evaluated>

`}`

##### HTTP Method

PUT

#### Response

##### Body

Empty

#### Error Response

Service Exception

Policy Exception

### Subscribe Presence

Requests to subscribe to a presentity’s data. No data will be available until the presentity authorizes the watcher using Update Subscription Authorization.

#### Request

##### URI

`http://host:port/rest/presence/subscription`

##### Request Content-Type

application/json

##### Body

`{`

`` `"application"``: "String",`<A descriptive name for the application whose data the watcher wishes to access. Informational only>

`` `"presentity"``: "URI",`<The address of the presentity or group whose data is being requested>

`` `"reference"``: {`

`` `"correlator"``: "String",`<A correlator identifying this request>

`` `"endpoint"``: "URI",`<The endpoint address to which the Notfiy Subscription notification is delivered>

`` `"interfaceName"``: "String"` <Descriptive only>

`},`

`"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"]`<The attributes this watcher wishes to see. An empty array means all attributes. See Table 10-1 for more information.>

`}`

##### HTTP Method

PUT

#### Response

##### Body

Empty

#### Error Response

Service Exception

Policy Exception

### Block Subscription

Allows a presentity to block a watcher’s access to the presentity’s data. The watcher is notified with a Subscription Ended notification.

#### Request

##### URI

`http://host:port/rest/presence/subscription/${watcher}`

${watcher}: The URI of the watcher to block

##### HTTP Method

DELETE

#### Response

##### Body

Empty

#### Error Response

Service Exception

Policy Exception

### Start Presence Notification

Begin delivering presence data to the endpoint defined in the reference attribute. This operation is only functional if the presentity has approved the watcher.

#### Request

##### URI

`http://host:port/rest/presence/notification`

##### Request Content-Type

application/json

##### Body

`{`

`` `"checkImmediate"``: "Boolean",`<Whether to check immediately after establishing the notification>

`` `"frequency"``: {`<Maximum frequency of notifications (can also be considered minimum time between notifications). In the case of a group subscription the service must make sure this frequency is not violated by notifications for various members of the group, especially in combination with checkImmediate.>

`` `"metric"``: "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",`<The metric in which to measure the frequency>

`` `"units"``: "Integer"`<The number of units of the metric>

`},`

`` `"presentity"``: "URI",`<The presentity or group whose data is being accessed>

`` `"reference``": {`

`` `"correlator"``: "String",`<A correlator identifying this notification>

`` `"endpoint"``: "URI",`<The endpoint address to which the notification is to be delivered>

`` `"interfaceName"``: "String"` <Descriptive only, the type of notification>

`},`

`"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"],`<The attributes this watcher wishes to see. An empty array means all attributes. See Table 10-1 for more information.>

`"count": "Integer",`<The maximum number of notifications. Zero or unspecified means no maximum>

`"duration": {`<The length of time over which notifications occur. For service default, do not specify>

`` `"metric"``: "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",`<The metric in which to measure the duration>

`` `"units"``: "Integer"`<The number of units of the metric>``

`}`

`}`

##### HTTP Method

PUT

#### Response

##### Response Content-Type

application/json

##### Body

{"result": ["URI"]}

The presentities to whose attributes the watcher did not successfully subscribe. Empty if there were no issues.

##### Header

`http://host:port/rest/presence/notifications`

The URI of the pub/sub server.

#### Error Response

Service Exception

Policy Exception

### End Presence Notification

Stops a presence notification

#### Request

##### URI

`http://host:port/rest/presence/notification/${correlator}`

${correlator}:String

The correlator passed in when the notification was started.

##### HTTP Method

DELETE

#### Response

##### Body

Empty

#### Error Response

Service Exception

Policy Exception

### Get User Presence

Gets the aggregated presence data of a presentity to whose data the watcher has previously successfully subscribed. Only the attributes that the watcher is authorized to see are returned.

#### Request

##### URI

`http://host:port;rest/presence/data?query=${query}`

${query}:

`{`

`` `"presentity"``: "URI",`<The address of the presentity being requested>

`"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"] <The attributes being requested.`An empty array means all attributes. See Table 10-1 for more information.>

`}`

##### HTTP Method

GET

#### Response

##### Response Content-Type

application/json

##### Body

`{"result": [{`

`` `"lastChange"``: "Calendar",`<The time and date the data last changed in ISO 8601 extended format >

`` `"typeAndValue"``: {`<The presence information>

`` `"unionElement"``: "Activity|Place|Privacy|Sphere|Communication|Other",`<See Table 10-1. Determines what data is presented.>

`"activity": "ActivityNone|Available|Busy|DoNotDisturb|OnThePhone|Steering|Meeting|Away|Meal|PermanentAbsence|Holiday|Performance|InTransit|Travel|Sleeping|ActivityOther",`<What the presentity is doing. `ActivityNone` indicates the value has not been set. `ActivityOther` refers to any non-listed activity type.>

`"communication": {"means": [{`<Connection information for presentity’s preferred forms of communication>

`` `"contact"``: "URI",`<The contact address for this particular means>

`` `"priority"``: "Float",`<The priority of this particular means. Between 0 and 1, with 1 indicating most preferred means>

`` `"type"``: "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"`<The type of contact client for this particular means. `Video` refers to a video phone. `MeansOther` refers to any other client type>

`}]},`

`"other": {`<An arbitrary name/value pair for the Other element of Table 10-1>

`` `"name"``: "String",`

`` `"value"``: "String"`

`},`

`"place": "PlaceNone|Home|Office|PublicTransport|Street|Outdoors|PublicPlace|Hotel|Theatre|Restaurant|School|Industrial|Quiet|Noisy|Aircraft|Ship|Bus|Station|Mall|Airport|Train|PlaceOther",`<The type of location for the presentity.`PlaceNone` means no value has been set. `PlaceOther` refers to any other type of place.>

`"privacy": "PrivacyNone|PrivacyPublic|PrivacyPrivate|PrivacyQuiet|PrivacyOther",`<The level of privacy in the presentity’s current environment. `PrivacyNone` means the value has not been set. `PrivacyOther` refers to any other privacy level>

`"sphere": "SphereNone|SphereWork|SphereHome|SphereOther"`<The sphere within which the presentity is currently acting. `SphereNone` means the value has not been set. `SphereOther` refers to any other sphere.

`> },<`

`"note": "String"`<An explanatory note>

`}]}`

#### Error Response

Service Exception

Policy Exception

### Publish

Allows the presentity to publish presence information

#### Request

##### URI

http://host:port/rest/presence/data

##### Request Content-Type

application/json

##### Body

`{"presence": [{`

`"lastChange"``: "Calendar",`<The time and date the data last changed in ISO 8601 extended format >

`` `"typeAndValue"``: {`<The presence information>

`` `"unionElement"``: "Activity|Place|Privacy|Sphere|Communication|Other",`<See Table 10-1. Determines what data is presented.>

`"activity": "ActivityNone|Available|Busy|DoNotDisturb|OnThePhone|Steering|Meeting|Away|Meal|PermanentAbsence|Holiday|Performance|InTransit|Travel|Sleeping|ActivityOther",`<What the presentity is doing. `ActivityNone` indicates the value has not been set. `ActivityOther` refers to any non-listed activity type.>

`"communication": {"means": [{`<Connection information for presentity’s preferred forms of communication>

`` `"contact"``: "URI",`<The contact address for this particular means>

`` `"priority"``: "Float",`<The priority of this particular means. Between 0 and 1, with 1 indicating most preferred means>

`` `"type"``: "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"`<The type of contact client for this particular means. `Video` refers to a video phone. `MeansOther` refers to any other client type>

`}]},`

`"other": {`<An arbitrary name/value pair for the Other element of Table 10-1>

`` `"name"``: "String",`

`` `"value"``: "String"`

`},`

`"place": "PlaceNone|Home|Office|PublicTransport|Street|Outdoors|PublicPlace|Hotel|Theatre|Restaurant|School|Industrial|Quiet|Noisy|Aircraft|Ship|Bus|Station|Mall|Airport|Train|PlaceOther",`<The type of location for the presentity.`PlaceNone` means no value has been set. `PlaceOther` refers to any other type of place.>

`"privacy": "PrivacyNone|PrivacyPublic|PrivacyPrivate|PrivacyQuiet|PrivacyOther",`<The level of privacy in the presentity’s current environment. `PrivacyNone` means the value has not been set. `PrivacyOther` refers to any other privacy level>

`"sphere": "SphereNone|SphereWork|SphereHome|SphereOther"`<The sphere within which the presentity is currently acting. `SphereNone` means the value has not been set. `SphereOther` refers to any other sphere.

`> },<`

`"note": "String"`<An explanatory note>

`}]}`

##### HTTP Method

PUT

#### Response

##### Body

Empty

#### Error Response

Service Exception

Policy Exception

## Notifications

The content of notifications delivered to the designated endpoint.

### Status Changed

`{"statusChanged": {`

`` `"changedAttributes"``: [{`

`"lastChange"``: "Calendar",`<The time and date the data last changed in ISO 8601 extended format >

`` `"typeAndValue"``: {`<The presence information>

`` `"unionElement"``: "Activity|Place|Privacy|Sphere|Communication|Other",`<See Table 10-1. Determines what data is presented.>

`"activity": "ActivityNone|Available|Busy|DoNotDisturb|OnThePhone|Steering|Meeting|Away|Meal|PermanentAbsence|Holiday|Performance|InTransit|Travel|Sleeping|ActivityOther",`<What the presentity is doing. `ActivityNone` indicates the value has not been set. `ActivityOther` refers to any non-listed activity type.>

`"communication": {"means": [{`<Connection information for presentity’s preferred forms of communication>

`` `"contact"``: "URI",`<The contact address for this particular means>

`` `"priority"``: "Float",`<The priority of this particular means. Between 0 and 1, with 1 indicating most preferred means>

`` `"type"``: "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"`<The type of contact client for this particular means. `Video` refers to a video phone. `MeansOther` refers to any other client type>

`}]},`

`"other": {`<An arbitrary name/value pair for the Other element of Table 10-1>

`` `"name"``: "String",`

`` `"value"``: "String"`

`},`

`"place": "PlaceNone|Home|Office|PublicTransport|Street|Outdoors|PublicPlace|Hotel|Theatre|Restaurant|School|Industrial|Quiet|Noisy|Aircraft|Ship|Bus|Station|Mall|Airport|Train|PlaceOther",`<The type of location for the presentity.`PlaceNone` means no value has been set. `PlaceOther` refers to any other type of place.>

`"privacy": "PrivacyNone|PrivacyPublic|PrivacyPrivate|PrivacyQuiet|PrivacyOther",`<The level of privacy in the presentity’s current environment. `PrivacyNone` means the value has not been set. `PrivacyOther` refers to any other privacy level>

`"sphere": "SphereNone|SphereWork|SphereHome|SphereOther"`<The sphere within which the presentity is currently acting. `SphereNone` means the value has not been set. `SphereOther` refers to any other sphere.

`> },<`

`"note": "String"`<An explanatory note>

`}]`

`` `"correlator"``: "String",`<The correlator passed in with the notification set up>

`` `"presentity"``: "URI"`<The presentity whose data this is>

`}}`

### Notify Subscription

`{"notifySubscription": {`

`` `"presentity"``: "URI",`<The address of the presentity who has or has not authorized the watcher to whom this notification is sent>

`"decisions": [{`

`` `"decision"``: "Boolean",`<Whether the subscription is authorized>

`` `"presenceAttribute"``: "Activity|Place|Privacy|Sphere|Communication|Other"`

`}]`<What attributes are authorized. See Table 10-1>

`}}`

### Status End

`{"statusEnd": {"correlator": "String"}}`

The notification indicated by the correlator has ended, because either the duration or count was completed. This is not delivered in the case of an error or the use of End Presence Notification.

### Subscription Ended

`{"subscriptionEnded": {`

`` `"presentity"``: "URI",`<The presentity in question>

`` `"reason"``: "String"`<Timeout or blocked>

`}}`

The subscription has been terminated, either blocked by the presentity or because of a timeout or connection failure.

## Errors

The content of possible error messages.

### Service Exception

{`"error"`:{

`"type":`"org.csapi.schema.parlayx.common.v2_1.ServiceException"

`"message"`:"String"

}}

### Policy Exception

{`"error"`:{

`"type"`:"org.csapi.schema.parlayx.common.v2_1.PolicyException"

`"message"`:"String"

}}