Skip Headers
Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide
Release 5.0

Part Number E16621-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

7 Terminal Status

This chapter describes the operations in the Terminal Status interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.

About the Terminal Status Interface

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.

REST Service Descriptions Available at Run-time

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 machine on which Services Gatekeeper is installed.


Get Status

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.

Authorization

Basic

HTTP Method

GET

URI

http://host:port/rest/terminal_status/status?query=${query}

where:

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

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

There is no request body.

Response Header

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

Response Body

The status of the specific terminal is returned in the body of the response as the value of the result attribute:

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"}

Examples

Example 7-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:10.182.100.218.8002

Example 7-2 Get Status 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":"Reachable"}

Get Status For Group

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

Authorization

Basic

HTTP Method

GET

URI

http://host:port/rest/terminal_status/status?queryForGroup=${query}

where:

For example,

GET /rest/terminal_status/status?queryForGroup="%7B%22address%22%3A%5B%22tel%3A123%22%2C%22tel%3A45622tel%3A789%22%5D%7D" HTTP/1.1

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

There is no request body.

Response Header

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

Response Body

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:

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"]
  }
}]}

Examples

Example 7-3 Get Status for Group Request

GET /rest/terminal_status/status?queryForGroup="%7B%22address%22%3A%5B%22tel%3A123%22%2C%22tel%3A45622tel%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:10.182.100.218.8002

Example 7-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"
          }]
}

Start Notification

The Start Notification operation starts requesting for notifications on the status of a specified terminal according to a specified frequency and for a specified limit of notifications over a specified time duration.

To set up for such notifications, provide the SIP-formatted URI of the terminal address for which the application must receive notifications, the criteria which will 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). 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 or not.

If the Start Notification request is successful, the endpoint address specified in the request body will receive a notification when:

Authorization

Basic

HTTP Method

PUT

URI

http://host:port/rest/terminal_status/status-notification

where host and port are the host name and port of the machine on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

The request body for the Start 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 parameters for the status check provided by the following:

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"
  }
}

Response Header

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 "Errors and Exceptions".

Response Body

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:

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:

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:

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"
}}

Examples

Example 7-5 Start 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:10.182.100.218.8002
Content-Length: 289
Content-Type: application/json

{
 "duration":null,
 "count":["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"
        }
}

Example 7-6 Start Notification Response

HTTP/1.1 200 OK
Date: Thu, 04 Nov 2101 09:59:05 GMT
Content-Length: 0
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
TerminalStatus: http://10.182.100.218:8002/rest/terminal_status/notifications
X-Powered-By: Servlet/2.5 JSP/2.1

End Notification

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 Start Notification, provide the correlator for the notification passed earlier in the Start 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.

Authorization

Basic

HTTP Method

DELETE

URI

http://host:port/rest/terminal_status/notification/${correlator}

where:

Request Body

There is no request body.

Response Header

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

Response Body

There is no response body.

Examples

Example 7-7 End Notification Request

DELETE /rest/terminal_status/status-notification/6789 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:10.182.100.218.8002

Example 7-8 End Notification Response

HTTP/1.1 204 No Content
Connection: close
Date: Thu, 04 Nov 2101 09:59:05 GMT
Content-Length: 0
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1