Managed connection factory properties, WebSphere Adapter for Email

IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Services and service-related functions > Access external services with adapters > Configure and using adapters > IBM WebSphere Adapters > Email > Reference > Outbound configuration properties
Managed connection factory properties

Managed connection factory properties are used by the adapter at run time to create an outbound connection instance with the mail server.

The following table lists and describes the managed connection factory properties for outbound communication. You set managed connection factory properties using the external service wizard and can change them using the IBM Integration Designer Assembly Editor before deployment. After deployment, you can change these values using the IBM BPM or WebSphere Enterprise Service Bus Process Administrative Console.
A more detailed description of each property is provided in the sections that follow the table. For information about how to read the property details tables in the sections that follow, see Guide to information about properties.
The external service wizard refers to these properties as managed connection factory properties, and the IBM BPM or WebSphere Enterprise Service Bus Process Administrative Console refers to them as (J2C) connection factory properties.

Managed connection factory properties
In the wizard In the Process Administrative Console Description
Adapter ID
AdapterID

Identifies the adapter instance for PMI events and for logging and tracing.
Alternate email ID in case of delivery failure
alternateEmailIdInCaseOf
DeliveryFailures

Specifies the alternate email address for receiving bounced mails.
Bidi format string BIDIContextEIS The bidi format for string type business data exchanged between the mail server and the adapter.
Retry interval if connection fails (in milliseconds) entities connectionRetryInterval Specifies the time interval between the attempts to reconnect to the mail server if the connection fails.
Disguise user data as "XXX" in log and trace files HideConfidentialTrace Specifies whether to disguise potentially sensitive information by writing X strings instead of user data in the log and trace files.
Host name HostName The IP address of the host where the mail server is running.
Maximum retries on connection failure (connectionRetryLimit) ConnectionRetryLimit Specifies the maximum number of times the adapter tries to reestablish an outbound connection to the EIS.
Password Password The password for the user name associated with the mail server.
Port Port The SMTP port where the mail server is listening.
Protocol Protocol The protocol used for outbound communication with the mail server.
Response set timeout Responsetimeout Specifies the time period for which the adapter waits to receive a response from the mail server.
Secure connection enableSSL Specifies whether secure socket layers are enabled for outbound communication.
Select when antivirus or firewall software is running closeConnection Specifies whether the adapter closes the managed connection with the mail server after each request.
User name UserName The user name for the mail server used to send outbound emails.

Adapter ID (AdapterID)

This property identifies a specific deployment or instance of the adapter.

Adapter ID details
Required Yes
Default 001
Property type String
Usage This property identifies the adapter instance in the log and trace files, and also helps identify the adapter instance while monitoring adapters. The adapter ID is used with an adapter-specific identifier, EMARA, to form the component name used by the Log and Trace Analyzer tool.
For example, if the adapter ID property is set to 001, the component ID is EMARA001.
If you run multiple instances of the same adapter, ensure that the first eight characters of the adapter ID property are unique for each instance so that you can correlate the log and trace information to a particular adapter instance. By making the first seven characters of an adapter ID property unique, the component ID for multiple instances of that adapter is also unique, allowing you to correlate the log and trace information to a particular instance of an adapter.

For example, when you set the adapter ID property of two instances of WebSphere Adapter for Email to 001 and 002. The component IDs for those instances, EMARA001 and EMARA002, are short enough to remain unique, enabling you to distinguish them as separate adapter instances. However, instances with longer adapter ID properties cannot be distinguished from each other. If you set the adapter ID properties of two instances to Instance01 and Instance02, you will not be able to examine the log and trace information for each adapter instance because the component ID for both instances is truncated to EMARAInstanc.
For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After you use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If you use the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure that you set them consistently, to prevent inconsistent marking of the log and trace entries.
Globalized Yes
Bidi supported No

Bidi format string (BIDIContextEIS)

This property indicates the bidi format for string type business data exchanged between the mail server and the adapter.

Bidi format string details
Required No
Possible values IBM BPM and WebSphere Enterprise Service Bus use ILYNN (implicit, left-to-right, on, off, nominal). These five attributes comprise the format used by Windows.
Default No default value
Property type String
Usage A five-character string that identifies the bidirectional format used by the mail server.
If the mail server that sends or receives data from the server uses a different format than ILYNN, the adapter converts the format before introducing the data to the server. For the conversion to occur, you use the external service wizard to set attribute values that represent the bidirectional format used by the mail server. This is done when you configure the module for the first time.
Example
ILYNN
VRYNN
VLYNN
Globalized No
Bidi supported No

