Email Configuration

The purpose of the Email Configuration screen is to allow users to configure their email accounts with Ephesoft Transact. This screen works with the Email Import plugin to import documents from a user’s email account. This configuration is done per batch class. Multiple email accounts can be set up for each batch class.

Prerequisites

Complete the following steps in order to turn on the email processing feature in Ephesoft Transact.

Open the applicationContext.xml file, located at [Ephesoft_Directory]\Application\applicationContext.xml
Locate and uncomment the following line to allow email processing. This line is commented out by default.

<import resource="classpath:/META-INF/applicationContext-dcma-mail-import.xml" />

Figure 1. Default Lines in applicationContext.xml File

Restart Ephesoft Transact to apply the configuration update.

You have enabled the email processing feature. Continue to Configuration Steps to connect your email account with Ephesoft Transact.

Email Configuration

Perform the following steps to configure email accounts:

Go to the Batch Class Management screen.
Open your batch class.
Click Email Configuration to begin defining user email accounts to be accessed by Ephesoft Transact.

Figure 1. Email Configuration Screen

Use the following table as a guide to configure Transact to connect to your email account.

Configurable Property	Value Type	Value Options	Description
Username	String	Valid email account username	The account name to be connected to Ephesoft Transact
Password	String	Corresponding password for the configured username	Password for the configured user account Note: Password will always visible as 8 * in the Password field.
Incoming Server	String	Valid mail server name	The type of the mail server that the configured user account belongs to.
Protocol or Server Type	Drop-down selection	Valid mail server type IMAP POP3 Exchange OAuth2*	The type of the mail server that the configured user account belongs to
Folder	String	Valid and existing mail folder name	The name of the mail folder that the email import will be checking. This folder name can be “Inbox.”
Security Type	Drop-down selection	PLAINTEXT SECURED STARTTLS	The property that defines the security type used to connect to a mail server.
Port	Integer	Valid port number	The port number on which the configured mail server type will work. This number will be determined by your email system.
Client ID*	String	Valid client ID from Azure Active Directory	The client ID used for Office365 authentication with OAuth2. Refer to Configuring Microsoft Email Services with OAuth2 for steps to obtain the client ID.
Client Secret*	String	Valid client secret from Azure Active Directory	The client secret used for Office365 authentication with OAuth2. Refer to Configuring Microsoft Email Services with OAuth2 for steps to obtain the client secret.
Enable	Checkbox	Checked Unchecked	The property that defines whether email ingestion is active for this email address.

^*^{Available for 2020.1.02 or above. This security type is only for the Exchange Online service offered through Office 365 or Microsoft 365 subscription plans.}

Click Test Email to verify if the configured user email account is valid.
Once the configuration is verified, click Deploy to enable automatic email ingestion for the batch class according to the cron schedule.

You have successfully configured Transact to work with your email account.

Property Files Configuration

For further email import configuration, refer to the following properties files:

mail-import.properties
open-office.properties
folder-monitor.properties

Important: The settings in these property files apply to all batch classes in the environment.

mail-import.properties

The mail-import.properties file is located at [Ephesoft_Directory]\Application\WEB-INF\classes\META-INF\dcma-mail-import\mail-import.properties.

Refer to the following table for an overview of configurable properties.

Configurable Property	Value Type	Value Options	Description
dcma.importMail.cronExpression	String	Valid cron expression	The cron expression defines the look-up time for the plugin, i.e. at what time the plugin looks for any updates in the configured mail account.
dcma.supported.attachment.extension	String	List of valid file extensions	Defines the documents supported by the plugin. Multiple entries are separated by a “;”.
dcma.mail.import.core.size	Integer	Any valid integer value	Defines the thread pool size that is used by the mail import service
dcma.mail.import.mail_body_extension_type	Integer	0 or 1	Extension type for the mail import body.
dcma.mail.import.max_mail_retry_count	Integer	Any valid integer value	The number of times Transact will try to process the mail.
dcma.mail.import.mail_retry_interval	Integer	Any valid integer value	The number of intervals Transact will try to process the mail.
dcma.mail.import.mail_body_download_flag	Integer	0 or 1	Determines if the email body or attachments are downloaded. The default value is 0 to download the body with attachments.
dcma.importMail.mailProcessCronExpression	String	Valid cron expression	Defines the mail processing time.
dcma.mail.import.max_mail_processing_capacity	Integer	Any valid integer value	Defines the maximum number of emails that should be processed simultaneously.
dcma.mail.import.mail_pickup_procedure	Integer	0 or 1	Defines whether the email pickup process is automated or timed. Set to “0” for automated pickup. Set to “1” for timed pickup.
dcma.mail.msg_download_and_process_flag	Integer	0 or 1	Defines whether the email attachments should be processed or not. Set to “0” to only download the attachments. Set to “1” to download and process the attachments.
dcma.mail.number_of_mails_downloaded_per_cron_cycle	Integer	Any valid integer value	Defines the number of emails to be downloaded per cron cycle.
dcma.mail.import.mail_conversion_tool	Integer	1 2 3	Determines which software will be used to process the HTML mail body. Set to “1” for LibreOffice (formerly known as OpenOffice). Set to “2” for iText. Set to “3” for wkhtmltopdf.
dcma.mail.html_to_pdf_conversion_parameter	String	N/A	Parameters used for wkhtml to define page, font size, and magnification.
dcma.mail.itext_html_tag	Boolean	True False	Used for iText software to resolve text from being cropped during the conversion process. Set to “true” to display tabular data in HTML tags. Set to “false” for tabular data to be displayed normally. Important: Set this to “true” if the dcma.mail.import.mail_conversion_tool property is set to “2”.
dcma.mail.headers_switch	Boolean	ON OFF	Determines if email headers are processed. Set to “ON” process email headers. Set to “OFF” to ignore email headers.
dcma.mail.required_headers	String	List of valid headings	Defines which headers are processed from the mail. Separate multiple values with semicolons (;). Note: The dcma.mail.headers_switch property must be set to “ON” for headers to be processed. Example: Subject;To;From
dcma.mail.import.max_connection_retry_count	Integer	Any valid integer value	Defines the maximum number of times to attempt reconnecting to the mail server if the connection is lost or fails.
dcma.mail.import.connection_retry_interval	Integer	Any valid integer value	Defines the time in milliseconds between each attempt to reestablish the mail server connection.

