Getting Your Hands Dirty with jPDL: Part 1

jBPM Developer Guide

December 2009


A Java developer's guide to the jBOSS Business Process Management software

This example will introduce us to all the basic jPDL nodes used in common situations for modeling real world scenarios. That's why this article will cover the following topics:

  • Introduction to the recruiting example
  • Analyzing the example requirements
  • Modeling a formal description
  • Adding technical details to our formal description
  • Running our processes

The idea of this article is to show you a real process implementation. We will try to cover every technical aspect involved in development in order to clarify not only your doubts about modeling, but also about the framework behavior.

How is this example structured?

In this article, we will see a real case where a company has some requirements to improve an already existing, but not automated process.

The current process is being handled without a software solution, practically we need to see how the process works everyday to find out the requirements for our implementation. The textual/oral description of the process will be our first input, and we will use it to discover and formalize our business process definition.

Once we have a clear view about the situation that we are modeling, we will draw the process using GPD, and analyze the most important points of the modeling phase. Once we have a valid jPDL process artifact, we will need to analyze what steps are required for the process to be able to run in an execution environment. So, we will add all the technical details in order to allow our process to run.

At last, we will see how the process behaves at runtime, how we can improve the described process, how we can adapt the current process to future changes, and so on.

Key points that you need to remember

In these kind of examples, you need to be focused on the translation that occurs from the business domain to the technical domain. You need to carefully analyze how the business requirements are transformed to a formal model description that can be optimized.

Another key point here, is how this formal description of our business scenario needs to be configured (by adding technical details) in order to run and guide the organization throughout its processes.

I also want you to focus on the semantics of each node used to model our process. If you don't know the exact meaning of the provided nodes, you will probably end up describing your scenario with the wrong words.

You also need to be able to distinguish between a business analyst model, which doesn't know about the jPDL language semantics and a formal jPDL process definition. At the same time, you have to be able to do the translations needed between these two worlds. If you have business analysts trained in jPDL, you will not have to do these kind of translations and your life will be easier. Understanding the nodes' semantics will help you to teach the business analysts the correct meaning of jPDL processes.

Analyzing business requirements

Here we will describe the requirements that need to be covered by the recruiting team inside an IT company. These requirements will be the first input to be analyzed in order to discover the business process behind them.

These requirements are expressed in a natural language, just plain English. We will get these requirements by talking to our clients—in this case, we will talk to the manager of an IT company called MyIT Inc. in order to find out what is going on in the recruiting process of the company.

In most cases, this will be a business analyst's job, but you need to be aware of the different situations that the business scenario can present as a developer. This is very important, because if you don't understand how the real situation is sub-divided into different behavioral patterns, you will not be able to find the best way to model it.

You will also start to see how iterative this approach is. This means that you will first view a big picture about what is going on in the company, and then in order to formalize this business knowledge, you will start adding details to represent the real situation in an accurate way.

Business requirements

In this section, we will see a transcription about our talk with the MyIT Inc. manager. However, we first need to know the company's background and, specifically, how it is currently working. Just a few details to understand the context of our talk with the company manager would be sufficient.

The recruiting department of the MyIT Inc. is currently managed without any information system. They just use some simple forms that the candidates will have to fill in at different stages during the interviews. They don't have the recruiting process formalized in any way, just an abstract description in their heads about how and what tasks they need to complete in order to hire a new employee when needed.

In this case, the MyIT Inc. manager tells us the following functional requirements about the recruiting process that is currently used in the company:

We have a lot of demanding projects, that's why we need to hire new employees on a regular basis. We already have a common way to handle these requests detected by project leaders who need to incorporate new members into their teams.

When a project leader notices that he needs a new team member, he/she will generate a request to the human resources department of the company. In this request, he/she will specify the main characteristics needed by the new team member and the job position description.

When someone in the human resources team sees the request, they will start looking for candidates to fulfill the request. This team has two ways of looking for new candidates:

  • By publishing the job position request in IT magazines
  • By searching the resume database that is available to the company

When a possible candidate is found through these methods, a set of interviews will begin. The interviews are divided into four stages that the candidate needs to go through in order to be hired.

These stages will contain the following activities that need to be performed in the prescribed order:

  • Initial interview: The human resources team coordinates an initial interview with each possible candidate found. In this interview, a basic questionnaire about the candidate's previous jobs and some personal data is collected.
  • Technical interview: During the technical interview stage, each candidate is evaluated only with the technical aspects required for this particular project. That is why a project member will conduct this interview.
  • Medical checkups: Some physical and psychological examinations need to be done in order to know that the candidate is healthy and capable to do the required job. This stage will include multiple checkups which the company needs to determine if the candidate is apt for the required task.
  • Final acceptance: In this last phase the candidate will meet the project manager. The project manager is in charge of the final resolution. He will decide if the candidate is the correct one for that job position. If the outcome of this interview is successful, the candidate is hired and all the information needed for that candidate to start working is created.