Retry interval if connection fails (in milliseconds) entities

This property specifies the time interval between attempts to reconnect to the mail server if the connection fails.

Retry interval if connection fails (milliseconds) property characteristics
Required No
Possible values Integers equal to and greater than 0
Default 60000
Unit of measure Milliseconds
Property type Integer
Usage
This property is applicable only if the value of the property “Maximum retries on connection failure” is set to greater than 0.
When the adapter encounters an error while establishing a connection to the mail server, this property specifies the time interval the adapter waits between attempts to reestablish a connection.
Globalized No
Bidi supported No

Disguise user data as "XXX" in log and trace files (HideConfidentialTrace)

This property specifies whether to replace user data in log and trace files with a string of X's to prevent unauthorized disclosure of potentially sensitive data.

Disguise user data as "XXX" in log and trace files details
Required No
Possible values
True
False
Default False
Property type Boolean
Usage If you set this property to True, the adapter replaces user data with a string of X's when writing to log and trace files.
For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After you use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If you use the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure that you set them consistently, to prevent inconsistent marking of the log and trace entries.
Globalized No
Bidi supported No

Alternate email ID in case of delivery failure

This property is used to specify an alternate email address to send a bounced email notification, in case of delivery failure due to an incorrect To address in an email message.

Alternate email ID property details
Required No
Default No default value
Property type String
Usage When an incorrect To address is specified in the email, a bounced email notification is sent to the alternate email address specified in the managed factory connection properties. This configuration ensures a backup address to receive notifications for mail delivery failures.
The alternate email address can be different from the From address.
Globalized No
Bidi supported No

Host name (HostName)

This property specifies the IP address of the host where the mail server is running.

Host name details
Required No
Default localhost
Property type String
Usage Specifies the IP address of the host where the mail server is running
Globalized No
Bidi supported No

Maximum retries on connection failure (connectionRetryLimit)

This property specifies the number of times the adapter attempts to reestablish a connection to the EIS, when the adapter encounters an error related to the outbound connection.

Maximum retries in case of system connection failure details
Required No
Possible values Integer equal to and greater than zero
Default 0
Property type Integer
Usage
When the adapter encounters an error related to the outbound connection, it attempts to reestablish a physical connection (when physical connection is not established) for the number of times specified for this property with a time delay specified in the property Retry interval if connection fails (in milliseconds) entities.
If the value is set to 0, the adapter does not validate the connection to the EIS and it executes the outbound operation. If the EIS connection is invalid, the outbound operation fails. The adapter does not attempt to reconnect to the EIS.
If the value is set to greater than 0, then during each request the adapter validates if the connection to the EIS is active.

If the connection is valid, the operation is completed.
If connection is invalid, the adapter terminates the current managed connection and a new managed connection is created (new physical connection).
If the adapter is successful in reestablishing the connection to the EIS, the outbound operation is completed otherwise the adapter generates the ResourceException after trying to reconnect for the specified number of times.

Globalized No
Bidi supported No

Password (Password)

This property specifies the password for the user name associated with the mail server.

Password details
Required No
Default No default value
Property type String
Usage Authenticates the outbound SMTP session with the mail server. IBM BPM or WebSphere Enterprise Service Bus Process Administrative Console does not encrypt the Password property the first time.
Globalized No
Bidi supported Yes

Port (Port)

This property specifies the SMTP port where the mail server is listening.

Port details
Required No
Default 25
Property type Integer
Usage
If the Secure connection (SSL) property is set to True, this property must be updated.
Globalized No
Bidi supported No

Protocol (Protocol)

This property specifies the protocol to be used for outbound communication with the mail server.

Protocol details
Required No
Default SMTP
Property type String
Usage SMTP is the only supported value for this property.
Globalized Yes
Bidi supported No

Response set timeout (ResponseSetTimeout)

This property specifies the length of time the adapter waits for receiving a response from the mail server.

