Stop using Mail Package! © – Simplify your mail receiver adapter scenarios

Update 16 Mar 2016: Include additional case for Scenario 1 if main payload needs to be renamed dynamically

Update 11 Mar 2016: Enhance Scenario 3 with Java mapping to dynamically set ASMA values

Introduction

PI (in its various names and forms) has evolved and changed in over the decade or so it has been around. New functionality and enhancements are introduced at every SP, EHP and version. However, despite all these changes, some of the techniques and functionalities that are obsolete, outdated, deprecated or no longer relevant are still widely used today. One such feature is the Mail Package feature used in the Mail adapter. As stated in SAP Note 856599, it is a deprecated feature and should not be used for new scenarios. Following are the excerpts from the note itself:

The mail package is a deprecated feature that is supported for the existing scenarios and the asma attribtues should be used for new scenarios

Q: Should I use MailPackage or ASMA?

A: SP14 introuced the Adapter Specific Message Attributes (ASMA) that can be used to import and export adapter/transport specific headers into and out of XI. This is a generic mechanism for all adapters and other components such as mapping and routing can directly access or manipulate these values. The functionality provided by MailPackage is available in ASMA. Therefore, it is recommended that new scenarios use ASMA instead of MailPackage.

Usage of Mail Package increases the complexity of the development, especially when an email with body and attachments need to be generated by the mail receiver adapter. This requires manual construction of the MIME stream using Java mapping or UDFs.

In the past, even without Mail Package, it is recommended to construct the MIME stream for the above mentioned scenario as detailed in Stefan Grube‘s blog Create email with body and attachments for binary payload with Java mapping. I have repeatedly point to that blog whenever a thread arises in the forum with such a requirement.

Recently, with the availability of the functionality to debug PI’s application as detailed in Vadim Klimov‘s blog Let’s Debug! Debugging and Decompilation on-the-fly in SAP Application Server Java, I have managed to understand further the behavior of the mail adapter. Apparently, my previous understanding is incorrect and it is possible to significantly simplify mail receiver adapter scenarios when Mail Package is not used.

In this article, I will share the design and configuration required when using the mail receiver adapter without Mail Package, for the most commonly used scenarios. All these scenarios use XIPAYLOAD as the Message Protocol.

Scenario 1 – Mail with Attachment Only

The first scenario is the simplest scenario, where the main payload is sent as an attachment in the mail. There will be no content in the email body. This is the default behavior of the mail adapter.

The scenario is an SFTP to Mail iFlow. For the sake of simplicity, the configuration of the SFTP channel is not included.

a) Retain original file name of the main payload as an attachment

The mail receiver channel is configured as follows:-

i) Use Mail Package – unchecked

ii) Keep Attachments – checked

Value of Content Encoding is optional, so it is left as the default of base64.

The following is the test file that is picked up by the SFTP sender channel.

The email received has the file as an attachment.

The attachment’s name is dynamically determined based on the input file name. This is true even when ASMA is not set on the SFTP sender channel. This is because the file name is stored in the MIME header (Content-Disposition and Content-Description) of the SOAP envelope’s attachment as shown below.

b) Fixed naming of the main payload as an attachment

If the attachment name needs to be statically fixed to a certain value, this can be achieved by setting the following MIME headers using MessageTransformBean as shown below.

• Content-Type
• Content-Disposition
• Content-Description

The reason all three headers need to be set is due to differing behavior of different mail clients. This is further explained in the question “How can I set the file name of a mail attachment?” of the SAP Note mentioned in the Introduction section.

c) Dynamic renaming of the main payload as an attachment

Additionally, if the main payload needs to be renamed dynamically, the above approach can be extended as detailed in the following article

SetMailAttachmentNameBean – Setting dynamic attachment name for main payload

Scenario 2 – Mail with Body Only

For this scenario, the main payload is to be used as the email body. There will be no attachment in the email.

