Handling Attachments in Mail to File Scenario using Payload Swap Bean
In a SAP – PI, adapters converts messages from the PI Protocol (SOAP with attachments over HTTP) to the respective protocol “understandable” by application system, and vice-verse thus enabling the compatibility between the PI Integration Server and an application system.
There are many adapters categorized in SAP-PI like Mail Adapter is categorized to Technical Adapter which enables you to send PI messages to mail server or create PI messages from incoming mails. Also File Adapter which falls again in Technical category of adapters, used to read and write the files at the OS level. The OS level directory must be accessible by the service user of Adapter engine, with the appropriate read-write permission.
User sends the business document as an attachment in a mail to the desired mail server from where it is been pulled and processed in PI. Once processing is done the message is sent the target application system.
Mail Adapter will pull mail (containing attachment) from the mail server using Transport Protocol IMAP4.The content of the attachment file is converted to an XML message (SOAP Message) through the adapter. The incoming SOAP document would undergo mapping before being converted to the output structure and than this message is send to the File Adapter for sending the File to the desired path in target system.
- Create Source Message Type “MT_MAS” with data type “DT_MAS”.
- Create Target Message Type “MT_MAS_IN” with data type “DT_MAS_IN”.
- Create Outbound, Asynchronous Message interface “SI_MAS_OA” with message type “MT_MAS”.
- Similarly create Inbound, Asynchronous Message interface “SI_MAS_IA” with message type “MT_MAS_IN”.
- Create one to one Message Mapping “MM_MAS”, between “MT_MAS” and “MT_MAS_IN” as source and target respectively.
- Create Operational Mapping “OM_MAS” between outbound(SI_MAS_OA) and inbound(SI_MAS_IA) Interface using Message mapping(MM_MAS).
Note: While configuring Operational Mapping we have a check box “Read Attachment”. Checking this option we will deal attachments in mapping and thus limiting us to use PayloadSwapBean. As in our scenario we are dealing with PayloadSwapBean that’s way we left this “Read Attachment” option Unchecked.
- Create the Business Scenario and create the sender business service and receiver business service.Here I used “Mail_Adapter_Component” as both sender and receiver service.
- Configure Sender Communication Channel with Adapter Type as Mail.
- TransportProtocol: Two types of Transport Protocols are present:
- POP3 : This protocol is used to read the mail from the inbox of the mail server and delete the file after reading the mail.If using POP3 protocol the
syntax for URL will be: URL: pops://MailServerPath
- IMAP4 : This protocol read the mails from the personal folder of the mail server and will not delete, only mark the mail as unread. If using IMAP4 protocol
the syntax for URL will be: URL: imaps://MailServerPath/PersonalFolderName 2) Message Protocol: Two types of Message Protocols are present:
- XI-ALL : In this mode, all information of the XI message is put in the message text of the e-mail. The content of the XI message is the same as the
content of the RFC822 mail message which is the standard one.
- XIPAYLOAD : In this mode, the payload of the XI message is used to create the mail message. If the payload is in mail package format, the header
information is also used for the e-mail. If mail package format is not used, the header information is obtained from the adapter
3) Configure User Authentication: Checking this box will give you the fields like Username and Password which is required just for authentication while connection to the mail server. This username and password is of the user owing the mail address to which the mail is to be sent or from which mail address is the mail to be pulled.
4) Delete Message Once Read: By checking this property, you need to give the folder name in which you want the mail to be pushed once it is read i.e. once the mail is read it will be deleted from the original folder and is moved to the given folder.
5) Mail Attributes:
- Use Mail Package: For Receiver Configuration , if checked then the header details like “To” and “From” addresses will be taken from the input XML file mentioned else the header information is obtained from the adapter configuration described below.
For Sender Configuration, it doesn’t play any role.
- Keep Attachments: If we checked “Keep Attachments” in “Mail Attributes” then, the content will be sent as an attachment otherwise, the content will be sent as body of the mail.
6) Security Parameter: If you have assigned the receiver agreement a communication channel, you can specify security settings for message security. You can digitally sign and encrypt e-mails. Here, message security is based on the S/MIME internet standard (Secure Multipurpose Internet Mail Extension). The S/MIME implementation is based on the Cryptographic Message Syntax (CMS) standard, RFC 3852. For Sender this functionality is not in use.
7) Processing Parameters:
- Quality Of Service: For Asynchronous scenario “Exactly Once” is used and for Synchronous scenario “Best effort” is used.
8) Module Parameter: PayloadSwapBean moduleis used to replace the application payload of the XI message that contains the business data with another payload that is appended to the XI message as an attachment.
To ensure that the attachment that is to replace the application payload can be found, we must now specify a parameter from the MIME header.
Enter a payload attribute such as payload-name or payload-description, or an attribute from the MIME header such as content-Disposition, content-description, and so on.
Enter the value that the attribute is to have. The MIME headers of the payloads are searched in order and the system takes the first payload that meets the criteria. This payload is swapped with the application payload.
Note: Using PayloadSwapBean we can not handle multiple attachments. Thus limits us to use when we are dealing with only one attachment.
- Configure Receiver Communication Channel with Adapter Type as File.
- Configuring Sender Agreement.
- Configuring Receiver Agreement.
- Configuring Receiver Determination.
- Configuring Interface Determination.
Test the Scenario:
To Test the scenario send the mail in your mailbox as an attached file as shown in screen shot below.
Since we are using IMAP4 as a Transport Protocol so the Mail Adapter will ping to the Mail server, mail will be marked as read from the personal Folder (Mail Adapter) as shown below.
Input File: Input.xml
- Check whether our scenario is successful or not.
2) Runtime Work Bench:
Once the processing is done successfully the output file will be created on target path (/var/XEF/data/Mail)
Output File: Output.xml
General Errors regarding this scenario:
1) ConnectException: A remote host refused an attempted connects operation.
Reason: This happens while configuring the mail communication channel in URL field
we will not specify the Transport protocol we are using.
Correction: Always specify the used Transport protocol in URL field.
2) Getting Synchronous Messages in SXBI_MONI.
Reason: Using “Best Effort” in Quality of Service while configuring sender
Correction: Update Quality of Services to “Exactly Once”
3) Parameter Value Issue: Mapping is not been processed.
Reason: Using different File name than the original attached filename in mail.
Correction: The parameter value for filename should always be same as the file name we
are getting as an attachment in a mail.