KB-1293 How to troubleshoot issues with emails not triggering processes in Appian

Purpose

This article details some common scenarios where emails fail to trigger processes in Appian. There are multiple causes for this issue and the article discusses the most common causes.

The article assumes that the necessary configuration to poll email servers is already in place. Review the Sending an Email Message to a Process documentation for details on how to send an email to a process in Appian.

Instructions

1. Connection issue between Appian Servers and the Email Server

The most common cause of emails not triggering processes in Appian is no network communication between Appian and the email server it is supposed to poll.

A common way to troubleshoot is by running a "telnet" from the Appian servers and see if you can connect to the email server. Note: In Windows, telnet needs to be enabled by following these steps.

2. Check for errors in the mail-listener.log

If you are able to telnet as expected following step 1, you can check the mail-listener.log present in the <APPIAN_HOME>/logs directory to see if there are any error messages present in this file. This log is a good starting point to see if the application server is polling the mail server as expected but is not able to fetch the emails.

For example, you might see something like the following error, which indicates there could be something at the network layer preventing Appian from connecting to the mailbox:

[Appian MailActivation - 1] ERROR com.appiancorp.ra.emailpoller.MailActivation - An error occurred while attempting to open the mailbox to poll; no mail will be fetched.
javax.mail.MessagingException: connect timed out;
  nested exception is:
        java.net.SocketTimeoutException: connect timed out
     .
     .
     .
     Caused by: java.net.SocketTimeoutException: connect timed out

3. Add DEBUG logging

If there are no errors in the mail-listener.log, add DEBUG logging to get insight on exactly what is happening when the application server polls the mail server.

DEBUG logging prints out every detail from the handshake between the application server and the mail server, including the number of new messages the application server found from the last time it polled the mailbox, the recipients of the email, the body, etc. Depending on the use case, these DEBUG messages can be helpful. Note: Since this output includes the contents of emails, it may contain sensitive information.

18.2 and later

To add DEBUG logging, the following line must be added or uncommented in custom.properties:

conf.mailhandler.poller.EmailHandlerBean.debug=true

18.1 and earlier

In between the <activation-config> tags in the ejb-jar.xml file (located in <APPIAN_HOME>/ear/suite.ear/email-handler.jar/META-INF), for the mailbox that is having issues, add the following tags:

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

4. Add DEBUG logging to print engine activity

Step 3 covers the handshake between the application server and the mail server. After the application server picks up the email, it has to route the message to the right process/process model. At this point, the application server needs to interact with the Appian engines. In the event you don't see any errors after step 3 and processes are still not launched in Appian, you can perform the steps below to get an insight on the engine activity:

Navigate to <APPIAN_HOME>/ear/suite.ear/resources and edit appian_log4j.properties.
Add the following three lines at the end of the file. If the lines are already present, uncomment them:

log4j.logger.com.appiancorp.messaging.MessagePublisherServiceImpl=DEBUG
log4j.logger.com.appiancorp.process.execution.service.ProcessExecutionServiceFacade=DEBUG
log4j.logger.com.appiancorp.mdb.EmailHandlerBean=DEBUG

In an ideal scenario, you would see messages like the following being printed in the application-server.log where you see the email is being correctly routed to the Execution and the Design engines:

INFO  [stdout] (Appian EmailHandlerBean - 2) YYYY-MM-DD HH:MM:SS,MMM [Appian EmailHandlerBean - 2] DEBUG com.appiancorp.messaging.MessagePublisherServiceImpl - publishing 1 message(s) to Process Execution
INFO  [stdout] (Appian EmailHandlerBean - 2) YYYY-MM-DD HH:MM:SS,MMM [Appian EmailHandlerBean - 2] DEBUG com.appiancorp.messaging.MessagePublisherServiceImpl - published 1 message(s) to Process Execution
INFO  [stdout] (Appian EmailHandlerBean - 2) YYYY-MM-DD HH:MM:SS,MMM [Appian EmailHandlerBean - 2] DEBUG com.appiancorp.messaging.MessagePublisherServiceImpl - publishing 1 message(s) to Process Design
INFO  [stdout] (Appian EmailHandlerBean - 2) YYYY-MM-DD HH:MM:SS,MMM [Appian EmailHandlerBean - 2] DEBUG com.appiancorp.messaging.MessagePublisherServiceImpl - published 1 message(s) to Process Design

Affected Versions

This article applies to all versions of Appian.

Last Reviewed: January 2021