Mail Adaptor

Symptom

You are experiencing problems with the SAP XI 3.0 Mail Adapter and/or need further detailed information about its operation and configuration.
Other terms

XI30, Adapter Framework, Frequently Asked Questions, HOWTO
Reason and Prerequisites

This note serves as FAQ document for the SAP XI 3.0 File Adapter and contains answers to the most commonly asked questions about the adapter's operation and configuration. It will be updated with new information from time to time as the need arises.
Solution

1. Sender Connection

* Q: My mail messages seem to be read by the adapter but not processed. At least there is no message shown in the message monitor.

A: Please look at the adapter monitor in Runtime Workbench. You should be able to find your mail sender channel under the Mail adapter. The detail text of the channel should describe the problem.

2. Sender with XIALL

* Q: I get some exception and my mail message does not seem to be processed.

A: Please check the status of your channel in the adapter monitor. The status of the adapter monitor is updated for each polling cycle. Therefore, you should look at the status right after a new message is picked up by your channel. From this status message, you should be able to find out if the problem is due to some communication problem with the mail server or to some mail format problem.

3. Sender with XIPAYLOAD

* Q: How can I get the original sender email address and subject, etc?

A: You need to use the mail package option to get mail transport specific information in the XI payload. In SP14, there will be a new mechanism to transport transport specific information for all adapters.

* How to use MailPackage in Sender?

A: When a mail message is fetched by the sender adapter, normally the content of the mail is placed in the XI payload. This means that the mail header information such as "From", "To", "Subject" are not imported into the XI payload. When the MailPackage mode is used, the adapter constructs an XML document containing these header entries and the content. The format of this mail package XML document is defined in note 748024.

Related questions: Should I use MailPackage or ASMA?



4. Sender Asynchronous Calls

* Q: What is offered by a sender channel configured as ExactlyOnce or ExactlyOnceInOrder?

A: The quality of service setting in the sender channel does not mean that this quality of service is automatically provided between the mail server and the XI system. The setting only allows the adapter to be able to call some XI asynchronous receiver and the specified quality of service is provided between the adapter engine and the receiving component. If some error occurs

5. Other Sender related Questions

* Q: My mail messages are not picked up.

A: The mail sender channel with IMAP4 fetches only the unread messages from the specified mail box in the order they are stored. Therefore, please make sure that you have some unread messages in the top of the list (if ordered by most recent on top). After a polling cycle, you can look at the status of this channel at the adapter's monitor. This should show any error if the messages are not processed correctly. Once the messages are read but not processed correctly, they remain in the mail box but are not read in the subsequent polling cycle. You must correct the problem and delete these messages using your mail client program or reset them as unread so that they can be resend.

The channel with POP3 fetches all messages from the specified mail box in the order they are stored. After a polling cycle, you can look at the status of this channel at the adapter's monitor. This should show any error if the messages are not processed correctly. Once the messages are read but not processed correctly, they remain in the mail box and read again in the subsequent polling cycle. If the problem is permanent, you must correct the problem or delete these messages using your mail client program.

6. Receiver Connection

* Q: My mail messages does not seem to be sent out.

A: Please look at the adapter monitor in Runtime Workbench. You should be able to find your mail receiver channel under the Mail adapter. If this status is OK. Please look into the message monitor and find the audit log entries for this message. The detail text of the audit log should describe the problem.

7. Receiver Asynchronous Calls

* Q: Is it guaranteed that an XI message with quality of service ExactlyOnce will result in one mail message to be sent?

A: No. Most mail gateways do not support quality of service. Therefore, the adapter simply sends the message. If some error occurs, the message is resent.

8. Other Receiver related Questions

* Q: Some characters such as ä,ö,ü are corrupted in my mail. How can I preserve these characters?

A: First, please make sure that the payload passed to the mail adapter contains the correct characters. When XIALL or XIPAYLOAD without the mail package is used, the mail message sent out from the mail adapter represents each payload of the original XI message passed to the mail adapter. Therefore, you can analyze the problem by capturing the mail message sent out form the mail adapter. When XIPAYLOAD with the mail package is used, the mail message is created from the mail package payload of the XI message. Therefore, you must temporarily change the mode to either of the other two and capture the mail message. To capture the mail message, you can use TCPGateway described in Question "Can I monitor what my mail adapter sends or receives from the mail server?" to capture the mail message. This tool can be placed between the mail adapter and the mail server to capture the messages. The captured messages can be saved in a file. Please see the included documentation for this tool for more details.

The reason for the corrupted characters is most likely caused by the corrupted original payload or the incorrect character code setting in the payload. By analyzing the captured message, the cause of this problem can be identified.



* Q: Can I choose the name of an attachment in the mail?

A: Yes. Most mail clients use some heuristics based on some MIME headers to derive the name of an attachment. The MIME headers involved in most heuristics are Content-Type, Content-Description, and Content-Disposition. When you create an XI message, the XI payload name is automatically set in the Content-Description. If you want to change or set all of these headers, you can use the MessageTransformBean module (Note 793922) in the adapter framework.

Related questions: How can I set the file name of a mail attachment?

