This chapter describes the Oracle Communications Services Gatekeeper Parlay X 2.1 Multimedia Messaging/SMTP, POP3, and IMAP protocols.
The Parlay X 2.1 Multimedia Messaging/SMTP, POP3, and IMAP 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 email server using the SMTP, POP3, and IMAP protocols. It provides the capability of applying policy such as throttling and black listing to manage and regulate the flow of email.
For the exact version of the standards that the Parlay X 2.1 Multimedia Messaging/SMTP, POP3, and IMAP communication service supports for the application-facing interfaces and the network protocols, see the Services Gatekeeper Statement of Compliance.
Using this communication service, an application can:
Send email messages to one or more destination addresses. The attachments in these email messages can be of any type that can be specified using MIME.
Sign up to be notified that delivery receipts for sent email messages have been delivered to the email server.
Receive delivery receipts on sent or retrying email messages.
Explicitly query Services Gatekeeper for delivery receipts on sent email messages.
Sign up to be notified when specified email messages for the application have been received from the email server.
Receive notifications that specified email messages for the application have been received from the email server. These notifications provide a message ID, but do not include the message payload.
Explicitly poll Services Gatekeeper for email messages sent to the application that have arrived from the email server and been stored in Services Gatekeeper.
Requests can flow in two directions. They can be application-initiated or network-triggered.
Application-initiated requests can be:
When an application sends a request using Parlay X 2.1 Multimedia Messaging protocol to Services Gatekeeper, if the sender address and destination addresses start with the schema email:, Services Gatekeeper transforms the request to an email and uses SMTP protocol to send the request to an email server.
Routing mechanism
For this communication service, each plug-in instance connects to an email server by SMTP. Routing should be based on sender address but not destination address. In PluginManager MBean, when adding a route for the email plug-in instance, the value should use ^.* to match all addresses, for example, ^.*@oracle.com$. This means that the plug-in instance connects to oracle email server and all the requests with a sender address that matches the regular expression should be routed to this plug-in instance.
SMTP connections management
Each email plug-in instance creates an SMTP connection pool. The connections in the pool connect to SMTP server separately. Each connection can be in IDLE, BUSY, or DISCONNECT status and should send heartbeat to maintain itself. If disconnected, it should reconnect to SMTP server. When a plug-in instance receives a new request, it should select a connection in IDLE status from the pool, and set it to BUSY status. If the connection fails, enlarge the pool until it reaches the maximum connection number. If it still fails, the plug-in instance sends the request to the retry manager.
Email subject, body and attachments
When transforming the Parlay X 2.1 Multimedia Messaging request to an email message, set subject in email with the subject value in the original request. For email body and attachments, since there are only attachments in the original request, add an X-Parameter ContentInFirstAttachment to indicate whether there is an email body or not. If this X-Parameter is set to true, or is absent, then the first attachment contains the email body and other attachments are handled as regular attachments. If this X-Parameter is set to false, then all attachments are handled as regular attachments and the email body is blank.
Multiple destination addresses
For a request with multiple destination addresses, since Services Gatekeeper cannot use the common routing mechanism as mentioned above, the plug-in instance should be responsible for splitting single email into multiple email messages and sending it to each address.
For this communication service, send receipts are acknowledgements that Services Gatekeeper has received the request from the application by means. The result values in the send receipts are UUIDs (universally unique identifiers) created by Services Gatekeeper used to correlate subsequent delivery receipts at a later time. Although a single email message may be sent to multiple destination addresses, 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 final delivery status of the email message. They report whether the email message has actually been delivered to the delivery recipient by the network. There is one delivery receipt per destination address, with one of four possible outcomes:
DeliveryUncertain (the initial status)
DeliveredToNetwork
MessageWaiting (retry status)
DeliveryImpossible (message could not be delivered since the retry limit was exceeded)
Applications can either choose to have delivery receipts delivered to them automatically by supplying Services Gatekeeper with a callback interface or they can choose to poll Services Gatekeeper.
When Services Gatekeeper receives a request from an application, it creates an UUID and returns that UUID in the send receipts to application. It stores the delivery receipt for each destination address with initial status in temporary in-memory storage with the UUID and callback interface (if any).
After Services Gatekeeper sends an email successfully or fails to do so, it updates the delivery receipt in the in-memory store, if a callback interface exists, and sends the delivery receipt to notify the application.
If the application does not supply a callback interface, the application can poll Services Gatekeeper with the UUID for these stored delivery receipts.
DeliveredToNetwork and DeliveryImpossible are final delivery statuses. The stored delivery receipt should be removed if the status for all the destination addresses belonging to one UUID is a final status and are delivered to application callback interface or have been polled by application.
Each stored delivery receipt is time stamped. After a configurable time period, the stored delivery receipt is removed.
When Services Gatekeeper sends an email which temporarily fails for any reason (such as no connection), it stores the request in storage, updates the status to MessageWaiting for this request, and sends a delivery receipt to the application (if a callback interface was provided).
After a configurable time interval, Services Gatekeeper retrieves the failed request from the store and attempts to resend the request. The number of retry attempts are also configurable.
If retry attempt for the send request succeeds, Services Gatekeeper updates the status to DeliveredToNetwork for this request and sends a delivery receipt.
If the number of retry attempts are exhausted and the send request has not succeeded, Services Gatekeeper updates the status to DeliveryImpossible for this request and creates a delivery receipt indicating the failure.
For an application to receive email 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 email. An application can use the following operations to register for online notification:
ParlayX 2.1 StartMessageNotification. See the Parlay X Web Services Part 5: Multimedia Messaging specification listed in Services Gatekeeper Statement of Compliance.
Use the startMessageNotification operation of EmailManagementMBean to register for online notification from the Administration console.
An application can also register to receive email messages offline. Services Gatekeeper stores the messages and delivers them when the application requests them. Use the enableReceiveEmail operation of EmailManagementMBean from the Administration console to provision offline notification of network-triggered email messages. See the "All Classes" section of Services Gatekeeper OAM Java API Reference for details on EmailManagementMBean.
Extensions to ParlayX 2.1 interface include:
X-Parameter Password to indicate the credential of the email service activation number. The value should be encrypted by AES (Advanced Encryption Standard) or 3DES (Triple Data Encryption Standard) algorithm.
X-Parameter SizeLimit to indicate the maximum total size (in kilobyte) of an email message attachment accepted by Services Gatekeeper.
Each registered notification must be unique, and notification attempts with overlapping service activation number are rejected.
When Services Gatekeeper receives an online/offline notification request, it starts a POP3 or IMAP process according to the configuration. When using POP3, Services Gatekeeper uses the polling mechanism and retrieves email messages from email server using a configurable interval. When using IMAP, Services Gatekeeper attempts to utilize IDLE mechanism (whereby when new email messages arrive it is notified by the email server and retrieves the email). If the email server does not support the IDLE mechanism, then Services Gatekeeper falls back to the polling solution.
When using POP3 or IMAP3 protocols, Services Gatekeeper handles email messages it receives in the following ways:
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 email only has pure text body without attachments, the text is included in the notification sent to the application.
If the email message is not pure text, the notification sent to the application includes a reference to the attachments stored in storage. The application uses that reference to retrieve the attachments.
Offline notification has been provisioned. Services Gatekeeper stores the email. The application retrieves the message as described in "Retrieving Offline Messages".
A ParlayX application fetches newly-arrived email messages with the getReceivedMessages operation. The response from this method is an array of MessageReference objects, one for each newly-arrived email message.
If an email message is pure text, the text message is included in the MessageReference object. If an email message is not pure text, the MessageReference object includes the reference to the attachments. The application then uses the reference to retrieve the attachment using the getMessage operation. See the Parlay X Web Services Part 5: Multimedia Messaging specification listed in theServices Gatekeeper Statement of Compliance for descriptions of this operation.
For information about the SOAP-based interface for the Parlay X 2.1 MultiMedia Messaging/MM7 communication service, see the discussion about Parlay X 2.1 Part 5: Multimedia Messaging in Services Gatekeeper Application Developer's Guide.
For information about the RESTful interface, see the discussion about the multimedia messaging interface in Services Gatekeeper Application Developer's Guide.
The RESTful Service interfaces provide RESTful access to the same functionality as the SOAP-based interfaces. The internal representations are identical, and for the purposes of creating service level agreements (SLAs), reading charging data records (CDR), and so on, they are the same.
This communication service uses a plug-in which enables applications to send email using Simple Mail Transfer Protocol (SMTP) and receive email using Post Office Protocol (POP) version 3 and Internet Message Access Protocol (IMAP).
See Services Gatekeeper Statement of Compliance for details on the SMTP, POP and IMAP interfaces supported.
The Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP communication service generates event data records (EDRs), CDRs, and alarms to assist system administrators and developers in monitoring the service.
See "Events, Alarms, and Charging" for general information.
Table 6-1 lists the IDs of the EDRs created by the Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP communication service. It does not include EDRs created when exceptions are thrown.
Table 6-1 EDRs Generated by Email Communication Service
| EDR ID | Method Called |
|---|---|
|
8107 |
SendMessage |
|
8108 |
getMessageDeliveryStatus |
|
8102 |
startMessageNotification |
|
8103 |
stopMessageNotification |
|
8104 |
getReceivedMessages |
|
8106 |
getMessage |
|
8110 |
notifyMessageDeliveryReceipt |
|
8111 |
notifyMessageReception |
|
8120 |
submit email to email server |
|
8121 |
delivery receipt for email |
|
8122 |
receive email from email server |
This section describes the properties and workflow for Parlay X 2.1 Multimedia Messaging/SMTP, POP3, and IMAP plug-in instances.
Table 6-2 lists the technical specifications for the communication service.
Table 6-2 Properties for MultiMedia Messaging/SMTP, POP3, and IMAP
| Property | Description |
|---|---|
|
Managed object in Administration Console |
sendMessagedomain_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=oracle.ocsg.plugin.multimediamessaging.email.management.EmailManagementMBean |
|
Network protocol plug-in service ID |
Plugin_px21_multimedia_messaging_email |
|
Network protocol plug-in instance ID |
The ID is assigned when the plug-in instance is created. See the description for SGADM456 |
|
Supported Address Scheme |
|
|
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-ParlayRestMms |
|
Exposes to the service communication layer a java representation of: |
Parlay X 2.1 Part 5: Multimedia Messaging |
|
Protocols used for interfaces with the network nodes |
SMTP, POP3, and SMTP |
|
Deployment artifact: NT.EAR wlng_nt_multimedia_messaging_px21.ear |
Plugin_px21_multimedia_messaging_mm7.jar Plugin_px21_multimedia_messaging_email.jar px21_multimedia_messaging_service.jar multimedia_messaging_mm7_rel5mm712.war 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 rest_multimedia_messaging.war |
Use the following procedure to configure the plug-in instance using the Administration Console or an MBean browser:
Create one or more instances of the plug-in service. See the section on configuring and managing the plug-in manager in Services Gatekeeper System Administrator's Guide.
Use the plug-in service ID listed in "Properties for Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP".
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 attributes related to the SMTP/POP3/IMAP protocols according to email server information.
Set up the routing rules to the plug-in instance.
See the section on 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 "Properties for Parlay X 2.1 MultiMedia Messaging/SMTP, POP3, and IMAP".
If required, create and load a node SLA. For details see the discussion on defining global node and service provider group node SLAs and managing SLAs in Services Gatekeeper Accounts and SLAs Guide.
Provision the service provider accounts and application accounts.
You can provision the Parlay X 2.1 MultiMedia Messaging communication service for the supported protocols (SMTP, POP3, or IMAP) in the following way:
Configure the connections to the email server for the required protocol.
Use the attributes of EmailManagementMBean appropriate for the protocol.
Enable the connection for SMPTP and IMAP3 protocols, by calling the appropriate method of EmailManagementMBean. For the POP3 protocol, the configuration takes effect immediately. It does not require such explicit connection activation.
Tip:
To monitor the status of each connection in the connection pool use, call the appropriate method of the MBean (listSMTPConnection, listPOP3Process, or listImap3Process).Enable mobile-oriented messages to be stored in Services Gatekeeper for polling by applications, by using the enableReceiveEmail method of EmailManagementMBean.
Manage offline notifications by using the following methods of EmailManagementMBean:
listOfflineNotificationInfo
getOfflineNotificationInfo
removeOfflineNotificationInfo
Manage online notifications by using the following methods of EmailManagementMBean:
listOnlineNotificationInfo
getOnlineNotificationInfo
removeOnlineNotificationInfo
For a description of the fields and methods of the EmailManagementMBean MBean, see the "All Classes" section of Services Gatekeeper OAM Java API Reference.