Proces email with the new UMS adapter of SOA Suite PS5

With the release of Soa Suite Patch Set 5 we can now try out the new UMS adapter. UMS stands for User Messaging Service but in this case it only supports email. The UMS adapter allows you to listen for new mail or send a mail from a service component. Combined with BPEL it’s now relative  easy to process email bodies or attachments. Remember that in PS5 the UMS adapter is still a  preview version so you can’t claim support and you can only use the Oracle forums for your ums questions.

It’s important to know that the UMS adapter does not work like a JMS topic or like EDN. So you can’t have two UMS adapters which are polling on the same mailbox.

In this blogpost I will show you how to setup and configure UMS, Listen plus send a mail and handle attachments.

We start with configuring our SOA Suite domain.

1st step is to copy two UMS libraries to your SOA Suite domain folder. Copy sdpmessagingclient.jar and sdpmessagingcommon.jar to the lib folder of the SOA Suite WebLogic Domain. You can find these jars at MiddlewareHome\Oracle_SOA1\communications\modules\oracle.sdp.client_11.1.1

2nd Install the UMS resource adapter.  Open the WebLogic Console and deploy the UMSAdapter.rar, you can find this adapter at MiddlewareHome\Oracle_SOA1\soa\connectors . Make sure you targeted this Resource Adapter to the SOA managed WebLogic server. And restart the SOA Suite Server.

3rd Check if the usermessagingdriver-email and usermessagingserver applications are active and targeted to the to the SOA managed WebLogic server. You can check this in the deployments of the weblogic console.

4th Configure the UMS Email driver.  For this we need to go the Enterprise Manager application. When everything is Ok you should see the User Messaging Service. Here we can select usermessagingdriver-email and in the menu we can go the Email Driver Properties.

Here we can set some defaults, like the default mail address, Cost and Speed ( cpu priority )

The UMS settings for outgoing mail.

The incoming settings are more complex because I will read two mail accounts, this is because I need one mail account for every polling UMS adapter.

To make this work I can use a “,” between the values so for IncomingMailIDs I use this as value soa@local.nl,soa2@local.nl , do the same for IncomingUserIDs = soa,soa2  and for the IncomingUserPasswords, I use CleartextPassword and also use a “,” between the passwords.

Restart the SOA Suite server.

 

At last we must enable the UMS adapter in JDeveloper.  Go to the JDev11.1.1.6\jdeveloper\integration\seed\soa\configuration folder and open the soa-config.xml. Find the adapterType with this ${UMS_ADAPTER_COMPONENT_NAME_L}  as name and remove the preview = true attribute. Now You will see the new UMS adapter in your SOA Component Palette.

 

In the next part we can finally try this out.

Let’s start with an easy one. Sending a mail from a composite. For this we need to drag the UMS adapter to the External Reference of the Composite.

Don’t change Connection JNDI name.

Choose for Outbound Send Notification. You can choose to receive the Mail Message Id as response, else it will be One Way.

Provide the Mail Header settings.

For Message Schema you got 3 options ( this talks about the mail body ) , off course Opaque, Message is a big String or based on a XML Schema.

 

Next we can take a look at incoming part of the UMS adapter. Drag the UMS adapter to exposed Services side of the composite.

Don’t change the default Connection JNDI Name

Choose Listener as Operation Mode, Polling does not work in this Preview Adapter and the UMS email driver already polls every few seconds.

Provide the mail adress this must match with your incoming UMS configuration.

Also provide the message type.

 

We can also define a message filter which can accept or ignore the incoming mails. The pattern string should be a java regexp. To test this pattern you can use this url  http://www.regexplanet.com/advanced/java/index.html

Too bad this feature does not work yet in this technical preview.

 

And also you can do a custom Java Callout ( I didn’t test it and don’t know the possibilities of this feature).

 

To test this I need to add the employee xml in the body of the mail ( not as attachment)  and send it to soa@local.nl. As response I will get a mail.

The request I will receive in SOA Suite.

And the response

 

Last part of this blogpost is about, how to handle mail attachments.

For this I will use the second mail address soa2@local.nl and also change the message type to String. A BPEL service component will write these attachments to a server location.

This is the request I received in the BPEL component. You can see that we only get a reference to the attachments.

So in BPEL we need to use a ForEach to handle every attachment and write this to a file.

To load the attachment and assign it to the file adapter input variable I need to use ora:getAttachmentContent

<assign name=”AssignInput”>
<copy>
<from>ora:getAttachmentContent(‘ReceiveMail_InputVariable’,’body’
,’/ns3:message/ns3:attachment/ns3:Attachment[$ForEachCounter]’)
</from>
<to>$InvokeWriteFile_InputVariable.opaque</to>
</copy>
</assign>

and this leads to two files.

Here you can download the UMS workspace https://github.com/biemond/soa11g_examples/tree/master/UmsSOA