Mail Server Setup

Appian sends email to notify users of task assignments and various alerts. It receives email to start processes and receive process information. Process designers can also configure the Send Email Smart Service to send email from a process application. Before Appian can send or receive emails, however, you must configure Appian to use your email server.

Sending Emails

The initial configuration is not ready to send email. The following configuration steps are required.

Configuring Appian to Send Email

  1. Open (or create) <APPIAN_HOME>/ear/suite.ear/conf/custom.properties.
  2. On a new line, add the IP address, hostname, or fully qualified domain name of the SMTP server to the following setting:conf.mailhandler.mail.smtp.host=
    • If the SMTP server runs on a port other than port 25, the : format can be used to specify the port to use for that host.
    • Multiple SMTP servers can be specified using a comma-separated list. They will be tried in the order specified and mail will be sent using the first available.

For SMTP server authentication (if required) add the following properties to <APPIAN_HOME>/ear/suite.ear/conf/custom.properties:

conf.mailhandler.mail.smtp.auth=true
conf.mailhandler.mail.user

Also add the following to <APPIAN_HOME>/ear/suite.ear/conf/passwords.properties (create the file if not already present):

conf.password.SMTP

To send email over SMTPS (a Secure Sockets Layer connection) add the following properties to <APPIAN_HOME>/ear/suite.ear/conf/custom.properties (create the file if not already present):

conf.mailhandler.mail.transport.protocol=smtps

You can enable starttls with the "smtp" protocol by adding the following property:

conf.mailhandler.mail.smtp.starttls.enable=true 

This will cause outgoing mail to use STARTTLS if supported by the remote server but will fall back to plain smtp otherwise.

You can require starttls with the "smtp" protocol by adding the following property:

conf.mailhandler.mail.smtp.starttls.required=true 

This will cause mail to fail if the remote server does not support STARTTLS.

Configuring a Process to Send Email

See also: Send Email Smart Service

Available Custom Properties

The following custom properties can be configured in <APPIAN_HOME>/ear/suite.ear/conf/custom.properties to configure sending email (inclusive of properties described elsewhere in this topic).

Property Description
conf.mailhandler.mail.smtp.host The designated host name of the email sender. List the port number if your SMTP server isn't running on port 25.
conf.mailhandler.mail.smtp.auth Set to true in order to provide credentials to the email server when establishing a connection.
conf.mailhandler.mail.user The username of the account used to connect to the email server. Only used when conf.mailhandler.mail.smtp.auth is set to true.
conf.password.SMTP

NOTE: This property must be configued in passwords.properties, not custom.properties.
The password of the account used to connect to the email server. Only used when conf.mailhandler.mail.smtp.auth is set to true.
conf.suite.MAIL_SCHEME This property (together with MAIL_APPLICATION_CONTEXT and MAIL_SERVER_AND_PORT) is used to tell the application server where to retrieve the body of an email before it is sent. You should define this property (together with the mail application context and the mail server and port) if the application server cannot readily connect to your configured site URL. The default setting is taken from your conf.suite.SCHEME configuration.
conf.suite.MAIL_APPLICATION_CONTEXT The default setting is taken from your conf.suite.APPLICATION_CONTEXT configuration.
conf.suite.MAIL_SERVER_AND_PORT The default setting is taken from your conf.suite.SERVER_AND_PORT configuration.

See also: Email Alert Address for the properties for setting the sender's email address and email display name.

Receiving Emails

The initial configuration is not ready to receive email. The following configuration steps are required.

Anonymous Access

The Anonymous user account must be enabled to allow the receipt of email messages to start a process.

See also: Anonymous User

Public Events

Public events must be enabled on the General tab of your process model's properties dialog box to enable the receipt of email messages to start a process.

See also: Public Events

Attach Appian to an Existing Email Server or Install an Email Server

Appian does not install an email server. You must set up an email server (with unique credentials for each Appian instance) in the following manner:

  1. Download a mail server (such as Apache James) and configure it to route email destined for Appian, or create an account on your existing email server to receive Appian email.
  2. On the email server, create an email address for Appian to use.
  3. Write down the email address for future reference. This account is used when sending email to Appian.
  4. If you are migrating an existing process that receives email, create an email account for each process that needs to receive email.
  5. Open <APPIAN_HOME>/ear/suite.ear/email-handler.jar/META-INF/ejb-jar.xml.example.
  6. Configure the following connection properties. Once you have configured your server settings, save the example file as <APPIAN_HOME>/ear/suite.ear/email-handler.jar/META-INF/ejb-jar.xml.
