AttachmentSplitterBean - Split attachments into child messages

[engswee]

Update 19 Feb 2016: New parameters sequenceId for EOIO processing (courtesy of r.herrmann) and replaceMainWithAttachment for main payload replacement

Update 5 Feb 2016: New parameter filenameFromAttachmentName for additional determination of attachment's file name (courtesy of r.herrmann)

Introduction

Splitting a message into multiple messages is a common integration requirement. One of the most common approach is with multi-mapping, however this approach only works for splitting the main payload of the message and not the attachments (unless a custom Java multi-mapping is developed). The splitting feature is also available in the following adapters/modules:

• Seeburger BIC/Splitter module
• B2B Add-on EDISeparator adapter
• Sender mail adapter (available from PI/PO 7.31 SP14, 7.4 SP09)

However, all the above functionality are limited to their respective adapter/module and there are no standard module available that can split attachments into separate messages.

AttachmentSplitterBean aims to provide a generic adapter module solution that is reusable for multiple scenarios across different adapter types. It is configurable and can be used for various scenarios as described in the following Use Cases section.

Use Cases

Below are some example use cases for this module:

• Split attachments generated from files within a ZIP archive
• Split mail attachments
• Split SOAP/Proxy attachments
• Split attachments generated using "Additional Files" feature of NFS/SFTP adapter
• Split attachments generated after Java mapping

Source Code and Deployment Archive

AttachmentSplitterBean belongs in the same adapter module project as FormatConversionBean. Refer to following blog for the location of source code and/or EAR deployment file.

FormatConversionBean - One Bean to rule them all!

Module Parameter Reference

The JNDI name for the module is listed below for adding the module to the processing chain of a communication channel.

Module name = Custom_AF_Modules/AttachmentSplitterBean

Below is a list of the parameters for configuration of the module. Certain parameters will automatically inherit the default values if it is not configured.

Parameter Name	Allowed Values	Default Value	Remarks
mode	binding, channel		Required field. Determines which channel the child messages should be sent to binding = Channel is determined via lookup of matching sender agreement based on child message header details channel = Channel is determined from Object ID of channel (found under Object Properties of Comm Channel in Swing version of Integration Directory). The child message header details are determined from corresponding binding of the channel. When using this mode, ensure that the comm channel is only used in a single sender agreement/ICO/iFlow.
qualityOfService	EO, EOIO, BE		Required field. Determines quality of service for child messages
sequenceId	Uppercase string of 1-16 characters		Required field when qualityOfService = 'EOIO'. Sets sequence ID of EOIO queue
contentType			Sets the content type of the child messages. If not configured, the content type is automatically determined from the corresponding attachment's content type
storeFileName	Y, N	N	Y = Determines the filename (if available) from the content type of the attachment, and stores the filename in Dynamic Configuration attribute of the child messages
filenameFromAttachmentName	Y, N	N	Available when storeFileName = 'Y'. Y = Determines the filename from the attachment's name instead of content type. Useful when attachment is binary content.
fileNameAttr		FileName	Dynamic Configuration attribute for file name
fileNameNS		http://sap.com/xi/XI/System/File	Dynamic Configuration namespace for file name
adapterType	Valid adapter types in the PI system		Required field when mode = 'binding'. Adapter type for the channel where the child messages will be sent to
adapterNS			Required field when mode = 'binding'. Adapter namespace for the channel where the child messages will be sent to
fromParty			Available when mode = 'binding'. Sender Party of sender agreement where the child messages will be sent to
fromService			Required field when mode = 'binding'. Sender Service of sender agreement where the child messages will be sent to
toParty			Available when mode = 'binding'. Receiver Party of sender agreement where the child messages will be sent to
toService			Available when mode = 'binding'. Receiver Service of sender agreement where the child messages will be sent to
interfaceName			Required field when mode = 'binding'. Sender interface name of sender agreement where the child messages will be sent to
interfaceNamespace			Required field when mode = 'binding'. Sender interface namespace of sender agreement where the child messages will be sent to
channelID			Required field when mode = 'channel'. Object ID of the channel where the child messages will be sent to
replaceMainWithAttachment	Y, N	N	Replaces content of main payload with first attachment's content. This allows use of single iFlow for design if content of original main payload is no longer required for further processing
messageLog	pre, post		Saves a log version of the message that is viewable in Message Monitor pre = logs main message before splitting post = logs main message after splitting
logLocation			Name of log version when messageLog is populated. Location defaulted to value in messageLog if logLocation not populated

Example Configuration

To demonstrate the usage of this module, we will use a scenario whereby attachments are generated by the "Additional Files" feature of the SFTP sender channel.

iFlow 1 - Main scenario to pickup main payload

In the main iFlow, a sender SFTP channel is configured to pick up additional files as attachments. As shown below, all .txt files a split prefix are picked up. Additionally, it will also pick up files of the same name with .file1 & .file2 extensions.

The custom module is configured in the module chain. For this example, mode = 'binding' is used, therefore the details of the sender agreement where we intend to send the child messages to are required.

Note: All attachments are sent as child messages to the same sender agreement.

iFlow 2 - Secondary scenario to route generated child messages to final destination

For the secondary scenario, the sender system/interface is configured to match the values in the module parameters above. Although it is technically possible to use a sender comm channel of any type, I recommend using the SOAP channel as it works in listening mode and will execute processing only when a child message is routed to it.

Additionally, if the attachments are non-XML payloads, ensure that the SWCV of the sender interface is blank.

Testing Results

Firstly, the main .txt files and the additional .file1 & .file2 files are uploaded to the SFTP source directory.

When the files are picked up by the SFTP channle of iFlow 1, the additional files are attached in the message.

Subsequently, when the message is processed through the module, the attachments are retrieved and dispatched as new messages to iFlow 2.

In the message monitor, both the main message and child messages are displayed.

And finally, we can view the content of the two child messages generated and routed on iFlow 2. These child messages are routed to the receiver system of iFlow 2 - for simplicity purposes, the delivery to the final receiver system will not be shown here.

Conclusion

With AttachmentSplitterBean, we now have a readily available solution to handle scenarios that require processing of attachments. The modules simplifies such scenarios as the child messages can be routed to a secondary iFlow scenario and handled separately. It will no longer be necessary to develop a complex logic to handle both main payload and attachments within a single scenario. Furthermore this is available to be used in any adapter type that allows extension of the module chain.

Below are some real life scenarios where utilizing this module can simplify the design:-

• Preserve file names of input Zip file - using Java Mapping. Solution: after the Zip file is unzipped with Java Mapping to create attachments, the attachments can be split to child messages via AttachmentSplitterBean in the receiver channel of iFlow 1. In iFlow 2, DynamicAttributeChangeBean can be added in the sender/receiver channel to dynamically set the filename and target location.
• Sender file adapter - check files before transmission to PI - Solution: AttachmentSplitterBean can be used to split the main PDF file and additional TXT file. The main PDF file can be processed as normal to the target file system, while the TXT file will be processed by the second scenario to map to IDoc (any additional modules can be added to the second scenario as required).