This chapter describes the operations in the Terminal Location interface of the RESTful facade provided in Oracle Communications Services Gatekeeper.
Applications use the RESTful Terminal Location interface to get a location for an individual terminal or a group of terminals; to get the distance of the terminal from a specific location; and to start and stop notifications, based on geographic location or on a periodic interval.
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_location/index.html
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The Get Location operation retrieves the location of a single terminal. The interface will return an error if the query object contains more than one address.
To retrieve the location of a specific terminal, provide its URI as the address value of the query object in the Request-URI of the GET method.
If the Get Location operation is successful, the response body contains a nested JSON data object containing the physical coordinates of each terminal and the date and time for when such data was last collected.
http://host:port/rest/terminal_location/location?${query}
where:
host and port are the host name and port of the system on which Services Gatekeeper is installed.
${query} is a nested JSON data object.
The parameters accepted by query are:
acceptableAccuracy: Integer. Required. The range that the application considers useful. If the location cannot be determined within this range, the application would prefer not to receive this information.
address: String. Required. The address of the terminal whose location is required, as a URI.
requestedAccuracy: Integer. Required. The range over which the application wants to receive location information. This may influence the choice of location technology to use (for instance, cell sector location may be suitable for requests specifying 1000 meters, but GPS technology may be required for requests below 100 meters).
tolerance: String. Required. Enumerated value denoting the priority of response time versus accuracy. Table 13-1 lists the possible values:
Table 13-1 Enumeration Values for Tolerance Attribute
| Value | Description |
|---|---|
|
NoDelay |
The server should immediately return any location estimate that it currently has. If no estimate is available, the server returns a failure indication. The server may optionally initiate procedures to obtain a location estimate (for example, to be available for a later request). |
|
LowDelay |
The response time is more important than the requested accuracy. The server attempts to fulfil any accuracy requirement, but not if it adds delay. A quick response with lower accuracy is more desirable than waiting for a more accurate response. |
|
DelayTolerant |
The network is expected to return a location with the requested accuracy even if this means not complying with the requested response time. |
maximumAge: JSON object. Optional. The maximum acceptable age of the location information. This object is defined by the following:
metric: String. The unit of time. Required if the maximumAge object is present in the body of the query. Possible entries are Millisecond, Second, Minute, Hour, Day, Week, Month or Year.
units: Integer. Required if the maximumAge object is present in the body of the query. The number of units for the metric.
responseTime: JSON object. Optional. The maximum response time that the application will accept. This object is defined by the following:
metric: String. The unit of time. Required if the responseTime object is present in the body of the query. Possible entries are Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required if the maximumAge object is present in the body of the query. The number of units for the metric.
The maximum duration and interval is 8916039 seconds, which converts to 99 days, 99 hours, 99 minutes, and 99 seconds. Do not enter a value that exceeds the 8916039 second interval. In other words, do not use the Year time metric, and only about three Months is allowed.
The ${query} object in the URI is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"acceptableAccuracy": "Integer",
"address": "URI",
"requestedAccuracy": "Integer",
"tolerance": "NoDelay|LowDelay|DelayTolerant",
"maximumAge": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
},
"responseTime": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
}
}
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 location of the specific terminal is returned in the body of the response as the value of the result JSON object. The parameters in this object are:
accuracy: Integer.
latitude: Number (floating point).
longitude: Number (floating point).
timestamp: String. The date and time when the terminal's geographical coordinates were collected, given in ISO 8601 extended format, yyyy-mm-ddThh-mm-ss.
altitude: Number (floating point).
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": {
"accuracy": "Integer",
"latitude": "Float",
"longitude": "Float",
"timestamp": "Calendar",
"altitude": "Float"
}}
Example 13-3 Get Location Request
GET /rest/terminal_location/location?query=%7B%22aceptableAccuracy%22%3A%22100%%22%2C%22address%22%3 A%22tel%3A1234%22%2C%22requestAccuracy%22%3A%22100%%22%2C %22tolerance%22%3A%22NoDelay%22%2C%22maximumAge%22%3Anull%2C%22responseTime%22%3 Anull%7D HTTP/1.1 X-Session-ID: app:5198750923966743997 Authorization: Basic ZG9tYWluX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host:servgtkpr_host.port
Example 13-4 Get Location Response
HTTP/1.1 200 OK
Date: Thu, 05 Nov 2101 05:52:41 GMT
Content-Length: 131
Content-Type: application/json
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1
{
"result":
{
"accuracy":"10",
"latitude":"37.78843",
"longitude":"-122.4374",
"timestamp":"2010-11-05T21:56:21+08:00"
}
}
The Get Location for Group operation retrieves the location information for a group of terminals.
To retrieve the location information 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 Location for Group operation is successful, the response body contains a JSON data object indicating the physical location for each terminal (whether or not the specific terminal is reachable, unreachable or busy).
http://host:port/rest/terminal_location/location?queryForGroup=${queryForGroup}
where:
host and port are the host name and port of the system on which Services Gatekeeper is installed.
${queryForGroup} is a nested JSON data object.
The parameters accepted by queryForGroup are:
acceptableAccuracy: Integer. Required. The range that the application considers useful. If the location cannot be determined within this range, the application would prefer not to receive this information.
addresses: Array of Strings. Required. The addresses of the terminals whose location is required, as URIs.
requestedAccuracy: Integer. Required. The range over which the application wishes to receive location information. This may influence the choice of location technology to use (for instance, cell sector location may be suitable for requests specifying 1000 meters, but GPS technology may be required for requests below 100 meters).
tolerance: String. Required. Enumerated value denoting the priority of response time versus accuracy. Table 13-2 lists the possible values:
Table 13-2 Enumeration Values for Tolerance Attribute
| Value | Description |
|---|---|
|
NoDelay |
The server should immediately return any location estimate that it currently has. If no estimate is available, the server return a failure indication. The server may optionally initiate procedures to obtain a location estimate (for example, to be available for a later request). |
|
LowDelay |
The response time is more important than the requested accuracy. The server attempts to fulfil any accuracy requirement, but not if it adds delay. A quick response with lower accuracy is more desirable than waiting for a more accurate response. |
|
DelayTolerant |
The network is expected to return a location with the requested accuracy even if this means not complying with the requested response time. |
maximumAge: JSON object. Optional. The maximum acceptable age of the location information. This object is defined by the following:
metric: String. The unit of time. Required if the maximumAge object is present in the body of the query. Possible entries are Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required if the maximumAge object is present in the body of the query. The number of units for the metric.
responseTime: JSON object. Optional. The maximum response time that the application will accept. This object is defined by the following:
metric: String. The unit of time. Required if the responseTime object is present in the body of the query. Possible entries are Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required if the maximumAge object is present in the body of the query. The number of units for the metric.
The ${queryForGroup} object in the URI is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"acceptableAccuracy": "Integer",
"addresses": ["URI"],
"requestedAccuracy": "Integer",
"tolerance": "NoDelay|LowDelay|DelayTolerant",
"maximumAge": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
},
"responseTime": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
}
}
Example 13-5 Request URI for Get Location for Group
GET /rest/terminal_location/location?queryForGroup=%7B%22aceptableAccuracy%22%3A%22100%%22%2C%22 addresses%22%3A%%5B22tel%3A1234%22%2C%22tel%3A123%22%5D%2C%22requestAccuracy%22 %3A%22100%%22%2C%22tolerance%22%3A%22NoDelay%22%2C%22maximumAge%22%3Anull%2C%22 responseTime%22%3Anull%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 is the attribute result whose value consists of an array of JSON objects. Each element in the array contain the report status, the location information (if any) and the error information (if any) for the terminals whose addresses were specified in the Request-URI for status?queryForGroup.
The following parameters make up the information associated with an individual terminal's location:
address: String. The address of a terminal whose location is required, as a URI.
reportStatus: String. The status of the terminal. It can be one of the following:
Retrieved: The terminal's location information is available. It is provided in this object as the current location of the terminal.
Not Retrieved: The terminal's location information is not available.
Error: There was an error in the attempt to get the location information for this terminal. The error data is provided in this object.
currentLocation: String. This parameter will be present if the value for reportStatus is Retrieved. The current location of the terminal as one of the following:
accuracy: Integer.
latitude: Number (floating point).
longitude: Number (floating point).
altitude: Number (floating point).
timestamp: String. The date and time when the terminal's geographical coordinates were collected, in ISO 8601 extended format, yyyy-mm-ddThh-mm-ss.
errorInformation: 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. Variables to substitute into text strings.
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",
"currentLocation": {
"accuracy": "Integer",
"latitude": "Float",
"longitude": "Float",
"timestamp": "Calendar",
"altitude": "Float"
},
"errorInformation": {
"messageId": "String",
"text": "String",
"variables": ["String"]
}
}]}
Example 13-6 Get Location for Group Request
GET /rest/terminal_location/location?queryForGroup=%7B%22aceptableAccuracy%22%3A%22100%%22%2C%22 addresses%22%3A%%5B22tel%3A1234%22%2C%22tel%3A123%22%5D%2C%22requestAccuracy%22 %3A%22100%%22%2C%22tolerance%22%3A%22NoDelay%22%2C%22maximumAge%22%3Anull%2C%22 responseTime%22%3Anull%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 13-7 Get Location for Group Response
HTTP/1.1 200 OK
Date: Thu, 04 Nov 2101 08:12:43 GMT
Content-Length: 438
Content-Type: application/json
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1
{"result":
[{"address":"tel:1234",
"errorInformation":null,
"reportStatus":"Retrieved",
"currentLocation":
{
"accuracy":"10",
"latitude":"37.78843",
"longitude":"-122.4374",
"altitude":"0.0"
"timestamp":"2010-11-05T22:13:28+08:00"
},
{"address":"tel:123",
"errorInformation":null,
"reportStatus":"Retrieved",
"currentLocation":
{
"accuracy":"10",
"latitude":"55.2776",
"longitude":"7.012778",
"altitude":"20.0"
"timestamp":"2010-11-05T22:13:28+08:00"
}
}
The Get Terminal Distance operation retrieves the distance between a specified terminal and a required location. The terminal distance is calculated in meters.
To retrieve the distance, provide the URI for the terminal and the geographic coordinates of the required location in the Request-URI of the GET method.
If the Get Terminal Distance operation is successful, the response body contains a JSON data object indicating the distance between a specified terminal and a required location, in meters.
http://host:port/rest/terminal_distance/distance?query=${query}
where:
host and port are the host name and port of the system on which Services Gatekeeper is installed.
${query} is a nested JSON data object.
The parameters accepted by the query attribute are:
address: String. Required. The address of the terminal, as a URI.
latitude: Number (floating point). Required. The latitude of the location.
longitude: Number (floating point). Required. The longitude of the location
The ${query} object in the URI is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"address": "URI",
"latitude": "Float",
"longitude": "Float"
}
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 distance between the specified terminal and the required location is returned as the value for result in a data object. The unit for the distance is meters and the value is an integer.
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 13-8 Get Terminal DIstance Request
GET /rest/terminal_distance/distance?query=%7B%22address%22%3A%22tel%3A1234%22%2C%22longitude%22 %3A%2237.7707%%22%2C %22latittude%22%3A%22122.4177%227D HTTP/1.1 X-Session-ID: app:5198750923966743997 Authorization: Basic ZG9tYWluX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host:servgtkpr_host.port
The Start Geographical Notification operation provides notifications based on whether terminals enter or leave a specified geographic area. The area to be monitored is circular with specified latitude and longitude as the center and having a specified radius.
To set up for such notifications, provide the SIP-formatted URI of the terminal addresses for which the application must receive notifications, the criteria which will trigger notifications and a reference object for the delivery of the notifications. Additionally, you can specify the request frequency, the total number of notifications and the duration for the notification and whether or not the check must start immediately or not. 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 for the Start Geographical Notification operation is successful, the endpoint address specified in the request body will receive a notification when:
The terminal location has been successfully retrieved.
The notification limit or the specified duration has been reached.
An error has been encountered in obtaining the location of the terminal.
http://host:port/rest/terminal_location/geographical-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 Start Geographical Notification operation is a nested JSON object. It accepts an array of addresses for the terminals in whose geographical information the application is interested, and the parameters for the check:
addresses: Array of string values. Required. Each element in the array is a SIP-formatted address for a terminal, as a URI.
checkImmediate: String. Required. Set to:
True: The application requires the geographical notification to start immediately and as often as required thereafter.
False: The application requires the geographical notification to start at the end of the time period.
count: Integer. Optional. The maximum number of notifications sent to the application. If this number is reached while notification operation is active a locationEnd notification is delivered to the endpoint address. If you omit this option, or set it to 0 there is no limit to the number of notifications.
criteria: String. Required. The status of the terminal. It can be one of the following:
Entering: The notification should be made when the terminal enters the area being monitored.
Leaving: The notification should be made when the terminal leaves the area being monitored.
duration: JSON object. Optional. Specifies a time limit for notifications. The maximum duration period can be limited by the underlying network. Omit this option, or set it to 0 to specify no time limit.
metric: String. Required. The unit of time for the duration specified as Millisecond, Second, Minute, Hour, Day, Week, Month or Year.
units: Integer. Required. The number of metric units that specify the duration. If this number is reached (and the application has not ended the notification operation), the locationEnd notification is delivered to the endpoint address.
frequency: JSON object. Required. Specifies the time between notifications. The value must be in the range of 1-8916039 seconds, which converts to 99 days, 99 hours, 99 minutes, and 99 seconds. Do not enter a value that exceeds the 8916039 second interval. In other words, do not use the Year time metric, and only about three Months is allowed.
metric: String. Required. The unit of time for the notification frequency. Can be specified in Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required. The number of metric units between notifications.
For example this entry:
metric=second unik=10
specifies a minimum time between notifications of 10 seconds. However this entry:
metric=month unit=6
is invalid because it exceeds the 8916039 second (99 day) limit.
latitude: Number (floating point). Required. The latitude of the location which will be the center of the area under surveillance.
longitude: Number (floating point). Required. The longitude of the location which will be the center of the area under surveillance.
radius: Number (floating point) in meters. Required. The radius of the circle around the location (center point), in meters.
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 managing application instances, see Services Gatekeeper Portal Developer's Guide.
interfaceName: String. Required. A descriptive string to identify the type of notification.
trackingAccuracy: Number (floating point). Required. The acceptable error in the tracking, in meters.
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": "Entering|Leaving",
"frequency": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
},
"latitude": "Float",
"longitude": "Float",
"radius": "Float",
"reference": {
"correlator": "String",
"endpoint": "URI",
"interfaceName": "String"
},
"trackingAccuracy": "Float",
"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_location/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 When Terminal Location is Successfully Retrieved (locationNotification)
When there is a match for the criteria value (specified in the request body) and the terminal's location is successfully retrieved, 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 locationNotification:
correlator: String. The correlator used to identify the notification and provided in the request body of the Start Geographical Notification operation.
criteria: String. The state of the terminal. It can be one of the following:
Entering: The terminal entered the area being monitored.
Leaving: The terminal left the area being monitored.
data: Array of JSON objects. Each element in the array contains the current location information of a terminal being monitored and contains the following parameters:
address: String. The URI of the terminal being monitored.
reportStatus: String. Retrieval status for this terminal which can be Retrieved, NotRetrieved, or Error. This allows for partial reports to avoid timeouts, and so on.
currentLocation: String. This object will be present only if the reportStatus is Retrieved. It contains the location information for the terminal, as of the date and time specified in this object. Table 13-3 lists the attributes in this object:
Table 13-3 Attributes in the currentLocation JSON Object
| Attribute | Description |
|---|---|
|
accuracy |
Number (floating point). The accuracy error in arriving at the terminal's location, in meters. |
|
latitude |
Number (floating point). The latitude for the terminal. |
|
longitude |
Number (floating point). The longitude for the terminal. |
|
timestamp |
String. The date and time when the terminal's geographical coordinates were collected, given in ISO 9601's extended format. |
|
altitude |
Number (floating point). The altitude for the terminal. |
errorInformation: JSON object. This object will be present if the value for reportStatus is Error. Table 13-4 lists the attributes in this object.
Table 13-4 Attributes in the errorInformation Object
| Attribute | Description |
|---|---|
|
messageID |
String. Message identifier for the fault |
|
text |
String. The text of the message. If this string contains replacement variables, the variables entry hold the |
|
variables |
Array of string values. Optional. An array of variables to substitute into text strings. |
The location notification data object delivered to the endpoint address is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"locationNotification": {
"correlator": "String",
"data": [{
"address": "URI",
"reportStatus": "Retrieved|NotRetrieved|Error",
"currentLocation": {
"accuracy": "Integer",
"latitude": "Float",
"longitude": "Float",
"timestamp": "Calendar",
"altitude": "Float"
},
"errorInformation": {
"messageId": "String",
"text": "String",
"variables": ["String"]
}
}],
"criteria": "Entering|Leaving"
}}
Example 13-10 locationNotification Object Delivered to the Application
{
"locationNotification":
{
"correlator":"6789",
"data":
[{
"address":"tel:123",
"reportStatus":"Retrieved",
"errorInformation":null,
"currentLocation":
{
"accuracy":"8",
"latitude":"37.80",
"longitude":"-122.56",
"altitude":"90",
"timestamp":"2010-11-08T10:29:38"
}
}],
"criteria":"Entering"
}
}
Notification of Error in Retrieving Terminal Location (locationError)
When there is an error in retrieving the location for the specified terminal, Services Gatekeeper sends a nested JSON data object to the endpoint address.
The nested JSON object contains the following as the value of the attribute name locationError:
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 string values. The array of variables to substitute into text strings.
address: String. The URI of a terminal to monitor.
The location error notification data object delivered to the endpoint address is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"locationError": {
"correlator": "String",
"reason": {
"messageId": "String",
"text": "String",
"variables": ["String"]
},
"address": "URI"
}}
Notification Signalling End to Monitoring Terminal's Location (locationEnd)
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.
The JSON object contains the following as the value of the attribute name locationEnd:
correlator: String. The correlator used to identify the notification and provided in the request body of the Status Notification operation.
Here is the structure of this notification:
{"locationEnd": {"correlator": "String"}}
Note:
This notification is not delivered in the case of an error, or if the application ended the notification using endNotification.Example 13-11 Start Geographic Notification Request
PUT /rest/terminal_location/geographical-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: 366 Content-Type: application/json
{
"addresses":["tel:123"],
"checkImmediate:"true",
"criteria":"Entering",
"frequency":
{
"metric": "Second",
"units": "5"
},
"latitude":"37.7707",
"longitude":"-122.4177",
"radius":"5000.0",
"reference":
{
"correlator":"6789",
"endpoint":"bayeux/app_instance_1/tl",
"interfaceName":"interfaceName"
},
"trackingAccuracy":"10.0",
"count":"5",
"duration":
{
"metric":"Minutes",
"units":"30"
}
}
The Start Periodic Notification operation provides notifications for the locations of a set of terminals at a defined interval.
To set up for such location notifications, provide the SIP-formatted URI of the terminal addresses for which the application must receive notifications, the request frequency, the total number of notifications and the duration for the notification and whether or not the check must start immediately. 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 for the Start Periodic Notification operation is successful, the endpoint address specified in the request body will receive a notification when:
The terminal location has been successfully retrieved.
The notification limit or the specified duration has been reached.
An error has been encountered in obtaining the location of the terminal.
http://host:port/rest/terminal_location/periodic-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 Start Periodic Notification operation is a nested JSON object. It contains an array of addresses for the terminals in whose information the application is interested, and the parameters for the check provided by the following:
addresses: Array of string values. Required. Each element in the array is a SIP-formatted address for a terminal, as a URI.
duration: JSON object. Optional. Specifies the total time for receiving notifications The underlying network sometimes limits this count. Omit this setting or set it to 0 to specify no limit.
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 number of metric units that specify the duration. If this number is reached while this operation is still active, the locationEnd notification is delivered to the endpoint address.
frequency: JSON object. Required. Specifies a minimum time between notifications:
metric: String. Required. The unit of time for the frequency specified as Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required. The frequency of the specified metric.
metric: String. Required. The unit of time for the frequency specified as Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required. The frequency of the specified metric.
This value must be in the range of 1-8916039 seconds, which converts to 99 days, 99 hours, 99 minutes, and 99 seconds. Do not enter a value that exceeds the 8916039 second interval. In other words, do not use the Year time metric, and only about three Months is allowed.
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 identifies 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.
requestedAccuracy: Number (floating point). Required. The acceptable error in the tracking, in meters.
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"],
"frequency": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
},
"reference": {
"correlator": "String",
"endpoint": "URI",
"interfaceName": "String"
},
"requestedAccuracy": "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_location/notifications
If the request fails, the Status-Line header field will contain the status code and the reason for the failure.
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.
Example 13-13 Start Periodic Notification Request
PUT /rest/terminal_location/periodic-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: 366 Content-Type: application/json
{
"addresses":["tel:123"],
"frequency":
{
"metric": "Second",
"units": "5"
},
"reference":
{
"correlator":"6789",
"endpoint":"bayeux/app_instance_1/tl",
"interfaceName":"interfaceName"
},
"requestedAccuracy":"10.0",
"duration":
{
"metric":"Minutes",
"units":"30"
}
}
Notification When Terminal Location is Successfully Retrieved (locationNotification)
See "Notification When Terminal Location is Successfully Retrieved (locationNotification)".
Notification of Error in Retrieving Terminal Location (locationError)
See "Notification of Error in Retrieving Terminal Location (locationError)".
Notification Signalling End to Monitoring Terminal (locationEnd)
See "Notification Signalling End to Monitoring Terminal's Location (locationEnd)".
The End Notification operation terminates an application's previously set up notification to get the geographical and periodic information for a specified terminal.
To stop a previously set up Start Geographical Notification or Start Periodic Notification, provide the correlator for the notification passed earlier in the appropriate start 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_location/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 request for the Start Geographical Notification or Start Periodic Notification operation.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure.