This chapter describes the operations in the Terminal Status interface of the RESTful facade provided in Oracle Communications Services Gatekeeper.
Applications use the RESTful Terminal Status interface to get the status of an individual terminal or a group of terminals, or to receive notifications of changes in the status of a terminal.
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/terminal_status/index.html
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The Get Status operation retrieves the status of a single terminal.
To retrieve the status of a specific terminal, provide its URI as the address value of the query object in the Request-URI of the GET method. The interface returns an error if the query object contains more than one address.
If the Get Status operation is successful, the response body contains a JSON data object indicating whether the specific terminal is reachable, unreachable or busy.
http://host:port/rest/terminal_status/status?query=${query}
where:
host and port are the host name and port of the system on which Services Gatekeeper is installed.
${query} contains the URI address for the terminal as the string value for URI in the data object:
{"address":"tel:123"}
For example, the operation to get the status for a terminal identified as "tel:123" is:
GET /rest/terminal_status/status?query="%7B%22address%22%3A%22tel%3A123%22%7D" HTTP/1.1
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The status of the specific terminal is returned in the body of the response as the value of the result attribute:
Reachable
unReachable
Busy
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": "String"}
Example 12-1 Get Status Request
GET /rest/terminal_status/status?query="%7B%22address%22%3A522tel%3A123%22%7D" HTTP/1.1 X-Session-ID: app:4130997928482260925 Authorization: Basic ZG9tYWluX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host:servgtkpr_host.port
The Get Status for Group operation retrieves the status for a group of terminals.
To retrieve the status of a specific terminals, provide their URIs as the address values of the query object in the Request-URI of the GET method.
If the Get Status for Group operation is successful, the response body contains a JSON data object indicating the status for each terminal (whether the specific terminal is reachable, unreachable or busy).
http://host:port/rest/terminal_status/status?queryForGroup=${query}
where:
host and port are the host name and port of the system on which Services Gatekeeper is installed.
${query} contains the URIs for the terminals as an array of string values in the data object:
{"addresses":["URI"]}
For example,
GET /rest/terminal_status/status?queryForGroup="%7B%22address%22%3A%5B%22tel%3A123%22%2C%22tel%3A456 22tel%3A789%22%5D%7D" HTTP/1.1
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The response body contains an array of structures as the value for result. Each element in the array contains the status for one of the terminals whose address was specified in the Request-URI for status?queryForGroup. The following parameters make up the individual terminal's status:
address: String. The URI of a terminal whose status is required.
reportStatus: String. The status of the terminal. It can be one of the following:
Retrieved. The terminal's status is available. It is provided in this object as the current status of the terminal.
Not Retrieved. The terminal's status is not available.
Error: There was an error in the attempt to get the status for this terminal. The error data is provided in this object.
currentStatus: String. This parameter will be present if the value for reportStatus is Retrieved. The current status of the terminal as one of the following:
Reachable
Unreachable
Busy
errorInformation. a JSON object. This object will be present if the value for reportStatus is Error. It will contain the following error information about the terminal:
messageID: String. The error message ID.
text: String. The text for the error message.
variables: Array of string values. An Array of variables to substitute into text.
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": [{
"address": "URI",
"reportStatus": "Retrieved|NotRetrieved|Error",
"currentStatus": "Reachable|Unreachable|Busy",
"errorInformation": {
"messageId": "String",
"text": "String",
"variables": ["String"]
}
}]}
Example 12-3 Get Status for Group Request
GET /rest/terminal_status/status?queryForGroup="%7B%22address%22%3A%5B%22tel%3A123%22%2C%22tel%3A456 22tel%3A789%22%5D%7D" HTTP/1.1 X-Session-ID: app:4130997928482260925 Authorization: Basic ZG9tYWluX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host:servgtkpr_host.port
Example 12-4 Get Status for Group Response
HTTP/1.1 200 OK
Date: Thu, 04 Nov 2101 08:12:43 GMT
Content-Length: 22
Content-Type: application/json
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1
{"result":
[{"address":"tel:123",
"errorInformation":null,
"reportStatus":"Retrieved",
"currentStatus":"Reachable"
},
{"address":"tel:456",
"errorInformation":null,
"reportStatus":"Retrieved",
"currentStatus":"Reachable"
},
{"address":"tel:789",
"errorInformation":null,
"reportStatus":"Retrieved",
"currentStatus":"Reachable"
}]
}
The Status Notification operation initiates requesting for notifications on the status of a specified terminal according to a specified frequency and for a maximum number of notifications over a specified time duration.
To set up for such notifications, provide the URI of the terminal address for which the application must receive notifications, the criteria to trigger 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 to which the notifications must be sent and, optionally, the interface name (a string to identify the notification). You can optionally specify the request frequency, the total number of notifications and the duration for the notification and whether or not the check must start immediately.
If the Status Notification request is successful, the endpoint address specified in the request body receives a notification when:
The current status for the terminal status has been retrieved.
The maximum number of notifications or the specified duration has been reached.
An error has been encountered in obtaining the status.
http://host:port/rest/terminal_status/status-notification
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the Status Notification operation is a nested JSON object. It contains an array of addresses for the terminals in whose status the application is interested, and the following parameters:
address: String. Required. The URI of a terminal to monitor.
checkImmediate: String. Required. Boolean value:
True: The application requires the status notification to start immediately and as often as required, thereafter.
False: The application requires the status notification to start at the end of the time period.
criteria. A set of strings. Required. The required criteria about the terminal. It can be one or more of the following:
Reachable
UnReachable
Busy
frequency. JSON object. Required. The frequency for checking the status specified by the following:
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 managing application instances, see Services Gatekeeper Portal Developer's 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 application. If this number is reached, the statusEnd notification is delivered to the endpoint address.
duration. JSON object. Required. The total duration before for the count specified by 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 for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"addresses": ["URI"],
"checkImmediate": "Boolean",
"criteria": ["Reachable|Unreachable|Busy"],
"frequency": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
},
"reference": {
"correlator": "String",
"endpoint": "URI",
"interfaceName": "String"
},
"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/terminal_status/notifications
If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
There is no response body. The appropriate notifications (described below) are sent to the endpoint address provided by the application in the request body of this operation.
Notification Of Current Terminal Status (statusNotification)
When there is a match for the criteria value specified in the request body, Services Gatekeeper sends a nested JSON data object to the endpoint address.
This nested JSON object contains the following as the value of the attribute name statusNotification:
correlator: String. The correlator used to identify the notification and provided in the request body of the Status Notification operation.
terminalStatus. An array of JSON objects. Each element in the array contains the current status of the terminal (based on the criteria) being monitored and defined by the following:
address: String. The URI of the terminal being monitored.
currentStatus: String. The current status which can be Reachable, unReachable, or Busy.
The notification data object delivered to the endpoint address when the criteria is statusNotification is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"statusNotification": {
"correlator": "String",
"terminalStatus": [{
"address": "URI",
"currentStatus": "Reachable|Unreachable|Busy"
}]
}}
Notification of Error in Retrieving Terminal Status (statusError)
When there is an error in retrieving the status of a terminal, Services Gatekeeper sends a nested JSON data object to the endpoint address.
This nested JSON object contains the following as the value of the attribute name statusError:
correlator: String. The correlator used to identify the notification and provided in the request body of the Status Notification operation.
reason: JSON object. The explanation of the error specified by the following:
messageID: String. The error message identifier.
text: String. The error message description.
variables: An array of strings. The text to string variables.
address: String. The URI of a terminal to monitor.
The notification data object delivered to the endpoint address when the criteria is statusError is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"statusError": {
"correlator": "String",
"reason": {
"messageId": "String",
"text": "String",
"variables": ["String"]
},
"address": "URI"
}}
Notification Signalling End to Monitoring Terminal (statusEnd)
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, Services Gatekeeper sends a nested JSON data object to the endpoint address.
This nested JSON object contains the following as the value of the attribute name statusEnd:
correlator: String. The correlator used to identify the notification and provided in the request body of the Status Notification operation.
This notification is not delivered in the case of an error, or if the application ended the notification using endNotification.
The notification data object delivered to the endpoint address when the criteria is statusEnd is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"statusEnd": {
"correlator": "String"
}}
Example 12-5 Status Notification Request
PUT /rest/terminal_status/status-notification HTTP/1.1
X-Session-ID: app:4130997928482260925
Authorization: Basic ZG9tYWluX3VzZXI6ZG9tYWluX3VzZXI=
X-Param-Keys:
X-Param-Values:
User-Agent: Jakarta Commons-HttpClient/3.0
Host:servgtkpr_host.port
Content-Length: 289
Content-Type: application/json
{
"duration":null,
"criteria":["Reachable","Busy","Unreachable"],
"frequency":
{
"metric":"Second",
"units":"5"
},
"checkImmediate":"true",
"addresses":["tel:123","tel:456","tel:789"],
"reference":
{"interfaceName":"interfaceName",
"correlator":"6789",
"endpoint":"/bayeux/domain-user/ts"
}
}
The End Notification operation terminates an application's previously set up notification to get the status of a specified terminal.
To stop a previously set up Status Notification, provide the correlator for the notification passed earlier in the Status Notification request.
There is no request or response body for the End Notification operation. If the request fails, the body of the error response will contain the identifier for the notification and the type of exception.
http://host:port/rest/terminal_status/notification/${correlator}
where:
host and port are the host name and port of the system on which Services Gatekeeper is installed.
correlator is the correlator for the notification provided in the reference object of the initial Status Notification operation request.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".