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

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.

Download the latest version of java mail from here. Drop this jar (typically named mail.jar) into your $CATALINA_HOME/lib directory.
Possibly get the javax.activation framework jar. This might be needed if you are getting errors sending email messages acessing the javax.activation.DataHandler class. Put it into the above Tomcat lib directory.
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"
         username="fionna@nazghul.org"
         debug="false"
      	 server="smtp.super-secure-server.net"
         recipients="admin@chem.bigstate.edu;staff@it.bigstate.edu">
         <messageTemplate>/opt/oa4mp/server/etc/oa4mp-message.template</messageTemplate>
         <subjectTemplate>/opt/oa4mp/server/etc/oa4mp-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}

OA4MP