Property Description
ejbName This property identifies the EJB. It should be the same as the value in the body of the <ejb-name> element. When defining multiple <message-driven> elements to configure polling of multiple mail accounts, be sure that this value is unique for each.
mailServer The hostname, IP address, or fully qualified domain name of the mail server that Appian checks for mail messages.
mailFolder The folder from which new messages should be read. The typical value for this property is INBOX.
port An optional named property used to specify the port number used to communicate with your mail server. Specify the desired port number using an <activation-config-property-value> sub-element.
storeProtocol The protocol that is used by the mailstore (pop3, imap, or imaps).
  • If you select pop3, and you're using multiple application servers, the mail server must be set to only allow one connection at a time.
  • With Apache James, this is done by setting the connectionLimit property to 1 in config.xml.
  • Setting the connectionLimit to 1 is only feasible if the pop3 mail server is dedicated for use by Appian.
  • imap and imaps (imap Secure) are preferred protocol options when multiple application servers are in use.
  • Make sure the protocol is set to lower case. i.e (pop3 and not POP3)
starttls This property governs whether or not to use SSL when connecting to the mail server – choices: true or false (default). If you set this property to true, and you're using IMAP, the storeProtocol must be set to IMAPS.
userName This property lists the username associated with the mailbox (the email account that is setup for use by Appian) storing the messages for your processes. Appian reads the email for the address of whatever account you are using to log into the email server. Depending on the brand, version, and configuration of your mail server, one of the following username formats may be applicable:
      username
      username@domain.tld
      DOMAIN\username
      DOMAIN\username\mailboxname
      
