Sender Mail Adapter - Basics

Sender Email Adapter:

Download e-mails from mailboxes using IMAP or POP3 protocol.

Can access contents of mail body.

Access email attachments.

To access the mail attributes/Headers like (Subject, From, To) , we have to allow these headers in the Runtime Configuration... in order to whitelist them.

To access the attachments, Script has to be used.

No functionality to authenticate the sender of an e-mail.

--------------------------------------------------------------

Sender email adapter:

Parameters:

Address:

• 143 for IMAP+STARTTLS 
•  993 for IMAPS 
•  110 for POP3+STARTTLS 
•  995 for POP3S

Proxy Type:

Select None if you are connecting directly to the email server.

Select On-Premise if you are connecting to on-premise system.

Location ID (only if On-Premise is selected for Proxy Type) :

To connect to an SAP Cloud Connector instance associated with your account, enter the location ID that you defined for this instance in the destination configuration on the cloud side, 

or enter ${header.headername} to dynamically read the value from a header.

Protection 

Specifies the method to use to establish an encrypted (secure) connection. 

•   Off No encryption is initiated by the client. 

•  POP3S (only when transport protocol POP3 has been selected when creating the channel) The TCP connection to the server is encrypted. The S (in POP3S) stands for secure; in technical terms, TLS encryption is applied in that case. 

•  IMAPS (only when transport protocol IMAP4 has been selected when creating the channel) The TCP connection to the server is encrypted. The S (in IMAPS) stands for secure; in technical terms, TLS encryption is applied in that case. 

•  STARTTTLS Mandatory If the server supports STARTTLS, the client initiates encryption using TLS. If the server does not support this option, the connection stops with an error.

•  STARTTTLS Optional If the server supports STARTTLS, the client initiates encryption using TLS. If the server does not support this option, client and server remain connected but communicate without encryption.

Authentication :

Specifies which mechanism is used to protect user name and password combination. 

•  Plain User Name/Password The user name and password are sent in plain text. You should only use this option together with SSL or TLS, as otherwise an attacker could obtain the password. 

•  Encrypted User/Password The user name and password are hashed before being sent to the server. This authentication mechanism (CRAM-MD5 and DIGEST-MD5) is secure even without encryption. 

Folder : Specify the IMAP folder containing the mails to be read

(only if as Transport Protocol the option IMAP4 has been selected)

Selection :  Specify which mails will be processed (all mails or only unread ones).

(only if as Transport Protocol the option IMAP4 has been selected)

Post-Processing :

Specify how to handle processed mails on the server.

Note: If Post-Processing is set to Mark as Read and the poll strategy is set to poll for all mails (Selection: All), then already processed mails will be processed again at every polling interval

Value Mapping

The value mapping referencing is required when a node value of a message needs to be converted to another representation. 

For example, Weight in Company A is referred as as 'Kg' whereas in Company B it is referred  as ''Kilogram". When Company A sends message to Company B, it needs to take care of the difference in the representations of the same item.

Populate Sender Agency, Schema and Value

Value Mapping can also be imported from a .CSV file.

Separator should be Pipe " | " Operator.

UDFs Groovy Script in Message Mapping

 The execution mode for functions are supported by two types: 

● Single value -

Here, the Function Return type can only be String

Template:

-----------------------------------------------------------------------------------------------------------------

import com.sap.it.api.mapping.* 

def String extParam(String P1,String P2,MappingContext context) 

{ 

 String value1 = context.getHeader(P1); 

 String value2 = context.getProperty(P2); 

 return value1+value2; 

} 

-----------------------------------------------------------------------------------------------------------------

● All values of context -

• No return statement to be used here.
• Argument 'output' is to which we can add values
• All the String inputs should be of Type Array.

Template:

-----------------------------------------------------------------------------------------------------------------

import com.sap.it.api.mapping.* 

def void extParam(String[] P1,String[] P2, Output output, MappingContext context) 

{ 

String value1 = context.getHeader(P1);

String value2 = context.getProperty(P2); 

 output.addValue(value1); 

 output.addValue(value2); 

} 

-----------------------------------------------------------------------------------------------------------------

Database Transactions

If one of the below listed steps is contained in an integration flow, the processing of the message is executed in one transaction.

●Data Store Operations step

1. Select (in case delete=true)
2. Write
3. Get (in case delete=true)
4. Delete

●Usage of Write variables

●Aggregator step

●Content Enricher

In case of an error, the whole process is rolled back and the original state is being re-established. That means, data from failed processes remain and, in case message processing fails, customers normally cannot access data about the failed processing (due to the roll-back).