Response set timeout details
Required No
Possible values Any positive integer
Default 0
Unit of measure Milliseconds
Property type Integer
Usage You can configure the outbound response time for number of specified milliseconds that the adapter waits for a response from the mail server. After the specified time period, the adapter stops waiting for a response from the mail server.
If the value is 0, the adapter continues to wait until it gets a response from the mail server.
Example A value of 5 specifies that the adapter waits for 5 milliseconds to get a response from the mail server.
Globalized No
Bidi supported No

Secure connection (SSL) (enableSSL)

This property specifies whether secure socket layers are enabled for outbound communication.

Enable secure socket layers details
Required No
Default False
Property type Boolean
Usage If set to True, the port property must be set to 465.
Globalized No
Bidi supported No

Select when antivirus or firewall software is running (SecureConnection)

Selecting this option closes the managed connection with the mail server after each outbound request. It is used when antivirus or firewall security software is running on the system where the adapter is deployed or the system that hosts the mail server.

Select when antivirus or firewall software is running details
Required No
Default True
Property type Boolean
Possible values
True
False
Usage
This property is provided because some antivirus programs consider the managed connection between the adapter and the mail server malicious. This results in the mail sent by the adapter to the mail server being blocked by an antivirus program or firewall.
If set to True, the adapter closes the managed connection after each outbound request, ensuring that antivirus and firewall software do not block emails from the adapter.
If set to False, the adapter does not close the managed connection after each outbound request. This setting might cause antivirus and firewall software to block emails from the adapter.
Globalized No
Bidi supported No

User name (UserName)

This property specifies the user name for the mail server to be used with the outbound SMTP session.

User name details
Required No
Default No default value
Property type String
Usage The mail server must be running on the host noted in this property.
Globalized Yes
Bidi supported Yes

Outbound configuration properties

Related concepts:

Outbound processing
WebSphere Application Server environment variables
Required folders for inbound processing

Related tasks:

Setting deployment and runtime properties for simple email data type
Setting deployment and runtime properties for generic email data type
Setting deployment and runtime properties for user-defined data type
Configure the module using the simple email data type
Configure the module using the generic email data type
Configure the module using the user-defined data type
Defining WebSphere Application Server environment variables

Related reference:

Guide to information about properties
Connection properties for the external service wizard
Resource adapter properties
Interaction specification properties
Activation specification properties

In the wizard	In the Process Administrative Console	Description
Adapter ID	AdapterID	Identifies the adapter instance for PMI events and for logging and tracing.
Alternate email ID in case of delivery failure	alternateEmailIdInCaseOf DeliveryFailures	Specifies the alternate email address for receiving bounced mails.
Bidi format string	BIDIContextEIS	The bidi format for string type business data exchanged between the mail server and the adapter.
Retry interval if connection fails (in milliseconds) entities	connectionRetryInterval	Specifies the time interval between the attempts to reconnect to the mail server if the connection fails.
Disguise user data as "XXX" in log and trace files	HideConfidentialTrace	Specifies whether to disguise potentially sensitive information by writing X strings instead of user data in the log and trace files.
Host name	HostName	The IP address of the host where the mail server is running.
Maximum retries on connection failure (connectionRetryLimit)	ConnectionRetryLimit	Specifies the maximum number of times the adapter tries to reestablish an outbound connection to the EIS.
Password	Password	The password for the user name associated with the mail server.
Port	Port	The SMTP port where the mail server is listening.
Protocol	Protocol	The protocol used for outbound communication with the mail server.
Response set timeout	Responsetimeout	Specifies the time period for which the adapter waits to receive a response from the mail server.
Secure connection	enableSSL	Specifies whether secure socket layers are enabled for outbound communication.
Select when antivirus or firewall software is running	closeConnection	Specifies whether the adapter closes the managed connection with the mail server after each request.
User name	UserName	The user name for the mail server used to send outbound emails.

