Sunday, November 7, 2010

Using Activiti's email task

In a small series of posts we show how to get started with Activiti BPMS by getting simple processes running on Activiti Engine. Today an Activiti specific construct will be addressed; the email task. To demonstrate this task we build a very small one-step process with Activiti's rc1 release and test it in Eclipse.

Before we can do that we need to set up a mail server first. We will use the Apache James project to do that. Download Apache James from and unzip de file in a directory of choice. We are not going to do anything very secure in this example so we will use the default setup. You can start the server by executing the or run.bat file in the james_install_dir/bin directory.

After the server is up and running smoothly in the background we need to add a user account so we have somebody to mail to from the process. Start a telnet session with localhost on port 4555; you can login with the preconfigured root user, password root. Then add a user with the following command:

Adduser miss.piggy piggy

A user called miss.piggy is added with the email address miss.piggy@localhost and the password piggy. To check if Miss Piggy’s account is actually added you can execute the listusers command to verify. The screenshot below gives a view on the telnet session to summarize things.

That is all there is to it. The James mail server is configured correctly and waiting to receive mails on port 25. Back to Activiti!

Now that our mail server is up and running smoothly we are ready to declare an email task in the BPMN 2.0 XML file. For the detailed information concerning different configuration options for the email task within Activiti you can check out the Activiti user guide. We will stick to the basics for the moment and create a simple standalone process that sends an email to the customer to test the mail server configuration.

<process id="simpleEmailProcess" >
<startEvent id="theStart" />
<sequenceFlow sourceRef="theStart" targetRef="sendMail" />
<serviceTask id="sendMail" activiti:type="mail">
<activiti:field name="to" expression="${recipient}"
<activiti:field name="subject">
<activiti:string>Hello ${name}!
<activiti:field name="html">
Hello ${name},<br/>
Just saying hi!<br/>
Kind regards,
<sequenceFlow sourceRef="sendMail" targetRef="theEnd" />
<endEvent id="theEnd" />

You can now run the process as we have done before within Eclipse, for example with a unit test. Make sure you deploy the BPMN 2.0 XML file correctly in the test and set up a process variables map with the name and recipient variable before you start the process from the code. Take a look at the JavaServiceTaskTest code in an earlier blog if you need a reminder of how to do this. Make sure that the mail server port in the activiti.cfg.xml file is configured for port 25.

When you are done, run the test. After the process is finished you should have received an email in the james_install_dir/apps/james/var/mail/inboxes/miss.piggy directory. To view the email you can install an email client like for example Mozilla Thunderbird. James is using the default ports in the standard setup, so you only have to configure Miss Piggy’s account.

That is all there is to it! Next time a look at gateways and event listeners..