In case an error is propagated back to the calling component, all data that have been written in the course of the (failed) transaction are being removed (in other words: not persisted in the database). For the calling component, an error implies, therefore, to restart the integration flow.

Transactional processing is also to be considered in scenarios that contain asynchronous decoupling.

 Let’s assume integration flow A contains a Data Store Operation step. Integration flow B contains a Select operation on the Data Store and runs into an error. 

In that case, that data is preserved that has been written to the database by integration flow A. 

This behavior makes sense in particular when you consider the case that integration flow B changes or deletes the data that has been stored by integration flow A. In case integration flow B fails, the original data from integration flow A can be retrieved.

Additional Exchange Properties in CPI

• SAP_CorrelateMPLs

You can use this property to specify whether message processing logs (MPLs) are to be correlated with each other using a correlation ID.

By default, MPL correlation is switched on. To specify this property, select Constant as Type and enter True or False as Value.

• SAP_ReceiverOverwrite

• SAP_ErrorModelStepID

You can use this property to set a Model Step ID for an integration flow step. This identifier is required to relate to an integration flow step in error handling.

• SAPJMSRetries

Contains the number of retries of a JMS message.

You can use this property to specify that the behavior of the integration flow changes depending on the number of retries that are actually performed. For example, you can configure a scenario where a mail is sent to an administrator with the message as an attachment and the integration flow is terminated successfully after a specified number of retries.

• SAPJMSAlerttime

Specifies the time when an alert needs to be sent.

• SAPJMSRetryAt

Specifies the time when a JMS message must be retried.

• SAP_MessageProcessingLogCustomStatus

You can use this property to set an at most 40 characters alphanumeric custom status for the current message processing log. The value is transferred as CustomStatus attribute to the root part of the message processing log and then stored in the message processing log header table.

Additional Message Headers in CPI

We can use the following headers under Message Header :

●SAP_ApplicationID

When you monitor the messages at runtime, you can search for all messages whose defined SAP_ApplicationID has a specific value (displayed as the MessageID attribute in the Message Monitoring editor).

●SAP_Sender

●SAP_Receiver

●SAP_MessageType

You can use this property to categorize messages.

●SAP_MessageProcessingLogID

Can use this property to read the ID of the message processing log (no write access supported).

If you have specified SAP_Sender or SAP_Receiver, the corresponding values are displayed in the message processing log. If you change the SAP_Receiver value during message processing, all values are added to the receiver field in the message processing log as a comma-separated list. If you don't want this behavior, you can specify the exchange property SAP_ReceiverOverwrite, as below:

-----------------------------------------------------------------------------------------------------------------------------

SAP_ReceiverOverwrite   (Exchange Property)

Headers that are added to a message using the SAP_Receiver header element during message processing are appended to the message processing log (MPL).

This behavior is helpful in scenarios like,the multicast pattern, for example, where a message is sent to several receivers and all receivers are to be collected in the MPL (not just the last added header).

By setting the SAP_ReceiverOverwrite exchange property to true, you can change this behavior in such a way that only the last added header is shown in the MPL. Note

Example configuration:Name: SAP_ReceiverOverwriteType: ConstantValue: True

-----------------------------------------------------------------------------------------------------------------------------

Headers and Exchange Properties

Message Header:

This is transferred as part of Message Headers.

If using an HTTP-based receiver adapter, these parameters are converted to HTTP headers and transferred as such to the receiver.

Content Modifier helps to manipulate the Headers transmitted to the Receiver system.

-----------------------------------------------------------------------------------------------------------------------------

Note: If the message header exceeds a certain value, the receiver may not be able to accept the inbound call (this applies to all HTTP-based receiver adapters). The limiting value depends on the characteristics of the receiver system, but typically ranges between 4 and 16 KB. To overcome this issue, you can use a subsequent Content Modifier step to delete all headers that are not supposed to be part of the outbound message.

-----------------------------------------------------------------------------------------------------------------------------

Exchange Property:

Its like a Data Container.  

Not transmitted to the Receiver system (scope is only within the iFlow)

Use cases:

To access certain element in the payload to derive some data.

To define some placeholders and depending on the content of the message, it will be set dynamically.

-----------------------------------------------------------------------------------------------------------------------------

Headers Relevant for Message Splitting:

• CamelSplitIndex

Provides a counter for split items that increases for each Exchange that is split (starts from 0).●

• CamelSplitSize

Provides the total number of split items (if you are using stream-based splitting, this header is only provided for the last item, in other words, for the completed Exchange).●

• CamelSplitComplete

Indicates whether an Exchange is the last split.

-----------------------------------------------------------------------------------------------------------------------------

Headers Relevant for Content Encoding

