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/SMTP, POP3, and IMAP protocols in Oracle Communications Services Gatekeeper.
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 communication service supports for the application-facing interfaces and the network protocols, see the appendix on standards and specifications in Concepts Guide.
Using this communication service, an application can:
Send emails to one or more destination addresses. The attachments in these emails can be of any type that can be specified using MIME.
Sign up to be notified that delivery receipts for sent emails have been delivered to the email server.
Receive delivery receipts on sent or retrying emails.
Explicitly query Services Gatekeeper for delivery receipts on sent emails.
Sign up to be notified when specified emails for the application have been received from the email server.
Receive notifications that specified emails 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 emails 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 emails 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 emails 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 Parlay X Web Services Part 5: Multimedia Messaging specification
Use Operation: startMessageNotification 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 Operation: enableReceiveEmail from the Administration console to provision offline notification of network-triggered email messages.
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 emails from email server using a configurable interval. When using IMAP, Services Gatekeeper attempts to utilize IDLE mechanism (whereby when new emails arrive it is notified by 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 emails 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 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 of Parlay X 2.1 Interfaces in Application Developer's Guide.
For information about the RESTful interface, see the discussion of Multimedia Messaging in RESTful 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 SLAs, reading CDRs, 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 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), Charging Data Records (CDRs) and alarms to assist system administrators and developers in monitoring the service.
For general information, see Appendix A, "Events, Alarms, and Charging."
Table 8-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 8-1 Event Types 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 8-2 lists the technical specifications for the communication service.
Table 8-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 managing and configuring the Plug-in Manager in System Administrator's Guide. |
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 Managing and Configuring the Plug-in Manager in 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 Managing and Configuring the Plug-in Manager in 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 section on 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: activeSmtpConfig to connect to email server by SMTP protocol after you configure or update SMTP-related attributes. Use Operation: listSmtpConnection to monitor the status of each connection in the connection pool.
Use Operation: enableReceiveEmail to register offline notifications. This specifies that received emails 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 received emails 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 user name for the SMTP server.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the password for the SMTP server.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the address for the SMTP server.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the port for the SMTP server.
Scope: Cluster
Unit: Not applicable
Format: Boolean
Specifies if the SMTP server needs authentication.
Set to true
to use authentication, otherwise false
.
Scope: Cluster
Unit: Not applicable
Format: Boolean
Specifies if the SMTP server requires SSL.
Set to true
to require SSL, otherwise false
.
Scope: Cluster
Unit: Not applicable
Format: Boolean
Specifies if the SMTP server requires TLS.
Set to true
to require TLS, otherwise false
.
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies number of retries.
Enter the number of retries. Default is 3.
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies the number of seconds between the retries for a request.
Enter the number of seconds. Default is 300.
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies the SMTP initial connection number.
Enter the initial connection number. Default is 1.
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies the maximum number of SMTP connections.
Enter the maximum connection number. Default is 16.
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies the number of seconds between the reconnection attempts.
Enter the number of seconds. Default is 60.
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies the number of seconds in the heartbeat interval.
Enter the number of seconds. Default is 300.
Scope: Cluster
Unit: Not applicable
Format: Integer
Specifies the number of seconds in the heartbeat interval.
Enter the number of seconds. Default is 300.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the protocol used to receive email.
Enter POP3 or IMAP. Default is IMAP.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the address to the POP3 Server.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the port for the POP3 Server.
Scope: Cluster
Unit: Not applicable
Format: Boolean
Specifies if the POP3 server requires SSL.
Set to true
to require SSL, otherwise false
.
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies the number of seconds in the polling interval for POP3 server.
Enter the number of seconds. Default is 120.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the address to the IMAP Server.
Scope: Cluster
Unit: Not applicable
Format: String
Specifies the port for the IMAP Server.
Scope: Cluster
Unit: Not applicable
Format: Boolean
Specifies if the IMAP server requires SSL.
Set to true
to require SSL, otherwise false
.
Scope: Cluster
Unit: Seconds
Format: Integer
Specifies the number of seconds in the polling interval for IMAP server.
Enter the number of seconds. Default is 120.
Scope: Cluster
Unit: Not applicable
Format: Boolean
Specifies whether to print debug information for SMTP/IMAP/POP3.
Set to true
to require the debug information, otherwise false
.
Scope: Local
Makes the modification to IMAP take effect.
Signature:
activeImapConfig()
Scope: Local
Makes the modification to SMTP-related attributes take effect. This method should be invoked after the following attributes are modified:
smtpUserName
smtpPassWord
smtpHost
smtpPort
smtpAuth
smtpSSLRequired
smtpStartTLS
Signature:
activeSMTPConfig()
Scope: Cluster
Adds an offline notification for applications that poll for email messages. Email messages matching the short code will not result in a callback to an application. Instead, the message is stored in Services Gatekeeper. This method returns the correlator uniquely identifying the new notification. The application has to use the correlator returned by this method to poll for email messages.
Signature:
enableReceiveEmail(shortcode: String, password: String, criteria: String, appInstGroupID: String, sizeLimit int)
Table 8-3 enableReceiveEmail Parameters
Parameter | Description |
---|---|
shortcode |
Destination address or the activation for the email account start with email:, for example, email: abc@mycompany.com |
password |
The credential for the email account indicated by the shortcode. |
criteria |
The text to match against to identify the application which is to receive the notification. (Not used in this service) |
appInstGroupID |
The application instance group ID associated with this notification |
sizeLimit |
The maximum kilobytes of total size of all attachments application can accept. |
Scope: Local
Lists the IMAP processes running in this server
Signature:
listImapProcess()
Scope: Local
Lists the POP3 processes running in this server
Signature:
listPop3Process()
Scope: Local
Lists the status of the SMTP connections in this server
Signature:
listSmtpConnections()
Scope: Cluster
Adds an online notification for applications that for some reason cannot (or are not allowed) call the startMessageNotification method. Returns the correlator uniquely identifying the new notification.
Signature:
startMessageNotification(shortcode: String, password: String, criteria: String, appInstGroupID: String, sizeLimit int)
Table 8-4 startMessageNotification Parameters
Parameter | Description |
---|---|
endpoint |
End point for the notification. |
shortcode |
Destination address or the activation for the email account starting with email:, for example, email:abc@mycompany.com |
password |
The credential for the email account indicated by the shortcode. |
criteria |
The text to match against to identify the application which is to receive the notification. Not used in this service. |
appInstGroupID |
The application instance group ID associated with this notification |
sizeLimit |
The maximum kilobytes of total size of all attachments application can accept. |
Scope: Cluster
Retrieves the notification associated with the specified correlator returned by Operation: enableReceiveEmail.
Signature:
getOfflineNotification(Correlator: String)
Scope: Cluster
Retrieves the notification associated with the specified correlator returned by Operation: startMessageNotification and the online notification started through an application interface.
Signature:
getOnlineNotification(Correlator: String)
Scope: Cluster
Displays a list of all notifications registered offline by Operation: enableReceiveEmail.
Signature:
listOfflineNotificationInfo()
Scope: Cluster
Displays a list of all notifications registered by Operation: startMessageNotification.
Signature:
listOnlineNotificationInfo()
Scope: Cluster
Removes a notification registered offline using Operation: enableReceiveEmail.
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)