Forward (Email) the received Attachment via UMS Adapter

Note : This post assumes that you already have some working knowledge of BPEL and XSLT functions and you're able to retrieve the content of Email attachment as described in my previous post - UMS Adapter - All about email attachments.

There may be cases when you have received an email attachment via UMS Adapter and you want to forward the same email as-is to another recipient e.g. if received attachment is invalid then forward to same to support team for further diagnosis. Following instructions show how you can achieve the same.

• Drag and Drop another UMS Adapter (because the one you may have already was used to originally receive the Email) onto the right swimlane and select Outbound Send Notification in the Operation Type . Also check Receive Message Id as Reply . Click Next.
• On the next screen choose Type of notification = Email and assign appropriate Subject and To Email ID. You can leave From as blank. Click Next.
• Choose Message is of String type . Click Next and Finish.
• Now drag and Drop an Invoke activity and connect to the UMS Adapter which will allow to create Input/Output variables e.g. InvokeSendErrorNotification_InputVariable and InvokeSendErrorNotification_OutputVariable
• Now drag another Assign activity and place it just before the Invoke just created.
• Assign relevant text for payload string to InvokeSendErrorNotification_InputVariable > body > message > payload . You can also use html formatted text if you wish in the payload.
• Not navigate to InvokeSendErrorNotification_InputVariable > body > message > attachment > href and assign the incoming attachment href variable (ReceiveEmail_InputVariable). This variable was created as part of Receive activity when we configured previous UMS Adapter to receive the incoming email and attachment. Click OK and that's it.

The code for Assign activity is shown below for guidance.

• First from expression - the payload that you want to appear as the email message. This is html formatted just to show how you can use html formatted tags.
• InvokeSendErrorNotification_InputVariable.body/ns7:payload - Input variable created as new UMS Adapter. We're assigning into payload element of the same.
• $ReceiveEmail_InputVariable.body/ns2:attachment[1]/@href - variable created from previous UMS Adapter to receve the attachment. [1] is used to refer to the first attachment in the email in case received email has multiple attachments.
• $InvokeSendErrorNotification_InputVariable.body/ns7:attachment/@href - the variable created as part of new UMS Adapter. We're referring to the @href here which contains the reference to the attachment.

Happy Learning and let me know if any doubts!

Parse and Read the contents of Email Attachment in the BPEL process

This post assumes that you already have some working knowledge of BPEL and XSLT functions and you're able to retrieve the content of Email attachment as described in my previous post - UMS Adapter - All about email attachments.

Many a times the requirement is to parse through the content of the attachment to extract desired information out of it. As attachment read is in the base64 binary data by default, first and foremost thing is to convert it into String and then parse it into the required XSD schema. Oracle provides a function Out-of-the-box (OOTB )to do both the bits in one call. Follow below steps to parse the incoming attachment.

The simple case I have taken here is that I receive a CSV file as attachment in email and I parse it into XML for further transformations on the content.

• Create a schema of the email attachment that you want to parse using Native Schema builder. Basically that means dragging and dropping a File Adapter and create a schema with that, later cancel or delete the adapter as we only need the schema so crated. I receive a comma delimited file as attachment, hence used a delimited option to create my schema but you can also parse XML, Fixed Length any other type of file. In case of XML files, please pay attention to the XML file namespace and the target Schema namespace .
• Create a variable targetMessage of the schema created above (shown below in Examples)
• Use the OOTB function ora:doTranslateFromNative(Input Message in binary format, Relative path to the schema from composite directory, Schema Root Element Name, 'DOM' ) as shown below
• The first assign is to fetch the Attachment Content into another Custom variable of the same type
• $targetMessage - is the Element Type variable of the target schema (Root element TargetRequest) which will hold the translated message
• Once the targetMessage is formed, you can traverse through all elements of this message and carry out all desired transformation operations on this like any other XML variable.

Below shown is the structure of file and the associated code, although not full but should give an idea of the main components involved.

Example Email Attachment format :

Example Schema :

Variable Created in BPEL:

Please let me know if any issues and I'll try to help! Happy Emails!

How to retrieve name of the Email Attachment

Once you have made Attachments to work (UMS Adapter - All about email attachments) in your BPEL process and able to parse them, it may be necessary to retrieve the actual name of the email attachment read. The best way to do that is using out-of-the-box function as given below

The above should return attachment; filename="test.txt"; however, nothing is as simple in this world and to make it true, it is a known BUG:19492062. Luckily, we have a patch 1941333.1 available to apply and get going but it may be time consuming to request a patch, do the impact assessment and get it applied across all environments. Whilst that may be the ideal solution in the long term but to quickly test and retrieve the attachment name you can use property Content-Type as given under.

• ora:getAttachmentProperty() function on Content-Type returns text/plain; charset=UTF-8; name=test.txt; any additional text;
• Substring-before() and substring-after() have been done to intelligently extract string after name=
• emailAttachmentName- is a string type custom variable to store the attachment name

Quite simple till the patch is applied, or do we indeed need the patch now!

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....