To accomplish this, the channel setting is similar to the above.

In order to set the main payload as the body, we need to change the MIME header’s Content-Type and Content-Disposition. This can be accomplished using MessageTransformBean with the following configuration.

The content of the previous test file is slightly modified as follows.

Following is the received email.

Scenario 3 – Mail with Body and Attachment(s)

Finally, we will construct an email with both body and attachments. In the past, this is the most complex scenario which requires MIME construction whether Mail Package is used or not. Additionally, if the content is binary, it needs to be encoded in Base64.

However, this can now be easily achieved with the exact same configuration in scenario 2. Additionally for this scenario, a Java mapping will be included to dynamically set the Email To and Subject ASMA values via Dynamic Configuration. As such, dummy values are configured in the channel.

In order to simulate a message with attachments, the SFTP sender channel is enhanced to pick up additional files, a PDF file and an Excel file.

The following logic is included using the Write Java Mapping directly in ESR! technique. In summary, it just performs a passthrough for the main payload content, and updates dynamically the THeaderTO and THeaderSUBJECT values.

public void transform(TransformationInput input, TransformationOutput output) throws StreamTransformationException {
  InputStream inStream = input.getInputPayload().getInputStream();
  OutputStream outStream = output.getOutputPayload().getOutputStream();
  try {
   // Transfer main payload content from input to output
   byte[] content = getInputStreamBytes(inStream);
   outStream.write(content);
   // Update dynamic configuration attributes
   DynamicConfiguration dynConfig = input.getDynamicConfiguration();
   // (1) Email To
   DynamicConfigurationKey emailToKey = DynamicConfigurationKey.create("http://sap.com/xi/XI/System/Mail", "THeaderTO");
   dynConfig.put(emailToKey, "abc@def.com; xyz@uvw.com");
   // (2) Email Subject
   DynamicConfigurationKey subjectKey = DynamicConfigurationKey.create("http://sap.com/xi/XI/System/Mail", "THeaderSUBJECT");
   dynConfig.put(subjectKey, "Dynamically updated email subject");
  } catch (Exception e) {
   throw new StreamTransformationException("Exception: " + e.getMessage(), e);
  }
}
private byte[] getInputStreamBytes(InputStream inStream) throws IOException {
  ByteArrayOutputStream baos = new ByteArrayOutputStream();
  byte[] buffer = new byte[8192];
  int read = 0;
  while ((read = inStream.read(buffer, 0, buffer.length)) != -1) {
   baos.write(buffer, 0, read);
  }
  baos.flush();
  return baos.toByteArray();
}

The files are uploaded to the SFTP server to be picked up.

In the message monitor, we can see that the message contains the main payload and the two attachments.

After the Java mapping is executed, the Message Attributes are updated accordingly.

And finally we received the email with the body and attachments (and their names) intact. Additionally, the email to and subject are populated with the dynamically determined values.

Conclusion

As shown above, we no longer need to resort to custom Java logic to generate email content for the various scenarios. By avoiding usage of the deprecated Mail Package, it is now possible (at least as of PO 7.4 SP08) to achieve the various mail scenarios with just configuration as well as the aid of the standard MessageTransformBean module. This will significantly reduce development effort for such scenarios.

Please note that for the purpose of this article, the mail headers (To, From, Subject, etc) have been configured as static values in the channel. It is also possible that these are dynamically determined during runtime by using ASMA and setting the corresponding Dynamic Configuration attributes prior to the execution of the mail adapter.

References

As a comparision, following are references for the other existing approaches for using the mail adapter:-

Constructing MIME stream for Mail Package with Java mapping

XI Mail Adapter: An approach for sending emails with attachment with help of Java mapping

Multiples content Email – File Attached and body text

Constructing MIME stream without Mail Package with Java mapping

Create email with body and attachments for binary payload with Java mapping

Dynamically setting the filename of the attachment using UDF

Dynamic filename in mail receiver adapter made easier