This chapter describes the Oracle Communications Services Gatekeeper Parlay X 2.1 Terminal Status/SIP communication service in detail.
The Parlay X 2.1 Terminal Status/SIP communication service exposes the Parlay X 2.1 Terminal Status set of application interfaces.
Note:
This communication service is preintegrated with the Oracle Communications Converged Application Server, Service Controller product, and you must purchase that product separately.This communication service uses the SIP protocol to connect to the Oracle Communications Converged Application Server (Converged Application Server), Service Controller product, using the IM-PSX GSM MAP interworking module. For details on configuring the IM-PSX GSM MAP module to work with this communication service, see ”Configuring IM-PSX GSM MAP” in Oracle Communications Service Broker Processing Domain Configuration Guide.
For the exact version of the standards that the Parlay X 2.1 Terminal Status/SIP communication service supports for the application-facing interfaces and the network protocols, see Services Gatekeeper Statement of Compliance.
Using the Parlay X 2.1 Terminal Status/SIP communication service, an application can:
Obtain the status (reachable, unreachable, or busy) of a single terminal or group of terminals as often as you specify, within a time period you specify.
Return the status of a terminal or group of terminals only if the status changes. The terminal statuses are checked as frequently as you specify, for a time period you specify.
This communication service receives requests from applications, opens a transaction, translates the requests into the SIP protocol, and queries the network. The network then returns the status to the plug-in, which passes the status back to the application inside the same transaction.
To receive current terminal statuses for multiple terminals in the same transaction, an application sends the addresses of the terminals to the communication service. The communication service then opens a transaction and sends a separate query to the network for each terminal address. The plug-in collects replies as they come in and returns them to the application inside a transaction.
To receive notification if a terminal status changes, an application sends the address of the terminal to the plug-in. The plug-in checks the status of the terminal periodically during the configured time period on a schedule defined by the frequency, duration, and count timer metrics to startNotification. For details on the timers scheduling see the Parlay X 2.1 Part 8 web site:
http://www.etsi.org/deliver/etsi_es/202300_202399/20239108/01.02.01_60/es_20239108v010201p.pdf
Also, see the discussion about the RESTful terminal status interface in Services Gatekeeper Application Developer's Guide for information on terminal status interface of the RESTful web service.
The Terminal Status/SIP plug-in accepts these parameters as input:
The terminal address or addresses.
The request frequency (number of seconds, minutes, or hours).
The total number of requests.
A true/false value for the checkImmediate parameter.
If checkImmediate=true the plug-in checks the status of the terminal or terminals immediately, and then thereafter as often as you specified. If checkImmediate=false the plug-in checks for status at the end of the first time period.
An application queries Services Gatekeeper for the status of a terminal by sending the terminal's address in a getStatus SOAP request. This communication service translates the request into a SIP SUBSCRIBE operation and forwards it to Converged Application Server, Service Controller. Converged Application Server, Service Conroller converts the SUBSCRIBE operation to an anyTimeInterrogationReq operation and passes it to the network node. The network node returns the status (reachable, unreachable, or busy) to Converged Application Sever, Service Controller. Converged Application Server, Service Controller then sends a SIP NOTIFY operation to this communication service, which then responds to the application with a getStatusResult SOAP message.
An application queries Services Gatekeeper for the status of a group of terminals by sending the terminal addresses in a getStatusForGroup SOAP operation. This communication service translates the request into a series of SIP SUBSCRIBE operations, one for each terminal, and forwards them to Converged Application Server, Service Controller. Converged Application Server, Service Controller then converts these messages to SIP NOTIFY operations and send them to this communication services. This communication service collects the results and returns them to the requesting application in a single getStatusResultForGroup message. Unreachable terminals are given a status of NotRetrieved.
Oracle recommends that you increase the default Transaction Timeout settings for both your Services Gatekeeper domain and deployment before you use the getStatusResultForGroup operation. You do this to avoid error messages such as: Value exceeds maximum column length (150) for column destination_party. To change the Transaction Timeout settings:
Domain:
Open the Administration Console
Navigate to Domain, then Services, then JTA.
Change the Timeout Seconds setting to 300 from 30.
Save your changes.
Deployment:
Open the Administration Console
Navigate to Deployments, then wlng_nt_terminal_status_px21(6.0.0.0), then TerminalStatus , then Configuration.
Change the Transaction Timeout setting to 300 from 0.
Save your changes.
An application sends a terminal status change request and timer metrics to this communication service using startNotification operation. The communication service creates a transaction and starts querying the Converged Application Server, Service Controller for the terminal status with SIP SUBSCRIBE as directed by the timer metrics. Converged Application Server, Service Controller then converts the SIP SUBSCRIBE operation into anyTimeInterrogationReq operation and forwards it to the network node. The network node returns the status (reachable, unreachable, or busy) to Converged Application Server, Service Controller. Converged Application Server, Service Controller then sends a SIP NOTIFY operation to this communication service.
If the terminal status changes during the time period, this communication service returns that information to the application using statusNotification message. If the status does not change during the time period, it sends a statusEnd message back to the application and closes the transaction. The application can also end the transaction itself by sending an endNotification message.
For information about the SOAP-based interface for the Parlay X 2.1 Terminal Status communication service, see the discussion about Parlay X 2.1 Part 8: Terminal Status Interfaces in Services Gatekeeper Application Developer's Guide.
For information about the RESTful Call Notification interface, see the discussion about RESTful Terminal Status in Services Gatekeeper Application Developer's Guide.
The Representational State Transfer (RESTful) Service Call Notification interfaces provide RESTful access to the same functionality as the SOAP-based interfaces. The internal representations are identical, and for the purposes of creating Service Level Agreements (SLAs) and reading charging data records (CDRs), and so on, they are the same.
The Parlay X 2.1 Terminal Status/SIP communication service generates Event Data Records (EDRs), CDRs, alarms, and statistics to assist system administrators and developers in monitoring the service.
See "Events, Alarms, and Charging" for more information.
Table 13-1 lists the IDs of the EDRs created by the Parlay X 2.1 Terminal Status/SIP communication service.
Table 13-1 EDRs Generated by Parlay X 2.1Terminal Status/SIP
| EDR ID | Method Called |
|---|---|
|
4000 |
getStatusForGroup |
|
4001 |
getStatus |
|
4002 |
startNotification |
|
4003 |
endNotification |
|
4015 |
statusNotification |
|
4016 |
statusError |
|
4017 |
statusEnd |
|
4018 |
getStatusForGroup (network) |
|
4019 |
getStatus (network) |
|
4020 |
startNotification (network) |
|
4021 |
endNotification (network) |
|
91631 |
getStatus/getStatusForGroup (application) |
|
91632 |
startNotification/endNotification (application) |
|
91633 |
statusNotification (application) |
|
91634 |
statusEnd (application) |
Terminal Status/SIP-specific CDRs are generated under the following conditions:
With the results of a getStatus or getStatusForGroup operation.
When statusNotification is called.
Table 13-2 maps methods invoked from either the application or the network to the transaction types collected by the Services Gatekeeper statistics counters
Table 13-2 Methods and Transaction Types for Parlay X 2.1 Terminal Status/SIP
| Method | Transaction Type |
|---|---|
|
getStatus |
TRANSACTION_TYPE_USER_STATUS |
|
getStatusForGroup |
TRANSACTION_TYPE_USER_STATUS |
|
startNotification |
TRANSACTION_TYPE_USER_STATUS |
|
endNotification |
TRANSACTION_TYPE_USER_STATUS |
|
statusNotification |
TRANSACTION_TYPE_USER_STATUS |
The following section list the Terminal Status/SIP errors.
Table 13-3 lists the application-facing service exceptions.
Table 13-3 Terminal Status/SIP Parlay X Exceptions
| Message ID | Description | Origin |
|---|---|---|
|
SVC0001 |
Service error |
All operations |
|
SVC0002 |
Invalid input value |
All operations |
|
SVC0004 |
No valid addresses |
getStatus, getStatusForGroup, startNotification |
|
SVC0005 |
Duplicate correlator |
startNotification |
|
SVC0006 |
Invalid group |
getStatusForGroup |
Table 13-4 lists the Terminal Status/SIP policy exceptions.
Table 13-4 Terminal Status/SIP Policy Exceptions
| Message ID | Description | Origin |
|---|---|---|
|
POL0001 |
Policy error |
All operations |
|
POL0002 |
Privacy error |
All operations |
|
POL0003 |
To many addresses |
getStatusForGroup, startNotification |
|
POL0004 |
Unlimited notifications not supported |
startNotification |
|
POL0005 |
Too many notifications requested |
startNotification |
|
POL0006 |
Groups not allowed |
getStatusForGroup |
|
POL0007 |
Nested groups not allowed |
getStatusForGroup |
|
POL0009 |
Invalid frequency requested |
startNotification |
|
POL0200 |
Busy criteria not supported |
startNotification |
Table 13-5 lists the Terminal Status/SIP internal error propagated to Parlay X SVC0001 messages.
Table 13-5 Terminal Status/SIP Internal Error Codes
| Error Code | Cause | Suggested Action |
|---|---|---|
|
TS-000001 |
The SIP fromAddress in the MBean is an invalid URI. |
Replace the value for fromAddress with a valid URI. |
|
TS-000002 |
The IM-PSX server address in the MBean is invalid. |
Replace the PsxServerAddress with a valid URI. |
|
TS-000003 |
The getStatusForGroup request violated the getGroupRequestTimeout attribute timer. |
Find out why the request is taking so long. Also make sure the getGroupRequestTimeout value is appropriate. |
|
TS-000004 |
Object initialization failed |
Check the instancemap configuration file. |
|
TS-000004 |
Failed to access storage. |
Check the status of storage service and Database. |
|
SIP-000001 |
Failed to send out SUBSCRIBE request. |
Check the Converged Application Server, Service Controller server. |
|
SIP-000002 |
Failed to receive NOTIFY from Converged Application Server, Service Controller server. |
Check the Converged Application Server, Service Controller server. |
|
SIP-000003 |
The NOTIFY status is Unknown. |
The HLR/VLR did not provide a status. |
|
SIP-000004 |
The application set the Expires header to a non-zero value. |
Check the SUBSCRIBE Expires header. |
|
SIP-000005 |
The application sets the value of the domain part in the requestURI which is different from the PsxSipDomain. |
Check the SUBSCRIBE request Request-URI header. |
|
SIP-000006 |
The application sets the value of the Accept header to a format which Service Broker does not support. |
Check the Accept header in the SUBSCRIBE request. |
|
SIP-000007 |
The application sets the Event header with an unsupported value |
Check the SUBSCRIBE request Event header. |
|
SIP-000008 |
An unexpected internal error has occurred in Converged Application Server, Service Controller server. |
Check the Converged Application Server, Service Controller server. |
|
SIP-000009 |
There's a mismatch between the Accept header value and the requested-info token value in Event. |
Check the Accept and Event header in the SUBSCRIBE request. |
|
SIP-000010 |
Interpret body in NOTIFY according to PIDF schema failed. |
Check whether the body in NOTIFY fulfills the PIDF xsd schema. |
|
MAP-000001 |
The HLR does not recognize the subscriber whose subscription information has been requested. |
Check the HLR status. |
|
MAP-000002 |
The HLR indicates that the data is missing from the MAP operation request. |
Check the HLR status. |
|
MAP-000003 |
The HLR found unexpected data in the MAP operation request. |
Check the HLR status. |
|
MAP-000004 |
There is a problem connecting to the HRL. |
Check the HLR status. |
|
MAP-000005 |
The HLR does not permit interrogation using the MAP-ANY_TIME-INTERROGATION operation |
Check the HLR status. |
|
MAP-000006 |
The HLR is not responding. |
Check the HLR status. |
This section lists, by parameter key, the parameters that can be tunneled or defined in the <requestContext> element of an SLA.
This section describes the properties and workflow for the Parlay X 2.1 Terminal Status plug-in instance.
The plug-in instance is not automatically created when the plug-in service is started.
Table 13-6 lists the technical specifications for this communication service.
Table 13-6 Properties for Parlay X 2.1 Terminal Status/SIP
| Property | Description |
|---|---|
|
Managed object in Administration Console |
To access the object, select domain_name, then OCSG, then server_name, then Communication Services, then plugin_instance_id, in that order. |
|
MBean |
Domain=com.bea.wlcp.wlngName=wlng_ntInstanceName=Plugin_px21_terminal_status_sipType=oracle.ocsg.plugin.terminal_status.sip.management.TerminalStatusMBean Documentation: See the "All Classes" section of Services Gatekeeper OAM Java API Reference |
|
Network protocol plug-in instance ID |
The ID assigned when the plug-in instance is created. See the discussion about configuring and managing the plug-in manager in Services Gatekeeper System Administrator's Guide. |
|
Network protocol plug-in service ID |
Plugin_px21_terminal_status_sip |
|
Supported Address Scheme |
tel |
|
Application-facing Interfaces |
com.bea.wlcp.wlng.px21.plugin.TerminalStatusPlugin com.bea.wlcp.wlng.px21.plugin.TerminalStatusNotificationManagerPlugin com.bea.wlcp.wlng.px21.callback.TerminalStatusNotificationCallback |
|
Service Type |
TerminalStatus |
|
Exposes to the service communication layer a Java representation of: |
Parlay X 2.1 Par 8: Terminal Status/SIP |
|
Interfaces with the network nodes using |
RFC 3265 |
|
Deployment artifacts: NT EARwlng_nt_terminal_status_px21.ear |
Plugin_px21_terminal_status_sip.jar px21_terminal_status_service.jar terminal_status_sip.war px21_terminal_status_callback_client.jar |
|
AT EAR: Normalwlng_at_terminal_status_px21.ear |
px21_terminal_status.war px21_terminal_status_callback.jar rest_terminal_status.war |
|
At EARP: SOAP Only wlng_at_terminal_status_px21_soap.earr |
px21_terminal_status.war px21_terminal_status_callback.jar |
Following is an outline for configuring the plug-in using the Administration Console or an MBean browser.
Create one or more instances of the plug-in service. See the discussion about configuring and managing the plug-in manager in Services Gatekeeper System Administrator's Guide. Use the plug-in service ID listed in the "Properties for Parlay X 2.1 Terminal Status/SIP".
Select the MBean for the plug-in instance. The MBean display name is the same as the plug-in instance ID assigned when the plug-in instance was created.
Configure the fields of the plug-in instance. See the TerminalStatusMBean:
SipNotifyTimeout
GroupRequestTimeout
GroupRequestInterval
PsxSipDomain
PsxServerAddress
FromAddress
ToParameters
Set up the routing rules to the plug-in instance. See the discussion about configuring and managing the plug-in manager in Services Gatekeeper System Administrator's Guide. Use the plug-in instance ID and address schemes listed in the "Properties for Parlay X 2.1 Terminal Status/SIP" section.
(Optional) Create and load a node SLA with Terminal Status usage restrictions. These usage restrictions are supported:
For details see the discussion about defining global node and service provider group node SLAs and managing SLAs in Services Gatekeeper Portal Developer's Guide.
For a description of the attributes and operations of TerminalStatusMbean, see Oracle Communication Services gatekeeper OAM Java API Reference.
This section lists SLA usage restrictions.
Data type: Boolean
Allowed values: True/False
Default Value: True
Attribute Name: oracle.ocsg.plugin.terminal_status.sip.policy.BusyAvailable
Description: Determines whether the Terminal Status/SIP plug-in treats a status of busy as a terminal status or terminal status change trigger.
Data type: Integer
Allowed values: 1~2147483647 (2^31-1)
Default Value: 2147483647
Attribute Name: oracle.ocsg.plugin.terminal_status.sip.policy.MaximumCount
Description: Specifies the maximum number of notifications that a single Terminal Status/SIP plug-in request can return. Cannot be used with "SLA Usage Restriction: UnlimitedCountAllowed".
Data type: Integer
Allowed values: 1~2147483647 (2^31-1)
Default Value: 2147483647
Attribute Name: oracle.ocsg.plugin.terminal_status.sip.policy.MaximumNotificationAddresses
Description: Specifies the maximum number of terminal addresses that a single Terminal Status/SIP plug-in request can contain.
Data type: Integer
Unit: Seconds
Allowed values: <TBA>
Default Value: 600
Attribute Name: oracle.ocsg.plugin.terminal_status.sip.policy.MaximumNotificationDuration
Description: Sets the maximum time limit that a Terminal Status/SIP plug-in request can last. Cannot be used with "SLA Usage Restriction: UnlimitedCountAllowed".
Data type: Integer
Unit: Seconds
Allowed values: 1~2147483647 (2^31-1)
Default Value: 2147483647
Attribute Name: oracle.ocsg.plugin.terminal_status.sip.policy.MaximumNotificationFrequency
Description: Sets the maximum number of seconds allowed between Terminal Status/SIP plug-in requests.
Data type: Boolean
Allowed values: True/False
Default Value: False
Attribute Name: oracle.ocsg.plugin.terminal_status.sip.policy.UnlimitedCountAllowed
Description: Directs the Terminal Server/SIP plug-in to allow an unlimited number of notifications for each request. If this attribute is set to true, neither "SLA Usage Restriction: MaximumNotificationDuration" nor "SLA Usage Restriction: MaximumCount" can be specified