11 Parlay X 2.1 Terminal Location/MLP

This chapter describes the Oracle Communications Services Gatekeeper Parlay X 2.1 Terminal Location/Mobile Location Protocol (MLP) communication service in detail.

Overview of the Parlay X 2.1 Terminal Location/MLP Communication Service

The Parlay X 2.1 Terminal Location/MLP communication service exposes the Parlay X 2.1 Terminal Location application interfaces.

The communication service acts as an LCS -MLS client to a location server using MLP over HTTP.

For the exact version of the standards that the Parlay X 2.1 Terminal Location/MLP communication service supports for the application-facing interfaces and the network protocols, see Services Gatekeeper Statement of Compliance.

Services Gatekeeper connects to the location server using HTTP. It always acts as a single LCS/MLS client to the location server. It can be configured to act in Standard Location or Emergency Location Immediate mode on the node level.

Using the Terminal Location communication service, an application can:

  • Ask for the location of one or many terminals by polling.

  • Ask for the distance between a specified terminal and a specified position.

  • Sign up to be notified when a terminal enters or leaves a specified geographical area.

  • Receive notifications when the terminal enters or leaves the specified geographical area.

  • Sign up to be notified periodically about the location of a terminal.

  • Receive periodic location notifications about the location of a terminal.

Note:

By default this communication service supports the Point and EllipticalArea data shapes from the MLP specification. Contact your Oracle Support representative for information on using more of the MLP data shapes.

The application can specify a number of parameters concerning the nature of the notification. These include:

  • Requested accuracy

  • Accepted accuracy

  • Accepted response time

  • Maximum age of location data

  • Tolerance, which expresses the priority of response time versus accuracy

  • Minimum frequency of notifications

  • Duration of notifications

  • Maximum number of notifications

The nature of the information available as well as the accuracy of the location provided, the response times, and the frequency of notification are all dependent on the specifics of the protocol and network node used. Not all networks or protocols support all operations.

Processing Direct Queries/Application-initiated Requests

If an application directly queries Services Gatekeeper for the location of a terminal or group of terminals, Services Gatekeeper sends the request to the network node. The location information is sent back synchronously in the response to the request.

Processing Notifications/Network-triggered Requests

If an application registers for periodic or geographically-defined notifications, information for the application (which may or may not include the location data for one or more terminals) arrives at Services Gatekeeper from the network. The notification is passed on to the application. If the application acknowledges the reception of the notification, Services Gatekeeper acknowledges the reception of the notification to the network. If the application does not acknowledge the reception of the notification, Services Gatekeeper does not acknowledge the reception of the notification to the network.

Understanding Terminal Location Precision

See the discussion about understanding Parlay X 2.1 terminal location precision in Services Gatekeeper Application Developer's Guide for information on terminal location precision.

Application Interfaces

For information about the SOAP-based interface for the Parlay X 2.1 Terminal Location/MLP communication service, see the discussion about Parlay X 2.1 Part 9: Terminal Location interfaces in Services Gatekeeper Application Developer's Guide.

For information about the RESTful Audio Call interface, see the discussion of Terminal Location in Services Gatekeeper System Administrator's Guide.

The RESTful Service Short Messaging 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, reading CDRs, and so on, they are the same.

Events and Statistics

The Parlay X 2.1 Terminal Location/MLP communication service generates event data records (EDRs), charging data records (CDRs), alarms, and statistics to assist system administrators and developers in monitoring the service.

See "Events, Alarms, and Charging" for more information.

Event Data Records

Table 11-1 lists IDs of the EDRs created by the Parlay X 2.1 Terminal Location/MLP communication service.

Table 11-1 EDRs Generated by Parlay X 2.1 Terminal Location/MLP

EDR ID Method Called

9001

getLocation

9002

getTerminalDistance

9003

getLocationForGroup

9004

sendLocationRequest

9011

LocationEnd

9012

LocationError

9013

LocationNotification

Charging Data Records

Terminal Location/MLP - specific CDRs occur under the following conditions:

  • When the response to a polling request (of whatever type) is successfully delivered to the application.

  • When a notification is received from the network.

Statistics

Table 11-2 maps methods invoked from either the application or the network to the transaction types collected by the Services Gatekeeper statistics counters.

Method names for network-initiated requests are specified by the internal Services Gatekeeper name, which is not necessarily the same as the message from the network.

Table 11-2 Transaction Types for Parlay X 2.1 Terminal Location/MLP

Method Transaction type

getLocation

TRANSACTION_TYPE_USER_LOCATION

getLocationForGroup

TRANSACTION_TYPE_USER_LOCATION

getLocationDistance

TRANSACTION_TYPE_USER_LOCATION

locationNotification

TRANSACTION_TYPE_USER_LOCATION

Alarms

For the list of alarms, see Services Gatekeeper Alarms Handling Guide.

Tunneled Parameters for Parlay X 2.1 Terminal Location /MLP

This section lists the parameters that can be tunneled.

terminal_location.name_area

Description

Defines the MLP <name_area> element.

Complements the existing Parlay X 2.1 functionality for startGeographicalNotification with support for named areas. The startGeographicalNotification operation is defined in theTerminalLocationNotificationManager interface.

Valid for application-initiated requests only.

When this parameter key is used to define the area, the latitude, longitude, and radius parameters provided by an application are not used.