• CamelCharsetName

Specifies the character encoding to be applied for message processing.

Is relevant for content encoding steps.

-----------------------------------------------------------------------------------------------------------------------------

Headers Relevant for the HTTP and HTTPS Adapter

• CamelHttpUri

Overrides the existing URI set directly in the endpoint.

This header can be used to dynamically change the URI to be called.

• CamelHttpUrl

Refers to the complete URL called, without query parameters.

For example, CamelHttpUrl=https://test.bsn.neo.ondemand.com/http/hello.

• CamelHttpQuery

Refers to the query string that is contained in the request URL.

In the context of a receiver adapter, this header can be used to dynamically change the URI to be called.

For example, CamelHttpQuery=abcd=1234.

• CamelHttpMethod

Refers to the incoming method names used to make the request. These methods are GET, POST, PUT, DELETE, and so on.

• CamelServletContextPath

Refers to the path specified in the address field of the channel.

For example, if the address in the channel is /abcd/1234, then CamelServletContextPath is /abcd/1234.

• CamelHttpResponseCode

This header can be used to manually set the HTTP response code.

• Content-Type

HTTP content type that fits to the body of the request.

The content type is composed of two parts: a type and a subtype.

For example, image/jpeg (where image is the type and jpeg is the subtype).

Examples:  text/plain for unformatted text

text/html for text formatted with HTML syntax

image/jpeg for a jpeg image file

application/json for data in JSON format to be processed by an application that requires this format

-----------------------------------------------------------------------------------------------------------------------------

Note:

If transferring text/* content types, you can also specify the character encoding in the HTTP header using the charset parameter.

Here is an example of such a header:Content-Type: text/html; charset=utf-8

The default character encoding that will be applied for text/* content types depends on the HTTP version: us-ascii for HTTP 1.0 and iso-8859-1 for HTTP 1.1.

Text data in string format is converted using UTF-8 by default during message processing. If you want to override this behavior, you can use the Content Modifier step and specify the CamelCharsetName Exchange property. To avoid encoding issues when using this feature together with the HTTP adapter, consider the following example configuration:

If you use a Content Modifier step and you want to send iso-8859-1-encoded data to a receiver, make sure that you specify the CamelCharsetName Exchange property (either header or property) as iso-8859-1. For the Content-Type HTTP header, use text/plain; charset=iso-8859-1.

-----------------------------------------------------------------------------------------------------------------------------

Headers Relevant for the SFTP Adapter

• CamelFileName

Overrides the existing file and directory name that is set directly in the endpoint.

This header can be used to dynamically change the name of the file and directory to be called.

-----------------------------------------------------------------------------------------------------------------------------

Headers Relevant for the Mail Adapter

• Subject

Specifies the subject of the e-mail message.

• To

Specifies the e-mail address that the message is sent to.

• Cc

Specifies the additional e-mail address that the message is sent to.

• From

Specifies the e-mail address that the message comes from.

• Date

Specifies the date and time when the e-mail was sent.

• Content-Type

Specifies the format of the e-mail (html or plaintext)

• Message-ID

Specifies the ID that the mail system assigned to the e-mail when it was first created.

• Reply-to

Specifies the message ID of the message that this e-mail is a reply to.

• Sender

Specifies the actual sender (acting on behalf of the e-mail address stated in the From header).

• Archived-At

Specifies a link to the archived form of an e-mail.

-----------------------------------------------------------------------------------------------------------------------------

Headers Relevant for the Aggregator Step

• CamelAggregatedCompletedBy

This header is relevant for use cases with message aggregation.

The header attribute can only have one of the following values:

• timeout

Processing of the aggregate has been stopped because the configured Completion Timeout has been reached.

• predicate

Processing of the aggregate has finished because the Completion Condition has been met.

-----------------------------------------------------------------------------------------------------------------------------

Headers Relevant for JMS Messages

•  JMSTimestamp

Specifies the time when a JMS message was created.

-----------------------------------------------------------------------------------------------------------------------------

Headers Relevant for the SOAP (SOAP 1.x), SOAP (SAP RM), and IDoc Adapter

•  SOAPAction Header

This header is part of the Web service specification.

• SapAuthenticatedUserName

Contains the user name of the client that calls the integration flow.

If the sender channel is configured to use client certificate authentication, no such header is set (as it is not available in this case)

• SapIDocType <XML Response>

The adapter parses the XML Response and generates the SapIdocType header from it.

An example header would be:

• SapIDocType WPDTAX01.
• SapIDocType <XML Response>

An example header would be:

• SapIDocType WPDTAX01

-----------------------------------------------------------------------------------------------------------------------------