If a candidate reaches the last phase and is successfully accepted, we need to inform the recruiting team that all the other candidate's interviews need to be aborted, because the job position is already fulfilled.

At this point, we need to analyze and evaluate the manager's requirements and find a graphical way to express these stages in order to hire a new employee. Our first approach needs to be simple and we need to validate it with the MyIT Inc. manager. Let's see the first draft of our process:

jBPM Developer Guide

With this image, we were able to describe the recruiting process. This is our first approach that obviously can be validated with the MyIT Inc. manager. This is our first draft that tells us how our process will appear and it's the first step in order to define which activities will be included in our model and which will not. In real implementations, these graphs can be made with Microsoft Visio, DIA (Open Source project), or just by hand. The main idea of the first approach is to first have a description that can be validated and understood by every MyIT Inc. employee.

This image is only a translation of the requirements that we hear from the manager using common sense and trying to represent how the situation looks in real life. In this case, we can say that the manager of the MyIT Inc. can be considered as the stakeholder and the Subject Matter Expert (SME), who know how things happen inside the company.

Once the graph is validated and understood by the stakeholder, we can use our formal language jPDL to create a formal model about this discovered process.

The idea at this point, is to create a jPDL process definition and discard the old graph. From now on we will continue with the jPDL graphic representation of the process. Here you can explain to the manager that all the new changes that affect your process will go directly to the jPDL defined process.

Until now our artifact has suffered the following transformations:

jBPM Developer Guide

The final artifact (the jPDL process definition) will let us begin the implementation of all the technical details needed by the process in order to run in an execution environment.

So, let's analyze how the jPDL representation will look for this first approach in the following figure:

jBPM Developer Guide

At this point we don't add any technical details, we just draw the process. One key point to bear in mind in this phase is that we need to understand which node we will use to represent each activity in our process definition.

Remember that each node provided by jPDL has its own semantics and meanings. You also need to remember that this graph needs to be understood by the manager, so you will use it in the activity name business language. For this first approach we use state nodes to represent that each activity will happen outside the process execution. In other words, we need to inform the process when each activity ends. This will mean that the next activity in the chain will be executed. From the process perspective, it only needs to wait until the human beings in the company do their tasks.

Analyzing the proposed formal definition

Now that we have our first iteration that defines some of the important aspects described by the MyIT Inc. manager, some questions start to arise with relation to our first sketch, if it is complete enough, or not. We need to be sure that we represent the whole situation and it defines the activities that the candidates and all the people involved in the process need, to fulfill the job position with a new employee. We will use the following set of questions and their answers as new requirements to start the second iteration of improvement.

The idea is that each iteration makes our process one step closer to reflecting the real situation in the company. For reaching that goal, we also need to be focused on the people who complete each activity inside our process. They will know whether the process is complete or not. They know all the alternative activities that could happen during the process execution.

If we see the proposed jPDL definition we can ask the following questions to add more details to our definition.

  • How about the first part of the description? Where is it represented? The proposed jPDL process just represents the activities of the interviews, but it doesn't represent the request and the creation of the new job position.
  • What happens if the candidate goes to the first interview and he/she doesn't fulfill the requirements for that job position?
  • How many medical checkups are done for each candidate?
  • What happens if we fulfill the job position? What happens with the rest of the candidates?

These questions will be answered by the MyIT Inc. manager and the people who are involved in the process activities (business users). The information provided by the following answers will represent our second input, which will be transformed into functional requirements. These requirements need to be reflected in our formal description once again. Let's take a look at the answers:


Yes, we will need to add that part too. It's very important for us to have all the processes represented from the beginning to the end. Also, you need to understand that the interviews are undertaken for each candidate found, and the request to fulfill a new job position is created just once. So the relationship between the interviews and the new employee request is 1 to N, because for one request, we can interview N candidates until the job position is fulfilled.


The candidate that doesn't pass an interview is automatically discarded. There is no need to continue with the following activities if one of the interviews is not completed successfully.

How many medical checkups are done for each candidate?

All the candidates need to pass three examinations. The first one will check the physical status of the candidate, the second will check the psychological aspects, and the third one will be a detailed heart examination.

What happens if a candidate fulfills the job position? What happens with the rest of the candidates?

If one of the candidates is accepted, all the remaining interviews for all the other candidates need to be aborted.

Refactoring our previously defined process

Now with the answers to our questions, we can add some extra nodes to represent the new information provided. Take a look at the following image of the process, you will find new nodes added, and in this section, we will discuss the reason for each of them.