Can be set using parameter tunneling

Format

String

Example
<param key="terminal_location.name_area" value="Sausalito" />

com.wlcp.wlng.terminal_location.start_time / com.wlcp.wlng.terminal_location.stop_time

Description

Defines the <start_time> and <stop_time> MLP elements.

Complements the existing Parlay X 2.1 functionality for startGeographicalNotification with support for explicit start and stop times.

Valid for application-initiated requests only.

The utc_off attribute is used in both elements.

Format

String

The time is expressed in UTC format: yyyy-MM-ddThh:mm:ss[+|-]HH:MM using the definitions in Table 11-3.

Table 11-3 Format for terminal_location.start_time and stop_time Values

Element Meaning

yyyy

year

MM

month

dd

day

T

a constant

hh

hours

mm

minutes

ss

seconds

[+|-]

Positive or negative GMT offset. Use either + or -.

HH

GMT offset in hours

MM

GMT offset in minutes

Example
<param key="terminal_location.start_time" value="2008-09-26T16:15:00+08:00"/>
<param key="terminal_location.stop_time" value="2008-09-26T19:15:00+08:00"/>

terminal_location.polygon.point.n

Description

This parameter represents a set of keys in which the prefix is terminal_location.polygon.point. and the suffix n is a number in the range of 1–15.

Defines the MLP <x> and <y> elements within the <coord> element. The <coord> elements are contained by the <LinearRing>. The <LinearRing> element is contained by the <outerBoundaryIs> and <polygon> elements.

Can be set using parameter tunneling.

Format

Each terminal_location.polygon.point key value is expressed in the format x:y where:

  • x corresponds to the <x> element

  • y corresponds to the <y> element

x and y are expressed as decimal degrees.

Example
<xparams>
  <param key="terminal_location.polygon.point.1" value="6.999:43.564" />
  <param key="terminal_location.polygon.point.2" value="7.027:43.564" />
  <param key="terminal_location.polygon.point.3" value="7.027:43.564" />
  <param key="terminal_location.polygon.point.4" value="6.999:43.564" />
</xparams>

Managing Parlay X 2.1 Terminal Location/MLP

This section describes the properties and workflow for the Parlay X 2.1 Terminal Location/MLP plug-in instance.

Properties for Parlay X 2.1 Terminal Location/MLP

Table 11-4 lists the technical specifications for the communication service.

Table 11-4 Properties for Parlay X 2.1 Terminal Location/MLP

Property Description

Managed object in Administration Console

To access the managed object, select domain_name, then OCSG, then server_name, then Communication Services, then plugin_instance_id, in that order.

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.terminallocation.mlp.management.TerminalLocationMLPMBean

Network protocol plug-in service ID

Plugin_px21_terminal_location_mlp

Network protocol plug-in instance ID

The ID is 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.

Supported Address Scheme

tel

Application-facing interfaces

com.bea.wlcp.wlng.px21.plugin.TerminalLocationPlugin

com.bea.wlcp.wlng.px21.plugin.TerminalLocationNotificationManagerPlugin

com.bea.wlcp.wlng.px21.callback.TerminalLocationNotificationCallback

Service type

TerminalLocation

Exposes to the service communication layer a Java representation of:

Parlay X 2.1 Part 9: Terminal Location

Interfaces with the network nodes using:

MLP 3.0/3.2

Deployment artifact:

NT EAR

wlng_nt_terminal_location_px21.ear

Plugin_px21_terminal_location_mlp.jar, px21_terminal_location_service.jar, and terminal_location_mlp.war

Deployment artifact:

AT EAR: Normal

wlng_at_terminal_location_px21.ear

px21_terminal_location.war, px21_terminal_location_callback.jar and rest_terminal_location.war

Deployment artifact:

AT EAR: SOAP Only

wlng_at_terminal_location_px21_soap.ear

px21_terminal_location.war and px21_terminal_location_callback.jar

Configuration Workflow for Parlay X 2.1 Terminal Location/MLP

Following is an outline for configuring the plug-in using the Administration Console or an MBean browser.

  1. 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 Location/MLP"section.

  2. Using the Administration Console or an MBean browser, select the MBean for the plug-in instance. The MBean display name is the same as the plug-in instance ID given when the plug-in instance was created.

  3. Configure the fields of the TerminalLocationMLPMBean:

    • characterEncoding

    • cleanupInterval

    • decimalDegreesToDMSH

    • maxDuration

    • mlpVersionSupported

    • mlpLocationEstimates

    • mlpPushAddr

    • mlpRequestType

    • mlpServerUrl

    • mlpSrsName

    • mlpVersionSupported

    • msidType

    • password

    • requestor

    • requestTimeout

    • serviceId

    • username

    • xmlDoctypeTagUsage

  4. Specify heartbeat behavior. See the discussion on configuring heartbeats in Services Gatekeeper System Administrator's Guide.

  5. 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 Location/MLP"section.

  6. If required, create and load a node SLA. For details see defining global node and service provider group node SLAs and managing SLAs in Services Gatekeeper Portal Developer's Guide.

  7. Provision the service provider accounts and application accounts. For information, see Services Gatekeeper Portal Developer's Guide.

For a description of the attributes and operations of the TerminalLocationMLPMBean MBean, see the "All Classes" section of Services Gatekeeper OAM Java API Reference.