EmailRetrieve Agent

The Email Retrieval agent is part of the Enterprise workflow service that polls an email box, retrieves any message found, strips all attachments from the message saving them to the EML sub-folder of the EQuIS work folder, and then deletes the message. Only the message attachments are saved. It is assumed that an EML channel is defined for the FileMonitor agent. An optional feature allows users to configure the agent to parse the body of an email for download links, and download those files that match a pattern into a FileMonitor channel. See Email EDD Submittals for configuration details.

Notes:

•Only one instance of EarthSoft.Workflow.Agents.EmailRetrieveAgent can be running per mailbox account.

•If using the Microsoft 365 email provider, see OAuth Authentication for Microsoft 365 Email for more information about generating an OAuth token to be used as the password when configuring EQuIS Enterprise for email.

•If the Enterprise site is configured to use the same email account for both EmailDeliver and EmailRetrieve, emails that fail to deliver will trigger a bounce back email to the email inbox with the .zip file attached. The EmailRetrieve agent will then attempt to process the bounce back email with .zip file attachment as an EDD. These erroneous submittals will fail because they will not comply with the EDD Package Naming Convention.

EQuIS Version: 7

Namespace: EarthSoft.Workflow.Agents.EmailRetrieveAgent

Products Affected: Enterprise

Required Modules:

•Enterprise

•Custom Code

Host

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	host	Required
STRING_VALUE	<hostname or ip address>	Valid host name or ip address of a mail server that is reachable from the EQuIS application server.

Port

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	port	Required
STRING_VALUE	<integer>	Network port number that mail server is listening on. Default value is 143.	See mail server configuration and firewall settings.

Protocol

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	protocol	Required
STRING_VALUE	<string>	Default value is IMAP Choose one of:	POP IMAP

Security

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	security	Required
STRING_VALUE	<string>	Default value is implicit. Choose one of:	implicit or ssl explicit or tls explicitoptional none

Username

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	username	Required
STRING_VALUE	<string>		As defined by mail server.

Password

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	password	Required
STRING_VALUE	<string>	This value is not encrypted by EQuIS.	As defined by mail server.

Enable SSL

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	enable_ssl	Required
STRING_VALUE	<boolean>	Default value is False. Choose one of:	True False

Compressed File Extension

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	compressed_file_extension	Required
STRING_VALUE	<string>	Default value is ".zip". Some mail systems may not allow zipped attachments. Set to a different extension (e.g., .piz or .zzz).

From Address

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	from_address	Required
STRING_VALUE	<string>		As defined by mail server.

Example

CONFIG_SECTION	CONFIG_KEY	OBJECT_TYPE	OBJECT_VALUE	STRING_VALUE
AgentsConfigSettings	agent	EmailRetrieve	host	exchange.example.com
AgentsConfigSettings	agent	EmailRetrieve	port	993
AgentsConfigSettings	agent	EmailRetrieve	protocol	IMAP
AgentsConfigSettings	agent	EmailRetrieve	security	implicit
AgentsConfigSettings	agent	EmailRetrieve	username	EQuIS-do-not-reply@example.com
AgentsConfigSettings	agent	EmailRetrieve	password	fe12!@EFG$$%^HJ&^^&*KI#B7564f
AgentConfigSettings	agent	EmailRetrieve	enable_ssl	True
AgentConfigSettings	agent	EmailRetrieve	compress_file_extension	.zip
AgentConfigSettings	agent	EmailRetrieve	from_address	EQuIS-do-not-reply@example.com

Optional Email Parsing Settings

An optional feature allows users to configure the Email Retrieval agent to parse the body of an email for download links, and download those files that match a pattern into a FileMonitor channel. At a minimum, parseBodyForLink, bodyLinkRegex, and bodyLinkChannel must be present for this optional functionality to work.

Parse Body for URL (optional)

This setting controls whether the email body should be parsed for links to files.

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	parseBodyForLink	Required
STRING_VALUE	true	Required

Body Link Regex (optional)

This setting configures the Regex for the links in the body.

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	bodyLinkRegex	Required
STRING_VALUE	<string>	Required	A Regex for matches email links.

Example

URL: https://www.example.com/directory1/directory2/VeryImportantReport.aspx?someParameter=123&anotherParameter=987

Regex: <https:\/\/:www\.example\.com\/.*VeryImportantReport.aspx.*>

The EmailRetrieve agent will parse the email and use this Regex to validate links with the domain .example.com and containing "VeryImportantReport.aspx", then download the linked file.

Body Link Channel (optional)

This setting configures the workflow subfolder for saving any files downloaded from the body of the email.

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	bodyLinkChannel	Required
STRING_VALUE	<string>	Required	The name of the folder (3 characters) in the workflow folder where to save the files downloaded from email body links.

Unwrap Links (optional)

Some email interfaces wrap URLs in <> symbols when converting HTML email to text, and if the URLs contained in the email body have URL parameters that are not easy to set express in Regex, it is possible to use these <> symbols in the Regex to define the limits of the link. This setting says that the first and last character of the matched URL should be removed, allowing for simplified Regex.

Example

URL: https://www.example.com/directory1/directory2/VeryImportantReport.aspx?someParameter=123&anotherParameter=987

Regex: <https:\/\/:www\.example\.com\/.*VeryImportantReport.aspx.*>

unwrapLink: true

ST_CONFIG	VALUE	REMARK	VALID VALUES
CONFIG_SECTION	AgentsConfigSettings	Required
CONFIG_KEY	agent	Required
OBJECT_TYPE	<service_name>	Begins with "EmailRetrieve"	One of the SERVICE_NAME values from the ST_SERVICE_RESERVATION table, where object_name='EarthSoft.Workflow.Agents,EarthSoft.Workflow.Agents.EmailRetrieveAgent'
OBJECT_VALUE	unwrapLink	Required
STRING_VALUE	true	Required	As defined by mail server.