| 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 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 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 register its interest in these multimedia messages by setting up a subscription in Services Gatekeeper. A subscription, or notification, is defined by a service activation number, 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.
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 subscription.
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 subscription must be unique, and subscription attempts with overlapping criteria are rejected. The application can choose either to poll Services Gatekeeper for received multimedia messages (if polling is enabled) or to include a callback interface when it sets up the original subscription.
If a multimedia message that matches a subscription arrives at Services Gatekeeper from the network and the original subscription includes a callback interface, there are two possible results:
Services Gatekeeper sends the notification that the multimedia message has arrived on to the application, and the application receives and acknowledges it. In this case, Services Gatekeeper stores the multimedia message in temporary in-memory storage and acknowledges the reception of the multimedia message to the network. Each stored multimedia message is time stamped and, after a configurable time period, removed. The application can poll Services Gatekeeper for any stored multimedia messages.
Services Gatekeeper sends the notification that the multimedia message has arrived on to the application, but the application does not acknowledge reception. Services Gatekeeper does not acknowledge reception to the network. In this case, it is the responsibility of the network node to handle any further processing of the multimedia message.
If a multimedia message that matches a subscription arrives at Services Gatekeeper and the original subscription does not include a callback interface, but polling is available, the multimedia message is stored in temporary in-memory storage and Services Gatekeeper acknowledges the reception of the multimedia message to the network. The application can poll Services Gatekeeper for any such multimedia messages. Each stored multimedia message is time stamped and, after a configurable time period, removed.
If a multimedia message arrives at Services Gatekeeper and no matching subscription is found and polling is not otherwise enabled, Services Gatekeeper does not acknowledge reception to the network. It is the responsibility of the network node to handle any further processing of the multimedia message.
The polling capability must be set up in advance.
It is controlled through the combined use of parameters sent in the request and the RequestDeliveryReportFlag attribute. See "Attribute: RequestDeliveryReportFlag" 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 Application Developer's Guide.
For information about the RESTful Call Notification interface, see the discussion of Multimedia Messaging in 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 4-1 lists the IDs of the EDRs created by the Parlay X 2.1 Multimedia Messaging/MM7 communication service.
Table 4-1 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 4-2 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 4-3 lists the technical specifications for the communication service
Table 4-3 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 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 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 suing the following attributes:
Attribute: HTTPBasicAuthentication
If you are using HTTP basic authentication, also define:
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 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/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 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 4-4 enableReceiveMms Parameters
| Parameter | Description |
|---|---|
|
shortcode |
The destination address or service activation number of the Multmedia 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)
Scope: Cluster
Displays information about a notification registered by an application or by "Operation: startMessageNotification".
Signature:
getOnlineNotificationInfo(correlator: String)
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)
Scope: Cluster
Removes a notification registered by an application or on behalf of an application by "Operation: startMessageNotification".
Signature:
removeOnlineNotificationInfo(Registration Identifier: String)
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 4-9 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, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
