Copyright © Cloud Software Group, Inc. All Rights Reserved

Receive Mail

Process Starter

The Receive Mail process starter polls a POP3 or IMAP mail server for new mail. When new mail is detected and retrieved, the Receive Mail process starter starts a new process for the process definition it resides in and passes the mail data to the next activity in the process flow.

Configuration

The Configuration tab has the following fields.

Field	Global Var?	Description
Name	No	The name to appear as the label for the activity in the process definition.
Description	No	Short description of the activity.
Host	Yes	Host name or IP address for the mail server. The default port (110) is used to connect to the POP3 server and the default port (143) is used to connect to the IMAP server. If your server is configured to use a different port, you can specify it in this field using the syntax:   <hostName>:<portNumber> For example, myMailServer.myCo.com:76
Protocol	No	Protocol used by mail server. The drop-down list has two options: POP3 and IMAP.
Authentication	No	This drop-down list is displayed only when you select the IMAP option in the Protocol drop-down list. It has two options: Basic Authentication and OAuth 2.0. If you select Basic Authentication, then the User Name and Password fields appear. If you select OAuth 2.0, then the User Name and Access Token Value fields appear. Note: You can obtain the field information for Access Token Value, User Name, and Password from a Service Provider.
User Name	Yes	User name to use when authenticating to the mail server
Password	Yes	Password to use when logging into the POP3 server or into the IMAP server with authentication as Basic Authentication.
Access Token Value	Yes	The value authorized by the authorization server’s token endpoint.
Polling Interval (sec)	Yes	Polling interval (in seconds) to check for new mail. The default, if no polling interval is specified, is 5 seconds.
Delete Mail	Yes	If selected, mail is deleted from the POP3 or IMAP server once the process starter has retrieved it. Note: If you choose to delete mail, you should place a Checkpoint activity immediately after the Receive Mail process starter to ensure the message is not lost in the event of machine failure. Alternatively, you can choose to leave this field unchecked, and then later in the process definition perform a checkpoint then use the Confirm activity to confirm the message. The Confirm activity will delete the message from the mail server.
SSL	Yes	The Use SSL check box specifies that a Secure Sockets Layer (SSL) should be used to specify client SSL configuration. When this field is checked, the Configure SSL button is enabled.
Upgrade Configuration	No	This field only appears in Mail palette resources placed into process definitions prior to release 5.2.0. In previous releases, attachments were lists in the input of the activity. In release 5.2.0 or later, a new schema is used to handle MIME attachments. If you have a Mail palette resource created prior to release 5.2.0, this field should be unchecked to maintain backward compatibility. This field does not appear for new resources created in release 5.2.0 or later. Unchecking this field disables the Advanced and Output Headers tab and changes the output schema.

Configure SSL Button

The Configure SSL button allows you to configure the SSL parameters when the transport supports SSL. Check SSL to display Configre SSl dialog. Provide values in the following fields to configure SSL.

Field	Description
Trusted Certificates Folder	Specifies a folder in the project containing one or more certificates from the trusted certificate authorities. This folder is checked when a client connects to ensure that the server’s certificate is from a trusted certificate authority. This prevents connections from rogue servers.
Identity	An Identity resource that contains the HTTP server’s digital certificate and private key. See TIBCO Designer Palette Reference for more information.
Verify Host Name	Specifies whether to verify that the host you are connecting to is the expected host. The host name in the host's digital certificate is compared against the value you specify in the Expected Host Name field. If the host name does not match the expected host name, the connection is refused.
Strong Cipher Suites Only	Specifies that only cipher suites with strong encryption should be used, if they are available on the host you are connecting to.

Test Connection Button

The Test Connection button tests the connection to the specified mail server. You can use this button to ensure that your Receive Mail activity is properly configured to receive mail from the specified mail server. This button is only enabled when the Host, Username, and Password fields on the Configuration tab are populated.

Advanced

The Advanced tab contains the following fields:

