Configure jBPM to send mail

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 = "";
    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("", 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("HERE-MAIL_ADDRESS"));
             new InternetAddress("HERE-MAIL_ADDRESS"));



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="">

    <start g="43,109,48,48">
        <transition to="review" />
    <mail g="99,25,115,45" language="juel" name="review">
        <to addresses="HERE-EMAIL-ADDRESS" />
        <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" />
    <end name="end1" g="269,109,48,48" />


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"?>


  <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" />

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

    <object class="">
      <field name="commandService"><ref object="newTxRequiredCommandService" /></field>

    <object class="" init="eager" />

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

    <address-resolver />

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

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

Sent by JBoss jBPM

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



And add the file to your classpath as well:


With the above configuration, you should be able to send mail from a jbpm mail node.