Note that the password corresponding to this username is not set in this file. Instead, it's set using the conf.password.<ejbName>.EMAIL_HANDLER properties in the passwords.properties file. (more information below)
pollingInterval This property indicates the frequency (in milliseconds) of how often the MDB logs into the mail server to check for new messages. The default setting is 100 years. This prevents error messages from showing up in the console if the customer does not configure the properties to allow it to connect to a mail server. The default in the example file is set to 5 minutes. More frequent polling intervals may not be allowed by the mail server (consult with your organization's email administrator when setting this value).

Setting the password for the email account(s) polled by Appian is accomplished using the passwords.properties configuration file.

  1. Open or create <APPIAN_HOME>/ear/suite.ear/conf/passwords.properties.
  2. Add the property conf.password.<ejbName>.EMAIL_HANDLER, where <ejbName> is replaced with the value of the name as configured in the <activation-config-property-value> element that corresponds to the <activation-config-property-name>ejbName</activation-config-property-name> element.
  3. Set the value of this property to the password corresponding to the userName defined for the given ejbName.
  4. Repeat this for each of the email accounts configured for polling.

For example, if using the default EJB definition as given in the ejb-jar.xml.example file, which has the ejbName property set to "EmailHandlerBean", assume that the account has the password "S3cr3t!". The following configuration should be placed in passwords.properties:

conf.password.EmailHandlerBean.EMAIL_HANDLER=S3cr3t!

The following ejb-jar.example.xml file can be used as the starting point for configuring your mail server connection(s).

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar metadata-complete="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:ejb="http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd" version="3.0">
<display-name>EmailHandlerMDB</display-name>
 <enterprise-beans>
    <message-driven>
       <description>An MDB that accepts mail messages</description>
       <ejb-name>EmailHandlerBean</ejb-name>
       <ejb-class>com.appiancorp.mdb.EmailHandlerBean</ejb-class>
       <messaging-type>com.appiancorp.ra.emailpoller.MailListener</messaging-type>
       <!--  these activation config properties must be configured to match the mail system -->
       <activation-config>
          <activation-config-property>
             <activation-config-property-name>ejbName</activation-config-property-name>
             <activation-config-property-value>EmailHandlerBean</activation-config-property-value>
          </activation-config-property>
          <activation-config-property>
             <activation-config-property-name>mailServer</activation-config-property-name>
             <activation-config-property-value>yourmailserver.yourdomain.com</activation-config-property-value>
          </activation-config-property>
          <activation-config-property>
             <activation-config-property-name>mailFolder</activation-config-property-name>
             <activation-config-property-value>INBOX</activation-config-property-value>
          </activation-config-property>
          <activation-config-property>
             <activation-config-property-name>storeProtocol</activation-config-property-name>
             <activation-config-property-value>pop3</activation-config-property-value>
          </activation-config-property>
          <activation-config-property>
             <activation-config-property-name>starttls</activation-config-property-name>
             <activation-config-property-value>false</activation-config-property-value>
          </activation-config-property>
          <activation-config-property>
             <activation-config-property-name>userName</activation-config-property-name>
             <activation-config-property-value>appianEmailReceiverUser</activation-config-property-value>
          </activation-config-property>
          <activation-config-property>
             <!-- polling interval in milliseconds 
                  the setting provided below is every 5 minutes 
                  consult your mail admin for acceptable frequecy -->
             <activation-config-property-name>pollingInterval</activation-config-property-name>
             <activation-config-property-value>300000</activation-config-property-value>
          </activation-config-property>
       </activation-config>
    </message-driven>
 </enterprise-beans>
</ejb-jar>

Routing Email Messages

Email messages are routed to process models, processes, or events using destination key value pairs embedded within the subject or body of the email. When formatting a routing key and value, use the bracketed [key=value] format. For example:

[DestinationPMUUID=0006d222-3c28-8000-1944-82000]

This key/value pair routes a message to a process model with the process model UUID of 0006d222-3c28-8000-1944-82000.

The following destination keys are available:

DestinationPMID - The ID of the process model

DestinationPMUUID - The UUID of the process model

DestinationProcessID - The ID of the process instance

DestinationEventPersistentID - The event persistent ID of the Receive Message Event node

Email Routing Details

If an email does not contain a proper key/value pair for routing, the message routing fails and an error message is logged.

  • Mail that cannot be routed because of missing destination information is returned to the original sender.

Key/value pairs remain in the email message after it is routed to its destination.

  • To exclude the routing information from the body of an email message, you can place the key/value pair in the subject line of the message.

Destination keys can only contain alpha-numeric characters and cannot begin with a numeric character.

  • If a destination key begins with an invalid character, it is automatically replaced in the following manner.
Starts With Replaced With Comment
Numeric character (0-9) initial_#_ The # symbol refers to the disallowed numeric character (0-9).
Any non alpha-numeric character initial___ Three underscore characters are used.

If a non alpha-numeric character (such as @) appears in the destination key (after the starting character) it is replaced with an underscore character (_).

As a best practice, adhere to the following:

  • Use the process model UUID instead of the process model ID for email routing.
  • Unlike the process model's ID property, the process model's UUID does not change when the process model is moved to a different server.
  • Email routing does not have to be reconfigured for events in process models that are exported and imported (as part of an application) when messages are routed to the event using a DestinationPMUUID key value pair.

Configuring Appian to Poll Additional Email Accounts

  1. Open a configured <APPIAN_HOME>/ear/suite.ear/email-handler.jar/META-INF/ejb-jar.xml file.
  2. Add a copy of the entire <message-driven> element of a configured connection, after the original </message-driven> closing tag.
  3. Assign a unique name in the body of the <ejb-name> element in the newly added message-driven element.
  4. Change the ejbName.
    • Edit the <activation-config-property-value> element that is paired with the ejbName <activation-config-property-name> element in the newly added message-driven element.
    • List the ejbName of the secondary email account that you want to add, making it match the <ejb-name> element you modified in the previous step.
  5. Change the userName.
    • Edit the <activation-config-property-value> element that is paired with the userName <activation-config-property-name> element in the newly added message-driven element.
    • List the userName of the secondary email account that you want to add.
  6. Update any other <activation-config-property> elements needed to establish a proper connection with your secondary email account.
    • For example, update the value paired with the mailServer named element if the secondary email account resides on a different email server.
  7. Add the password for the new account.
    • Open or create <APPIAN_HOME>/ear/suite.ear/conf/passwords.properties
    • Add the property conf.password.<ejbName>.EMAIL_HANDLER, where <ejbName> is replaced with the value of the name as configured in the <activation-config-property-value> element that corresponds to the <activation-config-property-name>ejbName</activation-config-property-name> element.
  8. Open the <APPIAN_HOME>/ear/suite.ear/email-handler.jar/META-INF/jboss.xml file (or the relevant file in the same directory that corresponds to your application server).
    • Add a copy of the entire <message-driven> element.
    • In the copy, change the value of the <ejb-name> element to correspond to the <ejb-name> element in your newly added <message-driven> element in ejb-jar.xml.

Adding a Routing Alias to custom.properties

Message driven beans can use aliases for routing the email messages received. You can create aliases for process models UUIDs, process model IDs, processes, or events. Configuring an email alias is recommended when handling legacy email addresses.

  1. Open (or create) <APPIAN_HOME>/ear/suite.ear/conf/custom.properties.
  2. Add a custom alias definition using the following pattern.

    conf.mailhandler.alias.=

For example, with an email alias of HelpDeskRequest@mydomain.topdomain, define a process model start event target using a UUID with the following parameters.

conf.mailhandler.alias.HelpDeskRequest=processmodeluuid0004cedf-a045-8000-234b-c0a8031014c0

The following routing prefixes can be used when defining an alias.

  • processmodeluuid
  • processmodel
  • process
  • event

Any routing key/value pairs in email sent to an address with an alias are used for routing instead of the alias; key/value pairs are evaluated first. Alias definitions are only used when routing information is not available.

Configuring a Process to Receive Email

See also: Start Event: Receive Message

Available Custom Properties

The following custom properties can be configured in <APPIAN_HOME>/ear/suite.ear/conf/custom.properties to configure receiving email (inclusive of properties described elsewhere in this topic).

Property Description
conf.mailhandler.alias.<recipientName>=<routing> A routing alias for email received by Appian.

Testing and Troubleshooting

Testing the Email Service

  1. Verify that your mail server is running.
  2. From a command prompt, type the following:

    telnet [mail.server.name] [port#]
    

    For example, if Appian is installed on server_name.mydomain.com, and the mail server is running on port 26, you would enter the following command.

    telnet server_name.mydomain.com 26
    
  3. Verify the mail server is running properly. For example, for Apache James, the following reply is displayed:

    220 servername SMTP Server (JAMES SMTP Server 2.2.0) ready Day, #1. Mmm yyyy hh:mm:ss -1200 (GMT-12:00)
    
  4. Type the following based your email address:

    EHLO myemail@mydomain.com
    

    You should receive the following reply.

    250 server-name Hello youremail@yourdomain.com (connecting.machine.hostname [ip.address]) 
    
  5. If you are using an older SMTP server version that does not support EHLO, use the HELO command.

  6. Log into Appian.

  7. Create a simple process that sends yourself an email.

  8. Save, publish, and run the process.

    • If your user profile lists your correct email address, you should receive an email notification when the process completes.
  9. If you do not receive the email, check the mail server log files, as well as the application server log

Troubleshooting Email Configuration

What if it doesn't appear to be working?

  1. Connect to the email server from an email client using the credentials you've specified in ejb-jar.xml.
  2. Verify that the account is the one that you want to use for Appian.
  3. Test this account's ability to send and receive email.
  4. Note the username format and the protocol used by the email client (such as POP3 or IMAP). Use the same format and settings in your configuration.
  5. If using a secure protocol, verify that the certificate presented by the email server is trusted by the JVM.

What if I send email to an Appian event and nothing happens?

The mail server might be down.

  1. Verify its status and restart it if necessary.
  2. Make sure that you are sending all the properties that are expected by the event and that the event is active.
  3. Make sure the latest version of your process is published. If you are trying to send email to a start event, check your alerts. In some scenarios, an error alert is generated that explains the issue.
  4. Double-check the email address you are using.

How can I determine whether or not emails are reaching my mail server?

Check the smtpserver.log for your mail server. This file should have an entry for every email received.

How can I determine whether my mail server is establishing a connection with Appian to receive emails?

Add the following sub-element property definition within the <activation-config> element of your ejb-jar.xml file.

<activation-config-property>
    <activation-config-property-name>debug</activation-config-property-name>
    <activation-config-property-value>true</activation-config-property-value>
</activation-config-property>

NOTE: Debug logging will include sensitive information such as the plain-text password used to connect to the mail server.

Review the JBoss console output to confirm whether a connection is being established. The debug messages are not written to a log file. They are only written to the JBoss console.

What if fetching is slow?

If fetch time for large emails is too long, you may need to disable partial fetch. To do this, follow these steps:

  1. Add the following to ear/suite.ear/email-handler/src/META-INF/ejb-jar.xml:

    <activation-config-property>
        <activation-config-property-name>partialFetch</activation-config-property-name>
        <activation-config-property-value>true</activation-config-property-value>
    </activation-config-property>
    
  2. Change the partialFetch property from the default true to false.

Mail Server Won't Start Due to a Bind Error

Another application (such as sendmail) is conflicting with your mail server on one or more ports (usually POP, port 110, or SMTP port 25). Look for clues in the stack trace about which server is conflicting (one of the classes in the stack should contain the type of server). There are two possible remedies:

  • Find the program that is conflicting (using a tool such as TCPView) and shut it down. Disable it from starting so that it does not conflict again.
  • In config.xml change the port for that server to an unused port (NOTE: If you change the SMTP port, and you are relaying messages through Microsoft Outlook, you will have to change the port in your Outlook account settings as well.)

Configuring Notifications

See also: Configuring Notifications

FEEDBACK