open-office.properties

Ephesoft Transact can use LibreOffice (formerly known as OpenOffice) to handle email-related conversions during the email ingestion process. Transact uses LibreOffice for non-email purposes, and it is included as part of the Ephesoft Transact installation.

The open-office.properties file is located at [Ephesoft_Directory]\Application\WEB-INF\classes\META-INF\dcma-open-office\open-office.properties.

Refer to the following table for an overview of configurable properties.

Configurable Property	Value Type	Value Options	Description
openoffice.serverUrl	String	Valid server URL	Defines the server used to connect to the remote OpenOffice server instance. This is used when connecting to an external or remote service.
openoffice.serverPort	Integer	Valid and available port number	Defines the port number used for connecting to the OpenOffice server instance. The default port is 8100.
openoffice.autoStart	Boolean	True False	Defines whether the OpenOffice server should be started or connected when the application starts. The default value is false.
openoffice.homePath	String	N/A	Path to OpenOffice installation. The default installation is at [Ephesoft_Directory]\Dependencies\libreoffice.
openoffice.maxTasksPerProcess	Integer	Any valid integer value	Defines the maximum number of simultaneous conversion tasks that should be handled by a single OpenOffice process. The default value for optimized performance is 50.
openoffice.taskExecutionTimeout	Integer	N/A	Defines the time in milliseconds before conversion tasks time out. The default value for optimized performance is 30000 milliseconds (30 seconds).

folder-monitor.properties

The file is located at [Ephesoft_Directory]\Application\WEB-INF\classes\META-INF\dcma-folder-monitor.

Configurable Property

Value Type

Value Options

Description

pdf.xfa.process.static.content

Note: Applies to Transact 2022.1.00 and above.

Boolean

True
False

Determines if PDF XFA files will be converted to TIFF files. If set to false, any process requiring PDF XFA to TIFF conversion will result in an error.

The default is set to false.

Note: Designed for use with static XFA data. Enabling this feature and processing dynamic XFA data may cause unexpected results when converting the PDF to a TIFF image.

File Name Length Requirements

Ephesoft Transact email import supports a maximum filename and path length. Exceeding this maximum may result in an error. Use the following formula to determine the maximum file name length that Ephesoft Transact supports for email import:

The length of the UNC_FOLDER_File_Name_Path must be less than MAX_PERMISSIBLE_PATH_LENGTH_OF_WINDOWS minus the length of the PDF_PROCESSING_FOLDER minus 10.

Examples are provided below:

MAX_PERMISSIBLE_PATH_LENGTH_OF_WINDOWS = 259
Calculated PDF_PROCESSING_FOLDER length = 22

The following is an example of this formula in application:

During the import process, the file !!!mail.pdf is located in the following directory:
- D:\Ephesoft\SharedFolders\TestBatch39455638711700
In this case, the maximum file name length is calculated to be as follows:
- length[D:\Ephesof\SharedFolders\TestBatch39455638711700!!!mail.pdf] < 227

Troubleshooting

The following table includes common errors and possible root causes.

Error Message	Possible Root Cause
Unable to convert Email into PDF file.	OpenOffice service is not running or has not been configured correctly.
Not able to establish connection.	Connection could not be established for your account configuration.
Could not find port number. Trying with a default value of 995.	Port number specified in the configuration is invalid, so the plugin tries to connect on the default POP3 port.
Could not find port number. Trying with a default value of 993.	Port number specified in the configuration is invalid, so the plugin tries to connect on the default IMAP port.
Error while reading mail contents.	The email body or other attachments could not be read and converted.
Not able to process the mail reading.	An error in reading the contents of mail occurs. OpenOffice could not convert the source file.
File type is not supported.	The file type in the email is not supported. Open the mail-import.properties file. Add the file type to the following line: dcma.supported.attachment.extension Refer to the Properties Files section for more information on the configurable properties.

Was this article helpful to you? Yes No