One common problem many users face in Java is sending mail through a Microsoft Exchange server. In this tutorial we will show how to send an authenticated mail using Java Mail Api and how to configure JBPM to use our Authenticator.

Sending a mail through Microsoft Exchange Server

The first problem will be sending an authenticated mail using Java Mail Api.

Pick up your Microsoft Exchange server address and add it as SMTP_HOST_NAME in this code. Replace as well SMTP_AUTH_USER and SMTP_AUTH_PWD with your user and password.

package sample;

import javax.mail.*;
import javax.mail.internet.*;
import javax.mail.Authenticator;
import javax.mail.PasswordAuthentication;

import java.util.Properties;


public class MailWithAuthentication {

    private static final String SMTP_HOST_NAME = "192.168.10.1";
    private static final String SMTP_AUTH_USER = "fmarchioni";
    private static final String SMTP_AUTH_PWD  = "francesco";

    public static void main(String[] args) throws Exception{
       new MailWithAuthentication().test();
    }

    public void test() throws Exception{
        Properties props = new Properties();
        props.put("mail.transport.protocol", "smtp");
        props.put("mail.smtp.host", SMTP_HOST_NAME);
        props.put("mail.smtp.auth", "true");

        Authenticator auth = new SMTPAuthenticator();
        Session mailSession = Session.getDefaultInstance(props, auth);
        // uncomment for debugging infos to stdout
        // mailSession.setDebug(true);
        Transport transport = mailSession.getTransport();

        MimeMessage message = new MimeMessage(mailSession);
        message.setContent("This is a test", "text/plain");
        message.setFrom(new InternetAddress("
 This e-mail address is being protected from spambots. You need JavaScript enabled to view it
 "));
        message.addRecipient(Message.RecipientType.TO,
             new InternetAddress("
 This e-mail address is being protected from spambots. You need JavaScript enabled to view it
 "));

        transport.connect();
        transport.sendMessage(message,
            message.getRecipients(Message.RecipientType.TO));
        transport.close();
    }

   
}

package sample;

public class SMTPAuthenticator extends javax.mail.Authenticator {
        public PasswordAuthentication getPasswordAuthentication() {
           String username = SMTP_AUTH_USER;
           String password = SMTP_AUTH_PWD;
           return new PasswordAuthentication(username, password);
        }
}

Run your MailWithAuthenticator class and verify that the mail is received correctly.

If you receive an error like "Connection Refused" it's likely that there's a firewall problem. It can be either that you have a firewall on your machine (most likely) or that you have another firewall between you and the mail server.

Sending a mail from your JBPM process.

Ok, now let's move to jbpm. JBPM has built-in support for mail with mail nodes. However the main configuration file (jbpm-cfg.xml) has default non-authentication mail support, so we have to extend its configuration.

Let's start with a simple process:

<?xml version="1.0" encoding="UTF-8"?>

<process name="MailExample4" xmlns="http://jbpm.org/4.3/jpdl">

    <start g="43,109,48,48">
        <transition to="review" />
    </start>
    <mail g="99,25,115,45" language="juel" name="review">
        <to addresses="
 This e-mail address is being protected from spambots. You need JavaScript enabled to view it
 " />
        <subject>This is the subject</subject>
        <text>This is the body of the message with a ${property} </text>
        <transition name="to end1" to="end1" g="-42,-18" />
    </mail>
    <end name="end1" g="269,109,48,48" />

</process>

Here, the sendmail node takes care to send an e-mail to the address specified by the <to addresses > tag.

Now the configuration: the configuration is contained in jbpm-cfg.xml. In this file you have the Mail Session properties and the Authenticator class which will be used to authenticate your mail on MS Exchange Server.

Where is the pitfall ? as reported by many users on jbpm forum, by upgrading jbpm-cfg.xml with just the <mail-session> information seem not to work. Because, if you import <import resource="jbpm.default.cfg.xml" /> then JBPM does not override the <mail-session> information provided.

So the solution is not to import jbpm.default.cfg.xml file. Rather insert it in your project with the <mail-session> information as follows:

<?xml version="1.0" encoding="UTF-8"?>

<jbpm-configuration>

   
  <import resource="jbpm.businesscalendar.cfg.xml" />
  <import resource="jbpm.tx.hibernate.cfg.xml" />
  <import resource="jbpm.jpdl.cfg.xml" />
  <import resource="jbpm.bpmn.cfg.xml" />
  <import resource="jbpm.identity.cfg.xml" />
  <import resource="jbpm.default.scriptmanager.xml" />

  <process-engine-context>
  
    <repository-service />
    <repository-cache />
    <execution-service />
    <history-service />
    <management-service />
    <identity-service />
    <task-service />

    <object class="org.jbpm.pvm.internal.id.DatabaseDbidGenerator">
      <field name="commandService"><ref object="newTxRequiredCommandService" /></field>
    </object>

    <object class="org.jbpm.pvm.internal.id.DatabaseIdComposer" init="eager" />

    <types resource="jbpm.variable.types.xml" />

    <address-resolver />

    <mail-template name='task-notification'>
      <to users="${task.assignee}"/>
      <subject>${task.name}</subject>
      <text><![CDATA[Hi ${task.assignee},
Task "${task.name}" has been assigned to you.
${task.description}

Sent by JBoss jBPM
]]></text>
    </mail-template>
  
    <mail-template name='task-reminder'>
      <to users="${task.assignee}"/>
      <subject>${task.name}</subject>
      <text><![CDATA[Hey ${task.assignee},
Do not forget about task "${task.name}".
${task.description}

Sent by JBoss jBPM
]]></text>
    </mail-template>
  
  </process-engine-context>

  <transaction-context>
    <repository-session />
    <db-session />
    
    <message-session />
    <timer-session />
    
    <history-sessions>
      <object class="org.jbpm.pvm.internal.history.HistorySessionImpl" />
    </history-sessions>
    
    <mail-session>
      <mail-server>
        <session-properties resource="jbpm.mail.properties" />
        <authenticator class="sample.CustomAuthenticator" auto-wire="true"/>
      </mail-server>
    </mail-session>

  </transaction-context>

</jbpm-configuration>

And add the jbpm-mail.properties file to your classpath as well:

mail.smtp.auth=true
mail.smtp.host=192.168.10.1
mail.smtp.port=25
mail.transport.protocol=smtp

With the above configuration, you should be able to send mail from a simple java class and from JBPM mail nodes.