Building MAP-Based Applications¶

Mobile Application Part (MAP), a 3GPP standard (TS 29.002), is the signaling protocol used to provide an application layer for various nodes in gsmSCF and UMTS mobile core networks.

XTML MAP Data Types¶

The SCE provides XTML data types that are strongly-typed objects, which differ from other XTML data types because they have a well-defined set of properties.

The SCE JavaScript Editor window displays these properties, as shown in the following image.

Strongly-typed objects make it easier to work with complex, well-structured sets of data that are commonly used across many applications. Application maintenance is easier when using these strongly-typed objects because all developers are storing and accessing information in similar, well-understood patterns.

The following XTML strongly-typed objects represent all the information related to these specific MAP messages that are either sent or received by the application server.

SendRoutingInfo
SendRoutingInfoRes
MapError

Many of the PACs listed under MAP on the Actions tab in the workspace pane operate on these data types or return one of these objects as a result of their action. Grouping all the information associated with the object makes it easier for an application to construct and manage MAP messages.

The optional parameters that are available for each object are defined by 3GPP in the Mobile Application Part (MAP) specification (Release 12).

Send_Routing_Info Properties¶

Property	Description
Cug_CheckInfo	Structured type containing the cug-Interlock and cug-OutgoingAccess values, as well as an extensionContainer.
NumberOfForwarding	Number of times the incoming call has already been forwarded. Will be present only if it was received in the IAM.
Or_Interrogation	Indicates that the interrogation is from a GMSC not in the same PLMN as the HLR.
Or_Capability	Indicates the phase of OR that the GMSC supports. Will be present only if the GMSC supports OR.
CallReferenceNumber	May be used by the gsmSCF for inclusion in a network optional gsmSCF call record. It must be coupled with the identity of the MSC which allocated it in order to define unambiguously the identity of the call. For MO calls, the call reference number is set by the serving VMSC and included in the MO call record. For MT calls, the call reference number is set by the GMSC and included in the RCF call record in the GMSC and in the MT call record in the terminating MSC. For VT calls, the call reference number is set by the GMSC and included in the RCF call record in the GMSC and in the MT call record in the terminating MSC. For CF calls, the call reference number is set by the GMSC and included in the CF record in the forwarding MSC.
ForwardingReason	Indicates why the call has been forwarded. Will be present only if the HLR has determined that the call is to be forwarded.
BasicServiceGroup	Basic service group which applies for this call. Will be present only if the interrogation type is forwarding.
NetworkSignalingInfo	Transported as external signal information.
CamelInfo	Contains the supportedCamelPhases, suppress-T-CSI, extensionContainer, and offeredCamel4CSIs values.
SuppressionOfAnnouncments	Indicates that announcements or tones generated as a result of unsuccessful call establishment should be suppressed. Will be present only if the HLR received it in the Send Routing Info IF.
ExtensionContainer	Contains PrivateExtensionList and PCS-Extensions values.
AlteringPattern	Will be present only if received in a Connect operation from the gsmSCF.
Ccbs_Call	Indicates if the call uses CCBS.
SupportedCCBS_Phase	A 7-bit integer, with only a single valid value of 1.
AdditionalSignalingInfo	An Ext-ExternalSignalInfo type, which has ext-ProtocolId, SignalInfo, and extensionContainer values.
IstSupportIndicator	Indicates if the call is basicISTSupported or istCommandSupported.
Pre_pagingSupported	Indicates whether the gsmSCF supports pre-paging.
CallDiversionTreatmentIndicator	A single octet string, described by TS 29.002 as follows: callDiversionAllowed (xxxx xx01) callDiversionNotAllowed (xxxx xx10) network default is call diversion allowed
LongFTN_Supported	Indicates whether the mobile subscriber supports Long Forwarded-to Numbers.
Suppress_VT_CSI	Indicates that VT-CSI should be suppressed for the called party. Will be present only if the HLR received it in the Send Routing Info IF.
SuppressIncomingCallBarring	Indicates that Incoming Call Barring should be suppressed for the called party.
Gsmscf_InitiatedCall	Indicates if the call was gsmSCF-initiated.
BasicServiceGroup2	Basic service group which applies for the less preferred service of the call.
NetworkSignalingInfo	An ExternalSignalInfo type, which has protocolId, SignalInfo, and extensionContainer values.
SuppressMTSS	Indicates that MTSS should be suppressed for the called party.
MtRoamingRetrySupported	Indicates whether the gsmSCF supports MT Roaming Retry.
CallPriority	Indicates the eMLPP priority of the call (see 3GPP TS 24.067 [137]). Will be present only if the HLR supports it and if the Call Priority was received in the MAP_SEND_ROUTING_INFORMATION request.

