jBPM for Developers: Part 1

In this article, the following key points will be covered:

  • Common development process
  • Decoupling processes from our applications
  • Graph Oriented Programming
    • Modeling nodes
    • Modeling transitions
    • Expanding our language
  • Implementing our graph-oriented solution in Java
  • Wait states versus automatic nodes
  • Executing our processes

Let's get started with the main cornerstone behind the framework. This article will give us the way to represent our business processes using the Java language and all the points that you need to cover in order to be able to represent real situations.

Graph Oriented Programming

We will start talking about the two main concepts behind the framework's internal implementation. The Graph Oriented Programming (GOP) approach is used to gain some features that we will want when we need to represent business processes inside our applications. Basically, graph oriented programming gives us the following features:

  • Easy and intuitive graphical representation
  • Multi-language support

These are concepts that jBPM implementers have in mind when they start with the first version of the framework. We are going to take a quick look at that and formulate some code in order to try to implement our minimal solution with these features in mind.

Starting with GOP as a bigger concept, you will see that the official documentation of jBPM mentions this topic as one of the most important concepts behind the framework. Here, we will reveal all of the advantages that this approach implementation will give us. Basically, by knowing GOP, we will gain complete knowledge about how processes are represented and how they are executed.

Therefore, a common question here is, why do we need a new approach (GOP) for programming our processes when we have already learnt about the object-oriented programming paradigm?

Common development process

In order to answer the previous question, we will quickly analyze the situation here. To achieve this, we need to understand the nature of our processes. We will also analyze what kind of advantages developers gain when the business process information is decoupled from the rest of the application code.

Let's clarify this point with a simple example. Imagine that we have to build an entire application that represents the stages in the "Recycling Things Co." example previously presented. The most common approach for a three-tier application and development process will be the following:

jBPM Developer Guide

This is a traditional approach where all the stages are iteratively repeated for each stage/module of the application.

One thing that we can notice here, and which happens in real software projects, is that the business analyst's description will be lost in the design phase, because the business analyst doesn't fully understand the design class diagrams as these diagrams are focused on implementation patterns and details. If we are lucky and have a very good team of business analysts, they will understand the diagrams. However, there is no way that they could understand the code. So, in the best case, the business analyst description is lost in the code—this means that we cannot show our clients how the stages of their processes are implemented in real working code. That is why business analysts and clients (stakeholders) are blind. They need to trust that we (the developers) know what we are doing and that we understand 100 percent of the requirements that the business analysts collect. Also, it is important to notice that in most of the cases, the client validates the business analyst's work—if changes emerge in the implementation phase, sometimes these changes are not reflected in the business analyst's text and the client/stakeholders never realize that some implementation aspect of their software changes.

Maybe they are not functional changes, but there are sometimes changes that affect the behavior of the software or the way users will interact with it. This uncertainty generated in the stakeholder causes some dependency and odd situations where the stakeholder thinks that if he/she cannot count on us (the developers and architects team) any longer, nobody will be able to understand our code (the code that we write). With this new approach, the client/stakeholders will be able to perceive, in a transparent way, the code that we write to represent each business situation. This allows them (the stakeholders) to ask for changes that will be easily introduced to reflect everyday business requirements. Let's be practical and recognize that, in most situations, if we have the application implemented in a three-tier architecture, we will have the following artifacts developed:

Database model

That includes logic tables to do calculations, UI tables to store UI customizations or users' data about their custom interfaces, domain entities (tables that represent the business entities, for example, Invoice, Customer, and so on), and history logs all together.

Business logic

If we are careful developers, here we are going to have all of the code related to a logical business processes method. In the case of the example, here we will have all the stages represented in some kind of state machine in the best cases. If we don't have a kind of state machine, we will have a lot of if and switch statements distributed in our code that will represent each stage in the process. For example, if we have the same application for all the branches of a company, this application will need to behave differently for the main office's employee than for the 'just finished' warehouse employee. This is because the tasks that they are doing are very different in nature. Imagine what would happen if we want to add some activity in the middle, probably the world would collapse! Developers will need to know in some depth how all the if and switch statements are distributed in the code in order to add/insert the new activity. I don't want to be one of these developers.

