| Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide Release 5.0 Part Number E16621-02 |
|
|
View PDF |
| Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide Release 5.0 Part Number E16621-02 |
|
|
View PDF |
This chapter describes the operations in the Presence interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.
Applications use the RESTful Presence interface to act as either of two different parties to a presence interaction: as a presentity or as a watcher.
When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of these operations can be found at
http://host:port/rest/presence/index.html
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
A presentity agrees to have certain data (called attributes) such as current activity, available communication means, and contact addresses made available to others. 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.
A watcher is the consumer of current activity, available communication means, and contact addresses made available by a presentity. 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.
This section describes the following data objects that are commonly used in the JSON data structures in RESTful Presence interface operations. They are described in detail here to avoid repeating the information.
The term attributes is used to describe the current attributes of a presentity. It specifies the single Presence attribute or the set of Presence attributes that a watcher might wish to view for a specified presentity. It is used in the request body for Subscribe Presence and Start Presence Notifications, the Request-URI query for Get User Presence and the response body for Get Open Subscriptions,
The following structure is used to specify the array of values for attributes:
"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"
Each element of the array denotes a single Presence attribute and in turn, represented by a JSON attribute-value pair (or a JSON data object). An empty array indicates that the watcher is interested in all of the Presence attributes associated with a presentity.
The term presenceAttribute indicates the type of presentity data that must be updated or changed for the watcher. It is used in the request body for Update Subscription Authorization and in subscription notifications.
The values presenceAttribute accepts are specified in the following name/value pair structure:
"presenceAttribute": ["Activity|Place|Privacy|Sphere|Communication|Other"
The term unionElement indicates the type of presentity data that is presented. It is used in the request body for Publish, the response body for Get User Presence and in notifications for a change in status.
The values unionElement accepts are specified in the following name/value pair structure:
"unionElement": ["Activity|Place|Privacy|Sphere|Communication|Other"
The term activity specifies the presentity's current activity. It is one of the values accepted by attributes. The values activity accepts are specified in the following name/value pair structure:
"activity": "ActivityNone|Available|Busy|DoNotDisturb|OnThePhone|Steering|Meeting|Away|Meal|PermanentAbsence|Holiday|Performance|InTransit|Travel|Sleeping|ActivityOther
where:
ActivityNone indicates that the value has not been set.
ActivityOther refers to any non-listed activity type.
The place attribute specifies the current type of location for a presentity. It is one of the values accepted by the attributes attribute. The values place accepts are specified in the following name/value pair structure:
"place": "PlaceNone|Home|Office|PublicTransport|Street|Outdoors|PublicPlace|Hotel|Theatre|Restaurant|School|Industrial|Quiet|Noisy|Aircraft|Ship|Bus|Station|Mall|Airport|Train|PlaceOther"
where:
PlaceNone indicates that the value has not been set.
PlaceOther refers to any other type of place not listed here.
The privacy attribute specifies the level of privacy in the presentity's current environment. It is one of the values accepted by the attributes attribute. The values privacy accepts are specified in the following name/value pair structure:
"privacy": "PrivacyNone|PrivacyPublic|PrivacyPrivate|PrivacyQuiet|PrivacyOther"
where:
PrivacyNone indicates that the value has not been set.
PrivacyOther refers to any other level of privacy not listed here.
The sphere attribute specifies the sphere within which the presentity is currently acting. It is one of the values accepted by the attributes attribute. The values sphere accepts are specified in the following name/value pair structure:
"sphere": "SphereNone|SphereWork|SphereHome|SphereOther"
where:
SphereNone indicates that the sphere has not been set.)
SphereOther is used to refer to any other type of sphere not listed here.
The type attribute specifies the type of contact client for a specified or preferred form of communication. It is one of the values accepted by the means JSON data object. The values type accepts are specified in the following name/value pair structure:
"type": "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"
The communication attribute specifies the connection information for a presentity's preferred form of communication. It is one of the values accepted by attributes, presenceAttribute and unionElement. It accepts only one value, means, specified in the following structure:
"communication": {"means": [{
"contact": "URI",
"priority": "Float",
"type": "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"
}]
}
The means object specifies the parameters for the preferred form of communication. It accepts the following parameters:
contact. String. Required. The contact address for this particular means or form of communications, as a URI.
priority. Number (floating point). required parameter. The priority of this particular means. Valid entries start at 0.0 for the lowest priority and range in increasing order to 1.0 as the value for highest priority.
type. Described earlier. See "Type".
The following structure is used to specify the array of values for means:
"means": [{
"contact": "URI",
"priority": "Float",
"type": "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"
}]
The typeAndValue JSON object contains the presence information for a presentity. It is used in Get User Presence and Publish operations and in the Presence notifications. It is made up of the following parameters (each of which has been described earlier):
unionElement. String. Required. See "unionElement".
activity. String. Optional. Present if the value for unionElement is Activity. See "Activity".
place. String. Optional. Present if the value for unionElement is Place. See "Place".
privacy. String. Optional. Present if the value for unionElement is Privacy. See "Privacy".
sphere. String. Optional. Present if the value for unionElement is Sphere. See "Sphere".
communication: JSON object. Optional. Present if the value for unionElement is Communication. See "Communication".
other: JSON object. Optional. See "Other".
The following structure is used to specify the values for typeAndValue:
"typeAndValue": {
"unionElement": "Activity|Place|Privacy|Sphere|Communication|Other",
"activity": "ActivityNone|Available|Busy|DoNotDisturb|OnThePhone|Steering|Meeting|Away|Meal|PermanentAbsence|Holiday|Performance|InTransit|Travel|Sleeping|ActivityOther",
"communication": {"means": [{
"contact": "URI",
"priority": "Float",
"type": "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"
}]
}
The other JSON object specifies the parameters for arbitrary information. It has the following parameters:
name. String. Required. The name for this specific information.
value. String. Required. The specific value to be matched for the name.
The following structure is used to specify the values for typeAndValue:
"other": {
"name": "String",
"value": "String"
}
The Get Open Subscription operation polls for any watchers who wish to subscribe to this presentity's data.
To retrieve the information on the applications, the subscription?status=open query string is included in the Request-URI of the GET method.
If the Get Open Subscription operation is successful, the response body contains the result JSON data object with the information on the watchers.
Basic
GET
http://host:port/rest/presence/subscription?status=open
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
the subscription?status=open query string is used to retrieve any watchers who wish to subscribe to this presentity's data.
The MIME-type for the Content-Type header field is application/json.
There is no request body.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The information on the watchers is returned as an array of values for the result attribute. Each element in the array contains the following attribute-value pairs.
application. String. Information only. A descriptive name for the application that operates on behalf of the watcher.
attributes. String. The array of Presence attributes that the watcher wishes to see. See "attributes".
watcher. String. The address (as a URI) of the watcher making the request.
The response body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"result": [{
"application": "String",
"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"],
"watcher": "URI"
}]}
The Get My Watchers operation retrieves an array of current watchers.
To retrieve the information on the current watchers, include the subscription?filter=watcher query string in the Request-URI of the GET method.
If the Get My Watchers operation is successful, the response body contains the result JSON data object with the list of current watchers.
Basic
GET
http://host:port/rest/presence/subscription?filter=watcher
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
the subscription?filter=watcher query string is used to retrieve the array of current watchers.
The MIME-type for the Content-Type header field is application/json.
There is no request body.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The response body contains a JSON data object as the value for the result entry. The value for result is an array of URIs which represent the addresses of the set of current watchers:
{"result": ["URI"]}
The Update Subscription Authorization operation is used to add watchers who have recently asked for subscriptions or to change permissions for any current watchers.
To do so, provide the address of the watcher along with the decision on whether permission must be granted, and the Presence attribute for which such permission must be granted (or revoked).
If the request fails, the Status-Line header field will contain the status code and the reason for the failure.
Basic
PUT
http://host:port/rest/presence/subscription/authorization
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The MIME-type for the Content-Type header field is application/json.
The request body for the Update Subscription Authorization operation accepts the following parameters:
watcher. String. Required. The URI of the watcher.
decisions: Array of JSON objects. Required. Each JSON object in the array contains the following parameters:
presenceAttribute. String. Required. The specific Presence attribute for which permission is to be granted (to a new watcher) or permission must be changed (for the current watcher). See "PresenceAttribute".
decision: Boolean. Required. If the value is true, permission is granted (to a new watcher) or permission is changed (for the current watcher).
The request body is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"decisions": [{
"decision": "Boolean",
"presenceAttribute": "Activity|Place|Privacy|Sphere|Communication|Other"
}],
"watcher": "URI"
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
There is no response body.
The Subscribe Presence operation requests a subscription to a presentity's data. No data will be available until the presentity authorizes the watcher using Update Subscription Authorization.
To request a subscription to a presentity's data, provide the address of the presentity or group whose data is being requested, the Presence attributes this watcher wishes to see. Because the actual data depends on whether the subscription is authorized, a reference data object must also be provided in the request body. The reference object (also a JSON object) contains the correlator for the notification, the endpoint address (a specific Bayeux channel name) to which the notifications must be sent and, optionally, the interface name (a string to identify the notification).
If the request fails, the Status-Line header field will contain the status code and the reason for the failure.
Basic
PUT
http://host:port/rest/presence/subscription
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The MIME-type for the Content-Type header field is application/json.
The request body for the Subscribe Presence operation accepts the following parameters:
application. String. Required. A descriptive name for the application whose data the watcher wishes to access. Informational only.
presentity: a JSON object. Required. The address of the presentity whose data is requested (as a URI).
attributes. An array of string values. Optional. The set of Presence attributes the watcher wishes to see. An empty array (or if this attribute is not present) indicates the watcher wishes to view all the attributes. For a description of the attributes, see "attributes".
reference: JSON object. Required. Use this object to provide the following information about the endpoint that is to receive the notification:
correlator. String. Required. The correlator used to identify the notification.
endpoint. String. Required. The URI which represents the endpoint address to which the notification should be delivered. This string should be a Bayeux protocol channel name that begins with /bayeux/appInstanceID where appInstanceID is the client application's application instance account ID.
For more information on application instances, see the discussion on creating and maintaining service provider and application accounts in Accounts and SLAs Guide.
interfaceName. String. Required. A descriptive string to identify the type of notification.
The request body is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"application": "String",
"presentity": "URI",
"reference": {
"correlator": "String",
"endpoint": "URI",
"interfaceName": "String"
},
"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"]
}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
There is no response body.
The Block Subscription operation allows a presentity to block a watcher's access to the presentity's data. The watcher is notified with a Subscription Ended notification.
To block a watcher's subscription to a presentity's data, provide the address of the watcher as a URI in the Request-URI of the DELETE method.
If the request fails, the Status-Line header field will contain the status code and the reason for the failure.
Basic
DELETE
http://host:port/rest/presence/subscription/${watcher}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
the ${watcher} is the URI of the watcher who must be blocked from viewing this presentity's data.
The MIME-type for the Content-Type header field is application/json.
There is no request body.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
There is no response body.
The Start Presence Notification operation begins delivering presence data to the endpoint defined in the reference attribute. This operation is only functional if the presentity has approved the watcher.
To set up for such notifications, provide the SIP-formatted URI of the presentity for which the watcher must receive notifications, the Presence attributes which will trigger the notifications and a reference object for the delivery of the notifications. The reference object (also a JSON object) contains the correlator for the notification, the endpoint address (a specific Bayeux channel name) to which the notifications must be sent and, optionally, the interface name (a string to identify the notification). Additionally, you can specify the request frequency, the total number of notifications and the duration for the notification and whether the check must start immediately.
If the Start Presence Notification request is successful, the endpoint address specified in the request body will receive a notification when:
the presentity has authorized the watcher. See "Notification of Subscription to a Presentity's Data".
the presentity's status changes. See "Notification of a Status Change for a Presentity".
the notification limit or the specified duration has been reached. See "Notification Signalling End to Monitoring of Presentity".
the subscription has been terminated or blocked by the presentity. See "Notification of End to a Subscription".
The application accesses the endpoint address to retrieve the specific notifications.
If there is any issue with subscriptions, the response body will contain the address(es) of the presentity (or presentities) to whose attributes the watcher did not successfully subscribe.
Basic
PUT
http://host:port/rest/presence/notification
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The MIME-type for the Content-Type header field is application/json.
The request body for the Start Presence Notification operation accepts following parameters:
presentity. String. Required. The URI of a presentity or group whose data is being accessed.
checkImmediate. String. Required. Boolean value ("true" or "false"). Set to:
True: The application requires the status notification to start immediately and thereafter, as often as required.
False: The application requires the status notification to start at the end of the time period.
criteria. String. Required. The status of the terminal. It can be one or all of the following:
Reachable
UnReachable
Busy
frequency: JSON object. Required. This object specifies the frequency for checking the status (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. It takes the following parameters:
metric. String. Required. The unit of time for the check specified as Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units. Integer. Required. The number of times the check must be made within the specified metric.
reference. A JSON object. Required. Use this object to provide the following information about the endpoint that is to receive the notification:
correlator. String. Required. The correlator used to identify the notification.
endpoint. String. Required. The URI which represents the endpoint address to which the notification should be delivered. This string should be a Bayeux protocol channel name that begins with /bayeux/appInstanceID where appInstanceID is the client application's application instance account ID.
For more information on application instances, see the discussion on creating and maintaining service provider and application accounts in Accounts and SLAs Guide.
interfaceName. String. Required. A descriptive string to identify the type of notification.
count. Integer. Required. The maximum number of notifications to be sent to the watcher. If this number is reached the statusEnd notification is delivered to the endpoint address.
duration. A JSON object. Required. This object specifies the total duration before for the count with the following:
metric. String. Required. The unit of time for the notifications specified as Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units. Integer. Required. The duration in the specified metric.
The request body is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"checkImmediate": "Boolean",
"frequency": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
},
"presentity": "URI",
"reference": {
"correlator": "String",
"endpoint": "URI",
"interfaceName": "String"
},
"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"],
"count": "Integer",
"duration": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
}
}
The Location header field contains the URI of the publish/subscribe server:
http://host:port/rest/presence/notifications
If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The requested information is returned in a JSON object as the value for the result attribute. It is an array of URIs which represent the addresses of the presentities to whose attributes the watcher did not successfully subscribe:
{"result": ["URI"]}
The actual notifications delivered to the endpoint address are described below.
Notification of Subscription to a Presentity's Data
The notifySubscription notification indicates whether the presentity has (or has not) authorized the watcher and the attributes that are permitted to be viewed.
The notifySubscription is a JSON object containing the following:
presentity. String. The URI of the presentity who has (or has not) authorized the watcher to whom the notification is sent.
decisions: Array of JSON objects. Required. Each JSON object in the array contains the following parameters:
presenceAttribute. String. Required. The specific Presence attribute for which permission is to be granted. See "PresenceAttribute".
decision. Boolean. Required. If the value is true, permission is granted or permission is denied.
The subscription notification is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"notifySubscription": {
"presentity": "URI",
"decisions": [{
"decision": "Boolean",
"presenceAttribute": "Activity|Place|Privacy|Sphere|Communication|Other"
}]
}}
Notification of a Status Change for a Presentity
The statusChanged JSON object is delivered when there is a change to a specified attribute.
This object is sent to the Bayeux channel name associated with the application instance and specified in the request body as the endpoint attribute value.
The statusChanged is a nested JSON object containing the following:
correlator. String. The correlator used to identify the notification and provided in the request body of the Start Presence Notification operation.
presentity. String. The URI of the presentity associated with this data.
changedAttributes. JSON object. Its value is an array of nested JSON objects and attributes which represent the aggregated presence data of the presentity. It contains the following:
lastChange. String. The date and time when this attribute was last changed in ISO 8601 extended format.
typeAndValue. JSON object. The presence information of the presentity. See "TypeandValue".
note. String. This optional entry is an explanatory note.
The notification for a status change is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"statusChanged": {
"changedAttributes": [{
"lastChange": "Calendar",
"typeAndValue": {
"unionElement": "Activity|Place|Privacy|Sphere|Communication|Other",
"activity": "ActivityNone|Available|Busy|DoNotDisturb|OnThePhone|Steering|Meeting|Away|Meal|PermanentAbsence|Holiday|Performance|InTransit|Travel|Sleeping|ActivityOther",
"communication": {"means": [{
"contact": "URI",
"priority": "Float",
"type": "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"
}]},
"other": {
"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",
"privacy": "PrivacyNone|PrivacyPublic|PrivacyPrivate|PrivacyQuiet|PrivacyOther",
"sphere": "SphereNone|SphereWork|SphereHome|SphereOther"
},
"note": "String"
}],
"correlator": "String",
"presentity": "URI"
}}
Notification Signalling End to Monitoring of Presentity
The statusEnd JSON object is delivered when the notification count specified as the value for count is reached or when the duration specified for units in the duration object is reached.
It is sent to the Bayeux channel name associated with the application instance and specified in the request body as the endpoint attribute value.
The statusEnd is a JSON object containing the following:
correlator. String. The correlator used to identify the notification and provided in the request body of the Start Presence Notification operation.
This notification is not delivered in the case of an error, or if the application ended the notification using endNotification.
The notification signalling the end of the monitoring of a presentity is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"statusEnd": {"correlator": "String"}}
Notification of End to a Subscription
The subscriptionEnded JSON object is delivered when the subscription has been terminated, either blocked by the presentity or because of a timeout or connection failure.
It is sent to the Bayeux channel name associated with the application instance and specified in the request body as the endpoint attribute value.
The subscriptionEnded is a JSON object containing the following:
presentity. String. The URI of the presentity.
reason. String. Required. The string indicates whether there was a timeout or the presentity blocked the watcher.
The notification signalling the end of the subscription to a presentity is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"subscriptionEnded": {
"presentity": "URI",
"reason": "String"
}}
The End Presence Notification operation stops a Presence notification.
To stop a previously set up Presence notification, provide the correlator for the notification passed earlier in the Start Presence Notification request.
There is no request or response body for the End Presence Notification operation. If the request fails, the body of the error response will contain the identifier for the notification and the type of exception.
Basic
DELETE
http://host:port/rest/presence/notification/${correlator}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
correlator is a string. It is the correlator for the notification provided in the reference object within the request body of the initial Start Presence Notification operation.
There is no request body.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
There is no response body.
The Get User Presence operation retrieves 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.
To retrieve the information, include the URI of the presentity and the required attributes as a data object in the query string of the Request-URI of the GET method.
If the Get User Presence operation is successful, the response body contains the result JSON data object with the aggregated presence data of the specified presentity.
Basic
GET
http://host:port/rest/presence/data?filter=${query}
where host and port are the host name and port of the machine on which Services Gatekeeper is installed. ${query} is a data object with the following parameters:
presentity. String. Required. The URI of the presentity to whose data the watcher has previously successfully subscribed.
attributes: Array of string values. Optional. The set of Presence attributes the watcher wishes to see. An empty array (or if this attribute is not present) indicates the watcher wishes to view all the attributes. For a description of the attributes, see "attributes".
The following JSON data structure represents this data object in the URI. The value part of each name/value pair indicates its data type:
{
"presentity": "URI",
"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"]
}
The MIME-type for the Content-Type header field is application/json.
There is no request body.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The requested information is returned in a JSON object as the value for the result attribute. It is an array of nested JSON objects and attributes which represent the aggregated presence data of a presentity. It contains the following:
lastChange. String. The time and date the data last changed in ISO 8601 extended format.
typeAndValue: JSON object. The presence information for a presentity (described earlier). See "TypeandValue".
note. String. This optional entry is an explanatory note.
The response body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"result": [{
"lastChange": "Calendar",
"typeAndValue": {
"unionElement": "Activity|Place|Privacy|Sphere|Communication|Other",
"activity": "ActivityNone|Available|Busy|DoNotDisturb|OnThePhone|Steering|Meeting|Away|Meal|PermanentAbsence|Holiday|Performance|InTransit|Travel|Sleeping|ActivityOther",
"communication": {"means": [{
"contact": "URI",
"priority": "Float",
"type": "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"
}]},
"other": {
"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",
"privacy": "PrivacyNone|PrivacyPublic|PrivacyPrivate|PrivacyQuiet|PrivacyOther",
"sphere": "SphereNone|SphereWork|SphereHome|SphereOther"
},
"note": "String"
}]}
The Publish operation allows the presentity to publish presence information.
To publish the information, the request body contains the presence JSON data object with the aggregated presence data of the specified presentity.
If the request fails, the body of the error response will contain the identifier for the notification and the type of exception.
Basic
PUT
http://host:port/rest/presence/data
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The MIME-type for the Content-Type header field is application/json.
The request body for the Publish operation is a nested data object. The value for presence attribute is an array of nested JSON structures which represent the aggregated presence data of a presentity. It accepts the following parameters:
lastChange. String. The time and date the data last changed in ISO 8601 extended format.
typeAndValue. JSON object. The presence information for a presentity (described earlier). See "TypeandValue".
note. String. This optional entry is an explanatory note.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"presence": [{
"lastChange": "Calendar",
"typeAndValue": {
"unionElement": "Activity|Place|Privacy|Sphere|Communication|Other",
"activity": "ActivityNone|Available|Busy|DoNotDisturb|OnThePhone|Steering|Meeting|Away|Meal|PermanentAbsence|Holiday|Performance|InTransit|Travel|Sleeping|ActivityOther",
"communication": {"means": [{
"contact": "URI",
"priority": "Float",
"type": "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"
}]},
"other": {
"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",
"privacy": "PrivacyNone|PrivacyPublic|PrivacyPrivate|PrivacyQuiet|PrivacyOther",
"sphere": "SphereNone|SphereWork|SphereHome|SphereOther"
},
"note": "String"
}]}
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
There is no response body.
|
 Copyright © 2007, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|