Email Notifications

The service can be configured to send email notifications on certain events. This requires that a mail server be specified with a user, password and other connection information as well as templates for messages.

Attribute Required? Default Description
enabled N false enable email notifications.
starttls N false

Some servers (e.g., gmail) require sending a STARTTLS command in addition to the usual commands. If you get an error involving this, set this flag to "true".

useSSL N false Connect to the server via ssl. Implictly sets the port to the standard default.
username N N/A The name of the user when authenticating with the server.
password N N/A The password of the user when authenticating with the server
port N 25 if no SSL, 465 if SSL. The port to use. If omitted standard ports will be used.
recipients Y N/A A semi-colon (;) separated list of recipients.
server Y N/A The server to use.

Configuring Tomcat

In order to use email notifications with Tomcat, you must globally enable email. This is a feature of Tomcat and can't easily be changed. Fortunately, this is really easy.

  1. Download the latest version of java mail from here. Drop this jar (typically named mail.jar) into your $CATALINA_HOME/lib directory.
  2. Add the following line right before the closing tag of the $CATALINA_HOME/conf/context.xml file:
 <Resource name="mail/Session" type="javax.mail.Session" auth="Container"/>


Note you must configure Tomcat even if you are not using email notifications.

This is, again, because Tomcat does this globally and there is no way to just have local application control of it.

Note about upgrading from Java 8 to another version.

After Java 8, certain classes in the Java activation framework were removed from the standard distribution. Much as the requirement that the Java Mail jar has to be deployed globally in Tomcat, you must add in the activation framework java

Example 1. Using SSL

This example will set up notifications using SMTP over SSL. Templates (see below) are specified for the message and subject line.

<config>
   <server name="default">
      <mail
         enabled="true"
         useSSL="false"
         password="mairzy-doats"
                debug="false"
      	 server="smtp.super-secure-server.net"
         recipients="admin@chem.bigstate.edu">
         <messageTemplate>/var/www/config/oa4mp-message.template</messageTemplate>
         <subjectTemplate>/var/www/config/os4mp-subject.template</subjectTemplate>
      </mail>
      <!-- rest of configuration >
   <\server>
<\config>

Templates

A template is a text file that has tokens of the form ${key} which will be replaced by system supplied values. This allows you customize notifications and include current information from the server. The default information every service notification gets is

Key Description
name The name supplied by the client
email the contact email address for the client
homeUri the home URI supplied by the client
failureUri the failure URI supplied by the client
creationTime the time of the requiest
identifier the identifier generated by the system for the client
publicKey the public key supplied by the client
host The canonical host name of the server that received the request.
Any line in a template file that starts with a "#" will be ignored.

The message template

This template will be used as the body of every notification. A sample is below.

# A sample template
A client has requested approval on ${host}.

Name: ${name}
Contact email: ${email}
Home uri: ${homeUri}
Failure uri:${failureUri}
Creation time: ${creationTime}
Generated identifier: ${identifier}

If you approve this request, you should send a notice
to the contact email and include the generated identifier.

The subject template

This template will be used as the subject of every notification. A sample is below.

Client approval request received for "${name}" on ${host}

Last modified 11/20/19.
©2000-2013 Board of Trustees of the University of Illinois.