| Oracle® Communications Services Gatekeeper Communication Service Guide Release 5.1 E37526-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Services Gatekeeper Communication Service Guide Release 5.1 E37526-01 |
|
|
PDF · Mobi · ePub |
This chapter describes the Parlay X 2.1 Multimedia Messaging/MM7 communication service in detail.
The Parlay X 2.1 Multimedia Messaging/MM7 communication service exposes the Parlay X 2.1 Multimedia Messaging set of application interfaces.
The communication service acts as a Value Added Service (VAS) application connecting to an MMS relay server using the MM7 protocol.
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 Oracle Communications Services Gatekeeper Concepts Guide.
Using a Multimedia Messaging communication service, an application can:
Send multimedia messages to one or many destination addresses. The payload in these multimedia messages can be any type that can be specified using MIME, including multipart messages.
Sign up to be notified that delivery receipts for sent multimedia messages have been received from the network.
Receive delivery receipts on sent multimedia messages that have arrived from the network.
Explicitly query Services Gatekeeper for delivery receipts on sent multimedia messages.
Sign up to be notified if specified multimedia messages for the application have been received from the network.
Receive notifications that specified multimedia messages for the application have arrived from the network. These notifications do not include the message payload, but they do provide a message ID.
Explicitly poll Services Gatekeeper for multimedia messages sent to the application that have arrived from the network and been stored in Services Gatekeeper.
Requests can flow in two directions. They can be application-initiated or network-triggered,
After an application has sent a multimedia message to one or more destination addresses, two different types of response can be returned:
Send receipts are acknowledgements that the network node has received the multimedia message from the application by means of Services Gatekeeper. Although a single multimedia message may be sent to multiple destination addresses, normally only one send receipt is returned to the application. The receipt is returned synchronously in the response message to the sendMessage operation.
Delivery receipts contain the delivery status of the multimedia message. They report whether the multimedia message has actually been delivered to the mobile terminal by the network. There is one delivery receipt per destination address, with one of three possible outcomes:
Successful.
Unsuccessful: The multimedia message could not be delivered before it expired.
Unsupported: Delivery notification for this address is not supported. This can occur if the originating network supports delivery receipts but is unable to acquire the appropriate information for one or more destination addresses. This status is reported for each address for which this is the case.
Because actual delivery of the multimedia message may take several hours, or even days (if, for example, the mobile terminal is turned off at the time the multimedia message is sent), delivery receipts are returned asynchronously. Applications can either choose to have delivery receipts delivered to them automatically by supplying Services Gatekeeper with a callback interface or they can chose to poll Services Gatekeeper.
If the application supplies a callback interface, there are two possible outcomes:
Services Gatekeeper sends the delivery receipt and the application receives and acknowledges it.
Services Gatekeeper sends the delivery receipt but the application does not acknowledge reception. In this case, Services Gatekeeper stores the delivery receipt in temporary in-memory storage. The application can poll Services Gatekeeper for these receipts. Each stored delivery receipt is time stamped and, after a configurable time period, is removed.
If the application chooses not to supply a callback interface, Services Gatekeeper stores the delivery receipt in temporary in-memory storage. The application can poll Services Gatekeeper for these receipts. Each stored delivery receipt is time stamped and, after a configurable time period, removed.
Two types of traffic destined for an application can arrive at Services Gatekeeper from the network:
Delivery receipts for application-initiated sent multimedia messages; see “Delivery Receipts”.
Mobile-originated multimedia messages destined for the application
For an application to receive multimedia messages from the network, it must indicate its interest in these messages by registering for online notification in Services Gatekeeper. A notification is defined by a service activation number, which is the destination address of the multimedia message. The service activation number may be translated by some mechanism, such as short codes, in the telecom network. Use "Operation: startMessageNotification" to register for online notification of network-triggered MMS messages from the Administration console. An application can also use the following operations to register for online notifications:
ParlayX 2.1 StartMessageNotification; see the 3GPP TS 29.199-05 Parlay X Web Services Part 5: Multimedia Messaging specification
REST Start Message Notification; see Oracle Communications Services Gatekeeper RESTful Application Developer's Guide
OneAPI Subscribe to MMS Delivery Notification; see Oracle Communications Services Gatekeeper OneApi Application Developer's Guide
An application can also register to receive multimedia messages offline. Services Gatekeeper stores the messages and delivers them when the application requests them. Use "Operation: enableReceiveMms" to provision offline notification of network-triggered MMS messages.
Additional criteria can be tied to the service activation number, such as the start of the first plain/text part in the multimedia message payload or the subject of the multimedia message. For the message to be accepted by Services Gatekeeper, both the service activation number and any additional criteria must match the notification.
Mobile-originated messages to applications are routed based on the criteria that are specified when the notifications are created. The behavior for matching criteria is as follows:
If the subject of the message is not null, the subject is used for criteria matching the specified criteria.
If the subject of the message is null, the first word of first text attachment is used for matching the criteria.
If the criteria is not null, messages with no subject and no text attachment are not delivered to the application.
If the criteria is null, all messages are considered a match and delivered to the application.
Each registered notification must be unique, and notification attempts with overlapping criteria are rejected. The application can either retrieve received multimedia messages from Services Gatekeeper or include a callback interface when setting up the original notification.
Following are the possible scenarios for receipt and handling of multimedia messages.
The application has registered for online notification. Services Gatekeeper sends the message to the application, and the application receives the message and acknowledges receiving it.
If the MMS message is pure text, the text is included in the notification sent to the application.
If the MMS message is not pure text, the notification sent to the application includes a reference to the multimedia attachments. The application uses that reference to retrieve the attachments.
The application has registered for online notification. Services Gatekeeper sends the multimedia message to the application, but the application does not acknowledge receiving it.
Offline notification has been provisioned.
Services Gatekeeper stores the multimedia message. The application retrieves the message as described in "Retrieving Offline MMS Messages".
The application has registered for online notification. Offline notification has not been provisioned.
Services Gatekeeper sends the multimedia message to the application, but the application does not acknowledge receiving it. Services Gatekeeper returns an error to the network. It is the responsibility of the network to handle any further processing of the multimedia message.
The application has not registered for online notification. Offline notification has been provisioned. Services Gatekeeper stores the multimedia message.
The application retrieves the message as described in "Retrieving Offline MMS Messages".
The application has not registered an online subscription, and offline notification has not been provisioned.
Services Gatekeeper returns an error to the network. It is the responsibility of the network to handle any further processing of the multimedia message.
A ParlayX application fetches newly-arrived MMS messages with the getReceivedMessages operation. The response from this method is an array of MessageReference objects, one for each newly-arrived MMS message.
If an MMS message is pure text, the text message is included in the MessageReference object. If an MMS message is not pure text, the MessageReference object includes the reference to the multimedia attachments. The application then uses the reference to retrieve the attachment using the getMessage operation. See the 3GPP TS 29.199-05 Parlay X Web Services Part 5: Multimedia Messaging specification for descriptions of this operation.
The process is similar for REST applications. For information about getting MMS messages from a REST application, see the descriptions of the Get Received Messages and Get Message operations in the "Multimedia Messaging" chapter of the Oracle Communications Services Gatekeeper RESTful Application Developer's Guide.
For information about getting MMS messages from a OneAPI application, see the description of the Retrieve Messages Sent to Web Application operation in the "OneAPI Multimedia Messaging" chapter of the Oracle Communications Services Gatekeeper OneAPI Application Developer's Guide.
Table 7-1 shows the MessageReference structure defined by the 3GPP TS 29.199-05 Parlay X Web Services Part 5: Multimedia Messaging specification. Elements related to this discussion are shown in boldface in Table 7-1
Table 7-1 ParlayX Message Reference Structure
| Element name | Element type | Optional | Description |
|---|---|---|---|
|
|
|
|
If present, contains a reference to a message stored in the ParlayX gateway. If the message is pure text, this parameter is not present. |
|
messageService ActivationNumber |
xsd:string |
No |
Number associated with the invoked Message service, i.e. the destination address used by the terminal to send the message. |
|
senderAddress |
xsd:anyURI |
No |
Indicates message sender address. |
|
subject |
xsd:string |
Yes |
If present, indicates the subject of the received message. This parameter will not be used for SMS services. |
|
priority |
MessagePriority |
No |
The priority of the message: default is Normal. |
|
|
|
|
|
|
dateTime |
xsd:dateTime |
Yes |
Time when message was received by operator |
Example 7-1 shows the message and messageIdentifer in the REST Notification Data Object.
Example 7-1 REST Notification Data Object
{"notifyMessageReception": {
"correlator": "String",
"message": {
"messageServiceActivationNumber": "String",
"priority": "Default|Low|Normal|High",
"senderAddress": "URI",
"dateTime": "Calendar",
"message": "String" --> if message is pure text it can be found here
"messageIdentifier": "String", --> if not pure text the reference is found here
"subject": "String"
}
}}
Each stored multimedia message is time stamped and, after a configurable time period, removed.
The OneAPI response to a request for the full MMS message including attachments is a multipart/form-data response in which the JSON message text and metadata are separated from the multimedia attachments by a separator that has the form
====12345====
The resourceURL in the response is the link to the message. The application uses this value to retrieve the entire message, including the attachments. Example 7-2 shows the structure of a response.
Example 7-2 OneAPI Response Body for Retrieving Full MMS messages
"inboundMessage": [
{ "dateTime": "dateTime",
"destinationAddress": "String",
"messageId": "String", --> server-geenerated message identifier
"inboundMMSMessage": "String", --> subject of the message
"resourceURL": "URL", --> link to the full message and attachments
"senderAddress": "String"},
====Content Divider====
Attachment(s)
The polling capability for retrieving offline notifications must be provisioned in advance.
To configure the polling capability:
Set the RequestDeliveryReportFlag attribute to non-zero. See "Attribute: RequestDeliveryReportFlag" for information about valid values.
Use the enableReceiveMms operation to allow applications to poll for mobile-originated messages. See "Operation: enableReceiveMms" for more information.
Messaging-capable networks use short codes and message prefixes to help route traffic and to make access to certain features easier for the end user. Instead of having to use the entire address, users can enter a short code that is mapped to the full address in the network. The Parlay X 2.1 Multimedia Messaging/MM7 communication service supports short codes and message prefixes, which allow the same short code to be mapped to multiple addresses based on the prefix to the enclosed message.
For information about the SOAP-based interface for the Parlay X 2.1 MultiMedia Messaging/MM7 communication service, see the discussion of Parlay X 2.1 Interfaces in Oracle Communications Services Gatekeeper Application Developer's Guide.
For information about the RESTful Call Notification interface, see the discussion of Multimedia Messaging in Oracle Communications Services Gatekeeper RESTful Application Developer's Guide.
The RESTful Service Multimedia 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
The Parlay X 2.1 Multimedia Messaging/MM7 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 7-2 lists the IDs of the EDRs created by the Parlay X 2.1 Multimedia Messaging/MM7 communication service.
Table 7-2 Event Types Generated by Parlay X 2.1 Multimedia Messaging/MM7
| EDR ID | Description |
|---|---|
|
8100 |
An MO message has arrived from the network. |
|
8101 |
An MO delivery receipt has arrived from the network. |
|
8102 |
The application has requested that a notification be started. |
|
8103 |
The application has requested that a notification be stopped. |
|
8104 |
The application has polled for a list of received messages. |
|
8106 |
The application has polled for actual messages, returned as attachments. |
Multimedia Messaging/MM7-specific CDRs are generated under the following conditions:
After a sendMessage request has entered the network plug-in from the application.
After a notifyMessageDeliveryReceipt request has entered the network plug-in from the network.
After a notifyMessageReception request has been delivered to the application.
When there is an error.
Table 7-3 maps methods invoked from either the application or the network to the transaction types collected by the Services Gatekeeper statistics counters.
This section lists, by parameter key, the parameters that can be tunneled or defined in the <requestContext> element of an SLA.
Specifies the party to be charged for a multimedia message submitted by the Value-Added Service Provider (VASP).
If defined, the ChargedParty xparameter is forwarded in the SOAP header in the north-bound interface.
Validated by the plug-in.
String
Valid values: Sender, Recipient, Both, Neither
Specifies the address of the third party expected to pay for the multimedia message.
If defined, the ChargedPartyID xparameter is forwarded in the SOAP header in the north-bound interface.
String
Specifies date and time that the multimedia message was submitted.
Date/Time
Specifies the desired time for the expiration of the multimedia message.
Date/Time
Specifies if VASP allows adaptation of the content.
Set to true to allow adaptation, false to prohibit it.
Boolean
In the event of a single "Delivery Condition", if the condition is met, the multimedia message is delivered to the recipient MMS User Agent. Otherwise the message is discarded.
Validated by the plug-in.
Positive Integer
This section describes the properties and workflow for Parlay X 2.1 Multimedia Messaging/MM7 plug-in instances.
Table 7-4 lists the technical specifications for the communication service.
Table 7-4 Properties for Multimedia Messaging/MM7
| Property | Description |
|---|---|
|
Managed object in Administration Console |
domain_name > OCSG > server_name > Communication Services > plug-in_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.multimediamessaging.mm7.management.MessagingManagementMBean |
|
Network protocol plug-in service ID |
Plugin_px21_multimedia_messaging_mm7 |
|
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 Oracle Communications Services Gatekeeper System Administrator's Guide. |
|
Supported Address Scheme |
tel, mailto, short |
|
Application-facing interfaces |
com.bea.wlcp.wlng.px21.plugin.MessageNotificationManagerPlugin com.bea.wlcp.wlng.px21.plugin.ReceiveMessagePlugin com.bea.wlcp.wlng.px21.plugin.SendMessagePlugin com.bea.wlcp.wlng.px21.callback.MessageNotificationCallback |
|
Service type |
MultimediaMessaging |
|
Exposes to the service communication layer a Java representation of: |
Parlay X 3.0 Part 5: Multimedia Messaging |
|
Interfaces with the network nodes using: |
MM7 |
|
Deployment artifact: NT EAR wlng_nt_multimedia_messaging_px21.ear |
Plugin_px21_multimedia_messaging_mm7.jar, px21_multimedia_messaging_service.jar, multimedia_messaging_mm7_rel5mm712.war, and multimedia_messaging_mm7_rel5mm715.war |
|
Deployment artifact: AT EAR: Normal wlng_at_multimedia_messaging_px21.ear |
px21_multimedia_messaging_callback.jar, px21_multimedia_messaging.war and rest_multimedia_messaging.war |
|
Deployment artifact: AT EAR: SOAP Only wlng_at_multimedia_messaging_px21_soap.ear |
px21_multimedia_messaging_callback.jar and px21_multimedia_messaging.war |
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 Oracle Communications Services Gatekeeper System Administrator's Guide. Use the plug-in service ID listed in the "Properties for Parlay X 2.1 Multimedia Messaging/MM7" section.
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.
Configure the behavior of the plug-in instance using the following attributes:
Attribute: HTTPBasicAuthentication
If you are using HTTP basic authentication, also define:
Specify heartbeat behavior. See "Configuring Heartbeats" in Oracle Communications Services Gatekeeper System Administrator's Guide.
Set up the routing rules to the plug-in instance. See "Managing and Configuring the Plug-in Manager" in Oracle Communications Services Gatekeeper System Administrator's Guide. Use the plug-in instance ID and address schemes listed in the "Properties for Parlay X 2.1 Multimedia Messaging/MM7" section.
Provide the administrator of the MM7 server with the URL to which the MM7 server should deliver mobile originated messages and delivery reports. The default URL is
http://IP_Address_of_NT_server:port/context-root/plug-in_instance_ID
If you are using the REL-5-MM7-1-2 XSD, the default context-root is mmm-mm7.
If you are using the REL-5-MM7-1-5 XSD, the default context-root is mmm-mm7-rel5mm7-1-5.
If you are using the REL-6-MM7-1-4 XSDm the default context-root is mmm-mm7-rel6mm7-1-4.
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 Oracle Communications Services Gatekeeper Accounts and SLAs Guide.
Provision the service provider accounts and application accounts.
The following steps outline the provisioning workflow for the communication service.
Use "Operation: enableReceiveMms" to register offline notifications. This specifies that mobile-originated messages should not result in notifications to an application but should instead be stored in Services Gatekeeper for polling.
Use the following operations to manage the offline registrations:
Use "Operation: startMessageNotification" to register online notifications. This is to manage registrations for mobile-originated messages on behalf of an application.
Use the following operations to manage the online registrations:
This section describes the attributes and operations for configuration and maintenance:
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the default priority for sent MMS messages. Enter one the following:
normal
high
low
Scope: Cluster
Unit: Not applicable
Format: Boolean
Specifies if HTTP basic authentication will be used for authentication with the MM7 server.
Set to true to use HTTP basic authentication, otherwise false.
If true, "Attribute: HTTPBasicAuthenticationUsername" and "Attribute: HTTPBasicAuthenticationPassword" must be specified.
Scope: Cluster
Unit: Not applicable
Format: String
The user name to use for HTTP basic authentication towards the MM7 server.
Scope: Cluster
Unit: Not applicable
Format: String
The password to use for HTTP basic authentication towards the MM7 server.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the address to the MM7 Relay Server. The address is an HTTP url.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the version of the MM7 protocol to be used. Applicable versions are:
5.3.0
6.8.0
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the Value Added Service (VAS) ID to be used for the plug-in instance when connecting to the MMSC.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the Value Added Service Provider (VASP) ID to be used for the plug-in instance when connecting to the MMSC.
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies how the plug-in instance requests and handles delivery reports for sent messages. Enter one of the following:
0: Delivery notifications are not processed, which means that no polling functionality is available to the applications using the communication service.
1: Delivery notifications are processed if the application provided a receiptRequest in the SendMessage requests or the application provided a tunnelled parameter with ID com.bea.wlcp.wlng.plugin.multimediamessaging.RequestDeliveryReportFlag with the value true in the SOAP header of the SendMessage request.
2: Delivery notifications are always processed.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the service used for billing purposes.
Scope: Server
Unit: Not applicable
Format: String
The MM7 xsd version that should be used for requests towards the MMSC.
Enter one of the following:
REL-5-MM7-1-0 to use an altered version of the REL-5-MM7-1-0.xsd. The altered version allows use of delivery notifications when the MMC-S requires this version of the xsd. This is a requirement when connecting to, among others, Comverse MMSCs.
REL-5-MM7-1-2 to use REL-5-MM7-1-2.xsd
REL-5-MM7-1-5 to use REL-5-MM7-1-5.xsd
REL-6-MM7-1-4 to use REL-6-MM7-1-4.xsd
Scope: Cluster
Adds an offline notification for applications that will poll for mobile originated messages. Mobile-originated messages matching this notification will not result in a callback to an application. Instead the application has to use the correlator returned by this method and poll for new messages.
Returns the correlator uniquely identifying the new notification.
Signature:
enableReceiveMms(shortcode: String, criteria: String, appInstanceID: String)
Table 7-5 lists the parameters that the enableRecieveMms operation accepts.
Table 7-5 enableReceiveMms Parameters
| Parameter | Description |
|---|---|
|
shortcode |
The destination address or service activation number of the Multimedia message. Prefixed with the URI, for example tel: |
|
criteria |
The first word in the text in the subject field of the MMS message to match. Exact matches only. |
|
appInstanceID |
The application instance ID associated with the notification. |
Scope: Cluster
Displays information about a notification registered offline. See "Operation: enableReceiveMms" for more information.
Signature:
getOfflineNotificationInfo(correlator: String)
Table 7-6 lists the parameters that the getOfflineNotificationInfo operation accepts.
Scope: Cluster
Displays information about a notification registered by an application or by "Operation: startMessageNotification".
Signature:
getOnlineNotificationInfo(correlator: String)
Table 7-7 lists the parameters that the getOnlineNotificationInfo operation accepts.
Scope: Cluster
Displays a list of all notifications registered offline by Operation: enableReceiveMms.
Signature:
listOfflineNotificationInfo()
Scope: Cluster
Displays a list of all notifications registered online by the application or by "Operation: startMessageNotification".
Signature:
listOnlineNotificationInfo()
Scope: Cluster
Removes a notification registered offline using "Operation: enableReceiveMms".
Signature:
removeOfflineNotificationInfo(Registration Identifier: String)
Table 7-8 lists the parameters that the removeOfflineNotificationInfo operation accepts.
Scope: Cluster
Removes a notification registered by an application or on behalf of an application by "Operation: startMessageNotification".
Signature:
removeOnlineNotificationInfo(Registration Identifier: String)
Table 7-9 lists the parameters that the removeOnlineNotificationInfo operation accepts.
Scope: Cluster
Creates an online notification on behalf of an application. Produces the same results as if an application registered for notifications using the startMessageNotification operation in the Parlay X 2.1 Multimedia Messaging MessageNotificationManager interface.
This operation can be used, for example, if the application is not allowed to register for notifications by restrictions defined in its SLA. Returns a correlator that uniquely identifies the notification.
Signature:
startMessageNotification(endpoint: String, shortcode: String, criteria: String, appInstanceID: String)
Table 7-10 lists the parameters that the startMessageNotification operation accepts.
Table 7-10 startMessageNotification Parameters
| Parameter | Description |
|---|---|
|
endpoint |
Notification endpoint implemented by the application. This endpoint implements the Parlay X 2.1 Multimedia MessagingMessageNotification interface. Format: URL |
|
shortcode |
Destination address for the MMS message. Must have the prefix tel:; for example, tel:1234 |
|
criteria |
The first word in the text in the subject field of the MMS message to match. Exact matches only. |
|
appInstanceID |
ID of the application instance for the application. |
|
 Copyright © 2011, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|