* Q: How can I set the file name of a mail attachment?

There are several MIME headers that play a role in how the client retrieves the file name of an attachment. Unfortunately, this behavior differs among various mail clients. The reason for this inconsistent behavior comes from the fact that this mechanism has been extended incrementally. The old way is to use the name parameter in the Content-Type header as specified in RFC1341. For example, you can set the content type of an XML attachment as:

Content-Type: application/xml; name="abc.xml"

RFC1521 discourages the use of this name parameter in anticipation of the new header Content-Disposition, which is defined in RFC1806.

With this Content-Disposition header, you can set the file name as:

Content-Disposition: attachment; filename="abc.xml"

Some clients may show the Content-Description value as the file name. The Content-Description header is typically used to associate some descriptive information to an attachment (RFC1341) as in

Content-Description: my xml file

To avoid potential interpretation problems, it is recommended to combine the use of these headers.



* How to use MailPackage in Receiver?

A: When a mail message is sent out by the receiver adapter, normally the mail header information such as "From", "To", "Subject" are taken from the channel configuration. In order to dynamically set these headers, you can use the MailPackage mode. In this case, the XI payload must be formated in the Mail Package XML format. The format of this mail package XML document is defined in note 748024.

Related questions: Should I use MailPackage or ASMA?



* My mail subject in non-ascii characters are not shown in my mail client. Is this an error?

A: The mail subject line containing non-ASCII characters is encoded in a special format that tags the encoded text with its character set name, which is utf-8. This means, if the mail client cannot display utf-8 characters, these lines are shown incorrectly. This is a limitation of the mail client.



* Can I set Cc and Bcc headers?

A: These headers are supported from SP17. For earlier versions, there is no direct way to set these headers. You may configure an external mail account to forward the mail message with these additional header properties.



9. Other Questions

* Q: Which URL do I need to specify for some IMAP4 folder?

A: You can specify your folder as URL. For example, if your server is called host and your folder is called MyInBox which is in another folder called path, your URL should look like

imap://host/path/MyInBox

If your server runs on another port than the default IMAP4 port (143), your URL can be written as

imap://host:port/path/MyInBox

where port is the port number

* Q: Which URL do I need to specify for some POP3 folder?

A: You can specify your POP3 server as URL. For example, if your server is called host, your URL should look like

pop://host/

If your server runs on another port than the default POP3 port (110), your URL can be written as

pop://host:port/

where port is the port number

* Q: How can I configure my sender channel for my SMTP server?

A: You can specify your SMTP server as URL. For example, if your server is called host, your URL should look like

smtp://host/

If your server runs on another port than the default SMTP port (25), your URL can be written as

smtp://host:port/

where port is the port number

* Q: Which user authentication mechanism is supported by the sender adapter?

A: The plain authentication and the CRAM-MD5 based authentication are supported(CRAM-MD5 support from SP11). The client certificate based authentication is not supported.

* Q: Can I use SSL for the connection to my mail server?

A: Yes. You can use URL imaps://... for IMAP4 over SSL, pops://... for POP3 over SSL, and smtps://... for SMTP over SSL. If the ports differ from the respective default ports (993, 995, 465, respectively), they should be given in the URL.

* Q: My sender adapter is still not working. What can I do?

A: Please open a problem report, describe the problem, and provide the necessary information. See question "Which information must be included in a problem report?".

* Q: What is the purpose of the XIALL mode?

A: This mode allows the transport of an XI message over some mail gateways. You can configure a mail rerceiver adapter at one XI system and a mail sender adapter at another XI system to transport XI messages between these two systems. All the information contained in the original XI message at the first system is reconstructed at the second system.

* Q: What is the purpose of the XIPAYLOAD mode with MailPackage?

A: The mail package format (Mail) allows some of the mail transport specific information to be included in the XI payload. For specific usage, please refer to "How to use MailPackage in Sender?" and "How to use MailPackage in Receiver?".

Related questions: Should I use MailPackage or ASMA?

* 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.



* Q: My receiver adapter is still not working. What can I do?

A: Please open a problem report and provide the information given in the answer to question "Which information must be included in a problem report?".

* Q: Can I monitor what my mail adapter sends or receives from the mail server?

A: The mail protocols such as IMAP4, POP3, and SMTP are TCP based protocols. You can configure any TCP gateway or monitor tool to capture the data.

You can find a tool called TCPGateway in the attachment section of the SOAP Adapter FAQ note 856597. Please see tcpgw.zip for more details.

* Q: Which information must be included in a problem report?

A: The following information must be included:

o Description (participating components and concrete problem)

o Adapter Version SP and patch numbers of SAPXIAFC and SAPXIAF

o For receiver problems

The channel setting

The message entry from the adapter's message monitor in Runtime Workbench.

The XI message that is passed to the adapter

The mail message that is posted to the mail server if available

The vendor information of the mail server

o For sender problems

The channel setting

The message entry from the adapters' message monitor or from the error message folder in Runtime Workbench

The mail message that is fetched by the adapter

The XI message that is passed to the adapter engine if available

The vendor information of the mail server