OracleFusionMiddleware , OIC/PCS/VBCS/SOA/BPEL/BPM/B2B/OSB/ODI/OBIEE/ADF/Weblogic: Configure SOA Suite 11g for sending email notifications with Google Mail

One of the ways of the SOA Suite 11g for communicating with the outside world – apart of course from web service calls and interaction via technology adapters – is through the new User Messaging Service (UMS), a facility installed in the SOA Domain during installation of the SOA Suite. The UMS enables two-way communication between users (real people) and deployed applications. The communication can be via various channels, including Email, Instant Messaging (IM or Chat), SMS and Voice. UMS is used from several components in Fusion Middleware, for example BPEL, Human Workflow, BAM and WebCenter and can also be used from custom developed applications.

This article describes how the User Messaging Service can be configured to use Google Mail as its mail server for sending and receiving emails and how we can make use of that facility from a simple BPEL process. Note that the steps described in this article apply to any public email server – Yahoo, Hotmail, Lycos and others – as well as your own email server.

Prerequisites

Before you can apply this article, you need to have installed the SOA Suite 11g, configured the SOA Domain and have the AdminServer and the SOA Server running. You also need access to the Oracle Enterprise Manager Fusion Middleware Control Console. You will also need JDeveloper 11g with the SOA extension in order to create a SOA Composite Application through which to test the email sending capabilities.

Configure the UMS Email Driver

The User Messaging Service comes with a number of drivers that each handle traffic for a specific channel. One of the drivers controls the email channel. This driver needs to be configured with the properties of the Google GMail Server and the email account from which emails are sent.

Go to the Oracle Enterprise Manager Fusion Middleware Control Console (typically http://host:7001/em) and open the User Messaging Service node. From the drop down menu in the right hand pane, select the option Email Driver Properties:

The form that is now shown allows you to set various properties on the Email Driver, including the details about the email server to be used by the driver for email operations.

The properties that need to be configured for sending emails are indicated in the red rectangle. They are:

OutgoingMailServer – that should be smtp.gmail.com for Gmail
OutgoingMailServerPort – 465 for Gmail
OutgoingMailServerSecurity – Gmail uses SSL
OutgoingDefaultFromAddress (optional) – the emailaddress that is indicated as the sender of the email message
OutgoingUsername – the Gmail user account from which the email is sent
OutgoingPassword – the Gmail account’s password (stored in encrypted format)

Press Apply. To have these settings take effect, the Driver has to be restarted. This happens automatically I presume when the SOA Server is restarted, which we will do at the end of the next step. Otherwise, you can use the options Shutdown and Start in the dropdown menu option Control.

Configure the SOA Suite Workflow Notification properties

To make sure that (email) notifications are really sent to the email server, we also need to adjust a setting for the SOA Suite Workflow Notification. Navigate to the properties form via the dropdown menu for SOA Infrastructure, under SOA Administration:

The Workflow Notification Properties are shown. Only one is really important at this point: the Notification Mode (default value is None) must be set to either All or Email, otherwise any notification is not really sent onwards by the SOA Suite to UMS!

At this point, the SOA Server needs to be restarted to have the changes take effect.

Create a BPEL process that sends an email

We will create a very simple composite application to try out the message sending capabilities we should now have at our disposal. Go through the normal steps:

1. Start JDeveloper (choose Default Role if you are prompted to select a role)

2. From the menu option File, choose menu item New. From the New Gallery that is presented next, select the SOA Application item in the Applications Category (under the General node).

You will be prompted to provide a name for the application – for example HelloWorldEmailSOAComposite – and a name for the project – the same or any other name will do nicely. JDeveloper then asks you what type of composite application this will be; pick ‘Composite with BPEL’ on the Configure SOA settings step. Press Finish to have the application, project and service composite created.

3. The Create BPEL Process dialog comes up next. Specify the name for the new BPEL process – HelloWorldEmail – and the Template: Synchronous BPEL process. Leave the checkbox Expose as SOAP Service checked and accept other defaults as well. Press OK.

4. The BPEL editor opens up. You will see the basic structure of the BPEL process with a receive and a reply activity, by default configured to receive a single string and return a single string. You need to add one activity to set the value of that string result: drag and Assign activity from the Component palette and drop it between the receive and reply activities already in the process.

Double click the assign activity, to open the editor. Click the green plus icon and select the Copy Operation from the drop down list. The client:result element in the outputVariable is the obvious target for the Copy Operation. Use an expression that concattenates the string "Hello dear " with the client:input element in the inputVariable.

5. Drag an Email activity from the Component Palette and drop it under the Assign Activity.

The configuration of the email activity must be specified. This includes the subject and body of the message (both can contain dynamic values from BPEL process instance) as well as the addressee (again, can be derived dynamically as well as defined at design time):

The content of the message body is defined as follows:

Dear Sir/Madam,

We would like to inform you of the fact that our HelloWorld service has been invoked again.

The value of the input string was:
<%bpws:getVariableData('inputVariable','payload','/client:process/client:input')%>.

The request was made around <%xpath20:format-dateTime(xpath20:current-dateTime(), '[D1o] [MNn], [Y] at [H01]:[m01]:[s01]')%>

6. Deploy the Composite Application to the SOA Suite.

Run the Composite Application

Open the Enterprise Manager (http://host:7001/em). Expand the node SOA node under the root node Farm_soa_domain. The node for HelloWorldEmailSOAComposite application should be listed. Select the node. The right side of the page is refreshed to present the details for this composite application. Click on the Test button to call the service exposed by this composite application. Enter a value for the input field – for example your first name – and press the button labeled Test WebService. The web service is invoked. This will create a new instance of the composite application. After a few seconds, the result from the service should be displayed, something to the effect of ‘Hello dear Lucas’.

As part of the now completed instance of the composite application, a call is supposed to have been made to the Notification Service that in turn engaged the UMS that approached the Gmail server to send an email on behalf of the BPEL process instance. We can see trace of this message on the Message Status page for the User Messaging Service in the Enterprise Manager console.