Configuring Email

Archibus can automatically send email notification messages when certain events occur. For example:

the Move Management application sends email to a move coordinator when a move is requested.
the Service Desk application sends notices when requests must be approved, must be scheduled, or have been escalated.
the Maintenance application automatically sends email to a requestor of maintenance work to let them know the status.

If you change the mail configuration properties, you must restart Archibus on the application server in order for your changes to take effect.

The admin should enter absoluteAppPath in \WEB-INF\config\context\compatibility\afm-config.xml. That URL will be used for links in emails.

Properties

The \WEB-INF\config\mail.properties file holds the name, port and, optionally, the username and password of the account that Archibus should use to send email notifications, as well as the default content type for email messages.

Other important preferences are:

`host.starttls`	When set to True, allows Web Central to use secure mail server connection using TLS: `mail.host.starttls=tre` In some SMTP server configuration, enabling STARTTLS may cause runtime errors. In this case, disable the secure connection: `mail.host.starttls=false` See https://www.fastmail.fm/help/technology_ssl_vs_tls_starttls.html.
`maintmgr`	The address of the maintenance manager used in the Technologies / User Interface Add-Ins / Assemblies with Tabs / Work Request Creation Wizard example. It is not used in the Service Desk or Building Operations products.
`administrator`	The administrator account that receives new password requests from the Sign In form or from which the system sends bulk notices, such as notices to large groups of new users that each should log in and change their password.
`mail.smtp.ssl.protocols`	Specifies the SSL protocols that will be enabled for SSL connections. The property value is a whitespace separated list of tokens acceptable to the javax.net.ssl.SSLSocket.setEnabledProtocols method. mail.host.sslProtocols=TLSv1.1,TLSv1.2
`mail.send.rate mail.send.rateUnit`	Limits the rate at which Web Central sends emails without attachments to an SMTP service. See below discussion.

The other items in this file are for compatibility with older versions of Archibus and are not used in the newer applications.

Configuring your Mail Server

You may need to configure your email server to grant permissions to the server hosting Archibus to relay mail. This will likely be the case if the email server will be forwarding the mail to mailboxes on other servers, or if you have some users who auto-forward email to other addresses.

If you have a small company for which all mail boxes are hosted on a single mail server (or mail cluster) and all mail terminates at the receiving server, then you do not have to configure your mail server to allow the Web Central server to relay mail.

Encrypting Passwords

If you do enter a mail server account password, and if you do wish to encrypt this password in the file:

Enter the plaintext password value surrounded with TO_ENCRYPT(...), such as: mail.host.password=TO_ENCRYPT(myPassword)
Run the System / Archibus Administrator - User and Security / Encrypt Passwords in Configuration Files task and its action.

Email Rate Limiter

Email providers often have a limit to the number of emails a user can send within a given time frame. For example, Office365 limits users to 30 email deliveries per minute. Similarly, concurrency limit also exists to limit email deliveries concurrently.

The Email Rate Limiter feature (MailRateLimiterService) can be used to safeguard Archibus from hitting these limits. This feature queues up the mail notification into Notifications Logs table, and then sequentially send each mail to recipients keeping check on the message rate configured. Since mails are sequenced, concurrency exception does not occur.

Specifically, this feature entails:

The mail messages from applications are collected into the afm_notifications_log table with status ‘CREATED’ and date time when it was created.

The Scheduler WFR instance has a continuous polling service which keeps polling at a regular interval of time and computes the chunk size
The Scheduler WFR then picks oldest messages with status ‘CREATED’ from afm_notifications_log and sends mails at the configured rate.
The afm_notifications_log table stores the cc, bcc, created_at, and created_time for the generated mail message.
The docs_assigned table includes a reference to afm_notifications_log.auto_number so that attachments stored in afm_docvers can be linked to the mail message.

Note: The email limiter is intended for one project running on a Web Central instance. It does not work if you have multiple projects on the same Web Central instance.

Configuration

The \WEB-INF\config\mail.properties file holds these properties for the email rate limiter feature.

Property	Description
mail.send.rate	This property accepts integer value. If Email Provider allows unlimited mails and we do not need to setup the Email rate limiter service, then we can disable this new feature by setting the value for this property to -1 or 0. This feature is enabled by setting value higher than 0. For example, office365 has the message rate limit of 30 messages per minute. So, we can set mail.send.rate = 30 andmail.send.rateUnit = ‘messages_per_minute’
mail.send.rateUnit	This property set the unit for rate. At present only ‘messages_per_minute’ is supported. It can be left blank also, which will set ‘messages_per_minute’ as default.

Property

Description

mail.send.rate

This property accepts integer value. If Email Provider allows unlimited mails and we do not need to setup the Email rate limiter service, then we can disable this new feature by setting the value for this property to -1 or 0.

This feature is enabled by setting value higher than 0. For example, office365 has the message rate limit of 30 messages per minute. So, we can set

mail.send.rate = 30 andmail.send.rateUnit = ‘messages_per_minute’

mail.send.rateUnit

This property set the unit for rate. At present only ‘messages_per_minute’ is supported. It can be left blank also, which will set ‘messages_per_minute’ as default.

Listener

It is necessary to run a mail listener continuously to send mail messages that is accumulated in afm_notifications_log table with status ‘CREATED’

Item	Description
id	The mailListener to run
p:runScheduledRules="${core.runScheduledRules}"	Ensures that the thread is only run on a designated server in a load-balanced architecture.

The existing association of applications with MailSender API is used to save the messages record into afm_notifications_log with status ‘CREATED’ and creation date time.

The MailRateLimiterService uses the MailSender API to send the new messages and update the record in afm_notifications_log with status ‘SENT’ and sent date time.

Application Parameter

The mail rate limiter feature needs to save the new messages into the afm_notifications_log table. .Therefore, when the rate limiter feature is enabled, the system ignores AbSystemAdministration.NotificationLoggingLevel (such as set to Off or Subject); instead, all messages are inserted into the notifications log (the afm_notifications_log table).