User interfaces

Once again, if we are lucky developers, the process stages will not be represented here, but probably many if and switch statements will be dispersed in our UI code that will decide what screen is shown to each of the users in each activity inside the process. So, for each button and each form, we need to ask if we are in a specific stage in the process with a specific user.

Decoupling processes from our applications

By decoupling the business process from these models, we introduce an extra layer (tier) with some extra artifacts, but this helps us to keep the application simple.

jBPM Developer Guide

This new paradigm proposed here includes the two Business Process Management (BPM) roles in all the development and execution stages of our processes (business analysts and developers). This is mainly achieved through the use of a common language that both sides understand. It lets us represent the current process that the business analysts see in the everyday work inside the company, and all of the technical details that these processes need, in order to run in a production environment. As we can see in the next image, both roles interact in the creation of these new artifacts.

We don't have to forget about the clients/managers/stakeholders that can validate the processes every day as they are running them. Also, they can ask for changes to improve the performance and the current way used to achieve the business goal of the process.

jBPM Developer Guide

On comparing with the OOP paradigm, class diagrams here are commonly used to represent static data, but no executional behavior. These newly created artifacts (process definitions) can be easily represented in order to be validated by our clients/stakeholders. One of the main advantages of this approach is that we can get visibility about how the processes are executed and which activity they are in at any given moment of time. This requirement will force us to have a simple way to represent our business processes—in a graphicable way. We need to be able to see, all the time, how our production processes are running.

Graph Oriented Programming on top of OOP

Here, we will discuss the main points of the Graph Oriented Programming paradigm. With this analysis, we will implement some basic approach to understand how we use this paradigm on top of the Java language in the next section.

In order to do that, we need to know the most important requisites that we have to fulfill in order to achieve the goal which integrates, maintains, and executes our business processes in real-world implementation:

  • Easy and intuitive graphical representation: To let the business analysts and developers communicate smoothly and to fully understand what is happening in the real process.
  • Must give us the possibility of seeing the processes' executions in real time: In order to know how our processes are going on to make more accurate business decisions.
  • Could be easily extended to provide extra functionality to fulfill all of the business situations.
  • Could be easily modified and adapted to everyday business (reality) changes. No more huge development projects for small changes and no more migrations.

Implementing Graph Oriented Programming on top of the Java language (finally Java code!)

With these requisites, presented in the previous section, in mind, we are able to implement a simple solution on top of the Java language that implements this new approach (called the Graph Oriented Programming paradigm). As the name of the paradigm says, we are going to work with graphs—directed graphs to be more precise.

A graph can be defined as a set of nodes linked to each other as the following image shows us:

jBPM Developer Guide

If we are talking about directed graphs, we need to know that our nodes will be linked using directed transitions. These transitions will be directed, because they will define a source node and a destination node. This means that if we have a transition that has node A as the source node, and node B as the destination node, that transition will not be the same as the one that has node B as the source node, and node A as the destination node. Take a look at the following image:

jBPM Developer Guide

Like in the object-oriented programming paradigm, we need to have a language with specific set of words (for example, object) here. We will need words to represent our graphs, as we can represent objects in the object-oriented paradigm. Here we will try to expand the official documentation proposed by the jBPM team and guide the learning process of this important topic. We will see code in this section and I will ask you to try it at home, debug it, and play with this code until you feel confident about what is the internal behavior of this example.

Let's get started first with the graph definition and with some of the rules that the graph needs to implement, in order to represent our business processes correctly.

Up until now, we have had two concepts that will appear in our graph oriented programming language—Node and Transition. These two concepts need to be implemented in two separate classes, but with a close relationship. Let's see a class diagram about these two classes and make a short analysis about the attributes and methods proposed in this example.

jBPM Developer Guide

Modeling nodes in the object-oriented world

This concept will be in charge of containing all of the information that we want to know about the activities in our process. The idea here is to discover the vital information that we will need to represent a basic activity with a Plain Old Java Object (POJO).

