Email Notification with SOA Suite 11g

Oracle SOA Suite 11g supports a number of different notification channels through the User Messaging Service (UMS). This blog provides a step-by-step guide for configuring and testing email notification. Once email notification has been configured, emails can be sent from SOA Suite components such as BPEL processes and Human Tasks. For this example, Gmail will be used as the mail server.

Configuring Email Notification

To support email notification from SOA Suite 11g the UMS email driver and workflow notification properties to be configured with the mail server details. This can be done through the Enterprise Manager Fusion Middleware Control console (e.g. http://localhost:7001/em) as follows:

1. Navigate to the Email Driver Properties page available under User Messaging Service > usermessagingdriver-email
    
   
   
   
2. Update the following properties according to your mail server configuration:
   
   

   OutgoingMailServer - The SMTP hostname

   OutgoingMailServerPort - The SMTP port

   OutgoingMailServerSecurity - The type of security (e.g. SSL)

   OutgoingUsername - The mail user account

   OutgoingPassword - The mail user password

   
   
    
3. Click Apply to save the changes.
    
   
   
4. Right-click on soa-infra under SOA and navigate to the Workflow Notification Properties page available under SOA Administration. 
   
   
    
5. Set the Notification Mode to 'Email' and enter the default values which you wish to use for from, actionable and reply to email addresses.
   
   
    
6. Click Apply to save the changes to the workflow notification properties.
    
7. Restart the SOA server for the changes to take effect. If you are using Gmail or any other mail server that requires SSL you will need to perform the steps in the next section. In this case, you may wish to hold off on restarting the server before these steps are performed. This will save you the trouble of having to restart twice.

Import the SSL Certificates to the Java Keystore

Before SOA Suite can send emails with Gmail there are some SSL certificates that will need to be imported. This step can be ignored if sending from an alternative mail server that does not require SSL.

1. Download the Gmail IMAP and SMTP certificates. This can be done with OpenSSL (Unix / Windows) by running the following from command prompt:

• openssl s_client -connect host:port

• where Gmail SMTP host:port is smtp.gmail.com:465
• where Gmail IMAP host:port is imap.gmail.com:993
   
2. Create a new file for the SMTP and IMAP certificates using the content between BEGIN CERTIFICATE & END CERTIFICATE
   
   
   
   
3. Use the Java Keytool to import the two certificates into a new or existing keystore. The keytool executable is available under the JAVA_HOME/bin directory. The following command can be used to import a certificate:
   

   • keytool -import -alias AliasName -keystore KeystoreLocation -file CertificateLocation

   • For example:
   • keytool -import -alias gmail-imap -keystore gmail-keystore.jks -file imap.txt
   • keytool -import -alias gmail-smtp -keystore gmail-keystore.jks -file smtp.txt
     
     
   • When prompted, enter a password for the keystore.
      
4. Add the following system properties to the WebLogic server startup arguments:

   -Djavax.net.ssl.trustStore=CertificateLocation
   -Djavax.net.ssl.trustStorePassword=CertificatePassword

   This can be done in Arguments field available under the Server Start tab for the SOA Server (e.g. soa_server1) in the WebLogic Administration Console (e.g. http://localhost:7001/console) or by adding the properties to the DOMAIN_HOME/bin/setDomainEnv.cmd (or setDomainEnv.sh). For example: 

   set EXTRA_JAVA_PROPERTIES=%EXTRA_JAVA_PROPERTIES% -Djavax.net.ssl.trustStore=%WL_HOME%\server\lib\gmail-keystore.jks -Djavax.net.ssl.trustStorePassword=changeit

5. Start the SOA server (or restart it if it is already running).

Testing Email Notification

Now that we have configured outbound email notification, we want to test our configuration easily without having to create a BPEL process or human task to do this. Fortuntately, we can do this from Enterprise Manager Fusion Middleware Control.

1. Right-click on soa-infra under SOA and navigate to the Human Workflow page available under Service Engines. 
   
   
    
2. Select the Notification Management tab.
    
3. Click Send Test Notification
   
   
    
4. The Send Test Notification dialog box should now appear. Enter the email subject, content, to address and be sure to select 'Email' for the channel. Click Send. Once the email has been sent, you should receive a value of 'SENT' for Response. You can now close the dialog box.
   
   
    
5. Ensure that the email has been received.

Troubleshooting

If you encounter an issue with the outgoing email notification, it is a good idea to check the SOA server log for error messages. There are log files available at:

• DOMAIN_HOME/servers/<soa server name>/logs/<soa server name>.log
• DOMAIN_HOME/servers/<soa server name>/logs/<soa server name>.out
• DOMAIN_HOME/servers/<soa server name>/logs/<soa server name>-diagnostic.log

Furthermore, it is a good idea to tick the UMS email driver debug flag.

Listed below are some common errors with their solution:

• Error Message: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
  
  Diagnosis: There is an issue with the SSL certificate.
  
  Remedy: Ensure all of the steps have been followed as described in "Import the SSL Certificates to the Java Keystore". Also make sure that the mail server certificates in the Java Keystore have not expired. You can ensure a fresh copy of the certificates are downloaded by executing the openssl s_client -connect command followed by the host and port details for the mail server.
   
• Error Message: ORABPEL-31023 - Cannot send email notification to <email address> address. The address is being marked as invalid and no further notification would be sent to this address.
  
  Diagnosis: Due to a number of previous failed send attempts to an email address, SOA Suite has added the address to the Bad Address List thus preventing subsequent sends to this address from failing. The previous failed attempts may been caused by a configuration issue.
  
  Remedy: Remove the email address from the Bad Address List. This can be done by selecting View Bad Addresses from the Notification Management page in Enterprise Manager. When the Bad Address List dialog box is displayed, remove the email address from this list.
   
• Error Message: No matching drivers found for sender address
  
  Diagnosis: The UMS Driver for the appropriate channel is configured with a specific list of SenderAddresses, and the message sent by the application has a Sender Address that does not match.
  
  Remedy: Make the Sender Address blank. This will ensure that all outbound messages will be sent regardless of the sender address.