Skip to Content

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.

/wp-content/uploads/2016/03/cfg1_904240.png

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

/wp-content/uploads/2016/03/content1_904255.png

The email received has the file as an attachment.

/wp-content/uploads/2016/03/mail1_904268.png

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.

/wp-content/uploads/2016/03/msg1_904254.png

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.

/wp-content/uploads/2016/03/mtb1_904281.png

/wp-content/uploads/2016/03/static_904280.png

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.

/wp-content/uploads/2016/03/cfg2_904323.png

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.

Parameter Value
Transform.ContentType text/plain; charset=”UTF-8″
Transform.ContentDisposition inline

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

/wp-content/uploads/2016/03/file2_904324.png

Following is the received email.

/wp-content/uploads/2016/03/email2_904342.png

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.

/wp-content/uploads/2016/03/cfg3b_905412.png

/wp-content/uploads/2016/03/module2_904340.png

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.

/wp-content/uploads/2016/03/sftp_904353.png

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.

/wp-content/uploads/2016/03/files_904354.png

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

/wp-content/uploads/2016/03/main_904370.png

/wp-content/uploads/2016/03/attachments_904371.png

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

/wp-content/uploads/2016/03/asma_905423.png

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.

/wp-content/uploads/2016/03/email3_905425.png

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

To report this post you need to login first.

10 Comments

You must be Logged on to comment or reply to a post.

  1. Vikas Kumar Singh

    Hey Eng,

    Awesome work. Even if I don’t praise the blog I have to praise the way you picked up the queried of mail adapter frequently appearing and solved in 1 shot with the blog.

    I still wish more ASMA elements are allowed and one specific requirement which I have seen a lot is filtering the mails based on subject or some other parameter i.e., the channel doesn’t pick up what we intend not to. Hope SAP considers that.

    Great work

    Regards,

    Vikas

    (0) 
    1. Eng Swee Yeoh Post author

      Hi Vikas

      Thanks for your comment 🙂 Coincidentally I was working on a similar requirement and wanted to nail down the behavior of the adapter before coming up with the solution.

      Yes, I say the few queries on filtering by subject. Maybe you can try submitting an idea for it at Ideas Place or wait for the next round of the Customer Influence project.

      Regards

      Eng Swee

      (0) 
  2. Raffael Herrmann

    Hi Eng,

    thanks for the well written article. I’ve got one more question. Will the SetMailAttachmentNameBean replace the MessageTransformBean in scenario 1 or does it have it’s own different purpose?

    Regards,

    Raffael

    (0) 
      1. Raffael Herrmann

        Hi Eng,

        I was just sending a commit to one of my open source projects, when I saw your SetMailAttachmentBean commit on Github. So I was curious about it’s functionalty. 😉

        Regards,

        Raffael

        (0) 
  3. Michael Hall

    Eng, thank you for the descriptive blog.  Scenario 2 was an exact requirement of mine.  My first couple of searches did not turn up the link to your blog, nor a useful solution.  That surprised me because this blog contains recent and very relative information about the email adapter, which we are using for the first time.  Thanks again!

    Michael

    (0) 
    1. Eng Swee Yeoh Post author

      Hi Michael

      Thanks for the feedback and I’m pleased to know that this has been helpful for your requirement.

      Searching is always a tricky bit – using the right search tool as well as the right search term. I personally use the Google Custom search as mentioned in the blog below:-

      Custom Google Search for the New SCN

      If you use the above search tool, this post would appear in the results with either of the following search terms:-

      – mail receiver without mail package – 1st result

      – mail adapter with body only – 5th result

      Regards

      Eng Swee

      (0) 
      1. Sachin Jangir

        Hello Eng,

        Hope you are doing good!

        I have a little similar requirement wherein PI Rest Adapter will pass on the attachment (may have different extension like jpg, pdf, xlsx, txt, docx and etc) content in bytearray and PI have to send a mail to the recipient with attachment.

        I have posted a question too for seeking help on this. Link: https://answers.sap.com/questions/139216/rest-to-pi-to-mail-receiver.html

        Could you please help or suggest me in this regard.

         

        Best Regards,

        Sachin Jangir

         

         

        (0) 
  4. Sam PI

    Hi there , nice article and I am working on scenario #3 and let me explain it and until now achieved via xslt mapping and I am in the process of enhancing.

    1.scenario# 1 is built already where 2 OM’s  work to update the ASMA variables and then to generate a crisp formatting of source into xhtml format.

    2.receiver mail adapter has a customer adapter module (pdfwrite) which renders PDF before the adapter sends it out.

    current requirement where I am stuck.

    1. Add a body which is static disclaimer text which matches scenario#3
    2. Add a logo to the existing scenario while rendering a PDF .

    any thoughts on this ? Your advice is appreciated in advance

    (0) 
  5. Fellipe Mendes

    Hello Eng Swee Yeoh!
    You have made a nice blog. Please, do you have any blog or tips to not use mail package in Mail Sender Scenario?

    Thank you very much!

    (0) 

Leave a Reply