jBPM Developer Guide

As you can see in the class diagram, this class will contain the following attributes that store information about each activity of our process:

  • id(long ): For a unique identification of the node
  • name (String ): To describe the node activity
  • leaving Transitions (List<Transition>): This represents all the transitions that leave the node

This concept will need to implement some basic methods about executional behavior, but it will be discussed when we jump to the executional stage. For now, we are only going to see how we can represent a static graph.

Modeling a transition in the object-oriented world

This concept is very simple, we want to know how the nodes will be linked to each other. This information will define the direction of our graph. For that, we need to know the following information:

  • name (String): That must be unique for the same source node
  • source (Node): This is the source node from where the transition begins
  • destination (Node): This is the destination node where the transition arrives

With these two classes, we will be able to represent our processes. But wait a minute; if our processes only have nodes, we are hiding what is happening inside them, we only see nodes and not what is happening in the process. So, we need more expressiveness, to describe our processes in a more shocking way. Those who see the process, can understand the process "direction" and the nature of each activity inside it. Of course, the behavior of each activity will also be clarified with a more specific language that provides us with other words, and not just nodes and transitions to describe activities and the flow.

Expanding our language

The only thing that we need to do in order to have more expressive power in our graphs is to increase the number of words in our language. Now we only have Node and Transition, these two words are not enough to create clear graphs that can be understood by our stakeholders. To solve that, we can have some kind of hierarchy from the most abstract concepts that represent a generic activity to more concrete concepts related to specific activities such as Human Tasks, Automatic Activities, Decision Activities, and so on.

In order to do this, you only need to extend the Node concept and add the information that you want to store for a specific activity behavior. Basically, what I am saying here is that the Node concept has the basic and generic information that every activity will have, and all subclasses will add the specific information related to that specific activity behavior in our specific domain.



As you can imagine, if we have different sets of nodes to represent different domains, we can say that our Graph Oriented Programming solution supports multiple languages.

Another important thing here, is to notice that the Node concept needs to be easily graphicable, just to have graphical views of our processes. In an Object Oriented Paradigm, we achieve that by implementing the graphicable interface, because we want all the subclasses of Node to be graphicable as well (this is not shown in the diagrams, but you can see it in the code). This interface provides the signature and makes us implement the methods to graph each node easily, giving us the flexibility to graph our process in different formats. It is also important to note that each subclass can override the graphic functionality in order to represent, graphically, the difference of each behavior.

The only thing that we need now is some container that represents the graph as a whole. As we have a collection of nodes and transitions now, we need a place to have all of them together.

Process Definition: a node container

This will be a very simple concept too, we can also use the word 'graph' to represent this container, but here we will choose 'definition', because it is more related to the business process world. We can say that this class will represent the formal definition or our real situation. This will only contain a list of nodes that represent our process. One interesting thing to see here is that this concept/class will implement an interface called NodeContainer, which provides us methods with which to handle a collection of nodes. For this interface, we need to implement the functionality of the methods addNode(Node n), getNode(long id), getNodes(), and so on.

jBPM Developer Guide

In the next section, we will see how these concepts and class diagrams are translated into Java classes.

Implementing our process definition

During the following section, we will implement our own simple solution to represent our business processes. The main goal of this section is to be able to understand from the source how the jBPM framework is built internally. Understanding this simple implementation will help you to understand how the framework represents, internally, our processes definitions. That knowledge will allow you to choose the best and more accurate way to represent your business activities in a technical way.

We are ready to see how this is translated to Java classes. Please feel free to implement your own solution to represent process definitions. If you don't feel confident about the requirements or if you are shy to implement your own solution, in this section we are going to see all the extra details needed to represent our definitions correctly. I also provide the Java classes to download, play, and test.

As in the previous section, we start with the Node class definition. In this class, we are going to see details of how to implement the proposed concept in the Java language.

Here we are just implementing our own solution in order to be able to represent simple business processes. This is just for the learning process. This implementation of GOP is similar and simpler than the real jBPM implementation.