Required	Yes
Default	001
Property type	String
Usage	This property identifies the adapter instance in the log and trace files, and also helps identify the adapter instance while monitoring adapters. The adapter ID is used with an adapter-specific identifier, EMARA, to form the component name used by the Log and Trace Analyzer tool. For example, if the adapter ID property is set to 001, the component ID is EMARA001. If you run multiple instances of the same adapter, ensure that the first eight characters of the adapter ID property are unique for each instance so that you can correlate the log and trace information to a particular adapter instance. By making the first seven characters of an adapter ID property unique, the component ID for multiple instances of that adapter is also unique, allowing you to correlate the log and trace information to a particular instance of an adapter. For example, when you set the adapter ID property of two instances of WebSphere Adapter for Email to 001 and 002. The component IDs for those instances, EMARA001 and EMARA002, are short enough to remain unique, enabling you to distinguish them as separate adapter instances. However, instances with longer adapter ID properties cannot be distinguished from each other. If you set the adapter ID properties of two instances to Instance01 and Instance02, you will not be able to examine the log and trace information for each adapter instance because the component ID for both instances is truncated to EMARAInstanc. For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After you use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If you use the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure that you set them consistently, to prevent inconsistent marking of the log and trace entries.
Globalized	Yes
Bidi supported	No

Required	No
Possible values	IBM BPM and WebSphere Enterprise Service Bus use ILYNN (implicit, left-to-right, on, off, nominal). These five attributes comprise the format used by Windows.
Default	No default value
Property type	String
Usage	A five-character string that identifies the bidirectional format used by the mail server. If the mail server that sends or receives data from the server uses a different format than ILYNN, the adapter converts the format before introducing the data to the server. For the conversion to occur, you use the external service wizard to set attribute values that represent the bidirectional format used by the mail server. This is done when you configure the module for the first time.
Example	ILYNN VRYNN VLYNN
Globalized	No
Bidi supported	No

Required	No
Possible values	Integers equal to and greater than 0
Default	60000
Unit of measure	Milliseconds
Property type	Integer
Usage	This property is applicable only if the value of the property “Maximum retries on connection failure” is set to greater than 0. When the adapter encounters an error while establishing a connection to the mail server, this property specifies the time interval the adapter waits between attempts to reestablish a connection.
Globalized	No
Bidi supported	No

Required	No
Possible values	True False
Default	False
Property type	Boolean
Usage	If you set this property to True, the adapter replaces user data with a string of X's when writing to log and trace files. For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After you use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If you use the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure that you set them consistently, to prevent inconsistent marking of the log and trace entries.
Globalized	No
Bidi supported	No

Required	No
Default	localhost
Property type	String
Usage	Specifies the IP address of the host where the mail server is running
Globalized	No
Bidi supported	No

Required	No
Possible values	Integer equal to and greater than zero
Default	0
Property type	Integer
Usage	When the adapter encounters an error related to the outbound connection, it attempts to reestablish a physical connection (when physical connection is not established) for the number of times specified for this property with a time delay specified in the property Retry interval if connection fails (in milliseconds) entities. If the value is set to 0, the adapter does not validate the connection to the EIS and it executes the outbound operation. If the EIS connection is invalid, the outbound operation fails. The adapter does not attempt to reconnect to the EIS. If the value is set to greater than 0, then during each request the adapter validates if the connection to the EIS is active. If the connection is valid, the operation is completed. If connection is invalid, the adapter terminates the current managed connection and a new managed connection is created (new physical connection). If the adapter is successful in reestablishing the connection to the EIS, the outbound operation is completed otherwise the adapter generates the ResourceException after trying to reconnect for the specified number of times.
Globalized	No
Bidi supported	No

Required	No
Default	SMTP
Property type	String
Usage	SMTP is the only supported value for this property.
Globalized	Yes
Bidi supported	No

Required	No
Possible values	Any positive integer
Default	0
Unit of measure	Milliseconds
Property type	Integer
Usage	You can configure the outbound response time for number of specified milliseconds that the adapter waits for a response from the mail server. After the specified time period, the adapter stops waiting for a response from the mail server. If the value is 0, the adapter continues to wait until it gets a response from the mail server.
Example	A value of 5 specifies that the adapter waits for 5 milliseconds to get a response from the mail server.
Globalized	No
Bidi supported	No

Required	No
Default	True
Property type	Boolean
Possible values	True False
Usage	This property is provided because some antivirus programs consider the managed connection between the adapter and the mail server malicious. This results in the mail sent by the adapter to the mail server being blocked by an antivirus program or firewall. If set to True, the adapter closes the managed connection after each outbound request, ensuring that antivirus and firewall software do not block emails from the adapter. If set to False, the adapter does not close the managed connection after each outbound request. This setting might cause antivirus and firewall software to block emails from the adapter.
Globalized	No
Bidi supported	No