The new proposed process is much more complex than the first, but the main idea is still intact. You need to be able to understand the process flow without problems. It's more complex just because it represents the real situation more closely.

jBPM Developer Guide

In this section, we will review all the nodes added at each stage of the process. With this, you will have a clear example to see how a real situation is translated to a specific node type in our process definition and how we will iteratively add information when we find more and more details about the situation.

jBPM Developer Guide

If you take a look at the CandidateInterviews process (/RecruitingProcess/src/main/resources/jpdl/CandidateInterviews/processdefinition.xml), you will see that the first node (Start State node) doesn't have the default name Start/start-state1. Here, I have chosen a more business-friendly name, Interview Possible Candidate. This name looks too long, but it says precisely what we are going to do with the process. Here a possible candidate was found and the process will interview him/her in order to decide if this candidate is the correct one for the job.

Using the business terminology will help us to have a more descriptive process graph that can be easily validated by the stakeholders.

The second node called Initial Interview will represent the first interview for each selected candidate. This means that someone in the recruiting team will schedule a face-to-face meeting with the candidate to have the first interview. If you take a close look at the process definition graph or the jPDL process definition XML, you will find that for this activity, I have chosen to use a State node. I chose this type of node, because the activity of having an interview with the candidate is an external activity that needs to be done by a person and not by the process. The process execution must wait until this activity is completed by the candidate and by the recruiting team. For now, we will use state nodes to represent all the human activities in our processes.

Once the Initial Interview is completed, an automatic decision node will evaluate the outcome of the interview to decide if the candidate must be discarded, or if he/she should continue to the next stage of the process.

This will look like:

jBPM Developer Guide

Just for you to know, this is not the only way to model these kinds of situations, feel free to try other combinations of nodes to represent the same behavior.

The decision node is used to decide for which transition the process will continue its execution. This decision node can define N (in this case, only two) leaving transitions, but at runtime, just one will be chosen to continue.

Remember that the Decision node takes a transition based on the following two evaluation methods:

  • Using an EL expression
  • Using a delegated class, implementing the method interface DecisionHandler

No matter which method we choose, the information that is used to make a decision needs to be set before the node was reached by the process execution. In this situation, the information used in the evaluation method of the decision node will be set in the state node called Initial Interview as the interview outcome.

Another way you can use to model this situation is by defining multiple leaving transitions from the state node.

jBPM Developer Guide

This approach writes the following logic inside an action of the state node:

  1. The logic used to determine which transition to take is based on the interview outcome.
  2. Explicitly signals one of the N leaving transitions defined based on the logic outcome.
This approach tends to be more difficult to maintain than a detached decision node that handles all that logic. Basically, it is up to you to decide how to model these kinds of situations.

The pattern of using a state node and then a decision node, to decide if the previous activity is completed, with the desired outcome, is applied throughout all the process stages in order to decide if the candidate can continue or not, based on each activity's outcome.

The next stage described in the process definition looks exactly the same as the first one. The Technical Interview looks exactly the same as the Initial Interview stage. It also includes a decision node to evaluate the outcome of this specific interview.

If the candidate passes/approves the first two interviews, some medical examinations need to be taken in the third stage.

As these check ups have to be done in different buildings across the city, taking advantage of the fact that all of them are independent from each other, a fork node is used to represent this temporal independence. Take a look at the following image:

jBPM Developer Guide

Here we need to understand that the Fork and Join nodes are used to define behavior, not to represent a specific activity by itself. In this situation, the candidate has the possibility to choose which exam to take first. The only restriction that the candidate has is that he/she needs to complete all the activities to continue to the next stage. It is the responsibility of the Join node to wait for all the activities between the Fork and Join nodes to complete before it can continue with the execution.

This section of the modeled process will behave and represent the following situations:

  • When the process execution arrives at the fork node. (Note that the fork node doesn't represent any one-to-one relationship with any real-life activity. It is just used to represent the concurrent execution of the activities.)
  • It will trigger three activities, in this case, represented by state nodes. This is because the checkups will be done by an external actor in the process. In other words, each of these activities will represent a wait state situation that will end when each doctor finishes each candidate's checkup and notifies the outcome of the process.
  • In this case, when the three activities end, the process goes through the join node and propagates the execution to the Decision node to evaluate the outcome of the three medical checkups. If the candidate doesn't have three successful outcomes, he/she will automatically be discarded.

We use the fork node because the situation behaviors can be modeled as concurrent paths of execution. It's important for you to play a little bit with it to start knowing this node type. Try to understand what we are doing with it here.

>> Continue Reading Getting Your Hands Dirty with jPDL: Part 2


[ 1 | 2 ]


Books to Consider

comments powered by Disqus