Field	Description
Provide Raw Message	When checked, this field specifies that the whole message is to be provided in binary form. The output schema changes to include an element named rawMessage that contains the message instead of bodyText and mimeEnvelopeElements. The Receive Mail process starter uses the javax.mail API. This API assumes that the content type of the message is multipart/mixed. When the multipart subtype is not mixed (such as multipart/signed or multipart/alternative) or when another content type is used (for example application/*), the javax.mail API may not correctly parse the message. Checking this field allows you to send the raw message to a Java Code activity that uses the Java Activation framework to implement the appropriate handlers to process the message. For more information on how the Java Activation framework can be used for this purpose, please consult the API documentation for javax.activation and javax.mail. You can also feed the binary message to the javax.mail.MimeMessage constructor in the form of a java.io.InputStream to construct a MimeMessage object. In that case, the default javax.mail API handler is used.
Write to File	Checking this field specifies that incoming messages whose body and attachments (or raw message size if the Provide Raw Message field is checked) exceed the specified threshold size should be written to a file instead of stored in memory. This allows you to accept large incoming messages without consuming a great deal of memory. When this field is checked, the Directory and Threshold Size fields appear. Leaving this field unchecked specifies that incoming messages should be kept in memory. Note: Once written, the files created by using this option are not deleted automatically. You must manage the storage used by these files and delete them when they are no longer used.
Directory	The directory to write messages that are above the specified threshold. The process engine does not attempt to create the directory if the specified directory does not exist. Therefore, create the directory before starting the process engine.
Create Non-Existing Directories	When checked, all directories in the path specified in the Directory field are created, if they do not already exist. If this field is unchecked and there are one or more directories in the specified path in the Directory field that do not exist, an exception is raised.
Threshold Message Data Size	The maximum size (in bytes) of an incoming message that can be kept in memory. Messages larger than the specified size are written to a file in the specified directory. The file’s name is output so that subsequent activities in the process definition can access the file and read its contents. Specifying zero (0) in this field causes all incoming messages to be saved to a file.

Output Headers

Incoming messages may have custom headers. The Output Headers tab allows you to define a custom schema for the headers of the incoming mail messages. You can specify any standard header supported by the javax.mail package. For example, X-Mailer or X-Priority. Values of headers in the incoming message will populate the corresponding output headers of the same name that you have defined.

See Appendix A, Specifying Data Schema for a complete description of using the Output Headers tab.

Misc

The Misc tab contains the following fields:

Field	Description
Sequencing Key	This field can contain an XPath expression that specifies which processes should run in order. Process instances with sequencing keys that evaluate to the same value will be executed sequentially in the order the process instance was created. See TIBCO ActiveMatrix BusinessWorks Process Design for more information about controlling the execution order of process instances and about XPath expressions.
Custom Id	This field can contain an XPath expression that specifies a custom ID for the process instance. This ID is displayed in the View Service dialog of TIBCO Administrator, and it is also available in the $_processContext process variable.

Output

The output for the activity is the following.

Output Item	Datatype	Description
from	string	The email address of the sender of the email.
to	string	The recipient list of the email.
cc	string	The cc (carbon copy) list of the email.
replyTo	string	The reply to list of the email.
subject	string	The subject of the email.
sentdate	string	The date the email was sent.
Fields available when the Upgrade Configuration field is checked
Headers	complex	This element contains the schema you defined on the Output Headers tab. You can specify custom headers that can be included in incoming mail messages. You can specify any standard header supported by the javax.mail package. For example, X-Mailer or X-Priority. Values of headers in the incoming message will populate the corresponding output headers of the same name that you have defined.
rawMessage	binary	The content of the message in binary form. This element is only available when the Provide Raw Message field on the Advanced tab is checked.
bodyText	string	The text of the email message. The Provide Raw Message field on the Advanced tab must be unchecked for this field to appear.
mimeEnvelopeElement	complex	This element contains the message attachments. This element contains a repeating element named mimePart that contains each mime attachment. The Provide Raw Message field on the Advanced tab must be unchecked for this field to appear.
mimeHeaders	complex	This element contains the mime header for each mimePart. Mime headers can contain the following information: • content-disposition • content-type • content-transfer-encoding • content-id • other mime header information See http://www.faqs.org/rfcs/rfc2045.html for more information about MIME headers and their syntax. Note: When the content type is specified as "text/*" (for example, "text/xml"), the attachment content is expected to be in either the textContent output element or the file name storing the attachment is expected to be in the fileName output element. When the content type is anything other than "text/*", the attachment content is expected to be in either the binaryContent output element or the file name storing the attachment is expected to be in the fileName output element.
binaryContent | textContent | fileName	choice	This element contains the mime attachment. The element can be one of the following: • binaryContent — content of the attachment when the attachment is binary data. • textContent — content of the attachment when the attachment is text data. • fileName — the file name of the attachment when the attachment is stored in the file system (see Advanced tab for more information).
Fields available when the Upgrade Configuration field is unchecked
bodyText	string	The text of the email message.
attachmentNames	string	A list of names for each attachment to the message. These names are typically the file names of the attachments. Note: The attachmentNames and attachmentData elements are corresponding lists. That is, for each item in the attachmentName element, there must be a corresponding item in the same position in the attachmentData list. For example, if there are three attachments, both elements must contain three items and item in the attachmentNames element corresponds to the element in the same position in the attachmentData list.
attachmentData	binary	A list of attachments to the message.
contentType	string	The MIME content type specified in the message.

Copyright © Cloud Software Group, Inc. All Rights Reserved