UMS Adapter - All about email attachments

SOA Suite - 11.1.7.6

A lot has already been written at this blog about how to configure UMS Adapter and read attachments from it. Hence this post is just to describe additional points to read/process the attachments. The post assumes that you're able to receive the incoming email using UMS Adapter successfully and able to get the BPEL process instantiated.

How to Read/Fetch the Attachment?

BPEL 1.1 - It's fairly simple in BPEL 1.1 using the following syntax in the Assign Activity.

• Receive1_ReceiveNotification_InputVariable - is the variable created out of Receive Activity connected to Inbound UMS Adapter
• Body, ns2:message/ns2:attachment - are the variable part and element inside the variable respectively created by default.
• ns2:/attachment [1] is used to read the first attachment always. You may want to loop through all the attachments and choose the one you desire based on Content-Type or Attachment Name or etc. Read my another post on how to retrieve the attachment names from the Email attachments.
• CustomAttachmentVariable - is the custom Element type variable of Attachment Message with the namespace {http://platform.integration.oracle/blocks/adapter/fw/metadata/ReadEmailAttachment}message. I created this variable simply to complete the Assign. You may further access this variable for extracting the contents of the attachment or writing to file etc.

BPEL 2.0 - It's not a rocket science here as well, just one thing to note is that default BPEL 2.0 variable format ($Receive1_ReceiveNotification_InputVariable.body/ns2:attachment) (note the . between InputVariable.body ) is not supported by the ora:getAttachmentContent() function. So you have to explicitly write the variable in the BPEL 1.1 format. You can assign intially from the Design View and then go into BPEL source and modify the default Assign code generated to below: (ora:getAttachmentContent('Receive1_ReceiveNotification_InputVariable' , 'body','/ns2:message/ns2:attachment[1]')) - note the body part.

 

What to do with the Attachment read?

There are basically 3 things that you may want to do with the attachment just read. To keep this post concise, they have been put into separate posts.

• Write the incoming attachment to another file
• Forward the incoming attachment
• Parse the attachment content into XML for further use within the process

Please feel free to navigate through and let me know if any doubts! Happy Emailing!

Write Email Attachment to a File

To be able to do this, you must be able to first retrieve the attachment from the Receive variable as described in the previous post. Also this post assumes that you have some basic knowledge of BPEL, Adapters and XSLT functions. Just for understanding, by default, Attachment is stored in the ATTACHMENT table in SOA_INFRA user schema and the table's row reference (called href) is received in the Receive variable. When ora:getAttachmentContent() function is called, it fetches the attachment content from the table in base64 encoded format and assigns to the target custom variable.

There are 2 ways you can write incoming attachment to an external file.

ora:writeBinaryToFile()

There's inbuilt function ora:writeBinaryToFile() that automatically extracts the attachment from the Attachment href (in the binary format) and writes to the specified target file (hence you don’t need to use ora:getAttachmentContent() in front of it). Follow the below steps to write it to file using ora:writeBinaryToFile() .

• If you're starting from the beginning, then create a new Simple BPEL project with Define service later option
• Drag and Drop the UMS Adapter and configure the adapter. It will automatically create the schema for UMS Adapter and WSDL file.
• Go to BPEL process and drag and drop Receive Activity on the swim lane. Connect the activity to UMS Adapter and create a Receive variable ( Receive1_ReceiveNotification_InputVariable )
• Create another variable of the type attachment and name $CustomAttachmentVariable
• Next drag and drop the Assign Activity and drop Expression on the $CustomAttachmentVariable on the Target side
• Assign the following in the Source side. In BPEL source , comple Assign statement would look like as shown below. -
• Receive1_ReceiveNotification_InputVariable','body','/ns2:message/ns2:attachment[1] - is the BPEL 1.1. notation of the variable as mentioned earlier. Even in BPEL 2.0 you must use the same format.
• /u01/app/oracle/userdir/NewAttachment.xml - specifies the full path of the file where attachment content needs to be written
• $CustomAttachmentVariable/ns2:attachment - is just meant to complete the Assign Statement. It doesn’t have any significance in writing the file. Run the project, it should work.

Using the File/FTP Adapter

The other way is to use a File Adapter through a opaque schema variable. Follow the below steps to write a file with the content retrieved from attachment. Note - You don’t have any control over the content of the file, so whatever comes in the attachment will be written directly. If you want to parse the content of the file before write read my another post - Parse and Read contents of Email Attachment in the BPEL process.

• Drag and Drop a File adapter to the above project (created with UMS Adapter) and choose option Native Format Translation is not Required (Schema is Opaque).
• Go to BPEL, drag and drop an Invoke activity, connect to File Adapter just created and create an Invoke Variable (Invoke1_Write_InputVariable.opaque )
• Assign the Attachment content to the variable just created as shown below. Note - we are using ora:getAttachmentContent() to first fetch the content in opaque base64 format which is then assigned to the opaque variable of the File Adapter.
• Run the project, it will write the attachment content in a file with the name specified in the File Adapter. You can also retrieve the name of the attachment and write with the same name if required. Read post - How to retrieve name of the Email Attachment .

Let me know if any issues and I'll try to help!

Export a SOA project from the FMW Console

Once projects deployed, they surely show up on the FMW Console but is the reverse possible? I mean is it possible to get the code of the project back from the deployed project that you see on the FMW console? Fortunately yes, it is possible. Follow the below steps to achieve the same.

- Navigate to your composite in FMW console and in the SOA Composite menu on top middle click Export.

- Choose the default option Option 1 and click again Export.You can try with other options too though.

- It will extract your project in .jar file and offer you to save it. Save the file to your local machine.
- Extract this jar file using Winzip into some directory and it'll create the files of your project. Note : There is no project (.jpr) or application (.jws) file still after extraction.
- Hence, you need to create a dummy application or you can use any existing application to create a New project in Jdeveloper with the same name as of your composite. In my case, HelloWorld.
- Once the project is created, copy the contents of the extracted directory above into the new project directory from the physical location.
- Refresh your project from Jdeveloper after copying and It's ready.

Very small but useful learning originated from someone's question.

String replace() function in BPEL XSLT

First of all a very Happy New Year to all the readers and the readers to come. May this year brings more prosperity and unending happiness for all across the globe.

This post originates from my recent cerebral exercise of pondering over the best way to replace the occurrence of a string inside another string in XSLT. Especially in BPEL which doesn't have this inbuilt string-replace() function and hence we're bound to have something of our own, this was worth thinking. However, this resulted in additional findings too but with due respect to this post I'd like to keep them with me for the time being. So following lists the ways to have something of our own that can do string replacement. You can choose the best way based on your requirements.

• Write an XSLT template for string replace function and call this template whenever string replacement is required.
• Create your own Custom XPath function for String replacement that can be imported in JDeveloper and used across the whole developer team
• Harness the capabilities of using Java classes in XSLT. This is the simplest method and I'll explain this in just 2 steps, attributed to its simplicity.
• Create a namespace in XSLT for the Java String class to be used (let's prefix this as  :strClass).
• Use replaceAll() function of the String class referenced above as highlighted under. And the job is done.

Please note that any function of the String class can be used above and also any of the Java classes can be referenced in the similar way e.g. Math, DOMParser, Integer etc.

Once again Happy New Year and Happy Learning....

MQ Adapter and SSL - Part 1

Oracle MQ Series Adapter enables applications to connect to MQ Series queue managers and enqueue/dequeue messages to/from the Queues. MQ Series supports secure communication through the use of SSL. SSL stands for Secure Socket Layer. Oracle MQ Series Adapter can be easily configured to support SSL to secure the data-communication between Adapter and Server.

The article further explains some general concepts of SSL on MQ Adapter and points how you can enable SSL on Oracle MQ Adapter.

There are 2 types of SSL that can be configured on MQ Adapter:

One-Way SSL: 

In this SSL pattern, only the server gets authenticated. This ensures that the server to which MQ adapter is connecting is valid and correct. When MQ Adapter connects to MQ server, it requests the MQ server-certificate. On providing the certificate by MQ server, MQ Adapter verifies and matches it against the list of certificates available with it in its store. If the certificate match is found, the certificate is considered valid and the SSL connection is established.

Two-Way SSL:
In two-way SSL, both Client and Server are authenticated. The connection process is very similar to One-way SSL except that client is also authenticated in two-way SSL. When MQ Adapter connects to MQ server, it requests the server-certificate. MQ server provides the appropriate certificate. This certificate is verified by the MQ Adapter against the list of certificates available with it. After this certficate is validated by MQ Adapter (client), MQ server (server) then requests the client certificate to ensure that the requesting client is also valid. MQ Adapter, then, presents its certificate to MQ server which is verified by the server against the list of certificates available with it. If both the client and server certificates are found valid, SSL connection is established.

Two-way SSL is always enforced by the server. Hence, to enable two-way SSL on MQ Series, MQ Server needs to enforce Two-way SSL on incoming channel. On the server side, set the property Authentication of Parties initiating connection to Required as shown in the screenshot. This will enforce the clients connecting to it to present their certificates for validation before an SSL connection can be established.

Also ensure that this channel must be of Server-connection type. Contact your MQ Server Administrator to confirm this.

Further, to configure One-way or Two-way SSL on MQ Adapter and simultaneously keeping this post short and sweet, follow another post Enabling SSL on MQ Series Adapter - Part 2.

Enabling SSL on MQ Series Adapter - Part 2

I've already explained the basic concepts in MQ Adapter and SSL - Part 1. This post explains how you can configure your MQ Adapter to use One-way or Two-way SSL.  To enable One-way or Two-way SSL on MQ Adapter, following steps need to be followed. I'm outlining the simplest possible steps. Once understood, they can be modified based on your security needs.

• Get the Public certificate (.DER, .CER) of the MQ Server Queue Manager. Ask your MQ server Admin to give this to you.
• Import this certificate into default Weblogic Trust store or you custom keystore if any (all Public certs are stored here because Weblogic trusts the certs imported here) at <WL_HOME>/server/lib/DemoTrust.jks using the following command. You need the keytool utility to execute following commands.

keytool -import -alias <choose_name_for_this_entry> -file <public_cert_received> -keystore DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase

• Verify the imported certificate by running following command. Your entry should be present here. 

keytool -list -v -keystore DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase

Note: Below 3 steps are required only for configuring Two-way SSL on MQ Adapter. For One-way SSL, you must skip these steps.

For Two-way SSL, you need to provide Weblogic Public certificate to MQ server Admin team so that they can import it in MQ Server's Trust store. Follow the additional 2 steps for Two-way SSL.

1. Extract the PUBLIC certificate of your Weblogic from its identity and give this certficate to MQ Server team.

keytool -export -alias demoidentity -file WLS_PUBLIC_CERT.der -keystore <WL_HOME>\server\lib\DemoIdentity.jks -storepass DemoIdentityKeyStorePassPhrase

2. Ask MQ server Admin to import the given certificate into the Server Trust store being used by the Queue Manager that you connect to.

 3. Ensure that the Private key and Identity Keystore passwords of your Keystore are same. Hence, change the keystore password to the Private key password by executing the following command.

keytool -storepasswd -new DemoIdentityPassPhrase -keystore <WL_HOME>\server\lib\DemoIdentity.jks

• Next step is to create a simple BPEL process with MQ Adapter that connects to MQ using a JNDI configured on Weblogic Server. The key to configure SSL on MQ Adapter lies in this JNDI only.  To create a JNDI for MQ Adapter,  Follow How to create MQ Adapter JNDI . 
• Once the JNDI is configured successfully and tested with a dummy BPEL process, edit the following JNDI properties. Remember to hit Enter after updating each property.

S. No	Property Name	Property Value	Description
1	channelName	<Channel Name>	The name of the channel which is of server-conection type. Ask your MQ Server Admin to provide with this detail. Your process will connect to this channel.
2	CipherSuite	SSL_RSA_EXPORT_WITH_ RC4_40_MD5	Cipher suite that will be used for Message Encryption. Ensure that this is same as CipherSpec set on the above channel. e.g. for CipherSpec to be set on Server Connection Channel for the mentioned CipherSuite is RC4_MD5_EXPORT
3	hostName	<Host Name>	The host name of the MQ server
4	KeyStoreLocation	<Keystore Location>	For One-way SSL, specify this to the location of the keystore in which you imported the Public certificate of the MQ Server (in our example DemoTrust.jks). This property will be same as TrustStoreLocation in One-way SSL. However, for Two-way SSL, specify the location of Identity keystore (in our example DemoIdentity,jks)
5	KeyStorePassword	<Keystore Password>	Specify the password to access the above keystore
6	KeyStoreType	jks	By default this is Java Keystore (jks). Ensure you create the Keystore of the .jks type.
7	password	<Password to access MQ>	Specify the password to access the MQ Server
8	portNumber	<MQ Server Port>	Network port to connect to MQ server
9	Protocol	TLS	The algorigthm used to manage the Keys. Default Value is TLS. Keep it as it is.
10	queueManagerName	<Queue Manager name on MQ Server>	Queue Manager provides access to the queues and also transfers messages to other queue managers through message channels.
11	SSLEnable	true	Set this value to true to tell MQ Adapter to use SSL
12	TrustStoreLocation	<Keystore Location>	Provide the Trust keystore location (e.g. /dir/DemoTrust.jks) in which you imported the PUBLIC cert of the MQ Queue Manager.
13	TrustStorePassword	<Keystore Password>	Provide the password for Trust Store
14	userID	<username to connect MQ>	User Id to access MQ server
15	XATransaction	false	By default this is False

• Save the properties and Update the Adapter as given in create JNDI post.

And it's done. This will enable One-way SSL (or Two-way SSL) for your MQ Adapter communication.

Troubleshooting:

• In case you encounter any errors, set the following EXTRA_JAVA_PROPERTIES in setDomainEnv.sh (or setDomainEnv.cmd) file and restart the servers.

set EXTRA_JAVA_PROPERTIES=%EXTRA_JAVA_PROPERTIES% -Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true -Dweblogic.security.SSL.verbose=true

• This will generate verbose logs for SSL to help you diagnose the errors. See the below logs for diagnosis.

<DOMAIN_HOME>/servers/soa_server1/logs/soa_server1.log

Still if you encounter any problems, I'm happy to help!

How to create a JNDI for MQ Adapter on Weblogic

This post explains how to create a simple JNDI for MQ Adapter in Weblogic 10.3.x. This JNDI properties can be further changed to configure One-way or Two-way SSL on MQ Adapter as explained in post Enabling SSL on MQ Series Adapter - Part 2.

• Login to Weblogic Server Administration Console and navigate to Deployments > MQSeriesAdapter > Configuration Tab > Outbound Connection Pool.





• Click on New button and select javax.resource.cci.ConnectionFactory and click Next.
• Give an appropriate JNDI name and press Finish. This JNDI name will be used by your MQ Adapter inside the BPEL process. If it asks to Create/Save a Deployment Plan, Create/Save a deployment plan for this JNDI reference.
• Go back to the MQSeriesAdapter > Configuration Tab > Outbound Connection Pool and expand the connection factory  javax.resource.cci.ConnectionFactory. Click on the JNDI created by you above.





• Set the following properties for the above created JNDI. Leave the other properties to their default. Remember to hit Enter after updating each property. 

S. No	Property Name	Property Value	Description
1	channelName	<Channel Name>	The name of the channel which is of server-conection type. Ask your MQ Server Admin to provide this detail. Your process will connect to this channel.
2	hostName	<Host Name>	The host name of the MQ server
3	password	<Password to access MQ>	Specify the password to access the MQ Server
4	portNumber	<MQ Server Port>	Network port to connect to MQ server
5	queueManagerName	<Queue Manager name on MQ Server>	Queue Manager provides access to the queues and also transfers messages to other queue managers through message channels.
6	SSLEnable	false	By default this value is false. As we're not using any SSL in this post, leave this value as false.
7	userID	<username to connect MQ>	User Id to access MQ server
8	XATransaction	false	By default this is False. Keep it false unless you want to enable global transactions on this adapter.

• Save the properties by hitting the Save button at the bottom of the properties page.
• Navigate back to Deployments and check MQSeriesAdapter. Now press Update button on the top.
• On the next page, choose to Redeploy this application using the following deployment files and hit Finish.

After the JNDI is created successfully and properties are set as above, use this JNDI in a simple BPEL process to enqueue a message in MQ. If this is successful, JNDI configuration is correct.