Configuring BatchMail

This task controls the sending of email notifications by ExtraView. In previous versions this was a separate process to ExtraView. From version 6.1, the BatchMail task can be started and stopped within ExtraView, and the log can be examined. It is recommended that this task be set to START_ON_BOOT, so that it initializes automatically when ExtraView starts.

When configuring BatchMail with Oauth2 connections, there is an appendix to this guide at OAuth2 Email Mailbox Settings to assist.

The parameters to set up and utilize BatchMail are as follows:

Parameter Explanation
ALLOW_ENCRYPTION This flags whether email encryption is to be set or not. The default is NO
BatchMail.properties This configuration file is used for standalone BatchMail operation. If you are running BatchMail from within this menu, this file is not needed. It is provided for backwards compatibility with previous versions of ExtraView, which did not run BatchMail as a task within ExtraView. See the Installation Guide for details of the settings within this file.
CHECK_CONNECTION_PAUSE This defines the number of seconds to wait when contacting your mail server, before assuming there is no connection. The default is 30 seconds
ENCRYPTION_DIR The directory where the encryption program is stored. This may be an absolute pathname or a relative pathname. Relative paths are relative to the WEB-INF directory on the server
ENCRYPTION_SCRIPT The script to be used to generate the encrypted result (either file or written to standard out). To test this execute the following from the scripts folder: ./encrypt.sh where is the placeholder for the recipient. It will be retreived by the BatchMail program and should match the name on the keyring. is the placeholder for the filename. Its value will be retreived by the BatchMail program and will be based on the filename generated by ExtraView. For example, this might be: ENCRYPTION_SCRIPT=scripts/encrypt.sh
ENCRYPTED_TO_STANDARD_OUT If this has a value of "yes" then BatchMail reads the encrypted standard out, otherwise if there is a value of "no" it reads the encrypted file
FORCE_DIRECTORY_RELOAD This may be YES or NO. It is used principally for NFS mounted directories which are used to store the outgoing emails. Occasionally, the directory entries may be cached and become stale, leading to ExtraView seeing out-of-date information. When this setting is YES, ExtraView forces a re-read of the directory for all operations.
LOG_FILE_MAX_RETAINED This is the maximum number of "rolled over" log files that are retained on the server before they are deleted. The default is 5
LOG_FILE_MAX_SIZE This is the maximum size to which the log file is allowed to grow, before it is "rolled over" and a new log file created. The old file is retained on the file system. The default is 20,000 kiloBytes
LOG_FILE_PATH_NAME This is the path to the BatchMail log file, held within the properties file.
LOG_FILE_PATH_NAME_ABSOLUTE This is used for standalone installations on Microsoft Windows, or when running in a war file
LOG_LEVEL The level of logging written to the log file. The standard operational value is 6, and a number up to 12 can be used to produce increasing amounts of debug information in the log, for debugging purposes
MAIL_DIR This is the absolute or relative path to the mail directory where outgoing emails are stored temporarily, defined in the Configuration.properties file. This must be set. Relative paths are relative to the WEB-INF directory on the server
MAIL_ENABLE_TLS This parameter enables TLS (Transport Layer Security) to facilitate end-to-end encryption of the connection to the mail server. Set the value of the property to YES to enable.
MAIL_PASSWORD When the outbound SMTP server requires a username and password to authenticate before sending the email, this parameter provides the password
MAIL_PORT The MAIL_PORT is typically 25 or 465, depending on whether you are using a secure connection
MAIL_SERVER The domain name to your mail server. This must be set
MAIL_USER When the outbound SMTP server requires a username and password to authenticate before sending the email, this parameter provides the username
NOTIFICATION This setting can be either NOTIFY_NEVER (by itself), or any combination of the following with each setting separated by semicolon(;) :
  • NOTIFY_DELAY
  • NOTIFY_FAILURE
  • NOTIFY_SUCCESS

For example, the setting might be NOTIFICATION=NOTIFY_SUCCESS;NOTIFY_FAILURE

PAUSE_AFTER_NUM_OF_EMAIL This setting pauses the EVMail task after sending the number of mails in the value of the setting. This pauses the EVMail task to stop it commanding all the resources on the server for long periods of time, such as might happen with a mass update of many issues sending out thousands of notifications in a very short period of time. An alternative method is to use the PAUSE_BETWEEN_SEND setting, It is recommended that you use only one of the two settings.
PAUSE_BETWEEN_SEND This is the number of milliseconds to wait between the sending of each mail notifications, to allow the server to process other tasks. Similar to the PAUSE_AFTER_NUM_OF_EMAIL setting, it reduces the load on the server. It is recommended that you use only one of the two settings. The default is 200 milliseonds
POLL_RATE The number of seconds to pause between checking for emails to be sent. The default is 5 seconds
RECIPIENTS_PER_CONNECTION Most mail servers have a limit in how many emails they will send with a single connection, typically 100.  Within sites that generate a large volume of email, a BatchMail configuration property is available to prevent this causing a problem.  The property is named RECIPIENTS_PE R_CONNECTION.  BatchMail queues the sending of mail to make sure no more than this number of mails are generated at one time.
RETURN_OPTION This defines the action to take with returned mail. You can elect to either return the full email or just the headers. The value can be either RETURN_FULL or RETURN_HDRS
SECURE_PORT This is a dedicated port number for this application. The default is 879. The number must always be less than 1024
SEND_TO_ALL_ONCE_ADDR This is used in conjunction with SEND_TO_ALL_ONCE setting to determine whether recipients of email notifications will see the other addressees who received the email notification.

The default for this optional setting is BCC.

SEND_TO_ALL_ONCE The default for this optional setting is false.  It may be set to a value of true, in which case you can set the SEND_TO_ALL_ONCE_ADDR to a value of TO or BCC.  If set to TO, the mail addresses of the recipients will appear in the TO header of the outgoing email, as opposed to the BCC.

It should be understood that this implies that all recipients will receive the email as if they are in the user role of the sender, as it is a single email that is generated, as opposed to an email being generated for each user, customized to their user role.

SERVER_FAILED_PAUSE This is the number of seconds to wait after a failed connection before retrying. The default is 60 seconds
SIGNING_SCRIPT The script to be used to generate the signed result (either file or written to standard out). To test this, execute the following from the scripts folder: ./sign.sh The return value will be retrieved by the BatchMail program and will be based on the filename generated by ExtraView. For example, use this: SIGNING_SCRIPT=scripts/sign.sh
TRANSPORT Use either smtp or smtps for a secure connection if this is configured on your mail server
   
XML_LOG_FLAG The default for this is FALSE. If you set it to true, the log will be created in an XML format