SetMailAttachmentNameBean - Setting dynamic attachment name for main payload

[engswee]

Update 3 Jun 2016: Include alternative standard solution for setting Content-Disposition header

Introduction

In my previous post Stop using Mail Package! © - Simplify your mail receiver adapter scenarios, I covered the various mail receiver scenarios that can be achieved without manually constructing the MIME stream through Java coding.

Although those scenarios should cover most of the commonly encountered requirement, there still exist requirements that would not fit into those scenarios and thereby require some custom development.

This article supplements and extends the "Stop using Mail Package ©" approach by introducing a custom adapter module that sets the MIME header fields related to attachment names. This cannot be achieved at mapping step because the mapping APIs only allow access to the Content-Type header and not the rest. As detailed in SAP Note 856599, it is recommended that all three MIME header fields related to attachment names are set in order for mail clients to interpret the email correctly. As such, the MIME header fields are set using adapter module APIs.

Update: It has come to my attention that it is also possible to set the Content-Disposition header using standard functionality by means of Variable Transport Binding and the use of an Advanced Mode parameter - more details in Wiki below.

Dynamic Email Attachment name for Received Mails with ASMA and without using mail package

As such, it is not necessary to use this custom approach unless a particular mail client's behavior requires all three headers to be set. Of course, no harm using this as well if it's already deployed and it simplifies the development

Design Approach & Use Cases

SetMailAttachmentNameBean is primarily designed to handle dynamic setting of the file name when the main payload is to be sent as an attachment. To allow for flexibility, the file name is retrieved from the configured Dynamic Configuration attribute (which should be set prior to this module, i.e. at sender adapter or mapping step). Following are the use cases for this module:-

• Non file-based sender adapter scenarios (i.e. other than NFS, FTP, SFTP)
  • As described in Scenario 1 of the previous post, the file name is set in the MIME header of the SOAP envelope. However, when non file-based sender adapters are used (i.e. REST, SOAP, RFC, etc), there is no filename available and it is normally defaulted to MainDocument.xml.

• File-based sender adapter scenarios that require dynamic changing of original file name
  • Although the MIME headers are set with the file name for file-based sender adapters, there might be requirements to change the name dynamically to something else in the email's attachment.

Source Code and Deployment Archive

SetMailAttachmentNameBean 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/SetMailAttachmentNameBean

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.

Due to differing behavior of mail clients, the module includes parameters for turning off modification of each MIME header if required. By default, all three MIME headers will be set.

Parameter Name	Allowed Values	Default Value	Remarks
attribute		FileName	Dynamic Configuration attribute for file name
namespace		http://sap.com/xi/XI/System/File	Dynamic Configuration namespace for file name
setContentType	Y, N	Y	Sets the MIME header Content-Type to:- mimeType; name="<filename>"
setContentDisposition	Y, N	Y	Sets the MIME header Content-Disposition to:- attachment; filename="<filename>"
setContentDescription	Y, N	Y	Sets the MIME header Content-Description to:- <filename>
mimeType	Valid MIME types	application/xml	MIME type used as the prefix in Content-Type.

Example Scenarios

Below are some sample scenarios of the module's usage based on the use cases mentioned above.

Scenario 1

SOAP to Mail scenario, where the main payload will be sent as an attachment in the email (with no body).

Design

To simulate the setting of the file name in the Dynamic Configuration attribute, a simple passthrough Java mapping is used to set the filename as follows.

Configuration

The channel configuration is similar as per the previous post.

For the module chain, SetMailAttachmentNameBean is used in default mode without any parameters configured.

Testing

The following payload is sent via SOAP UI to the SOAP sender channel.

As shown in the SOAP envelope, the file name is defaulted to MainDocument.xml.

After the mapping step, the file name is stored in the Dynamic Configuration attribute.

The audit log shows the MIME headers being populated by the adapter module.

And finally, the email received by the mail client shows the dynamically set file name for the original main payload sent via SOAP.

Scenario 2

For this scenario, it will be a File to Mail passthrough scenario. The extension for the file name has to be changed with an additional timestamp.

Design

A passthrough scenario from SFTP to Mail.

Configuration

In the SFTP sender channel, the ASMA is set to capture the source file name.

In the mail receiver channel, we will configure SetMailAttachmentNameBean to use the namespace configured above. The MIME type is also configured.

To achieve dynamic naming of the file name in this passthrough scenario, we will utilize DynamicAttributeChangeBean to change the extension and add a timestamp.

Testing

To test, we will drop the following file into the SFTP source folder.

From the audit log, we can see that the file name has been dynamically changed and subsequently the MIME headers are populated with the new file name.

And finally, the mail client displays the email with the correct attachment name.

Conclusion

As shown above, with the usage of SetMailAttachmentNameBean, we can further extend the "Stop using Mail Package ©" approach to other scenarios without additional coding to construct the MIME stream.