Email:Email tag failure after enabling Clarity mail configuration with TLS

Products

• Clarity PPM On Premise

Issue/Introduction

After enabling TLS (Transport Layer Security) for the SMTP mail server configuration in Clarity, processes utilizing the standard Apache Jelly mail:email tag (xmlns:email="jelly:email") fail. This issue specifically occurs when attempting to send emails with file attachments through a process. The process aborts with the following error message:

BPM-0704: An error occurred while executing custom script: org.apache.commons.jelly.JellyTagException: null:16:74: <mail:email> 530 #5.7.0 Must issue a STARTTLS command first at org.apache.commons.jelly.tags.email.EmailTag.doTag(EmailTag.java:302)

It's important to note that other Clarity email functionalities, such as regular system notifications and processes using the Clarity-specific gel:email tag (xmlns:gel="jelly:com.niku.union.gel.GELTaglibrary"), continue to function correctly with the TLS-enabled mail server. The problem is isolated to the mail:email tag's interaction with the TLS requirement.

We ensure following all the steps mentioned in below KB article:
Clarity Email configuration issue with STARTTLS

Environment

Clarity 16.3.3

Cause

The mail:email or email:email tag is part of the standard Apache Commons Jelly tag library. Its underlying JavaMail API implementation does not explicitly issue the STARTTLS command when connecting to an SMTP server.

When the mail server is configured to enforce TLS, it expects a STARTTLS command from the client before establishing a secure, encrypted connection. Since the mail:email tag does not send this command, the SMTP server rejects the connection, resulting in the "530 #5.7.0 Must issue a STARTTLS command first" error. This is a known limitation of the specific Apache Jelly mail:email tag implementation.

For more information on the Apache Jelly Email tag library and its support tags, refer to: https://commons.apache.org/proper/commons-jelly/libs/email/tags.html#jelly:email

Resolution

The Clarity product's native gel:email tag (from the namespace xmlns:gel="jelly:com.niku.union.gel.GELTaglibrary") does support SMTPS and SMTP with STARTTLS (from Clarity 16.3.0 onwards), aligning with other Clarity email notification features.

However, the gel:email tag currently does not support sending attachments. Therefore, it cannot directly replace the mail:email tag for processes that require attaching files to emails.

Actionable Steps :

1. For processes requiring attachments:
   
   A direct out-of-the-box solution using either email:email or gel:email is not available if STARTTLS is mandatory and attachments are critical.
   
   
2. For processes sending without attachments
   
   Switch from using the email:email tag to the gel:email tag within your processes. The gel:email tag is compatible with TLS-enabled mail servers and will allow emails to be sent successfully (without attachments).