In this tutorial we will configure the UMS adapter provided by Oracle SOA Suite to work with Gmail. The UMS allows us to send emails, IM, SMS, and voice notifications. It’s a very powerful tool for users and applications to communicate.

 

These are the steps that we will follow to configure the UMS Adapter:

1. Get Gmail SSL certificates.
2. Import the certificates into Weblogic’s default Keystore.
3. Send a test email.
4. Configure Email Driver
5. Important Notes
6. Common Exceptions

 

1.- Get Gmail SSL certificates.

Before configuring anything in the SOA Suite we have to get the Gmail SSL certificate first, to do that we need Open-SSL installed in our system, if you are running Linux you can run the following commands:

UBUNTU

RHEL/CENTOS

WINDOWS

Download the full package from OpenSSL for Win32 and install it.
Once you have Open-SSL installed, store the certificates in your local machine. Run the following command:

That will connect you to gmail imap service and in the trace printed you’ll find the certificate. Copy all the lines between:

Paste them in notepad and save everything in a file named gmail-imap.cert

Do the same to get the smtp certificate running the following command.

Copy all the lines between BEGIN CERTIFICATE and END CERTIFICATE and save it in a file named gmail-smtp.cert

 

2.- Import the certificates into Weblogic’s default Keystore.

To import the certificates we will use the default Java tool named Keytool, just run the following commands:

The password for DemoTrust.jsk Keystore is DemoTrustKeyStorePassPhrase

Also you need to import the Gmail SMTP certificate, run the following command:

Note that for development purposes we are using the Weblogic’s default keystore but in production you might want to use a custom keystore with your own password and passphrase.

And that’s all, check if the certificates are listed in the keystore.

You will see gmail-imap and gmail-smtp listed.

 

3.- Send a test email.

To ensure that the certificates have been imported correctly send a test email, to do that we have to configure the Workflow Notification Properties in the SOA Infra.

Right click on soa-infra then go to SOA Administration > Workflow Notification Properties

Select  email as the Notification Mode and in the Notification Service section, configure the following email addresses:

• Email From Address: The email address from which you want to send email notifications.
• Email Actionable Address: The email address for actionable incoming messages. This is not required.
• Email Reply To Address: The email address to include in the Reply To field of the outgoing email notification header.

 

Click Apply to save the changes and re start SOA server.

Once the server starts again right click on  soa-infra then go to Service Engines > Human Workflow

Then open the Notification Management Tab

and click on the “Send Test Notification” button at your right hand, you will prompt with this popup

 Fill the fields in with the following information:

• Send to: some_email_to_test@email.com
• Channel: email
• Subject: Test
• Content: the email’s body.

Click the Send button and wait to get a SENT notification, if everything goes well you will receive an email from the outgoing email account that you configured before.

 

4.- Configure Email Driver

This is the most important step in the configuration so pay attention, you can commit many errors by configuring wrong the driver.

Go to User Messaging Service and right click on usermessagingdriver-email then go to Email Driver Properties

Then go to Email Driver Properties and set up the next configuration:

Click Apply to save the changes, re start SOA server and that’s it, now you have the UMS Adapter up and running for use in your SOA projects.

 

5.- Important Notes

In this section we will review some important notes that you will have to consider.

Where to find the Email Driver Configuration XML File

The driver configuration is very sensitive and a bad configuration could stop SOA Server from starting up, so if you are in that situation you still can make corrections to your configuration, go to [Oracle_Home]/Middleware/user_projects/domains/soa_domain/config/fmwconfig/servers/
soa_server1/applications/usermessagingdriver-email/configuration and you will find a file named driverconfig.xml which holds all the drivers properties.

Cleartext Password usage

You might want to use cleartext password for development purposes but for production I strongly recommend to use an indirect password, remember that cleartext password is stored in an XML file and its anyone could read the file.

 

6.- Common Exceptions

In this section we will cover the common exceptions that you could face.

Could not initialize Email Store

This exception is related to the SMPT or IMAP certificates, you will have to erase them from the keystore and re import again, Gmail changes their certificates almost every year so you will have to import the certificates again.

 

Could not connect to SMTP host 

When this exception is thrown, it means that the server is not reaching Gmail’s SMTP, it could be a closed port or a firewall that is blocking communication.

 

Invalid credentials

Check the user or password and re start the server.

 

IMAP Read timed out

To solve this try to enter the IMAP account credentials again and re start the server.

 

7.- References

http://docs.oracle.com/cd/E28280_01/user.1111/e23486/hcfp_notifications.htm

http://docs.oracle.com/cd/E23943_01/core.1111/e12037/managing.htm#WCEDG392