| 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 Call Notification interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.
Applications use the RESTful Call Notification interface to set up and remove call notifications which inform the application about the particular state of a call (such as busy, unreachable, and so on).
Additionally, applications use this interface to set up and remove call direction notifications (which require the application to provide further directions on handling a call that is in a particular state).
For such operations, the application client subscribes to and uses the Bayeux channel to which Services Gatekeeper is subscribed. The application provides the Bayeux channel name as the location for Services Gatekeeper to publish the notifications that the application client requires. See "Notifications and Publish/Subscribe".
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/call_notification/index.html
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The details of a call event about which the application receives information are identical whether the called party was busy Busy, not reachable NotReachable, did not answer NoAnswer, and a call was being attempted CalledNumber.
These details are provided to the application in a JSON object which contains the following parameters:
calledParty. String. Required. The address (URI) of the party to whom the call is made.
callingParty. String. Required. The address (URI) of the party making the call.
correlator. String. Required. The correlator used to identify the notification and provided in the Start Call Notification request.
callingPartyName. String. Optional. The name of the party making the call.
These details are specified in the following structure:
{
"calledParty": "URI",
"callingParty": "URI",
"correlator": "String",
"callingPartyName": "String"
}}
You will find this object in the following operations:
Start Call Notification: This object is used to provide the call details in the notifications sent (by Services Gatekeeper) to the application following a successful Start Call Notification Request. See "Notification Data Object Delivered to Bayeux Channel Name"
Start Call Direction Notification: This object is used to provide the call details in the notifications sent (by Services Gatekeeper) to the application to request instructions (from the application) on handling a call event that has occurred. See "Notification Data Object Requesting Instruction from Application"
The Start Call Notification operation sets up call notifications to a specified endpoint address for call events associated with the addresses specified in the request.
To set up a call notification, provide the SIP-formatted URI of the addresses for which the application must receive notifications, the criteria that will trigger notifications, and a reference object for the delivery of the notifications. The criteria can be one or more of four possible call events (Busy, NotReachable, NoAnswer, and CalledNumber). If you do not specify any value for criteria, each of the four call events will trigger a notification.
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).
If the Start Call Notification request is successful:
The response header will contain the URI of the publish/subscribe server.
Notification data objects appropriate to the call event will be sent to the endpoint address specified in the request body. Each data object will contain the appropriate notification on the call.
When the application receives such a response, it must access the endpoint address to retrieve the specific call event notifications.
Basic
PUT
http://host:port/rest/call_notification/call_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 Start Call Notification accepts the following parameters:
addresses. Array of string values. Required. The set of addresses to be monitored, provided as a list of URIs separated by commas.
criteria. String. Optional. The call event for which the notification is required.
If you do not specify any value for criteria, all of the four call events will trigger a notification. The four call events are:
Busy: This entry indicates that the called party is busy.
CalledNumber: This entry indicates that a call between the two parties is being attempted.
NoAnswer: This entry indicates that the called party does not answer.
NotReachable: This entry indicates that the called party is not reachable.
reference. A JSON object. Required. Use this object to provide the following information about the endpoint address that is to receive the notification:
correlator. String. Required. The correlator used to identify the call notifications for the specified addresses.
endpoint. String. Required. 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. Optional. A descriptive string to identify the notification.
The request body for this operation is represented by the following JSON structure, where the value part of each name/value pair indicates its data type:
{
"addresses": ["String"],
"reference": {
"correlator": "String",
"endpoint": "URI",
"interfaceName": "String"
},
"criteria": ["Busy|NotReachable|NoAnswer|CalledNumber"]
}
The Location header field contains the URI of the publish/subscribe server as:
http://host:port/rest/call_notification/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".
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 Data Object Delivered to Bayeux Channel Name
Services Gatekeeper delivers the appropriate notification for each of the following call events:
Busy: When the called party is busy, the notification is sent as the value for notifyBusy represented by the following JSON structure:
{"notifyBusy": {
"calledParty": "URI",
"callingParty": "URI",
"correlator": "String",
"callingPartyName": "String"
}}
NotReachable: When the called party is not reachable, the notification is sent as the value for notifyNotReachable represented by the following JSON structure:
{"notifyNotReachable": {
"calledParty": "URI",
"callingParty": "URI",
"correlator": "String",
"callingPartyName": "String"
}}
NoAnswer: When the called party does not answer, the notification is sent as the value for notifyNoAnswer represented by the following JSON structure:
{"notifyNoAnswer": {
"calledParty": "URI",
"callingParty": "URI",
"correlator": "String",
"callingPartyName": "String"
}}
CalledNumber: When the called party call is being attempted, the notification is sent as the value for notifyCalledNumber represented by the following JSON structure:
{"notifyCalledNumber": {
"calledParty": "URI",
"callingParty": "URI",
"correlator": "String",
"callingPartyName": "String"
}}
The Stop Call Notification operation generates a request that terminates a previously set up call notification.
To stop a previously set up call notification, use the appropriate correlator in the DELETE method for this operation. This correlater should have been specified earlier in the request body of the Start Call Notification operation.
There is no request or response body for the Stop Call 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/call_notification/call_notification/${correlator}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
${correlator} is the correlator for the notification provided in the reference object of the initial Start Call Notification request.
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 Call Direction Notification operation initiates notifications to a specified endpoint for call events associated with the addresses specified in the request. The notifications provided by Services Gatekeeper will contain the information necessary for the application to provide instructions on directing the call.
To set up a call direction notification, provide the SIP-formatted URI of the addresses for which the application must receive notifications, the criteria that will trigger notifications, and a reference object for the delivery of the notifications. The criteria can be one more of four possible call events (Busy, NotReachable, NoAnswer, and CalledNumber. If you do not specify any value for criteria, each of the four call events will trigger a notification.
The reference object (also a JSON object) contains the correlator for the notification, the endpoint address (a specific Bayeux channel name) to which the call direction notifications must be sent and, optionally, the interface name (a string to identify the notification).
If the Start Call Direction Notification request is successful:
The response header will contain the URI of the publish/subscribe server.
A notification data object appropriate to the call event will be sent to the endpoint address specified in the request body. This data object will contain the appropriate notification on the call. It will also contain the reply-to private channel address to be used by the application to provide further instructions on handling and routing the call.
When it receives such a response, the application:
Retrieves the notification data object from the endpoint address. See "Notification Data Object Requesting Instruction from Application".
Sets up a data object with instructions on how the call must be handled (and charged); and an address to which the call must now be routed. See "Call-Handling Instructions".
Publishes this data object to the reply-to private channel address it received. See "Application's Call-Handling Response to Services Gatekeeper".
Basic
PUT
http://host:port/rest/call_notification/call_direction
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 Call Direction Notification accepts the following parameters:
addresses. Array of string values. Required. The set of addresses to be monitored, provided as a list of SIP-formatted URIs separated by commas.
criteria. String. Optional. The call event for which the notification is required.
If you do not specify any value for criteria, all of the four call events will trigger a notification. The four call events are:
Busy: This entry indicates that the called party is busy.
CalledNumber: This entry indicates that a call between the two parties is being attempted.
NoAnswer: This entry indicates that the called party does not answer.
NotReachable: This entry indicates that the called party is not reachable.
reference: a JSON object. Required. Use this object to provide the following information about the call direction notification:
correlator. String. Required. The correlator used to identify the call direction notification for the specified addresses.
endpoint. String. Required. The URI which represents the endpoint address to which the call direction 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. Optional. A descriptive string to identify the notification.
The request body for this operation is represented by the following JSON structure, where the value part of each name/value pair indicates its data type:
{
"addresses": ["String"],
"reference": {
"correlator": "String",
"endpoint": "URI",
"interfaceName": "String"
},
"criteria": ["Busy|NotReachable|NoAnswer|CalledNumber"]
}
The Location header in the response displays the URI of the publish/subscribe server:
http://host:port/rest/call_notification/notifications
The application must access this location to retrieve the notification or delivery status information about the request.
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 endpoint address holds the appropriate notification data object containing information on the type of call event when there is a match for the criteria value specified in the request body of this operation.
Notification Data Object Requesting Instruction from Application
When the application needs to take further action on a call event, Services Gatekeeper provides the application with a corresponding notification data object for the application to act upon.
It places this notification data object at the endpoint address mentioned above. The notification data object is a nested JSON object containing the following parameters:
reply-to. String. The Bayeux channel address to which the application must deliver its instructions for handling the call. This is a private Bayeux channel set up by Services Gatekeeper.
data. Nested JSON object. Services Gatekeeper provides the appropriate call details as the value for handleBusy, handleNotReachable, handleNoAnswer, handleCalled Number named for the four types of call events. These details have been described under "Common Data".
handleBusy: For a Busy call event, Services Gatekeeper provides the appropriate call details as the value for the attribute handleBusy in the following JSON structure:
{"handleBusy": {
"calledParty": "URI",
"callingParty": "URI",
"correlator": "String",
"callingPartyName": "String"
}}
handleNotReachable: For a NotReachable call event, Services Gatekeeper provides the appropriate call details as the value for the attribute handleNotReachable in the following JSON structure:
{"handleNotReachable": {
"calledParty": "URI",
"callingParty": "URI",
"correlator": "String",
"callingPartyName": "String"
}}
handleNoAnswer: For a NoAnswer call event, Services Gatekeeper provides the appropriate call details as the value for the attribute handleNoAnswer in the following JSON structure:
{"handleNoAnswer": {
"calledParty": "URI",
"callingParty": "URI",
"correlator": "String",
"callingPartyName": "String"
}}
handleCalledNumber: For a CalledNumber call event, Services Gatekeeper provides the appropriate call details as the value for the attribute handleCalledNumber in the following JSON structure:
{"handleCalledNumber": {
"calledParty": "URI",
"callingParty": "URI",
"correlator": "String",
"callingPartyName": "String"
}}
Whether the call event is Busy, NotReachable, NoAnswer or CalledNumber, the application needs to specify the following:
actionToPerform. String. Required. Specifies the required action to take on the call. Table 4-1 lists the actions that Services Gatekeeper must perform with respect to the call:
charging. a JSON object. Optional. This object defines the cost charging properties for the call. A call with no charging parameters is entered as "charging":null. If a charge is to be applied, values for the following in the charging object:
description. String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
amount. Number (integer, or decimal). Optional. The amount to be charged.
code. String. Optional. The charging code, from an existing contractual description.
currency. String. Optional. The currency identifier as defined in ISO 4217 [9].
routingAddress. String. URI. The address to which the call must be routed.
Application's Call-Handling Response to Services Gatekeeper
The application sends the appropriate instruction (described in the previous section) as the response to the reply-to address it had retrieved earlier from the endpoint address. See "Notification Data Object Requesting Instruction from Application".
The possible responses that the application provides to Services Gatekeeper are:
Instructions to handle a Busy call event: The application provides the instruction data as the value for handleBusyResponse in the following JSON structure:
{"handleBusyResponse": {"result": {
"actionToPerform": "Route|Continue|EndCall",
"charging": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
},
"routingAddress": "URI"
}}}
Instructions to handle a NotReachable event: The application provides the instruction data as the value for handleNotReachableResponse in the following JSON structure:
{"handleNotReachableResponse": {"result": {
"actionToPerform": "Route|Continue|EndCall",
"charging": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
},
"routingAddress": "URI"
}}}
Instructions to handle a NoAnswer event: The application provides the instruction data as the value for handleNoAnswerResponse in the following JSON structure:
{"handleNoAnswerResponse": {"result": {
"actionToPerform": "Route|Continue|EndCall",
"charging": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
},
"routingAddress": "URI"
}}}
Instructions to handle a CalledNumber event: The application provides the instruction data as the value for handleCalledNumberResponse call event in the following JSON structure:
{"handleCalledNumberResponse": {"result": {
"actionToPerform": "Route|Continue|EndCall",
"charging": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
},
"routingAddress": "URI"
}}}
The Stop Call Direction Notification operation terminates a previously set up call direction notification.
To stop a previously set-up call direction notification, use the appropriate correlator in the DELETE request for this operation. This correlater should have been specified earlier in the request body of the Start Call Direction Notification operation.
There is no request or response body for the Stop Call Direction 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/call_notification/call_direction/${correlator}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
${correlator} is the correlator for the notification provided in the reference object of the initial Start Call Direction Notification request.
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.
|
 Copyright © 2007, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|