7 Parlay X 2.1 Terminal Location/MLP

This chapter describes the 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 communication service supports for the application-facing interfaces and the network protocols, see the appendix on standards and specifications in Concepts Guide.

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.

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.

Application Interfaces

For information about the SOAP-based interface for the Parlay X 2.1 Terminal Location/MLP communication service, see the discussion of Parlay X 2.1 Interfaces in Application Developer's Guide.

For information about the RESTful Audio Call interface, see the discussion of Terminal Location in RESTful Application Developer'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.

For general information, see Appendix A, "Events, Alarms, and Charging."

Event Data Records

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

Table 7-1 Event Types 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.

• When an error occurs.

Statistics

Table 7-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 7-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 Alarm 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 7-3.

Table 7-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=" com.wlcp.wlng.terminal_location.start_time" value="2008-09-26T16:15:00T+08:00" />
<param key=" com.wlcp.wlng.terminal_location. stop _time" value="2008-09-26T19:15:00T+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="com.wlcp.wlng.terminal_location.polygon.point.1" value="6.999:43.564" />
  <param key="com.wlcp.wlng.terminal_location.polygon.point.2" value="7.027:43.564" />
  <param key="com.wlcp.wlng.terminal_location.polygon.point.3" value="7.027:43.564" />
  <param key="com.wlcp.wlng.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 7-4 lists the technical specifications for the communication service.

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

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.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 "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.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 "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 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 attributes of the plug-in instance:

   • Attribute: CharacterEncoding

   • Attribute: CleanupInterval

   • Attribute: DecimalDegreesToDMSH

   • Attribute: MaxDuration

   • Attribute: MlpVersionSupported

   • Attribute: MlpLocationEstimates

   • Attribute: MlpPushAddr

   • Attribute: MlpRequestType

   • Attribute: MlpServerUrl

   • Attribute: MlpSrsName

   • Attribute: MlpVersionSupported

   • Attribute: MsidType

   • Attribute: Password

   • Attribute: Requestor

   • Attribute: RequestTimeout

   • Attribute: ServiceId

   • Attribute: Username

   • Attribute: XMLDoctypeTagUsage

4. Specify heartbeat behavior. See "Configuring Heartbeats" in System Administrator's Guide.

5. 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 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 the Accounts and SLAs Guide.

7. Provision the service provider accounts and application accounts. For information, see Accounts and SLAs Guide.

Reference: Attributes for Parlay X 2.1 Terminal Location/MLP

This section describes the attributes for configuration and maintenance:

• Attribute: CharacterEncoding

• Attribute: CleanupInterval

• Attribute: DecimalDegreesToDMSH

• Attribute: MaxDuration

• Attribute: MlpAltitudeSupported

• Attribute: MlpLocationEstimates

• Attribute: MlpPushAddr

• Attribute: MlpRequestType

• Attribute: MlpServerUrl

• Attribute: MlpSrsName

• Attribute: MlpVersionSupported

• Attribute: MsidType

• Attribute: Password

• Attribute: Requestor

• Attribute: RequestTimeout

• Attribute: ServiceId

• Attribute: Username

• Attribute: XMLDoctypeTagUsage

Attribute: CharacterEncoding

Scope: Cluster

Unit: Not applicable

Format: String

Indicates the type of Unicode character encoding accepted by the MLP node. The values are not case sensitive. A typical value is UTF-8.

Attribute: CleanupInterval

Scope: Cluster

Unit: Seconds

Format: Integer [0–3600]

Specifies the time interval at which periodic notification expiration checks are performed.

Attribute: DecimalDegreesToDMSH

Scope: Cluster

Unit: Not applicable

Format: Boolean.

Specifies if the coordinates provided by an application, in the form of decimal degrees, should be converted to Degrees Minutes Seconds Hemisphere (DMSH) format.

Enter:

• true to convert to DMSH

• false to use decimal degrees

Attribute: MaxDuration

Scope: Cluster

Unit: Seconds

Format: Integer

Specifies the maximum duration for a periodic location request.

Rejects startPeriodicNotification and startGeographicalNotification requests on the TerminalLocationNotificationManager interface if the duration is larger than this value.

If the duration is not provided in the request, this value is used.

Attribute: MlpAltitudeSupported

Scope: Cluster

Unit: Not applicable

Format: Boolean

Specifies if the MLP server supports altitude requests. When set to true, the <alt_acc> element is included in requests towards the MLP server.

Only applicable when the plug-in instance operates in MLP 3.2 mode. See "Attribute: MlpVersionSupported" for more information.

Attribute: MlpLocationEstimates

Scope: Cluster

Unit: Not applicable

Format: Boolean

Specifies if the MLP server is allowed to estimate locations. Use true if estimates are allowed, otherwise false.

Defines the value of the loc_estimates attribute in MLP.

Attribute: MlpVersionSupported

Scope: Cluster

Unit: Not applicable

Format: String

Specifies which version of MLP to use.

Valid values are:

• 3.0.0

• 3.2.0

Attribute: MlpPushAddr

Scope: Server

Unit: Not applicable

Format: URL

Specifies the callback URL to which the MLP server delivers location reports, periodic or triggered. This is the URL at which the plug-in instance listens for location reports. The format for the URL is:

http://ipaddressOfNTMachine:portOfWLS/tl-mlp/mlp_client

For example:

http://172.16.0.0:8001/tl-mlp/mlp_client

Attribute: MlpRequestType

Scope: Cluster

Unit: Not applicable

Format: String

Specifies which type of location request to use towards the MLP server.

Defines the DTD to be used for constructing the request towards the MLP server.

Valid values are:

• eme_lir for EME_LIR (Emergency location request)

• slir for SLIR (Standard location request)

Attribute: MlpServerUrl

Scope: Cluster

Unit: Not applicable

Format: URL

Specifies the MLP server's URL.

Attribute: MlpSrsName

Scope: Cluster

Unit: Not applicable

Format: String

Specifies requested MLP srsName attribute.

Normally, this is www.epsg.org#4326.

Attribute: MsidType

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the MSID type of the subscriber's Mobile Station ID (MSID).

Valid values are "MSISDN" and "MDN". The default is "MSISDN".

Attribute: Password

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the password used when Services Gatekeeper connects to the MLP server. The password is provided by the MLP server administrator.

Attribute: Requestor

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the requestor ID. If set to an empty string, the <requestorid> element will not be used in the MLP request. The requestor ID is provided by the MLP server administrator.

Attribute: RequestTimeout

Scope: Cluster

Unit: Seconds

Format: Integer [0–3600]

Specifies the HTTP time-out for MLP requests.

Attribute: ServiceId

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the Services Gatekeeper service ID. If set to an empty string, the <serviceid> element will not be used in the MLP request. The service ID is provided by the MLP server administrator.

Attribute: Username

Scope: Cluster

Unit: Not applicable

Format: String

Specifies the Services Gatekeeper user ID used for connecting to the MLP server. The user ID is provided by the MLP administrator.

Attribute: XMLDoctypeTagUsage

Scope: Cluster

Unit: Not applicable

Format: Boolean

Specifies if the XML tag !DOCTYPE should be included in requests towards the MLP node. Valid values are:

• true - include the tag

• false - do not include the tag