Business Process Management using jBPM – Part I

Posted: March 31st, 2013 | Author: sabre1041 | Filed under: Technology | Tags: JBoss, jBPM | No Comments »

Companies are constantly searching for ways to innovate and improve efficiency. One such method is to incorporate a Business Process Management (BPM) solution into their organization. BPM involves the modeling of a business goal into distinct steps and expressing these steps visually as a workflow. There are a number of BPM solutions available on the market today, with one such solution being jBPM. jBPM is a suite of tools which aims to bridge the gap between business analysts and technical developers. There are two versions currently available, jBPM3 and jBPM5. While they each have similar goals, they are built on very different technologies. In this post, I will introduce the core technology behind jBPM3 and illustrate the underlying technology by building a simple application and deploying  the application on the JBoss Service Oriented Platform (SOA-P).

The key behind any BPM solution is the workflow defining the business process itself. A jBPM3 workflow is created as a process definition written in the jBPM Process Definition Language (jPDL) and expressed as an XML schema to describe a business process graphically. A process definition contains the logic for the workflow and is expressed using nodes, transitions and tasks. The process definition, supporting classes and libraries are packaged into a process archive (.par) file and deployed to the JBoss server. Process archives are deployed one of three ways: programmatically, using an Ant task or through the jBPM console. Seeing as jBPM3 has been available for a few years, there is a wealth of documentation compiled by others in the open source community. However, the best place to start is with the https://access.redhat.com/knowledge/docs/en-US/JBoss_Enterprise_SOA_Platform/5/html-single/JBPM_Reference_Guide/index.html as it covers the entire stack.

To help illustrate various concepts, we will build a sample application for an order intake system. At a high level, this is a very simple application. The contents of an order are received. Based on the details of the order, the order is either approved or denied. A notification of the results is then sent via email to a single recipient’s email inbox.

Before we get to the project itself, we need to make sure our environment is set up first with the following prerequisites being met:

• Apache Maven
• JBoss Developer Studio with SOA Tooling (Eclipse with JBoss Tools can also be used but this post will focus on a JBoss Developer Studio installation)
• JBoss SOA-P 5.0+

jBPM3 is included in the default, production and all profiles of the JBoss SOA-P so one of these profiles must be used for running the application. jBPM is functional out of the box, however further configuration is required for providing additional features as you will see shortly. Process definition and state is persisted to a database and is configured in the jBPM datasource file located at <JBoss_Root>/server/<JBoss_Server_Profile>/deploy/jbpm.esb/jbpm-ds.xml.

The latest jbpm-jpdl dependency is not available in the public JBoss Maven repository and must installed into the local Maven repository. Navigate to the following path:

cd <JBOSS_ROOT>/server/<Server_Profile>/deploy/jbpm.esb/

Run the following command to install the required dependencies to your local Maven repository:

mvn install:install-file -Dfile=jbpm-jpdl.jar -DgroupId=org.jbpm -DartifactId=jbpm-jpdl -Dversion=3.2.13 -Dpackaging=jar

With the dependencies in place, the sample project can be downloaded from the Git repository.The sample project is available on GitHub

Import the project into JBoss Developer Studio as an existing Maven project. If JBoss Developer Studio 5 is used, the SOA Tools add on must also be installed. It can be installed from the Software Update page within JBoss Central.

The process graph for the sample application is called processdefinition.xml and located within the workflow-jbpm3 folder in the jbpm-jbpm3 project. It should look like the following:

You can view process definition and node properties through the Properties view. If this view is not currently visible, it can be opened by navigating to Window -> Show View -> Properties. If this is not an option, click Other… Within the Show View window, expand General and select Properties.

 

Process Variables and Nodes

Process variables are key/value pairs which can be used to maintain process instance information through the execution of a workflow. In the sample application, we use process variables to store the id of the user who submitted the order and the total amount of the order. In a real world application, these values would be passed in at the beginning of the workflow. However, if we wanted to test the application from the jBPM Console, there is no way to create these variables. To work around this limitation, we create test variables at the beginning of the workflow. We accomplish this by placing the logic in a node. There are several types of nodes (task, decision, state, fork, join) whose responsibility is to compete the function of the node and to pass on process execution to the next phase of the workflow. For applying the test values, we will use a plain old node and attach a Java handler class to it. The handler class must implement the ActionHandler interface and the execute method. The sample application defines the class TestDataActionHandler as follows:

public class TestDataActionHandler implements ActionHandler {

	static final long serialVersionUID = 1L;
	private static final Logger LOGGER = LoggerFactory.getLogger(TestDataActionHandler.class);

	public void execute(ExecutionContext executionContext) throws Exception {

		try
		{
			if(executionContext.getVariable("user") == null)
			{
				LOGGER.info("Values Not Found. Setting Random Values");

				int high = 150;
				int low = 50;

				Random rand = new Random();

				String user = "User"+rand.nextInt(10);
				String amount = String.valueOf(rand.nextInt(high-low)+low);

				executionContext.setVariable("user", user);
				executionContext.setVariable("amount", amount);
			}
		}
		catch(Exception e)
		{
			LOGGER.error("An Exception Occurred", e);
		}
		finally
		{
			executionContext.leaveNode();
		}
	}
}

Within the execute method, we create a random user id and random order amount and set two process variables within the ExecutionContext. Finally, we tell the ExecutionContext to leave the node and proceed to the next step in the workflow.

Decisions

