To properly configure the E-mail BIC and optimize it for your particular needs, you must edit the EmailBic.config file installed on the BIC Manager host system in <EPX>\bin\agents\ <hostname>.
To configure the E-mail BIC to either use the SSL or TLS for a secure inbound or outbound transaction, refer to Configuring SSL/TLS.
The EmailBic.config file has an SMTP default 'from' e-mail address used for outgoing e-mails. The unit of the inbound mail-polling interval is in seconds.
The code sample below displays the default EmailBic.config file contents:
# Available threads
minThreads=1
maxThreads=100
# The smtp default 'from' e-mail address, which is used for
# outgoing e-mails. sys.smtp_from_email_address=name@domain
# The inbound mail polling interval in seconds
sys.inbound_mail_poll_period=60
# Specifies the number of times the BIC should retry to connect
# if the InboundStore failed due to an
AuthenticationFailedException. # set the value to 0 if no retries are to be attempted
sys.retry.count=15
# Specifies an underscore to dot notation conversion or
vice-versa
# "sys.workitem.property.delimiter=." - will do
underscore to dot conversion
# "sys.workitem.property.delimiter= " - no conversion
will be done for null or empty space value
sys.workitem.property.delimiter=. # contains the server certificate chain
sys.truststore.file=
sys.truststore.password=changeit
# contains the client certificate chain
sys.keystore.file=
sys.keystore.password=changeit
# comma separated list of SSL providers
ssl.provider.list=com.sun.net.ssl.internal.ssl.Provider
internationalization.encodingname=ISO-8859-1 Thread Configuration
The minThreads and maxThreads parameters are used to control the number of concurrent threads. As threads are created, they are added to a pool. The minThreads and maxThreads settings determine the size of this pool.
- minThreads is the minimum number of instances of the BIC that will be created. The lower the minThreads value, the more time will be needed for the BIC to start a new instance. By increasing the minThreads value, memory usage is increased but processing time is decreased when a BIC instance is required. A value of zero (0) means that the thread pool can become empty when no work is done. The valid values are from 0 to 32767, with 0 as the default value.
- maxThreads is the maximum number of instances of the BIC that will be created. By increasing the maxThreads value, the maximum number of concurrent BIC instances is increased, denoting that a higher volume of work can be passed to this BIC. Increasing the number too high could cause the BIC to consume the system resources on the server or servers hosting the BIC Manager and the instance of the EPX Application Server being used. The maxThreads should have a value of at least one (1), so that at least a thread can be created to process work items. The valid values are from 1 to 32767, with 32767 as the default value.
If minThreads is greater than maxThreads, their values will automatically be swapped and a warning will be displayed in bic.log.
Connection Retry Configuration
The value of sys.retry.count specifies the number of times the BIC should retry to connect if an inbound e-mail failed due to some authentication errors.
The value of sys.retry.count is set to 15 by default; hence, the system will attempt to connect for up to 15 times in case of inbound e-mail failure.
Setting the sys.retry.count value to 0 instructs the system not to retry to connect at all.
Default Outbound E-mail Return Address Configuration
When configuring an E-mail BIC activity to send e-mail, one of the parameters is the e-mail's From address. If no address is entered, the E-mail BIC uses the default outbound return address indicated in the EmailBic.config file. Before using the E-mail BIC to send e-mail, you should configure this address accordingly. Upon installation, the default address is name@domain. Change this address to the address you would like to use, and then remove the spaces before and after the equal sign, so that the key/value pair has the format:
sys.smtp_from_email_address=<your_address>@<your_domain>
Inbound Mail Polling Interval Configuration
When using an E-mail BIC activity as a starting point in a flow, by default it checks for new mail every 60 seconds. You can shorten or lengthen this polling interval by adjusting its value in the EmailBic.config file. To do this, change the value of the sys.inbound_mail_poll_period key to the desired number of seconds.
Underscore to Dot Conversion
Keys in the message body of inbound e-mails can make use of the conversion from underscore to dot notation.
By default, the sys.workitem.property.delimiter is equal to "." to convert all occurrences of underscore in the work item property keys to dot.
Setting the sys.workitem.property.delimiter to null or empty space value results to no conversion.
Keystore and Truststore Configuration
The EmailBic.config contains the keystore and truststore files which contain the public and private keys for authentication and data integrity. Modify the location and password of the truststore and keystore files for the server or client certificate chain to reflect the appropriate settings specified after generating the keystore and truststore.
# contains the server certificate chain
sys.truststore.file=d:/Enterworks/EPX/bin/certs/server.keystore
sys.truststore.password=changeit
# contains the client certificate chain
sys.keystore.file=d:/Enterworks/EPX/bin/certs/server.keystore
sys.keystore.password=changeitRefer to Configuring SSL/TLS for information on creating and verifying the keystore and truststore files.
Configuring SSL/TLS
The E-mail BIC user can enable a secure E-mail connection by setting up E-mail BIC to use either SSL or TLS for a secure inbound or outbound transaction.
SSL is the common protocol for managing a secure message transmission over the internet. SSL utilizes a cryptographic system that uses two keys to encrypt data - a public and a private key.
TLS has two layers. One is the TLS Record Protocol which provides connection security with or without an encryption method, and the TLS Handshake Protocol which allows the server and the client to authenticate each other and negotiate encryption and cryptographic keys before data is exchanged between them.
Refer to Creating a Keystore File for information on how to enable the security settings for the inbound and outbound security settings.
Creating a Keystore File
This section describes how to generate the keystore file along with the truststore file using the keytool utility to allow the following: self-authentication, data integrity, and authentication services.
The keystore can manage two types of entries -- the Key Entry and the Trusted Certificate Entry. The Key Entry holds sensitive cryptographic key information in a secure, protected format; while the Trusted Certificate Entry contains a single public key certificate and can be used to authenticate other parties.
The truststore file contains the public keys which are stored as signer certificates used for authentication and data integrity. This file verifies and authenticates the legitimacy of the client operating on behalf of the user.
- Create a keystore file importing the matching certificate from the mail server. You can use the keytool utility located in your <EPX>/jre/bin folder.
- Open the keytool utility by clicking on keytool.exe. Execute the following command:
keytool -import -trustcacerts -alias <alias> -file <cert_file>
-keystore <keystore_file>
This command generates both the keystore and the truststore files.
Note: Keep in mind that the <alias> is the name you want to specify for the certificate when you import it into the keystore file. Since your keystore file may contain more than one certificate, the alias can be used to identify each individual certificate in the keystore file.
The <cert_file> is the name of your .cer file (certificate file matching the mail server's)
The <keystore_file> is the name of your .keystore file
Verifying the Keystore File
The keytool utility can also be used to verify if the certificate was successfully imported into the keystore file. To use this tool, perform the following command:
keytool -list -keystore <keystore_file>
Verify if the alias you specified during the import is included in the output. Refer to the output example below:
<alias>,<Date>,<type of entry>
Certificate fingerprint(MD5):XX:XX:XX:XX:Configuring the config.properties and/or the EmailBic.config Files
Open the config.properties or the EmailBic.config file and add the appropriate values for the keystore file path and keystore password keys under the server and client's certificate chain settings.
For a system-wide configuration which includes the E-mail Notification and E-mail BIC, add the keystore file path in the directory below:
<EPX>/bin/config.properties
To configure your settings only for the E-mail BIC, add the keystore file path in the directory below:
<EPX>/bin/agents/<machine_name>/EmailBic.config
Enabling SSL/TLS for Inbound and Outbound
After having configured and generated the files needed to ensure a secure data transmission either by SSL or TLS, you can set the security settings either for inbound or outbound by doing the following:
- On the Inbound tab, select the SSL Enabled checkbox to set the security settings for the inbound transaction to SSL;
- On the Outbound tab, select SSL in the Security options to set the security settings for the outbound transaction to SSL. Alternatively, you may choose to use instead the TLS as your secure transaction option by selecting TLS.
TLS and SSL are not interoperable. However, a message sent with TLS can be handled by a client that handles SSL but not TLS.
When using the MS Exchange Server as the mail server which is configured to use the secure SMTP, the outbound security option for the E-mail BIC should be set to TLS and not SSL.
Enabling TLS for the outbound secure setting works appropriately when using the MS Exchange Server 5.5 version.
Sending E-mail with the E-mail BIC
When an E-mail BIC activity is not the starting point in a flow, it is used for generating and sending e-mail messages. The BIC activity can generate an e-mail message using the work item property keys and values it receives from the previous activity in the process flow. An e-mail sent by the BIC can include attachments such as files that were appended to work items and files existing in the file system.
The E-mail BIC uses existing e-mail accounts for sending messages. In order to send messages generated by an E-mail BIC activity, an e-mail account must be available to the activity.
The E-mail BIC requires values for the following fields: the mail Server, the Userid, Password, the message Body, and the Result Set. In addition, the Outbound tab requires SMTP From which should contain a valid e-mail address and the SMTP Port Number field which contains the port number being used by the SMTP. The Recipient address and e-mail Subject should also be provided.
E-mail Formatting Options
On the Outbound tab of the E-mail BIC editor, the To, Cc, Bcc, Subject, and Body boxes can contain constant values, work item property table keys, or both. The use of work item property table keys allows the work item in the flow to supply the appropriate e-mail address, and allows customization of the subject line and body text. Work item property table keys must be fully qualified and enclosed within percent signs (%) to be valid.
For example, you are the Order Fulfillment manager for a software retailer called K&L Software Supply and you are using an E-mail BIC activity in a flow used for order processing, and you want to send an order confirmation e-mail to each customer after their order is received. Assume also that the work item property table includes the following keys for the customer's first name, last name, e-mail address, and order number, respectively:
customer.firstname
customer.lastname
customer.email.address
order.no In the To box, you would type:
%customer.email.address%
In the Subject box, you might type:
Order Confirmation for %customer.firstname% %customer.lastname% - Order #
%order.no%
In addition to work item property table keys, the body text can also contain HTML content if desired. <HTML> and </HTML> opening and closing tags are not required. In the Body box, you might type:
To: %customer.firstname% %customer.lastname%
Thank you for your order. We have begun processing the order and we will notify you when it is shipped. Your order number is %order.no%. Please refer to this number in any correspondence regarding your order. <EM>K&L Software Supply</EM>When the outgoing message is generated, the keys resolve to the corresponding values from the work item.
Receiving E-mail with the E-mail BIC
When used as a starting point in a process flow, an E-mail BIC activity creates a new work item for every incoming e-mail message received. The E-mail BIC activity retrieves inbound e-mail from an accessible mailbox on a POP3 or IMAP mail server that you designate, converts the e-mail into a work item, and initiates the process flow. The E-mail BIC polls mailboxes for incoming mail based on the polling frequency defined in the EmailBic.config file. At the default setting, this polling occurs once every sixty seconds. For instructions on changing the polling interval, see Inbound Mail Polling Interval Configuration.
In addition to converting an e-mail message to a work item, an E-mail BIC activity can also append any file attachments received with the message to the work item that it creates. An E-mail BIC activity can also save a copy of the e-mail message body and any attachments to an external file system.
There are three ways to use the E-mail BIC to receive messages. One, you can create a separate mailbox for each process flow that starts with an E-mail BIC activity. Two, you can configure a single E-mail BIC activity that uses a decision point activity (DPA) to invoke the appropriate subflow based on the content of the e-mail message. Three, you can also have multiple process flows start with an inbound BIC that has the same server settings.
Each process flow will have a work item created for each e-mail sent to the specified e-mail account. Each process flow should then screen the work items to ensure that only the appropriate ones are processed. The difference of this approach to the second one (DPA to route work item) is that each process screens e-mail work items and only accepts the ones it needs, rather than just route the work item to the appropriate subflow. Additional processes that use the same e-mail account can be created without any modification to the existing flows. A new name for each work item is also possible.
Dynamic Creation of Work Item Property Table Keys
Upon retrieving a new message, the E-mail BIC automatically creates a new work item, with the work item property table keys for the To, From, Cc, Bcc, Subject, and Body fields of the message. In addition, content in the body of the message can be used to create additional work item property table keys. Body content can be formatted in either of the following ways:
- Each key/value pair on a separate line. For example:
lastname=Sardinia
firstname=Diane
birth=01/01/1980
address=Main+Street
city=Arlington
state=VA- As a string, with each key/value pair delimited by an ampersand (&), and replacing spaces with the plus sign (+), for example:
lastname=Sardinia&firstname=Diane
birth=01/01/1980&address=Main+Street&city=Arlington&state=VAWhen a message is received in the mailbox specified on the Inbound tab in the E-mail BIC editor, the E-mail BIC retrieves the message, parses the message body, and generates a work item with a work item property table containing:
- Key/value pairs, which record the To, From, Cc, Bcc, Subject, and Body values from the incoming message
- Valid key/value pairs for this work item type, derived from the body of the incoming message
In the work item property table, all key names are prefixed by the result set name entered in the Result Set box on the Inbound tab. For example, for an E-mail BIC activity with a result set name of emailresults, the work item property table for the resulting work item would contain keys like the following:
emailresults.to=datapool@some-company.com
emailresults.from=joe.campbell@some-company.com
emailresults.cc
emailresults.bcc
emailresults.subject=Personal Information
emailresults.body=lastname=Sardiniafirstname=Dianebirth=01/01/80
address=Maine streetcity=Arlingtonstate=VA
emailresults.content.lastname=Sardinia
emailresults.content.firstname=Diane
emailresults.content.birth=01/01/1980
emailresults.content.address=Main Street
emailresults.content.city=Arlington
emailresults.content.state=VAYou can refer to any of these keys in subsequent flow activities.