Send_Routing_Info_Resp Properties¶

Property	Description
RoamingNumber	E.164 address required to route the call to the VMSC of the B party. Will be present in the Send Routing Info ack, sent in response to a Send Routing Info with interrogation type of basic, only if the HLR has determined that the charging requirements for optimal routing are not contravened and that the call should not be forwarded.
ForwardingData	Used to instruct the GMSC how to forward the call. Contains forwardToNumber, forwardToSubaddress, forwardingOptions, extensionContainer, and longForwardToNumber.
CamelRoutingInfo	Used to instruct the GMSC to perform CAMEL processing for the call. Contains ForwardingData, gmscCamelSubscriptionInfo, and extensionContainer.
Cug_CheckInfo	Structured type containing the cug-Interlock and cug-OutgoingAccess values, as well as an extensionContainer.
CugSubscriptionFlag	Will be present only if CUG is supported.
SubscriberInfo	Contains locationInformation, subscriberState, extensionContainer, locationInformationGPRS, ps-SubscriberState, imei, and other information about the subscriber.
Ss_List	List of SS-codes for the more preferred service of a SCUDIF call.
BasicService	Indicates the type of the basic service for the more preferred service.
ForwardingInterrogationReq	Indicates that if the VMSC of the forwarding subscriber requests the GMSC to resume handling of the call, the GMSC should interrogate the HLR for forwarding information.
Vmsc_Address	E.164 address of the VMSC in whose area the B subscriber is currently registered. Will be present in the Send Routing Info ack only if the OR interrogation indicator in the Send Routing Info was present, the HLR supports optimal routing of basic mobile-to-mobile calls, and the HLR has determined that the call should not be forwarded.
ExtensionContainer	Carries extensions which are defined outside this specification. Private extensions can be defined by, for example, network operators, manufacturers, and regional standardization bodies.
Naea_PreferredCI	A list of the preferred carrier identity codes that are subscribed to. When the VLR receives this parameter from the HLR, it should replace the previously stored preferred carrier identity codes with the received ones.
Ccbs_Indicators	Indicates whether a CCBS request can be made for the call.
Msisdn	MSISDN of the subscriber.
NumberPortablilityStatus	Indicates the number portability status of subscriber.
1stAlertTimer	If included in the IST Alert response, includes the new IST Alert timer value that must be used to inform the HLR about the call activities that the subscriber performs.
SupportedCamelPhasesInVMSC	Indicates which phases of CAMEL are supported in VMSC.
OfferedCamel4CSIsInVMSC	Indicates CAMEL14 CSI in VMSC actions are supported.
RoutingInfo2	Indicates the routing information for the less preferred service.
Ss_List2	List of SS-codes for the less preferred service of a SCUDIF call.
BasicService2	Indicates the type of the basic service for the less preferred service.
AllowedServices	Indicates which services are available for an SCUDIF call.
UnavailibilityCause	Indicates the reason a service of a SCUDIF call is not available.
ReleaseResourcesSupported	Indicates whether the MAP_RELEASE_RESOURCES service is supported at the VMSC. Will be present if so indicated by the VMSC with MAP_PROVIDE_ROAMING_NUMBER confirm.
Gsm_BearerCapability	Specific information defining the lower layer characteristics required within the network.

XTML MAP Events¶

XTML MAP events are listed on the Events tab in the workspace pane.

These MAP events are triggered when the corresponding messages are received by the SIGTRAN agent:

SendRoutingInfo
SendRoutingInfoResponse

XTML MAP PACs¶

