| Oracle® Communications Services Gatekeeper Communication Service Guide Release 5.0 Part Number E21362-01 |
|
|
View PDF |
| Oracle® Communications Services Gatekeeper Communication Service Guide Release 5.0 Part Number E21362-01 |
|
|
View PDF |
This chapter describes the Parlay X 2.1 Terminal Status/Mobile Application Part (MAP) communication service in detail.
The Parlay X 2.1 Terminal Status/MAP communication service exposes the Parlay X 2.1 Terminal Status set of application interfaces.
The communication service uses the TietoEnator-SS7 stack to connect to an SS7 network. The communication service acts as an MAP application client for the SS7 network.
For the exact version of the standards that the communication service supports for the application-facing interfaces and the network protocols, see the appendix on standards and specifications in Concepts Guide.
Using the Parlay X 2.1 Terminal Status/MAP 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.
By default, the Parlay X 2.1 Terminal Status/MAP communication service directs the network to probe for the terminal status (network-triggered). You also have the choice of using the plug-in itself to do the probing (plug-in-triggered). Network-triggered is the default because it supports high-availability features and is generally more efficient. However if for some reason your network cannot support ATM operations, you can switch to plug-in-triggered.
The communication service receives requests from applications, opens a transaction, translates the requests into the SS7/MAP 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 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. See the Parlay X 2.1 Part 8 web site at:
http://docbox.etsi.org/TISPAN/Open/OSA/ParlayX21.html
or RESTful interface in the discussion of Terminal Status in the Restful Application Developer's Guide for details.
The Terminal Status/MAP plug-in takes 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 thereafter as often as you specified. If checkImmediate=false the plug-in checks for status at the end of the first time period.
By default the plug-in uses anyTimeModification to perform the network-triggered probe for a status change. If you change this to plug-in-triggered notification, the plug-in uses anyTimeInterrogation to probe for the status. If your network does not support anyTimeModification, use plug-in triggered notification.
The plug-in retains connection and identification information so it can query other nodes if the one it first contacts is unresponsive. This strategy also allows multiple applications to query the same terminal status. The plug-in confirms that all interested applications have ended their queries before ending the transaction.
If your network supports high-availability features, network-triggered probing can take advantage of them. The Parlay X 2.1 Terminal Status/MAP communication service can automatically query different network nodes if one is unresponsive and confirm that no other applications have an open status change query operation.
An application queries Services Gatekeeper for the status of a terminal by sending the terminal's address in a getStatus operation. The communication service translates the request into a SS7/MAP anyTimeInterrogation operation and passes it to the network node. The network node returns the status (reachable, unreachable, or busy) to the requesting application synchronously.
An application queries Services Gatekeeper for the status of a group of terminals by sending the terminal addresses in a getStatus operation. The communication service translates the request into an SS7/MAP anyTimeInterrogation operation and forwards it to the network node. The node returns the statuses for each terminal (reachable, unreachable, or busy) separately. The plug-in collects the results and returns them to the requesting application synchronously with a single message. Unreachable terminals are given a status of NotRetrieved.
As long as your network supports anyTimeModification (ATM) calls, use network-triggered poll status operations to direct your network to do the probing. The AllowATM attribute controls this choice. If AllowATM=true, the Terminal Server/MAP plug-in passes the startNotification terminal addresses and timer metrics through for your network to interpret.
If the terminal status changes during the time period, the network sends a NoteMMEvent call to the plug-in, which passes that information to the application using statusNotification and closes the transaction.
If the status does not change during the time period, the plug-in sends an endNotification back to the application and closes the transaction.
Requesting status for nested groups of terminals is not supported.
If your network cannot support ATM operations, you can set AllowATM=false and direct the plug-in to probe for terminal status changes. In this case, an application sends a terminal status change request and timer metrics to the Terminal Status/MAP plug-in using startNotification operation. The plug-in creates a transaction and starts querying the network for the terminal status with anyTimeInterrogation as directed by the timer metrics. If the terminal status changes during the time period, the communication service returns that information to the application using statusNotification and closes the transaction. 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.
Requesting status for nested groups of terminals is not supported.
This implementation creates a connection between the plug-in and a specific node. If that node crashes, the transaction never completes.
For information about the SOAP-based interface for the Parlay X 2.1 Terminal Status communication service, see the discussion of Parlay X 2.1 Interfaces in Application Developer's Guide.
For information about the RESTful Call Notification interface, see the discussion of Terminal Status in RESTful Application Developer's Guide.
The 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 SLAs and reading CDRs, and so on., they are the same.
The Parlay X 2.1 Terminal Status/MAP communication service generates Event Data Records (EDRs), Charging Data Records (CDRs), alarms, and statistics to assist system administrators and developers in monitoring the service.
For general information, see Appendix A, "Events, Alarms, and Charging."
Table 10-1 lists the IDs of the EDRs created by the Parlay X 2.1 Terminal Status/MAP communication service.
Terminal Status/MAP-specific CDRs are generated under the following conditions:
With the results of a getStatus or getStatusForGroup operation
When a notification is received from the network
If you requested a terminal status change notification, the terminal's present status is sent periodically.
Table 10-2 maps methods invoked from either the application or the network to the transaction types collected by the Services Gatekeeper statistics counters.
Table 10-2 Methods and Transaction Types for Parlay X 2.1 Terminal Status/MAP
| Method | Transaction type |
|---|---|
|
getStatus() |
TRANSACTION_TYPE_USER_STATUS |
|
getStatusForGroup() |
TRANSACTION_TYPE_USER_STATUS |
|
startNotification() |
TRANSACTION_TYPE_USER_STATUS |
|
endNotification() |
TRANSACTION_TYPE_USER_STATUS |
|
generate() |
TRANSACTION_TYPE_USER_STATUS |
|
statusNotification() |
TRANSACTION_TYPE_USER_STATUS |
|
statusError() |
TRANSACTION_TYPE_USER_STATUS |
|
statusEnd() |
TRANSACTION_TYPE_USER_STATUS |
This section describes the properties and workflow for the Parlay X 2.1 Terminal Status plug-in instance.
This plug-in service does not support multiple instantiation using the Plug-in Manager. You can create only one instance by using the Plug-in Manager. The plug-in instance is not automatically created when the plug-in service is started.
Table 10-3 lists the technical specifications for the communication service.
Table 10-3 Properties for Parlay X 2.1 Terminal Status/MAP
| Property | Description |
|---|---|
|
Managed object in Administration Console |
domain_name > OCSG > server_name > Communication Services > plugin_instance_id |
|
MBean |
Domain=com.bea.wlcp.wlng Name=wlng_nt InstanceName=same as the network protocol instance_id assigned when the plug-in instance is created Type=com.bea.wlcp.wlng.plugin.ts.map.management.MapTsMBean |
|
Network protocol plug-in service ID |
Plugin_px21_terminal_status_map |
|
Network protocol plug-in instance ID |
The ID assigned when the plug-in instance is created. See "Managing and Configuring the Plug-in Manager" in System Administrator's Guide. |
|
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 Part 8: Terminal Status/MAP |
|
Interfaces with the network nodes using: |
3GPP TS 29.002 V4.18.0 (2007-09) |
|
Deployment artifacts: NT EAR wlng_nt_terminal_status_px21.ear |
px21_terminal_status.war, px21_terminal_status_callback.jar, and rest_terminal_location.war |
|
AT EAR: Normal wlng_at_terminal_status_px21.ear |
px21_terminal_status.war, px21_terminal_status_callback.jar, and rest_terminal_location.war |
|
AT EAR: SOAP Only wlng_at_terminal_status_px21.ear |
px21_terminal_status.war and 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 "Managing and Configuring the Plug-in Manager" in System Administrator's Guide. Use the plug-in service ID listed in the "Properties for Parlay X 2.1 Terminal Status/MAP" section.
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 attributes of the plug-in instance:
Specify heartbeat behavior. See "Configuring Heartbeats" in System Administrator's Guide.
Set up the routing rules to the plug-in instance. See "Managing and Configuring the Plug-in Manager" in System Administrator's Guide. Use the plug-in instance ID and address schemes listed in the "Properties for Parlay X 2.1 Terminal Status/MAP" section.
Set up at least one network selection and one network selection route to direct Terminal Server Status requests to the correct SSN using "Operation: addNetworkSelection" and "Operation: addNetworkSelectionRoute" operations. See "Setting Up Network Selection Routes and Network Selections" for more information.
(Optional) Create and load a node SLA with Terminal Status usage restrictions. These usage restrictions are supported:
For details see “Defining Global Node and Service Provider Group Node SLAs” and “Managing SLAs” in the Accounts and SLAs Guide.
The Parlay X 2.1 Terminal Status/MAP plug-in matches each terminal status request with the correct SSN (HLR) node using network selections and network selection routes. You create these network selections and network selection routes using these operations:
Figure 10-1 illustrates how the plug-in routes terminal status requests with the correct SSN.
The addNetworkSelectionRoute operation offers the option of associating one or more regular expressions, or the string default, with each of your service providers. When a request arrives, the plug-in attempts to match the address against all network service route regular expressions. If it finds a match, it then the passes the request to the network service with the matching network selection ID. The network service then matches the network selection ID with an SSN and passes the terminal status request to that SSN. If the network service route could not match the address with a regular expression, it passes the request to the default network selection ID if one is defined.
The plug-in does not do any overlap testing of the regular expressions you create in network service routes.
The addNetworkSelection operation specifies an SSN to use for a terminal status request for a network selection ID. It also specifies details about the type and format of the request.
At least one network selection and network selection route must be defined for the plug-in to function. Typically you set up at least one pair per service provider.
After network selections and network selection routes are set up, manage them with these operations:
This section describes the attributes, operations, and SLA usage restrictions for configuration and maintenance:
Scope: Cluster
Unit: Not applicable
Format: Boolean
Determines whether the StatusNotification interface uses AnyTimeModification (instead of the default AnyTimeInterrogation) to set up the terminal status notification. The default value is true.
Scope: Cluster
Unit: Milliseconds
Format: Integer
The timeout period used by each AnyTimeInterrogation call. The default value is 5000.
Scope: Cluster
Unit: Not applicable
Format: String
The CommonParts user ID that you map to a CommonParts User ID instance in the SS7 stack configuration file. The default value is USER01.
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies a time limit for the getStatusForGroup and startNotification (with AnyTimeInterrogation) interfaces. If all addresses are not processed within this time period, the Terminal Status/MAP plug-in aborts the query process, reports any retrieved terminal statuses, and marks the rest as NotRetrieved. The default value is 30.
Scope: Local
Unit: Not applicable
Format: Integer
The local global title, used in originating addresses.
Scope: Cluster
Unit: Number of JCP queue messages
Format: Integer
Sets the JCP (TE stack attribute) message queue size. This queue stores the most recent MAP primitive messages in the JCP attribute of the TE stack, which the JTCAP provider then retrieves. A large queue size allows you to store more messages which helps ensure that none are abandoned before the JTCP provider can retrieve them. A large queue size is useful during high workload periods, but it also requires more memory. The default value is 90.
Scope: Local
Unit: Not applicable
Format: Integer [0–16383] or [0–16777215], depending on the standard used.
The SS7 network address for the plug-in instance (the local SCCP Signaling Point Code (SPC) served by the local SS7 stack). The Terminal Status/MAP plug-in uses this as the originating SPC.
You must correlate this value with the property SCCP Local SSN in the SS7 stack back-end configuration file.
Scope: Local
Unit: Not applicable
Format: Integer [2–254]
The local SCCP Sub System Number to bind to this plug-in instance.
You must correlate this value with the property SCCP Local SSN in the SS7 stack back-end configuration file.
Scope: Local
Unit: Not applicable
Format: Integer
Total number of Terminal Status plug-in instances that use the Attribute: LocalSsn. The default value is 1.
Scope: Local
Unit: Not applicable
Format: Integer
Must be 0 or less than the value for Attribute: NoOfPluginInstances. Used to create a unique dialogue reference for every plug-in instance using a different LocalSsn. The SS7 stack uses this unique reference to identify the correct Terminal Status/MAP plug-in to reply to. The default value is 0.
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies the SS7 port number for the Terminal Status/MAP plug-in instance to use. The default value is 7001.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the SS7 host IP address for the Terminal Status/MAP plug-in instance to use. The default value is 127.0.0.1.
Scope: Cluster
Unit: Not applicable
Format: String
The SS7 BackEnd for the Terminal Status/MAP plug-in instance to use, encoded as a comma-separated byte array, for example, 1, 2, 3. Set this value to 0 if you only use one active BackEnd. The default value is 0.
Scope: Local
Adds a network selection.
Maps a service provider to an SSN (that presumably has terminal status information). This operation associates a network section ID with a specific SSN, and includes terminal status format details.
The values specified in this operation depend on the SSN configuration and the MAP message's target node. Network selection determines how MAP messages are encoded for a specific address, for example whether it uses GT+SSN or SPC+SSN. Network selection also specifies how ApplicationContext and DialogueAS appear in the ATI message. NetworkSelectionRoutes is then used to determine which network selection to use for a specific address.
This operation throws an exception if any parameter values are outside of their valid ranges, or if there is a problem adding the configuration to the database.
See Setting Up Network Selection Routes and Network Selections for more information.
Signature:
addNetworkSelection(NetworkSelectionId: String, MAPVersion: String, MAPApplicationContext: String, MAPApplicationHandlingContext: String, MAPApplicationReportingContext: String, MAPDialogueAS: String, SSN: Integer, DPC: Integer, GTI: Integer, TT: Integer, Na: Integer, Np: Integer)
Table 10-4 addNetworkSelection Parameters
| Parameter | Data Type | Description |
|---|---|---|
|
NetworkSelectionId |
String |
Identifies each service provider this operation is creating a network selection for. Used by addNetworkSelectionRoute to map a terminal addresses with a service provider. This operation then specifies an SSN to query for the address. To avoid confusion, use a separate string than the Services Gatekeeper service provider ID. |
|
MAPVersion |
String |
Identifies the MAP version that the PDU uses. Currently only 3GPP TS 29.002 V4.18.0 (2007-09) is supported. |
|
MAPApplicationContext |
String |
The application context name to use, encoded as a comma separated byte array, for example: 4, 0, 0, 1, 0, 29, 3. Where:
|
|
MAPApplicatonHandlingContext |
String |
Application context name of ATM message to use, encoded as a comma separated byte array, for example: 4, 0, 0, 1, 0, 43, 3 Where: 4 ccitt/identified-organization 0 etsi 0 mobileDomain 1 gsm-Network 0 map-ac 43 anyTimeInfoHandling 3 version3 |
|
MAPApplicationReportingContext |
String |
Application context name of ATM message to use, encoded as a comma separated byte array, for example: 4, 0, 0, 1, 0, 42, 3 Where:
|
|
MAPDialogueAS |
String |
The object identifier to use for Where: 4: ccitt/identified-organization 0: etsi 0: mobileDomain 1: gsm-Network 1: as-Id 1: map-DialoguePDU 1: version1 |
|
SSN |
Integer |
The destination SSN. |
|
DPC |
Integer |
(Optional) The destination SPC. A value of -1 directs this operation to use GT+SSN instead of SPC+SSN in the destination address. |
|
GTI |
Integer |
The global title indicator. Controls how the SCCP address for both called and calling addresses is built. Suitable values would be something like (international E.164 number): GTI=4 TT=1 NP=1 NA=4. Can be one of these values: 0: GT included 1: GT includes nature of address indicator only 2: GT includes translation type only 3: GT includes translation type, numbering plan, and encoding scheme 4: GT includes translation type, numbering plan, encoding scheme, and nature of address indication |
|
TT |
Integer |
The translation type that directs the message to the appropriate GT translation function. Must be in the range 0-254. |
|
Na |
Integer |
Nature of Address indicator (GSMSCF-Address). Can be one of: 0: unknown 1: international number 2: national significant number 3: network specific number 4: subscriber number 5: reserved 6: abbreviated number 7: reserved for extension |
|
Np |
Integer |
Address Numbering Plan indicator (GSMSCF-Address). Can be one of: 0: unknown 1: ISDN/Telephony Numbering Plan (Rec ITU-T E.164) 2: spare 3: data numbering plan (ITU-T Rec X.121) 4: telex numbering plan (ITU-T Rec F.69) 5: spare 6: land mobile numbering plan (ITU-T Rec E.212) 7: spare 8: national numbering plan 9: private numbering plan 15: reserved for extension |
Scope: Local
Maps a terminal address with a service provider ID. The plug-in uses the service provider ID to determine the SSN to probe for terminal status information.
Each network selection route needs to be associated with a network selection (using addNetworkSelection) that maps a service provider with the SSN with terminal status information. The plug-in is only active if at least one NetworkSelectionRoute / NetworkSelection pair is configured.
Note:
The network selection ID string and your Services Gateway service provider ID identify the same service providers, but these are used for different purposes. To avoid confusion use different values for these strings.When the terminal status request enters the plug-in, its MSISDN address(es) are matched against the regular expressions of the network selection routes. If a match is found, the request is sent to the SSN specified by the network selection. If the network selection route uses the default expression, all requests are sent to the default SSN.
Wildcards are allowed in the regular expression. For example, the value ^46730.* matches all MSISDN addresses that start with 46730. However this plug-in does not check for wildcard overlapping.
An exception is thrown if no corresponding network selection exists for the network selection route, if another route already exists for the service provider ID, or if there is a problem adding the route to the database.
See Setting Up Network Selection Routes and Network Selections for more information.
Signature:
addNetworkSelectionRoute(NetworkSelectionId: String, Expression: String)
Table 10-5 addNetworkSelectionRoute Parameters
| Parameter | Data Type | Description |
|---|---|---|
|
NetworkSelectionId |
String |
Identifies each service provider this operation is creating a network selection route for. To avoid confusion, use a different string than the Services Gatekeeper service provider ID. |
|
Expression |
String |
[ default | There is no overlap control for the regular expressions. |
Scope: Local
Binds the Terminal Server/MAP plug-in to the SS7 stack. This operation is required if the configuration has changed. If bindToStack is successful, the Terminal Status/MAP plug-in not yet connected; it has only started to connect and bind to the stack. Use the Bound parameter to confirm whether the stack is actually bound. This is operation is performed implicitly at startup, but must be manually invoked if any connection attributes were changed.
Signature:
bindToStack()
Scope: Local
Retrieves the configured values for a specific network selection and the network selection route it maps to.
Signature:
getNetworkSelection(NetworkSelectionId: String)
Scope: Local
Retrieves the network selection route and the network selections it maps to.
Signature:
getNetworkSelectionRoute(Expression: String)
Table 10-7 getNetworkSelectionRoute Parameters
| Parameter | Data Type | Description |
|---|---|---|
|
Expression |
String |
A unique regular expression to match against the target MSISDN address, or the string DEFAULT (use the default route if no match exists). For example ^46730.*, Note that there is no overlap control for the regular expressions. |
Scope: Local
List all the configured NetworkSelectionRoutes and the NetworkSelection IDs each is mapped to.
Signature:
listAllNetworkSelectionRoutes()
Scope: Local
Lists all network selection routes mapped to a specific network selection.
Signature:
listNetworkSelectionRoutes(NetworkSelectionId: String)
Scope: Local
Lists all network selections, their configured values, and their corresponding network selection routes.
Signature:
listNetworkSelections()
Scope: Local
Removes a network selection. Returns the removed network selection or null if it cannot be removed.
Signature:
removeNetworkSelection(NetworkSelectionId: String)
Scope: Local
Removes the specified network selection route. Returns the removed network selection, or null if the network selection could not be removed.
Signature:
removeNetworkSelectionRoute(NetworkSelectionId: String)
Scope: Local
Explicitly removes notifications from the database. After a server crash old (inactive) notifications are removed implicitly.
Signature:
removeNotifications(IncludeActiveNotifications: Boolean)
Determines whether the Terminal Status/MAP plug-in treats a status of busy as a terminal status or terminal status change trigger.
Data type: Boolean
Allowed values: true and false
Default Value: true
Attribute name:
oracle.ocsg.plugin.terminal_status.map.policy.BusyAvailable
Specifies the maximum number of terminal addresses that a single Terminal Status/MAP plug-in request can contain.
Data type: Integer
Allowed Values: 1 ~ 2147483647 (2^31-1)
Default Value: 2147483647
Attribute name:
oracle.ocsg.plugin.terminal_status.map.policy.MaximumNotificationAddresses
Sets the maximum number of seconds allowed between Terminal Status/MAP plug-in requests.
Data type: Integer (represents seconds)
Allowed Values: 1~2147483647 (2^31-1)
Default Value: 2147483647
Attribute name:
oracle.ocsg.plugin.terminal_status.map.policy.MaximumNotificationFrequency
Sets the maximum time limit that a Terminal Status/MAP plug-in request can last. Cannot be used with SLA Usage Restriction: UnlimitedCountAllowed.
Data type: Integer (represents seconds)
Default Value: 600
Attribute name:
oracle.ocsg.plugin.terminal_status.map.policy.MaximumNotificationDuration
Specifies the maximum number of notifications that a single Terminal Status/MAP 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.map.policy.MaximumCount
Directs the Terminal Server/MAP 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 should also be specified.
Data type: Boolean
Allowed Values: true and false
Default Value: false
Attribute name:
oracle.ocsg.plugin.terminal_status.map.policy.UnlimitedCountAllowed
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
