Software AG Products 10.7 | Administering Integration Server | Configuring Ports | Adding an E-Mail Port
 
Adding an E-Mail Port
 
Security Considerations for E-Mail Ports
By setting up one or more e-mail ports on your Integration Server, you can receive client requests through an e-mail server (POP3 or IMAP). The client builds an e-mail that contains the name of the service to run and parameters to pass to the service. The e-mail can also contain user ID and password information.
Before adding an e-mail port, review the information in Security Considerations for E-Mail Ports.
*To add an e-mail port
1. Open Integration Server Administrator if it is not already open.
2. Go to Security > Ports.
3. Click Add Port.
4. In the Add Port area of the page, select webMethods /E-mail.
5. Click Submit. Integration Server displays the Edit E-mail Client Configuration page requesting information about the port.
6. Under Package, specify the following information:
For this parameter...
Specify...
Package Name
The package associated with this port. When you enable the package, the server enables the port. When you disable the package, the server disables the port.
If you replicate this package, Integration Server creates a port with this number and the same settings on the target server. If a port with this number already exists on the target server, its settings remain intact. This feature is useful if you create an application that expects input on a specific port. The application will continue to work after it is replicated to another server.
Alias
An alias for the port that is unique for this Integration Server. An alias must be between 1 and 255 characters in length and include one or more of the following: letters (a -z, A-Z), numbers (0-9), underscore (_), period (.), and hyphen (-).
Description
A description of the port.
7. Under Server Information, supply the following information:
For this parameter...
Specify...
Enable
Whether to enable (Yes) or disable (No) the e-mail port. The port can receive requests only when it is enabled.
Type
Type of mail server. Select POP3 or IMAP.
Host Name
Name of the machine on which the POP3 or IMAP server is running.
Port
Port on the e-mail server to which Integration Server is to connect.
For a POP3 mail server, the defaults are 110 for explicit SSL and 995 for implicit SSL.
For an IMAP mail server, the defaults are 143 for explicit SSL and 993 for implicit SSL.
User Name
Username that identifies you on the e-mail server.
Authentication
The type of authentication that Integration Server should use to connect to the specified e-mail server. Select Basic Authentication or OAuth.
*Select Basic Authentication if you want to authenticate the user on the specified e-mail server with only login credentials (username and password).
*Select OAuth to authenticate the user on the specified e-mail server using the credentials issued by the OAuth server.
Note:
This authentication type is not for e-mail ports associated with a POP3 server.
Note:
Only the Authorization Code grant type is supported for OAuth.
Note:
To obtain the OAuth credentials for Integration Server, you must first register Integration Server with the OAuth Server. For details about registering an application and obtaining the OAuth credentials, see your authorization server's documentation. If you are using Microsoft Azure Active Directory as your OAuth server, see this article.
Password
The password associated with the username that identifies you on the e-mail server. This field applies only to Basic Authentication.
Auth URL
The URL of the endpoint that Integration Server must use to request authorization code. This field applies only to OAuth.
Client ID
The unique public identifier that the OAuth server generates for Integration Server during registration. This field applies only to OAuth.
Client Secret
The unique string that the OAuth server provides to Integration Server during registration. It is only known to Integration Server and the OAuth server. This field applies only to OAuth.
Scope
The e-mail server access permissions configured for Integration Server during registration. You can specify multiple scopes separated by a space. This field applies only to OAuth.
Access Token URL
The URL of the endpoint that Integration Server must use to request an access token from the OAuth server. This field applies only to OAuth.
Redirect URL
The URL that the OAuth server must use to send authentication responses to Integration Server.
*If you are accessing Integration Server locally, enter the redirect URLs in one of the applicable formats:
http://localhost:port/WmRoot/security-oauth-get-authcode.dsp or https://localhost:port/WmRoot/security-oauth-get-authcode.dsp
*If you are accessing Integration Server remotely, use https://ISHostName:port/WmRoot/security-oauth-get-authcode.dsp.
This field applies only to OAuth.
Authorization Code
Click Get Authorization Code to receive a unique string from the OAuth Server that Integration Server requires to request an access token.
Note:
Whenever you edit the OAuth credentials for an email port, ensure to get the authorization code.
Access Token Expiry Time
Specifies the time until when an access token issued to webMethods Integration Server is valid. This field applies only to OAuth. This is a read-only field and is generated based on the access token.
Transport Layer Security
Type of SSL encryption that Integration Server uses when communicating with an e-mail server. You can configure the port to use explicit, implicit, or no Transport Layer Security.
Specify...
To...
None
Default. Use a non-secure mode when communicating with an e-mail server.
When you specify None, the e-mail server authenticates the e-mail client using only the username and password.
Explicit
Use explicit security when communicating with an e-mail server. With explicit security, Integration Server establishes an un-encrypted connection to the e-mail server and then upgrades to the secure mode.
With explicit Transport layer Security, Integration Server can communicate with e-mail servers that support and do not support SSL encryption. If the e-mail server does not support Transport Layer Security, Integration Server will disconnect the connection established to the e-mail server. You can then establish an un-secure connection with the e-mail server by selecting the None option in the Transport Layer Security field and enabling the port.
Implicit
Use implicit security when communicating with an e-mail server. With implicit security, Integration Server always establishes an encrypted connection to the e-mail server. Only clients that support SSL will be permitted access.
Truststore Alias (optional)
Optional. Alias for the truststore that contains certificates presented by the e-mail server to Integration Server. If you do not select a truststore alias, the default truststore alias specified in the watt.security.trustStoreAlias property will be used. For more information about this property, see watt.security.. For more information about truststore alias, see Creating Truststore Aliases.
Time Interval
How often (in seconds) Integration Server is to check for e-mails in the POP3 or IMAP server.
Log out after each mail check
For use with IMAP and multithreading only. If you select Yes, Integration Server logs out a read-only thread to the IMAP mail server after checking for mail on that thread. The main read/write thread to the IMAP server remains intact. If you select No, all the read-only threads remain intact. Select Yes if your IMAP server restricts the number of connections it will allow to remain logged in.
8. Under Security, provide the following information:
For this parameter...
Specify...
Run services as user
If you select Yes in the Require authentication within message field, the Run services as user field remains blank because Integration Server expects the user name and password to be in the e-mail. If you select No in the Require authentication within message field, you must enter the user under which the service is to run on Integration Server.
Require authentication within message
If you select Yes, Integration Server checks for $user and $pass parameters in the Subject line of the e-mail. The user name is the user under which the service is to run on Integration Server. If you select No, you must specify the user in the Run services as user field above.
When you select No, search icon appears next to this field. Click search icon to look up and select a user. The user can be an internal or external user.
Use JSSE
Select Yes to use the JSSE library to create a port that supports TLS 1.1, TLS 1.2, or TLS 1.3.
Select No to use the Entrust IAIK library to create a port that supports only TLS 1.0 which is not secure.
9. Under Message Processing, complete the following information:
For this parameter...
Specify...
Global Service (optional)
Service to be executed on Integration Server. This field overrides a service specified in the Subject line of the e-mail.
Default Service (optional)
Service to be executed if the e-mail does not provide a valid service in the Subject line and the Global Service field is blank.
Send reply e-mail with service output
Click Yes if you want Integration Server to send any output generated by the service to the original sender in an e-mail attachment. Click No if you do not want to do so. If the original e-mail contained multiple attachments, the reply contains an equal number of attachments.
Send reply e-mail on error
Click Yes if you want Integration Server to report any errors that occurred during service execution to the original sender in the Body portion of an e-mail. Click No if you do not want to do so.
Note:
For more information about sending e-mail notifications when errors occur, see Sending Messages About Critical Issues to E-mail Addresses.
Delete valid messages (IMAP only)
Click Yes if you want to delete a valid e-mail from the IMAP server once Integration Server has successfully received the e-mail. This setting helps prevent e-mails from accumulating on the IMAP server, possibly affecting disk space and performance. Integration Server always deletes e-mails on a POP3 server. Click No if you want to retain the e-mails on the IMAP server.
Delete invalid messages (IMAP only)
Click Yes if you want to delete invalid e-mails from the IMAP server. Click No if you do want to remove these e-mails from the server.
Invalid e-mails are those that reference services that cannot be invoked. For example, if the referenced service does not exist, the server will delete the e-mail. If the service was invoked, but encountered errors, the server considers the associated e-mail to be valid.
This setting helps prevent invalid e-mails from accumulating on the IMAP server, possibly affecting disk space and performance. Integration Server always deletes e-mails on a POP3 server.
Multithreaded processing (IMAP only)
Click Yes if you want Integration Server to use multiple threads for this port. This setting allows the port to handle multiple requests at once and avoid a bottleneck. Click No if you do not need this feature.
Number of threads if multithreading is turned on.
Tells Integration Server the number of threads to use for this port. The default is set to 0.
Note:
If the e-mail port is configured to allow multithreading and if the e-mail port receives a large number of messages in a short period of time, the e-mail port will monopolize the server thread pool for retrieving and processing messages. This will slow down the performance of Integration Server. To avoid this, you can limit the number of threads used to process messages received by the e-mail port by setting the watt.server.email.waitForServiceCompletion property. For more information about this property, see Server Configuration Parameters.
Invoke service for each part of multipart message
Specifies whether Integration Server invokes the service for each part of a multi-part message or just once for the entire message.
If you specify No, the entire e-mail is passed to the appropriate content handler and then to the specified service for execution. When you send an entire multi-part e-mail, make sure the server includes the e-mail headers from the beginning of the message, so that the content handler and/or service knows how to process the content type headers included in each part of the e-mail. See Include e-mail headers when passing message to content handler below.
If you specify Yes, Integration Server treats each part of the message individually. That is, Integration Server sends each part to the content handler and then to the specified service. When you specify Yes, you probably do not want to include the e-mail headers from the beginning of the message, because each section has its own headers that the content handler and/or the service already knows how to process. See Include e-mail headers when passing message to content handler below.
Include e-mail headers when passing message to content handler
Specifies whether Integration Server includes the e-mail headers when passing an e-mail message to the content handler. The e-mail headers are typically found at the beginning of an e-mail message. Specify Yes if you are processing a multi-part message as a single message. This ensures that the content handler and/or service can properly process the body of the e-mail. Specify No if you are processing the different parts of an e-mail individually. If you are processing a single-part e-mail, you probably do not want to include e-mail headers.
E-mail body contains URL encoded input parameters
Specifies how Integration Server treats input parameters it finds in e-mail messages. With this value set to Yes, Integration Server considers a string such as ?one=1+two=2 to be a URL encoded input parameter. It then decodes this string into an IData object, puts it into the pipeline, and passes it to the service. With this value set to No, Integration Server treats the string as plain text and passes it to the appropriate content handler.
10. Click Save Changes. If you have configured OAuth, Integration Server receives the access token and displays the Access Token Expiry Time.
Note:
Whenever you create or edit an email port, you must clear the browser cache. This applies only if you are using the OAuth authentication type.
11. On the Ports page, click Edit to change the Access Mode if necessary. You may Set Access Mode to Allow by Default or Reset to default access settings.
Note:
If you set port access restrictions, be sure the watt.net.email.validateHost server configuration property is set to true, so Integration Server honors your IP access restrictions.
For more information about setting access mode for a port and controlling IP access for a port, see Controlling Access to Resources by Port
12. On the Ports page, also check the list of ports to ensure that the status in the Enabled column is Yes. If it is not, click No to enable the port.