› Importing documents › Email Import configuration › Email configuration

Email configuration

On the Email Configuration screen, users can configure their email accounts with 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.

Configure email accounts

Perform the following steps to configure email accounts:

  1. Go to the Batch Class Management screen.
  2. Open your batch class.
  3. Click Email Configuration to begin defining user email accounts to be accessed by Transact.
  4. Use the following table 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

    Password is 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 is 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 works.

    This number is determined by your email system.

    Client ID*

    String

    Valid client ID from Azure Active Directory

    The client ID used for Office365 authentication with OAuth2.

    See Configure 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.

    See Configure Microsoft Email Services with OAuth2 for steps to obtain the client ID.

    Import

    Drop-down selection

    • Email and Attachments
    • Attachments Only

    The property defines whether to process the body of an email or just the attachments.

    The Email and Attachments options is the default setting for new email configuration entries.

    For Upgrades with email configurations existing in system, whatever is configured in the properties file will be replicated to the database.

    Enable

    Check box

    • Selected
    • Cleared

    The property that defines whether email ingestion is active for this email address.

    *This security type is only for the Exchange Online service offered through Office 365 or Microsoft 365 subscription plans.

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

Property files configuration

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

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 <Transact_Directory>\Application\WEB-INF\classes\META-INF\dcma-mail-import\mail-import.properties.

See 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.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.
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 to 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 (;).

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.

dcma.mail.import.advanced_inline_body_attachment_handling Boolean
  • ON
  • OFF
  • Set to ON to reduce duplicate document processing associated with attachments that should be referenced once in the email body and not processed as a separate document. (default)
  • Set to OFF to disable this feature. This setting is set to OFF for upgraded environments missing this option.
dcma.mail.import.proxy_host String

N/A

Defines the proxy server IP address.

Example: 127.0.0.1

dcma.mail.import.proxy_port String

N/A

Defines the proxy server port.

Example: 80

dcma.mail.import.proxy_credential_required Boolean

  • True

  • False

Defines if proxy requires authentication.

dcma.mail.import.proxy_server_username String

N/A

Defines the proxy server user name.

Example: Ephesoft

dcma.mail.import.proxy_server_password String

N/A

Defines the proxy server password.

Example: Ephesoft

dcma.mail.import.proxy_server_domain String

N/A

Defines the proxy server domain.

Example: Ephesoft

mail.util.connection.timeout Integer

Any valid integer value

Defines the MAP and POP3 connection timeout in milliseconds.

mail.util.request.timeout Integer

Any valid integer value

Defines the IMAP and POP3 request (I/O) timeout in milliseconds.

dcma.mail.import.charset.autodetect Boolean

  • True

  • False

Enables or disables automatic character-set detection (from the email subject and body) for incoming emails.
dcma.mail.import.charset.default String

N/A

Sets the default character-set to use when automatic detection fails for the email subject or body.

Example: utf-8

dcma.mail.import.download_inline_attachments Boolean

  • True

  • False

Enables or disables downloading of the inline attachments for incoming emails.
dcma.mail.import.attachments_invalid_characters

String

N/A

Removes invalid characters from the attachment name.

Example: [/\\\\:*?\"<>|]

open-office.properties

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 Transact installation.

The open-office.properties file is located at <Transact_Directory>\Application\WEB-INF\classes\META-INF\dcma-open-office\open-office.properties.

See 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 <Transact_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).
openoffice.pdf.PaperFormat Integer
  • 0

  • 1

  • 2

  • 3

  • 4

  • 5

Defines the PaperFormat type:

  • A3:0

  • A4:1 (default)

  • A5:2

  • B4:3

  • B5:4

  • Letter:5

openoffice.pdf.PaperOrientation Integer
  • 0

  • 1

Defines the PaperOrientation type:

  • Portrait: 0 (default)

  • LANDSCAPE: 1

openoffice.userProfileResetEnabled Boolean
  • True

  • False

Enables or disables the background job for the openoffice user profile reset.

The default is False.

For Windows only.

openoffice.userProfilePath String

N/A

Defines a path to the openoffice user profile location.

Only valid if openoffice.userProfileResetEnabled is set to true.

openoffice.userProfileBackupPath String

N/A

Defines a location where the last user profile is backed up.

Only valid if openoffice.userProfileResetEnabled is set to true.

openoffice.userProfileCronJob Cron

N/A

Defines a cron expression to run the openoffice user profile reset job.

The default is 0 0 02 * * ?

Only valid if openoffice.userProfileResetEnabled is set to true.

folder-monitor.properties

The file is located at <Transact_Directory>\Application\WEB-INF\classes\META-INF\dcma-folder-monitor.

Configurable property Value type Value options Description
pdf.xfa.process.static.content 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.
foldermonitor.ignoredBatchClassIdentifiers String

N/A

Defines the folder monitor service based on cron that can be set to ignore batch classes. A comma-separated list can be provided for ignoredBatchClassIdentifiers to enable the ignore feature.

foldermonitor.wait_time Integer Any valid integer value

Defines the folder monitor waiting time in milliseconds.

foldermonitor.valid_extensions String

N/A

Example: bmp;doc;docx;htm;html;jpeg;jpg;odf;odg;odp;ods;odt;pdf;png;ppt;pptx;psd;rtf;sxc;sxd;sxi;sxw;tif;tiff;txt;wpd;xls;xlsx;zip
foldermonitor.re_add_watch.cronjob.expression String

Valid cron expression

Applicable only if foldermonitor.jnotify_switch is set to true.

The cron job expression that can be configured to refresh the JNotify watchers for the folder monitor service.

foldermonitor.jnotify_switch Boolean
  • True
  • False

Defines a switch to turn ON and OFF JNotify.

When JNotify is enabled, foldermonitor.cronjob_expression is not taken into account.

foldermonitor.cronjob_expression String

Valid cron expression

Defines the cron job expression that can be configured to run folder monitor service for picking up new batches.

The cron based folder monitor service is recommended as default. Set jnotify_switch to false and configure cronjob_expression as required.

foldermonitor.threadPoolSize Integer

Valid integer value

Thread pool size for the folder monitor by cron.

pdf.xfa.process.static.content Boolean
  • True
  • False

Determines the processing of PDF/XFA files (static content only).

The default value is false, which retains the original behavior of batches with PDF/XFA content going into error.

When enabled, the batches are processed successfully (static content only).

When enabled, the dynamic content can be lost.

File name length requirements

Transact email import supports a maximum file name 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: 

  • 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

See the Property files configuration section for more information on the configurable properties.