Oracle User Messaging Service (UMS) enables two-way communications between actors in processes such as human users or automatic activities and deployed applications. UMS has support for a variety of messaging channels, such as e-mail, IM, SMS, and text-to-voice messages. Any process components, such as BPEL/BPMN, Human Workflow, or BAM, can leverage UMS to send notifications and alerts to user mailboxes. The Oracle SOA Suite 12c UMS infrastructure provides a range of features such as:
- Support for multiple messaging channels such as email, instant messaging (IM), Extensible Messaging and Presence Protocol (XMPP), short message service (SMS), Twitter, and voice. Actionable e-mail messages can also be delivered to a process user's inbox.
- Two-way messaging allows sending messages from applications to users (referred to as outbound messaging) who can then initiate messaging interactions (inbound messaging).
- User messaging preferences provide process users with a web interface to define preferences for how and when they receive messaging notifications, allowing applications to become immediately more flexible. Rather than deciding whether to send to a user's e-mail address or IM client, the application can simply send out the message and let UMS route the message according to the user's preferences.
UMS in Oracle SOA Suite 12c is made up of a layer of clients, servers, and drivers. The UMS server consists of EJB interfaces, standard web services, and a stateless session bean to provide business logic to client applications. The UMS architecture heavily relies on JMS queues used to buffer content between clients, servers, and drivers. The UMS server layer has JAX-WS servlets to implement web services and also the simple Oracle ADF Faces UI component for managing end-user messaging preferences. The UMS drivers contain JCA resource adapters to interface with external gateways. There is also a database in which the UMS messaging states are stored.
The
OrderBookingComposite application that we are managing in the infrastructure has to send status emails to process users configured to receive notifications. All that developers need to do is simply add an e-mail activity in their BPEL process and populate its e-mail details or enable notifications for human worfklow tasks. It is your job as an administrator to configure e-mail drivers to both send and receive messages. E-mail drivers send messages over SMTP and use either IMAP or POP3 for receiving incoming messages.
In the following section, you will learn to configure and set up e-mail driver properties by specifying connection parameters of the e-mail messaging server. This is shown in Figure 7.28:
- Log in to Oracle Enterprise Manager Fusion Middleware Control.
- On the navigator, expand User Messaging Server.
- Right-click on usermessagingdriver-email and navigate to Email Driver Properties.
- Click on the Create button to set up a new driver configuration by providing a name and properties for outgoing/incoming mail servers.
- For outgoing notifications, enter the Outgoing Mail Server and Outgoing Mail Server Port properties of your SMTP server as well as Outgoing Default From Address, Outgoing Username, and Outgoing Password.
- For incoming notifications, enter values for a POP server that requires properties such as Incoming Mail Server, Incoming Mail Server Port, Incoming Mail IDs, Incoming User IDs, and Incoming Password.
- Click on OK to save the configuration.
This screenshot shows the email configuration settings being set:
Figure 7.28: Configuring Email driver properties for UMS
The messaging driver configuration as described earlier is a generic user messaging service configuration. For human workflow engine to process notifications through UMS, the workflow notification properties must be configured as well. This can be done by following these steps:
- Right-click on soa-infra and navigate to SOA Infrastructure | SOA Administration | Workflow Properties to view the configuration screen of the Workflow Notification properties see Figure 7-29.
- Change the Notification Mode to All or Email.
- Click on the More Workflow Notification Configuration Properties link to view additional MBean properties for configuring workflow notification settings.
- Enter the From Address, Actionable Address, and Reply To Address of your mail server.
- Click on Apply and then restart all servers on which the UMS drivers are targeted. In a cluster, these properties are automatically propagated to the other servers.
Note
The hostname and IP address of the inbound (IMAP) e-mail server and outbound (SMTP) e-mail server which are to be configured for UMS must be added to the /etc/hosts file of the server on which Oracle SOA Suite 12c infrastructure is running. A restart of all managed servers on which UMS is targeted is necessary for the setting to take effect.
The property configuration changes for human workflow notifications can also be altered using WLST scripting, which is preferred by administrators who wish to automate configuration changes. Launch the WebLogic scripting tool console from $ORACLE_COMMON_HOME/common/bin/wlst.sh. An example script is provided here:
connect('<username>','<password>','<soahost>:<soaport>')
custom()
cd ('oracle.as.soainfra.config/oracle.as.soainfra.config:name=human-workflow,type=HWFMailerConfig,Application=soa-infra')
set('ASNSDriverEmailFromAddress', '[email protected]')
set('ASNSDriverEmailReplyAddress','[email protected]')
set('ASNSDriverEmailRespondAddress',' [email protected] ')
set('HWFMailerNotificationMode','ALL')
disconnect()The resultant changes is shown in the following screenshot:
Figure 7.29: Configuring workflow notification properties
This is it! You have now configured the UMS e-mail driver and Workflow Notification to integrate with the e-mail server. To test whether e-mail notifications are working, perform the following steps:
- Log in to Oracle Enterprise Manager Fusion Middleware Control.
- Right-click on soa-infra and navigate to Service Engines | Human Workflow.
- Click on the Notification Management tab and then on the Send Test Notification button.
- Enter a valid e-mail address under Send To and set Channel to Email.
- Hit the Send button to send a mail to the given e-mail address.
Figure 7.30 shows the Notification Management dashboard and the result of testing the e-mail driver configuration via the Send Test Notification button. If the e-mail is sent successfully, a SENT response output is seen immediately.
The Notification Management dashboard also displays all notifications sent from various components along with their delivery status and also offers the ability to resend undelivered notifications. You can select an individual outgoing notification and click on the Resend button to resubmit it. Optionally, you can also select a single notification column with Status set to Failure and click on Resend All Similar Notifications to resubmit all such kinds in one go.
This screenshot demonstrates sending a test notification:
Figure 7.30: Sending test notifications from the Notification Management dashboard
The UMS queues that are used to store messages intermittently can be managed from the WebLogic Server Administration Console by navigating to JMS Modules | UMSJMSSystemResource. The database schema used to store the UMS messaging state is [PREFIX]_ORASDPM. Connect to this schema and execute the following query to get the list of all UMS messages that are in the faulted state along with the fault reasons:
SELECT S.TYPE, M.CHANNEL,M.SENDER, M.STATE, S.CONTENT FROM STATUS S, (SELECT A.VALUE SENDER, A.DELIVERY_TYPE CHANNEL, D.DELIVERY_STATE STATE, D.ADDRESS_ID FROM ADDRESS A, DELIVERY_ATTEMPT D WHERE A.ADDR_ID =D.ADDRESS_ID) M WHERE S.ADDRESS_ID=M.ADDRESS_ID AND M.STATE<>'SUCCESS';
Figure 7.31 shows an example of the output of the preceding query:
Figure 7.31: SQL query result showing failed UMS message information
There will most definitely be practical scenarios where e-mail notification needs to be distinguished based on the From address information in the e-mail. To understand this better, assume there is one order confirmation BPEL process sending e-mails with From Address set to [email protected]; a customer rewards process may need to send e-mails with a different From address, such as [email protected].
There is just one default From address configured for the e-mail driver in the infrastructure. Configuring multiple send addresses is tricky, but you may do it by following the steps given here (also illustrated in Figure 7.32):
- Log in to Oracle Enterprise Manager Fusion Middleware Control.
- Right-click on soa-infra and navigate to Administration | System MBean Browser.
- Expand Application Defined MBeans | oracle.as.soainfra.config | Server: server_name > HWFMailerConfig | human-workflow.
- Click on the Operations tab and then on setASNSDriver.
- The
propertyName,propertyValue, anddriverNamevalues have to be entered in the form. EnterEmailFromAddress,[email protected](replace with actual email address), andOrderStatusrespectively in each of these fields. - Click on the Invoke button to add the entry and repeat from step 4 to add another set of properties (for the Customer Service From Address).
- Other properties such as
EmailToDoTaskAddress,EmailReplyToAddress, andEmailRespondToAddresscan similarly be added by providing property name/value combinations against the same driver name. - Click on the Operations tab and invoke the
getASNSDriverAddressesoperation by passing a driver name. This will return all the addresses being used for the specified driver. - Similarly, another
ASNSdriver address can be created, albeit with different e-mail notification properties. - In order to now use these different sender addresses, the value specified in the
driverNameattribute has to be used in the From Account field of the Email activity during design time. For example, if you need to send an e-mail from the[email protected]account name, the From Account field needs to have a value ofOrderStatus.
This screenshot shows where the multiple From addresses are configured:
Figure 7.32: Configuring multiple default From addresses for Email activity