We want to have our workflow take different actions depending on whether the price of the order is above or below a certain threshold.  This is accomplished by adding a decision node to the workflow. Decisions can be modeled directly in the workflow using Expression Language, Beanshell scripts, or an external entity. Personally, I prefer using the external entity route by providing a Java class as it gives you finer grained control over the decision making process. A Java class handler which extends the DecisionHandler interface is used. The interface specifies the decide method which must be implemented returning a string value as the name of the outgoing transition which should be taken by the workflow. In our application, we have created the AmountDecisionHandler class for this purpose and created two outgoing transitions from the decision node to fulfill the handler requirements. In our handler class, we check to see if the order amount is greater than $100. If the condition is met, the transition with the name “Approved” is taken, otherwise the transition with the name “Denied” is taken.

public class AmountDecisionHandler implements DecisionHandler {

	private static final long serialVersionUID = 4843616362227490130L;

	private static final String AMOUNT_PROP = "amount";
	private static final String RESULT_PROP = "result";

	private static final String APPROVAL_TRANSITION = "to-approval";
	private static final String DENIAL_TRANSITION = "to-denial";
	private static final BigDecimal AMOUNT_THRESHOLD = new BigDecimal(100.00);

	public String decide(ExecutionContext executionContext) throws Exception {

		String amountString = (String) executionContext.getVariable(AMOUNT_PROP);

		if(amountString == null)
		{	
			executionContext.setVariable(RESULT_PROP, "Denied");
			return DENIAL_TRANSITION;
		}

		BigDecimal amount = new BigDecimal(amountString);

		if(amount.compareTo(AMOUNT_THRESHOLD) >= 0)
		{
			executionContext.setVariable(RESULT_PROP, "Approved");
			return APPROVAL_TRANSITION;
		}
		else
		{
			executionContext.setVariable(RESULT_PROP, "Denied");
			return DENIAL_TRANSITION;
		}
	}
}

 

Sending Emails

Emails are sent in jBPM3 using an Email node. In our application, we want to notify a recipient with the details of the order process. This will include the user id, order amount and result of the order approval process which was implemented previously. There are two steps required to send email via jBPM:

1. Configure the email server (jBPM system configuration)
2. Configure the email node for each individual email being sent

Configuration of email server properties is made in the jBPM configuration file (jbpm.cfg.xml). Alternatively, these settings can be placed in a properties file which is configured by setting the resource.settings.properties property to the name of the properties file. Both files would be located at the root of the classpath. The following table describes the settings required for email configuration.

 
You will find the jbpm.cfg.xml and a jbpm.mail.properties file in the src/main/resources folder of the sample application. Fill out these values accordingly to match your email server configuration. If you plan to deploy the sample application to your JBoss server, you must modify the jbpm.cfg.xml file in the <JBoss_Root>/server/<JBoss_Server_Profile>/deploy/jbpm.esb/ folder. Modify the property jbpm.mail.smtp.host which by default is set at local and update with the appropriate value. Be sure to add the other configuration, or if using an external properties file, remove the jbpm.mail.smtp.host configuration property and add a resource.settings.properties configuration.

The second component to sending emails within jBPM is to configure email nodes within the process definition. In the sample application, open the process definition and you will notice two email nodes are defined. Click on one of the email nodes and inspect the properties.  You will see a series of tabs on the left side of the pane. Click the Mail Info tab to view the details of the outgoing email. The only value requiring modification is the “To” field. Enter a destination email address you would like to have emails sent to from the sample application.The subject and body of the message has already been preconfigured.

Running the Sample Application

Within the previous sections, we have described how to modify the sample application in order to run as a JUnit test or deployed on a JBoss server. I’ll admit a lot of content was covered so I’ll provide the CliffNotes version just in case you skipped the sections above. Feel free to skip this section if you already made the necessary modifications otherwise refer back to the previous section for any material which may appear unclear.

1. Configure the email server in the jbpm.cfg.xml file
   • Host, Port, Username, Password
   • Configuration is made either within this file or configured within the an external properties file specified by the resource.settings.properties property
2. Configure each email node in the process definition
   • Set the “To” address to the recipient email address

 

Running the JUnit Test

The provided JUnit test class Jbpm3WorkflowTestIT emulates the executions of jBPM processes. The provided sample will test both workflow decision conditions: an approved order and a denied order.

Deploying the sample application

As mentioned previously, process definitions can be deployed multiple ways. Personally, I prefer to build the project using Maven and deploy the resulting process archive in the jBPM console because it allows me to view the contents of the process archive prior to deployment.

Build the project in Maven by navigating to the project directory and packaging the project using the following command which will produce a process archive (.par) in the target folder:

mvn clean package

Start up the JBoss server and navigate to the jBPM Console at http://localhost:8080/jbpm-console. Login using the default credentials of admin:admin

On the left side of the page, click “Deploy a new process” to deploy a new process definition

Click Browse and navigate to the process archive located in the target folder of the project directory and click Deploy to deploy the process

Click “Start a new instance of this process”

Tokens represent the current position within a workflow. By default, once a process is initiated, the token is positioned at the start node. Click Tokens under the Views panel on the left side of the page. You should see a token listed at the start-state node with a status of Running. Under the actions column, click Examine

Click Signal to move the token out of the start-state node

If you view the server console, you will notice the workflow has taken the appropriate decision based on random sample values, an email notification has been sent to the configured recipient and a message has been printed with the results of the decision to the server console.

That’s it! We have successfully run our sample jBPM3 application as both a JUnit test and deployed on JBoss SOA-P. In an upcoming post, we will cover the latest release,  jBPM5, and how the jBPM platform transitioned to the JBoss Business Rules Management Platform (BRMS) world and how jBPM5 compares to jBPM3.

---