The Node concept in Java

This Node  class appears as follows:

public class Node implements Graphicable{
private Long id;
private String name;
private Map<String, Transition> leavingTransitions =
new HashMap<String, Transition>();

public Node(String name) {
this.name = name;
public void addTransition(String label, Node destination) {
leavingTransitions.put(label, new Transition(label, this,destination));

public void graph() {
String padding="";
String token="-";
for(int i=0; i < this.getName().length(); i++){
System.out.println("| "+this.getName()+" |");
Iterator<Transition> transitionIt =
while(transitionIt.hasNext()){ transitionIt.next().graph();
... (Setters and Getters of each property)

As you can see, there is nothing to worry about. It is a simple class that contains properties—here, you need to notice:

  • Implementing the Graphicable interface forces us to define the graph() method.
  • The graph()  method's implementation, in this case, will print some ASCII characters on the console.
  • The use of a Map to store each transition with a name associated to it. The idea here is to use the transitions based on names and not objects. In other words, we can choose which transition to take using just a String.
  • The addTransition(String, Node) method that wrap the put method of the Map and creates a new instance of the Transition class.

The Transition concept in Java

We can find the definition of the Transition class in the package of the Node class:

public class Transition implements Graphicable{
private Node source;
private Node destination;
private String label;
public Transition(String label,Node source, Node destination) {
this.source = source;
this.destination = destination;
this.label = label;
... (Getters and Setters for all the properties)

Another very simple class. As you can see, here we have two Node class properties that allow us to define the direction of the transition. Also, we have the label property that allows us to identify the transition by name. This property (the label property) is a kind of ID and must be unique inside all the leaving transitions of a particular node, but it could be repeated in any other node.

The Definition concept in Java

We can find the Definition class in the package containing the Node class. The idea of this class is to store all the nodes that compose a process definition.

public class Definition implements Graphicable, NodeContainer {
private String name;
private List<Node> nodes;
public Definition(String name) {
this.name = name;
public void graph(){
for (Node node : getNodes()){
public void addNode(Node node) {
if(getNodes() == null){
setNodes(new ArrayList<Node>());
public Node getNode(Long id) {
for(Node node : getNodes()){
if(node.getId() == id){
return node;
return null;
...(Getters and Setters for all the properties)

The main things to notice here:

  • The name property will store the name of our process definition. This will be important when we want to store these definitions in a persistent way.
  • This class implements the Graphicable and NodeContainer interfaces. This forces us to define the graph() method from the Graphicable interface, and the addNode(Node) and getNode(Long) methods from the NodeContainer interface.
  • The graph()  method, as you can see, only iterates all the nodes inside the list and graphs them, showing us the complete process graph in the console.
  • The addNode(Node) method just inserts nodes inside the list and the getNode(Long) method iterates the nodes inside the list, until it finds a node with the specified id.

Testing our brand new classes

At this point, we can create a new instance of the Definition class and start adding nodes with the right transitions. Now we are going to be able to have some graphical representation about our process.

If you don't know how to use maven, there is a quick start guide at the end of this article. You will need to read it in order to compile and run these tests.

In the test sources, you will find a test class called TestDefinition, it contains two tests—one for the simple approach and the other with the more expressive approach. Each of these test methods inside the TestDefinition class uses the JUnit framework to run the defined tests. You can debug these tests or just run them and see the output on the console (and yes, I'm an ASCII fan!). Feel free to modify and play with this implementation. Always remember that here we are just defining our processes, not running them.

If you see the test code, it will only show how to create a definition instance and then graph it.

public void testSimpleDefinition(){
Definition definition = new Definition("myFirstProcess");
System.out.println(" PROCESS: "+definition.getName()+" ");
Node firstNode = new Node("First Node");
Node secondNode = new Node("Second Node");
Node thirdNode = new Node("Third Node");
firstNode.addTransition("to second node", secondNode);
secondNode.addTransition("to third node", thirdNode);



>> Continue Reading jBPM for Developers: Part 2


You've been reading an excerpt of:

jBPM Developer Guide

Explore Title