This chapter describes the purpose, features and limitations of Oracle User Messaging Service (UMS) drivers. It discusses the following UMS drivers:
UMS drivers contain protocol specific implementation to connect UMS to various messaging gateways, for instance, email servers, or short message service centers (SMSC), and so on. Drivers can be deployed or undeployed, independently of one another, depending on the availability of messaging channels in a given installation.
The Email Driver sends and receives messages. It supports all relevant email protocols, SMTP for sending emails, and IMAP and POP3 for receiving emails, to be able to communicate with every standard mail server. Support is implemented for enabling the security protocols, TLS or SSL, to protect email contents on the wire. The Email Driver uses JavaMail v1.4, which is the standard Java component that implements the required protocols and clients, to create, access, send, and receive emails.
The Email Driver uses a multi-threaded design to be able to poll multiple mail boxes (over IMAP or POP3 protocol). One limitation is that if there is only one mail box to poll, this leads to only one thread working on that box.
When the connection to the Email Server fails, the Email Driver will wait and retry. The wait period and maximum retries are configurable.
The Email Driver is compatible with these protocols: POP3, IMAP4, and SMTP. Table 3-1 lists the Email Driver gateway vendors and their versions.
The Email Driver handles transformation of a UMS message to an email message (and vice versa), including headers, content type and charset encoding, MIME multipart and body parts. For an incoming message, the UMS Message recipient is the email address of the email box that received the mail. You can tell if the recipient was in the email To, CC or BCC field, by looking at the Address metadata.
When an outbound email is not deliverable, a Delivery Status Notification (DSN) can be created by the recipient's mail server and sent back to the sender's email address. The Email Driver tries to match a received DSN to the outbound email which the DSN is referring to and create a ”failed to deliver” status of that outbound message. In such a case, a successful delivery status may, after some time, be changed to a failed delivery status.
The Short Message Peer-to-Peer (SMPP) protocol is a TCP/IP based industry protocol for exchanging SMS messages between SMS peer entities such as short message service centers (SMS-C) and/or External Short Messaging Entities (ESME). The UMS SMPP Driver is implemented as an ESME. It is based on SMPP protocol v3.4.
If the sending feature is enabled, the SMPP driver opens one TCP connection to the SMS-C as a transmitter for sending. If the driver's receiving feature is enabled, it opens another connection to the SMS-C as a receiver for receiving. Only two TCP connections (both initiated by the driver) are needed for all communication between the driver and the SMS-C.
The SMPP Driver can be scaled out to multiple nodes. There would be a limitation only if the SMS-C does not allow multiple login by the same account.
If the connection to the SMS-C is lost, the SMPP driver will periodically attempt to reconnect.
The SMPP driver is based on SMPP Protocol v3.4. Table 3-2 lists the SMPP Driver gateway vendors.
The outgoing text message is a concatenation of the UMS Message Subject and Content. The incoming SMS Content is put in the UMS Message Content. The UMS Message Subject will be empty.
The UMS Message API Priority Levels are translated into SMPP Priority as follows:
MessagePriorityType.LOWEST, MessagePriorityType.LOW, MessagePriorityType.NORMAL => Smpp Priority: 0
MessagePriorityType.HIGH => Smpp Priority: 1
MessagePriorityType.HIGHEST => Smpp Priority: 2
However, the Smpp Priority may be limited by the SMPP Driver configuration parameter ”PriorityAllowed”.
The SMPP Driver honors the UMS API MessageInfo ”expiration” data and passes that information with the message to the SMS-C.
The XMPP Driver provides unidirectional or bidirectional access from Oracle Fusion Middleware to end users for real-time IM through the Extensible Messaging and Presence Protocol (XMPP). This driver enables end users to receive alert notifications or interactively chat with applications through the IM client of their choice.
XMPP is an open XML-based protocol for IM and consists of a client/server architecture, which resembles the ubiquitous email network. Recipients are addressed by an XMPP ID (or Jabber ID or JID) with the following form: [username]@domain[/resource]. To use the XMPP Driver in UMS, you must have access to a Jabber/XMPP server and an XMPP account for the UMS XMPP Driver instance with which to log in.
An end user of XMPP connects to an XMPP server using an XMPP client to send instant messages to other XMPP users. XMPP, however, is not the only protocol network available for IM. XMPP has an extensible and modular architecture. It integrates with proprietary IM networks, enabling XMPP users to communicate with those on other networks.
An XMPP Driver cannot be scaled out to multiple servers since the XMPP server does not allow multiple drivers (i.e. clients) to access the same account. When the second driver logs in, the XMPP server disconnects the first driver. The first driver, then, reconnects after a while and then the second driver is disconnected and so on. In this setup, outgoing messages work only if the driver that handles the message is connected at that particular moment.
When there are connection problems towards the XMPP server, the XMPP driver keeps attempting to reconnect to the remote server, but, increases the delay to avoid tight loops.
The Extension Driver sends messages to the configured Endpoint URL that implements the Notification WebServices interface defined by UMS. A messaging gateway, or an adapter to a gateway, can implement this Web Service, thereby, extending UMS with no changes in UMS.
The Extension driver also supports sending messages to any ADF Business Components web application, for instance, the ATK Popup Service which is one of Oracle's workflow and collaboration products. At runtime, the Extension Driver detects if the configured Endpoint URL is the Notification WebService or the ATK Popup Service and acts accordingly.
The Extension Driver is used for outgoing messages only.
The driver communicates with the external system via WebServices calls and the host part in the Endpoint URL is a virtual IP, that is, the external system is behind a load balancer.
The UMS Message content must be textual, not binary. To enable a new protocol in UMS using the Extension Driver, perform the following tasks:
Implement and deploy a web service listener endpoint based on the MessagingNotifyService WSDL (umsnotify.wsdl):
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://xmlns.oracle.com/ucs/messaging/extension"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
name="MessagingNotifyService"
targetNamespace="http://xmlns.oracle.com/ucs/messaging/extension">
<wsdl:types>
<xsd:schema targetNamespace="http://xmlns.oracle.com/ucs/messaging/extension">
<xsd:element name="notification">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="messageId" type="xsd:string" minOccurs="0"
maxOccurs="1">
<xsd:annotation>
<xsd:documentation>Unique message identifier from User
Messaging Service.</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="sender" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The sender address.</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="recipient" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The recipient address (typically
username).</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="subject" type="xsd:string" minOccurs="0"
maxOccurs="1">
<xsd:annotation>
<xsd:documentation>The subject of the message, if
available.</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="contentType" type="xsd:string"
default="text/plain">
<xsd:annotation>
<xsd:documentation>The MIME type of the message. e.g.
text/plain, text/html, text/xml.</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="content" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The main body of the message. Textual
content only (no binary content).</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="parameters" type="tns:parameter" minOccurs="0"
maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>Additional key-value pairs. This interface
does not define any specific key-value pair meanings. Use of such parameters
is defined on a private basis by particular implementations of this interface.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="parameter">
<xsd:sequence>
<xsd:element name="name" type="xsd:string">
<xsd:annotation>
<xsd:documentation>Parameter name</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="value" type="xsd:string">
<xsd:annotation>
<xsd:documentation>Parameter value</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="notificationResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="messageId" type="xsd:string" minOccurs="0"
maxOccurs="1">
<xsd:annotation>
<xsd:documentation>A message identifier returned in response to
successfully accepting the message. If returned, the identifier should be
unique. Note: A fault is raised if the message cannot be
accepted.</xsd:documentation>
</xsd:annotation></xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="notificationFault">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="code" type="xsd:string"/>
<xsd:element name="message" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</wsdl:types>
<wsdl:message name="notifyRequest">
<wsdl:part element="tns:notification" name="parameters" />
</wsdl:message>
<wsdl:message name="notifyResponse">
<wsdl:part element="tns:notificationResponse" name="parameters"/>
</wsdl:message>
<wsdl:message name="notifyException">
<wsdl:part element="tns:notificationFault" name="parameters"/>
</wsdl:message>
<wsdl:portType name="Notify">
<wsdl:operation name="invoke">
<wsdl:input message="tns:notifyRequest"/>
<wsdl:output message="tns:notifyResponse"/>
<wsdl:fault message="tns:notifyException" name="NotifyException"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="NotifySOAPBinding" type="tns:Notify">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http" />
<wsdl:operation name="invoke">
<soap:operation
soapAction="http://www.oracle.com/ucs/messaging/extension/" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>
<wsdl:fault name="NotifyException">
<soap:fault name="NotifyException" use="literal"/>
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="NotifyService">
<wsdl:port binding="tns:NotifySOAPBinding" name="Notify">
<soap:address location="http://localhost:8001/NotifyService"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
Configure the extension driver by performing the following tasks:
Target the predeployed extension driver called usermessagingdriver-extension (or a new deployment) to the appropriate server where UMS (usermessagingserver) is running and start the driver.
In Enterprise Manager Fusion Middleware Control, navigate to the usermessagingserver home page.
Click User Messaging Service and navigate to Driver Properties.
Select and edit the driver usermessagingdriver-extension or create a new driver with the same name as your new driver deployment.
Under Driver-Specific Configuration, add a new extension endpoint configuration group and specify the properties. EndpointURL is the URL to the web service listener endpoint that you created in Step one. Protocol is the value of the new messaging channel for which you want to add notification support (for example, myProtocol).
Under Common Configuration, update Supported Protocols with a comma-separated list of protocols defined in each Extension Endpoint group.
Click OK to save the configuration.
This completes the configuration and integration of a new messaging channel (protocol) in UMS using the extension driver.
To send notifications to this new channel (protocol), recipients must be specified for the URI delivery type using the following URI addressing format:
URI:scheme:scheme-specific-address-value
where, scheme is the protocol. The URI delivery type is optional. For example, if the extension driver was configured to support the protocol, myProtocol, an application can compose a message to myProtocol:john.doe@example.com.
End users can also declare their messaging preferences by creating a new messaging channel for the new channel type in the User Communication Preferences UI. Note that user preferences are only applied when applications send user-based notifications (that is, to recipients of the form USER:username).
The Twitter driver is a UMS driver that communicates with the Twitter API server. It provides a bi-directional messaging service to, or from the Twitter server. Thus, the Twitter driver enables the application users to publish their Twitter feed and receive response for the same.
The following are some features of the Twitter driver:
Multiple Authentication Modes: The Twitter REST API allows the following two forms of authentication:
OAuth: This is a Single Sign-On type of authentication mode. You can enable this authentication mode from the Fusion Middleware Control (EM) page. On the driver specific EM page, you must set the Authentication Mode parameter to Oauth, and configure two pairs of keys, namely, Customer key, Customer Secret, Access Token, and Access Token Secret. For more information about these keys, see Table 4-15, "Custom Properties of the Twitter Driver".
xAuth: This authentication mode is based on OAuth. The Twitter driver grants xAuth only to those applications that do not meet the requirements of OAuth. The user must provide the username and password at each request in order to enable this authentication mode.
Mutiple Options for Messaging: The following are the two categories of messages that a user comes across when using the Twitter driver:
Outbound Message: The messages sent from a UMS client application to the Twitter server are called Outbound messages. These messages could be treated as Tweets or Direct Messages.
Tweets: The messages sent to the username, that is configured with the Twitter driver, are posted as tweets. For instance, if the Twitter driver is configured with the credentials of user TW, then all messages sent to URI:twitter:TW will be posted as tweets from user TW.
Direct Message: The messages sent from the username of the configured user to another Twitter user can be treated as Direct messages. Twitter allows a configured user to send direct messages to his direct followers only. If the recipient of a direct message is not a registered user of Twitter and is not a direct follower of the sender, then the delivery of the message will fail and an error message will be displayed.
Inbound Message: The messages received by the Twitter driver from the Twitter server are called Inbound messages. Inbound messages can be of the following types:
Timeline Message: This is a list of tweets posted by the configured user or a Twitter user who is followed by the configured user.
Direct Message: This is a private message sent to the configured user by a Twitter user, who is followed by the configured user.
Limited Size of the Tweet: Twitter limits the length of each tweet to 140 bytes. Any tweet exceeding this limit is rejected by the Twitter server. The Twitter driver truncates long tweets before sending them to the Twitter server.
Limited Rate of Tweets: Twitter limits the usage of tweets per user. For information about all Twitter limits, see the About Twitter Limits page. If the rate limit of a user exceeds the rate limit of that Twitter user, then the delivery of outbound messages fail and the reception of inbound messages are ceased.
If you are using UMS behind a firewall, then you must configure proxy settings for WebLogic Server. For information about configuring proxy settings for WebLogic Server, see "Using System Properties to Specify the Proxy Server" in Oracle Fusion Middleware Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.
When there are connection problems towards the Twitter server, the Twitter Driver polls the server with reduced frequency ranging from once every 4 minutes to once every 16 minutes until the Twitter server is back to its normal state. During normal operations, the driver polls the Twitter server with a frequency ranging from once every minute to once every 4 minutes.
Twitter actively monitors the usage of their services. If the limit of a user is reached, it may refuse to provide services requested by that client with an error message that states the reason. All limits are listed on the current limits page. When usage is limited by the Twitter server, the driver first waits for 30 minutes then it polls the server with a reduced frequency ranging from once every 4 minutes to once every 16 minutes.
For outgoing messages, that is, when posting a tweet or sending a direct message, the tweet text is the UMS Message Subject concatenated with the UMS Message Content. For incoming tweets and direct messages, the text is placed in the UMS Message Content.
Table 3-4 lists the metadata used for outbound messages
Name space: ”UMS-TWITTER”
Table 3-4 Metadata used by Twitter Driver for Outbound Messages
| Name | Description | Note |
|---|---|---|
|
retweet_id |
The twitter id of the message to be retweeted. This id is available when receiving a message/tweet. |
This metadata is for the recipient Address object. |
|
reply_to_id |
The twitter id of the message to reply to. This id is available when receiving a message/tweet. |
This metadata is for the recipient Address object. |
|
geo_location |
Latitude and longitude expressed as latitude,longitude where latitude and longitude will be converted to the java primitive data type, double. |
This metadata is for the Message object. |