The function of each MAP PAC is to create and send the specific message with the same name. For example, the Send_Routing_Info PAC sends a Send_Routing_Info message.

This section defines the unique tabs included in the Properties window and the standard results available for each PAC listed under MAP on the Actions tab in the workspace pane.

For more information about the common Description tab and Custom tab, see Build Functions and Custom Results.

Send_Routing_Info¶

The Send_Routing_Info PAC creates and sends a Send_Routing_Info message.

Properties¶

The Send_Routing_Info PAC includes the General and Optional tabs.

General¶

*General Fields*¶
Field Name	Description
Called Party Address	The digits representing where the called number is stored.
MAP Version	Specify the 3GPP version of MAP protocol.
MSISDN	MSISDN of the subscriber.
Interrogation Type	Specifies if the call is Forwarding or BasicCall.
Return Address	The digits representing the location to return the message.
Return Immediately	If selected, the system will not wait for an acknowledgment from the SIGTRAN Agent before continuing to the next action.
Timeout	The amount of time to wait for an error or response before timing out completely.
Response	The response/result message from the SIGTRAN agent. Either a plain object indicating success or a SIGTRAN error object.

Optional¶

The Optional tab allows you to add applicable parameters to the Send_Routing_Info PAC.

Add Parameters

Click Add.
In the Parameter field, select an optional property to apply to the PAC.
In the Value field, type the value for the selected parameter.

Note

Click Insert to add a parameter below the parameter currently selected. Click Delete to remove a parameter from the PAC.

Exit Paths¶

In addition to the default result exit path, the Send_Routing_Info PAC also includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the operation is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Send_Routing_Info_Resp¶

The Send_Routing_Info_Resp PAC creates and sends a Send_Routing_Info_Resp message.

Properties¶

The Send_Routing_Info_Resp PAC includes the General and Optional tabs.

General¶

*General Fields*¶
Field Name	Description
SendRoutingInfo	Message being responded to.
IMSI	The International Mobile Subscriber Identity.

Optional¶

The Optional tab allows you to add applicable parameters to the Send_Routing_Info_Resp PAC.

Add Parameters

Click Add.
In the Parameter field, select an optional property to apply to the PAC.
In the Value field, type the value for the selected parameter.

Note

Click Insert to add a parameter below the parameter currently selected. Click Delete to remove a parameter from the PAC.

Exit Paths¶

In addition to the default result exit path, the Send_Routing_Info_Resp PAC also includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the operation is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Error Handling¶

Error handling is a critical component of MAP application development. Sometimes an error is the only way that a transaction terminates, and if that error is not properly handled, the transaction will not terminate and a license can be locked.

Errors can occur locally within the application or remotely. Local errors are caused by a failure to send the message from the PAC. For example, attempting to send a message to an unavailable point code or subsystem number, not including the appropriate required parameters in a PAC, or network-related errors.

Local errors can be handled immediately by the application. Each PAC has a Returns field that accepts an object variable. When a local error occurs, the object specified in this field is populated with the error information and exits on its error path.

Remote errors are generated by a remote machine. In a remote error, the message is sent successfully, but an error notification is received back from a switch at a later point in the call flow.

Remote errors are more difficult to capture because they can happen at any point once the message has been sent. Remote errors are handled using the SigTranNotification event. This event has one parameter that is an error object with the same signature as the Returns object in the PAC. To handle a remote error, use either the Wait for PAC to wait for a response or the SigtranNotification to a message you sent or add an event handler for SigtranNotification in your application.

SigTranNotification Event¶

When an application sends a query from the application server, it is important to have a SigTranNotification to handle the remote error. In this situation the application is waiting for either a response or an error before the transaction ends. If neither the response nor the error are received, the transaction does not end and a transaction license is locked.

When an application responds to queries from the application server, handling the remote error case is not as important. In this case, the transaction ends once the application responds to a query with a final response and a transaction license is not locked.

Application Development Guidelines¶

The following are guidelines to follow when developing applications:

Use the Returns object to handle local errors for the application. This field is optional, but good development practices recommend that you use this field for all PACs in your application.