KB-1028 System emails/process emails are no longer being sent with an "Email body failed to render...unable to find valid certification path to requested target" error

Symptoms

In an environment with a web server with SSL enabled without making other configuration changes, the following symptoms will occur:

• System emails for account creation are not sent.
• System emails for resetting a password are not sent.
• Process models with Send Email nodes are paused.
• The application server log will contain the following errors:
  

  ERROR com.appiancorp.ra.workpoller.WorkItemListener - The following exception occurred while attempting to complete work item [(WorkId: 14, WorkType: [AbstractMailRequest: from=null, to=xxxx@appiancorp.com, subject=Appian account creation], Response: null, ServerName: NotificationsEmail)] - Exception:
  javax.resource.spi.work.WorkCompletedException: com.appiancorp.process.engine.EmailBodyException: Email body failed to render
  …
  Caused by: javax.ejb.EJBException: com.appiancorp.process.engine.EmailBodyException: Email body failed to render
  …
  Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
  

Cause

This error will be seen when an Appian environment is configured with a web server to use HTTPS/SSL scheme. All email requests in Appian are routed through the server specified in the conf.suite.SERVER_AND_PORT property unless values are given for conf.suite.MAIL_SCHEME and conf.suite.MAIL_SERVER_AND_PORT, all found in custom.properties located in <APPIAN_HOME>/ear/suite.ear/conf.

The above symptoms are a result of Appian trying to route email requests from the application server to the web server. As the web server has been configured with SSL, the application server needs to use SSL for creating the email body. By default, the application server does not have the necessary certificates to create this connection and thus it fails to create the email body.

Action

The error can be resolved by using the application server to create the email body instead of the web server. Change the following lines in the custom.properties file located on the application server:

conf.suite.MAIL_SCHEME=http
conf.suite.MAIL_SERVER_AND_PORT=localhost:<APP_SERVER_PORT>

Save the file and restart the application server for the changes to take effect.

Workaround

In a situation where the application server is not accessible, then the certificate needs to be imported into the trusted keystore of the JDK. This is not recommended because the certificate needs to be imported every time JDK is updated. Run the following commands to import the certificates into the Java Keystore:

1. cd <JAVA_HOME>/bin
2. keytool -import -alias <webserver.example.com> -file <CERT_NAME>.crt -keystore "<JAVA_HOME>/jre/lib/security/cacerts"

Note: The value of webserver.example.com should match conf.suite.SERVER_AND_PORT set in the custom.properties.

Affected Versions

This article applies to all versions of Appian.