SMTP Send Adapter
The SMTP Send adapter allows documents to be sent to any valid email address by using an accessible (SMTP-aware) mail server, usually the mail server of the trading partner that is running Sterling B2B Integrator.
The SMTP Send adapter does this by enabling Sterling B2B Integrator to mail (send) documents using SMTP, within Sterling B2B Integrator, to the designated mail server. The back-end mail server system examines the document and does further processing, including the actual sending of the email.
This adapter can be used when messages and documents need to be sent during the execution of a business process.
- mail.smtp.timeout=30000 (default in miliseconds) - length of the socket I/O timeout
- mail.smtp.connectiontimeout=30000 (default in miliseconds) - length of the socket connection timeout
The following table provides an overview of the SMTP Send adapter:
Category | Description |
---|---|
System name | SMTP Send Adapter |
Graphical Process Modeler (GPM) categories | All Services, Communications |
Description | The Sterling B2B Integrator SMTP Send adapter allows documents to be sent to any valid email address by using an accessible mail server (usually of the trading partner that is running Sterling B2B Integrator). It does this by enabling Sterling B2B Integrator to mail (send) documents using SMTP, within Sterling B2B Integrator, to the mail server. |
Business usage | Documents and messages are sent by email through the use of the SMTP Send
adapter. Sterling B2B Integrator mails (sends)
documents to the mail server. The back-end mail server examines the document and does further
processing. Note: For B2B applications and for transmitting EDI data, the required SMTP information
can be specified in the trading profiles and accessed in a business process by using the B2B Send
service. See B2B Send System Service.
|
Usage example | A business process runs with the trading partner information that sends/receives document(s). As part of the business process, the SMTP Send adapter picks up the primary document and sends it to the mail server, which does further processing of the document. This adapter is commonly used to send email notification about documents that have been sent or processed or need some action from the recipient. |
Preconfigured? | No |
Requires third-party files? | None |
Platform availability | All supported Sterling B2B Integrator platforms. |
Related Services | Related services include:
|
Application requirements | An internal SMTP mail server to send the email. |
Initiates business processes? | No. This adapter does not initiate business processes. This adapter cannot be used without a business process. |
Invocation | Not applicable (internal service) |
Business process context considerations | The configuration parameters and the outgoing documents are picked up by the adapter in the WFC. |
Returned status values | Values:
|
Restrictions | Three types of input document formats are supported
by the SMTP Send adapter:
|
Testing considerations | To test an instance of the SMTP Send adapter, create an SMTP_SEND_ADAPTER
configuration. Set up a business process using this adapter to send an email to a valid email
address. See SMTP Send Adapter Business Process Usage for setting up a business process. The
most frequent problems encountered are:
|
How the SMTP Send Adapter Works
The SMTP Send adapter can mail (send) documents to the back-end mail server of trading partners. The document is then e-mailed to the recipient designated in the To field of the configuration. This adapter picks up the document sent from the primary document in the business process.
The following section describes a business scenario and a sample solution using the SMTP Send adapter.
Business Scenario
A document has been sent to your trading partner for processing and you want to send an email notifying them that the document has been sent and needs action. The message that you are sending is a standard text message telling the recipient that a document has been sent and what action is needed from them.
Business Solution Example
The following example shows a simple solution to this business scenario using the GPM. This example uses a File System adapter to pick up the text document containing the message to be sent. This document becomes the primary document. Since the b2b-raw-message value is set to false, this document is sent as the body of the email.
The message has the following properties:
FROM: sender@company1.com
TO: receiver@company2.com
SUBJECT: Document Notification
The mail host address for the mail server is 000.000.1.103.
The mail port for the mail server is 25.
GPM Example
Business Process Modeling Language (BPML) Example
The following example shows the corresponding business process solution by using BPML.
Implementing the SMTP Send Adapter
- Collect the following information:
- The IP address or hostname of the mail server that you will be using to send your email
- The port for the mail server (usually this is 25)
- Valid email account(s) for the host mail server
- If SMTP authorization is required to access the mail server
- Valid username
- Valid password
- Verify this information with the system administrator to make sure that the parameters are correct and that Sterling B2B Integrator is able to access the mail server.
- Create an SMTP Send adapter configuration. For information, see Managing Services and Adapters.
- Configure the SMTP Send adapter. For information, see Configuring the SMTP Send Adapter.
- Use the SMTP Send adapter in a business process.
Configuring the SMTP Send Adapter
To configure the SMTP Send adapter, you must specify field settings in Sterling B2B Integrator and in the GPM.
Sterling B2B Integrator Configuration
The following table describes the fields used to configure the SMTP Send adapter in Sterling B2B Integrator:
Field | Description |
---|---|
Name | Unique and meaningful name for the service configuration. Required. |
Description | Meaningful description for the service configuration, for reference purposes. Required. |
Default SMTP Server | Trading partner SMTP mail server host system IP
address or hostname. This is the host where the SMTP mail server is
running – usually not the same as the Sterling B2B Integrator mail server
host. This is the SMTP mail server within the sending company. Optional.
Valid values:
Note: Can also be configured in the GPM.
|
Default SMTP Server Port | Port number for the Default SMTP Server. The port that the SMTP mail server
listens on for incoming email requests. Optional. Valid value is a valid port number. The default
port for an SMTP service is 25. Note: Can also be configured in the GPM.
|
SMTP Authentication required | SMTP mail server requires authentication. Optional.
Valid values:
Note: Can also be configured in the GPM.
|
User Name | User name for mail server authentication. Required if SMTP Authentication set to true. Valid value is a valid user name. |
Password | Password for mail server authentication. Required if SMTP Authentication set to true. Valid value is a valid password. |
Connection Retries | Number of times SMTP Send adapter tries to connect
to the SMTP mail server if the connection is not successful. Optional.
Valid value is an integer. Note: Can also be configured in the GPM.
|
Retry Interval (Sec) | Time delay between retrying the connection. Optional.
Valid value is an integer. Note: Can also be configured in the GPM.
|
Subject | Mail message subject. This appears in the subject line of the email.
Optional. Note: Can also be configured in the GPM.
|
Encoding Type | The type of encoding for the email message subject. Optional. Valid values:
Note: Can also be configured in the GPM.
|
Request for a delivery receipt notification. | Delivery receipt requested. Optional. Valid values:
Note: Delivery notification only available for mail servers that
support this option. Can also be configured in the GPM.
|
Request for a read notification. | Read notification requested. Optional. Valid values:
Note: Read notification only available for mail servers that
support this option. Can also be configured in the GPM.
|
SMIME Encryption User Certificate | Valid user certificate. Optional. |
SMIME Decryption User Certificate (System Store) | Not used in this release. Leave at default. |
SSL | The Secure Socket Layer (SSL) flag that turns on
SSL socket negotiation. Optional. Valid values:
Note: Can also be configured in the GPM.
|
Key Certificate Passphrase | Passphrase for the keystore if you are using SSL Client Authentication. Optional. |
Cipher Strength | The level of encryption applied to the message
that flows through the socket connection. Optional. Valid values:
Note: Can also be configured in the GPM.
|
Key Certificate (System Store) | Digital certificate that contains the private key
and public certificate. The trading partner trusted certificate authority
signs the certificate. Optional. Valid values: Any valid digital certificate
in Sterling B2B Integrator. Note: Can
also be configured in the GPM.
|
CA Certificates | Digital certificate that contains the trusted certificate
authority public certificate. Optional. Note: Can also be configured
in the GPM.
|
GPM Configuration
The following screen shows the graphical view of the GPM parameters for the SMTP Send adapter. The dimmed values were generated from the SMTP Send adapter configuration. All parameters are set on the Message To Service tab. No entries are required on the Message From Service tab.
All of the parameters beginning with smtp were either set or are defaults from the service configuration. To set the same values in the GPM or the business process, the following relationships exist:
SMTP Service Configuration (BPML value) | GPM Configuration (BPML value) |
---|---|
smtpAuthenticationOpt | xport-smtp-auth |
smtpEncodingType | xport-smtp-mailsubjectencoding |
smtpHost | xport-smtp-mailhost |
smtpnotifyDelivery | xport-smtp-notifyDelivery |
smtpnotifyRead | xport-smtp-notifyRead |
smtpPort | xport-smtp-Port |
smtpSubject | xport-smtp-mailsubject |
The following example shows the corresponding BPML parameters for the SMTP Send adapter as configured above.
<operation name="SMTP Send Email">
<participant name="SMTP_SEND_ADAPTER"/>
<output message="Xout">
<assign to="." from="*"></assign>
<assign to="xport-smtp-auth">true</assign>
<assign to="xport-smtp-mailBCC">Recipient@company1.com</assign>
<assign to="xport-smtp-mailCC">Recipient2@company2.com</assign>
<assign to="xport-smtp-mailfrom">sender@company1.com</assign>
<assign to="xport-smtp-mailhost">000.000.1.103</assign>
<assign to="xport-smtp-mailport">25</assign>
<assign to="xport-smtp-mailsubject">Document Notification</assign>
<assign to="xport-smtp-mailsubjectencoding">ASCII</assign>
<assign to="xport-smtp-mailto">receiver@company2.com</assign>
<assign to="xport-smtp-notify-delivery">true</assign>
<assign to="xport-smtp-notify-read">true</assign>
<assign to="xport-smtp-retries">3</assign>
<assign to="xport-smtp-retryinterval">1</assign>
<assign to="xport-tp-cakeycert-id">server:105e37:f3be012345:-52e9</assign>
<assign to="xport-tp-cipher">STRONG</assign>
<assign to="xport-tp-keycert-id">server:218e57:f3bd123456:-733b</assign>
<assign to="xport-tp-ssloption">SSL_MUST</assign>
</output>
<input message="Xin">
<assign to="." from="*"></assign>
</input>
</operation>
The following table describes the fields used to configure the SMTP Send adapter in the GPM. This lists the fields that are only set in the GPM.
Parameter Name | Description |
---|---|
Config | Name of the adapter configuration. Required. |
xport-smtp-host | Trading partner host system IP address or host name. Required if not set in the Service Configuration. Valid values: The IP address or hostname of the mail server that will be sending the email. |
xport-smtp-port | Trading partner port number. Required if not set in the Service Configuration. Valid values: The port number used by the mail server sending the email. The most commonly used port is 25. |
xport-smtp-mailfrom | Originator email address. Required when b2b-raw-message is set to false. Valid values: Valid email address for the mail server used to send the email. This address appears in the From line of the email. |
xport-smtp-mailto | Recipient email address. Required when b2b-raw-message is set to false. Valid values: Valid email address where the email is being sent. This address appears in the To line of the email. |
xport-smtp-mailCC | CC list email address. Optional. Valid values: The email address to send a copy of the email. This address appears in the CC line of the email. |
xport-smtp-mailBCC | BCC list email address. Optional. Valid values:email address to send a blind copy of the email. This address appears in the BCC line of the email. |
xport-smtp-mailsubject | Subject of the message. Optional. This information appears in the SUBJECT line of the email. |
xport-smtp-auth | Valid values:
|
xport-tp-authfile | Added using the Advanced Editor. The authfile option is being deprecated but has been kept for backward compatibility. If SMTP authorization is required, set it in the service configuration. |
b2b-raw-message | Indicates if the primary document input to the
adapter is a raw or non-raw message. Valid values:
|
xport-smtp-notify-delivery | Delivery notification requested. Optional. Valid
values:
Note: Delivery notification only available for mail servers that
support this option.
|
xport-smtp-notify-read | Read notification requested. Optional. Valid values:
Note: Read notification only available for mail servers that
support this option.
|
xport-smtp-retries | Number of times SMTP Send adapter tries to connect to the SMTP server if the connection is not successful. Optional. Valid value is an integer. |
xport-smtp-retryinterval | Time delay between retrying the connection. Optional. Valid value is an integer. |
xport-smtp-mailsubjectencoding | The type of encoding for the email message subject. Valid values:
|
xport-tp-ssloption | SSL flag that turns on SSL socket negotiation.
Valid values:
|
xport-tp-cipher | Level of encryption to be applied to the message
document that flows through the socket connection. Valid values:
|
xport-tp-cakeycert-id | Object ID (from the Trading Partner > Digital Certificate menu) that contains the trusted certificate authority public certificate. |
xport-tp-keycert-id | Object ID (from the Trading Partner > Digital Certificate menu) that contains the PrivateKey and public certificate. The certificate is signed by the trading partner Trusted Certificate Authority. |
SMTP Send Adapter Business Process Usage
This section contains additional examples using the SMTP Send adapter for sending email. Examples are included both in the GPM and in BPML. The following business process examples illustrate various modes of operation for the SMTP Send adapter.
Non-raw Message Mode with SMTP authentication
The following example demonstrates using the SMTP Send adapter with a primary document that is not in raw message format. This document needs to be either a plain text document or one that is readable as a plain text document. The adapter creates an RFC822 compliant document to send with the primary document as the plain text body of the email.
- The primary document is not in raw message format.
- You are sending email messages using mail host 00.000.00.00 on port 25.
- The email subject is set to “This is the subject.”
- The originator is stest1@co.com.
- The recipient is stest2@co.com.
- The cc is set to stest3@co.com.
- The bcc is set to stest4@co.com.
- The connection to the mail host server is established over an SSL session, using client authentication.
- The certificates are retrieved from the system using Key cert-id = server:105e37:f3be012345:-52e9.
The following example shows the corresponding business process solution using BPML.
<process name="Test_SMTP_SSL">
<sequence name="e-mail sequence">
<operation name="Send with copies">
<participant name="SMTP_SEND_ADAPTER"/>
<output message="Xout">
<assign to="." from="*"></assign>
<assign to="b2b-raw-message">false</assign>
<assign to="xport-smtp-auth">true</assign>
<assign to="xport-smtp-mailBCC">stest4@co.com</assign>
<assign to="xport-smtp-mailCC">stest3@co.com</assign>
<assign to="xport-smtp-mailfrom">stest1@co.com</assign>
<assign to="xport-smtp-mailhost">00.000.00.00</assign>
<assign to="xport-smtp-mailport">25</assign>
<assign to="xport-smtp-mailsubject">This is the subject</assign>
<assign to="xport-smtp-mailto">stest2@co.com</assign>
<assign to="xport-tp-cakeycert-id">server:105e37:f3be012345:-52e9
</assign>
<assign to="xport-tp-keycert-id">server:218e57:f3bd123456:-733b
</assign>
<assign to="xport-tp-ssloption">SSL_MUST</assign>
</output>
<input message="Xin">
<assign to="." from="*"></assign>
</input>
</operation>
</sequence>
</process>
The following example shows a sample text message sent in the non-raw message format. It is the primary document and becomes the body of the message.
This is a simple example of a text message.
This message is used to test the
SMTP Send adapter configuration with the non raw message format.
This entire text appears in the body of the e-mail.
Raw Message Format
“Raw Message” refers to an Internet RFC822-compliant message as described in the parameter table. This message contains a message envelope and message content. The message envelope contains all the information needed to accomplish transmission and delivery of the message.
When the Raw Message-Format option is selected, the primary document must be in Internet RFC822-compliant format. This message can be passed to or picked up by the business process in this format, or the message can be constructed dynamically by the business process. A common way to construct a simple dynamic message is through the use of XSLT (see XSLT Service page 713). This allows the message as well as the header (envelope) information to change as needed.
The following is an example of raw message format:
From: "John, Doe" <john_doe@e-mailaddress.com>
To: "Jane, Jones" <jane_jones@e-mailaddress.com>
Subject: Testing Raw Message
Date: Mon, 16 Feb 2004 15:51:44
MIME-Version: 1.0
Content-Type: text/plain charset="iso-8859-1";
This is a simple RFC822 compliance message.
The message envelope consists of the originator
and recipient fields, and this is the content
of the message.
The following business process sends email using mail host 00.000.00.00 on port 25. This configuration takes a raw document of the type described above or a multipart MIME document that is Internet RFC822-compliant (see Multiple Documents (email with multiple attachments)).
The following example shows the corresponding business process solution using BPML.
<process name="Test_SMTP_Using_Raw_Message">
<sequence name="Raw Message">
<operation name="e-mail Raw Message">
<participant name="SMTP_SEND_ADAPTER"/>
<output message="Xout">
<assign to="." from="*"></assign>
<assign to="xport-smtp-mailhost">00.000.00.00</assign>
<assign to="xport-smtp-mailport">25</assign>
<assign to="b2b-raw-message">true</assign>
</output>
<input message="Xin">
<assign to="." from="*"></assign>
</input>
</operation>
</sequence>
</process>
Multiple Documents (email with multiple attachments)
To send multiple documents in a single email message, an RFC822-compliant MIME message must be constructed with all the documents included. This MIME message is sent by the SMTP Send adapter using raw message mode. Please refer to MIME Service document, Appendix A, for how to construct an RFC822 compliant MIME message.
In the event that a message of this type is used, the SMTP Send adapter is configured as in Raw Message Format.
B2B Mode
B2B mode is used when trading partner information is required as part of the application. There is a specialized application of the SMTP Send adapter that is available for use when working with B2B applications. See B2B SMTP Client Adapter for information on how to use this application.
For B2B applications and for transmitting EDI data, the required SMTP information can be specified in the trading profiles and accessed in a business process by using the B2B Send service. See B2B Send System Service for more information about the B2B Send service.