How-to: An Embedded jBPM hello, world example

Ok, I admit it. BPM is not the hottest of hot trends right at the moment. But it still has a place. For example, BPM is rock solid at collaboratively modeling business processes with diagrams and orchestrating enterprise services — especially microservices. In fact, BPM might let you keep your microservices finely grained, as they should be, and avoid too many composite microservices.

But what if you don’t want to implement an entire BPM server and suite? Instead, you want to flip it around (as I argued for in mode 3 of my draft whitepaper on the same subject). You want to expose a service that embeds the workflow execution engine. If this is what you’re thinking about doing, then I think this is the hello, world example you’ve been Googling for.

Model your hello, world “business process”

I did this TDD, but let’s start our discussion with a super simple business process model. The workflow it describes accepts some initial parameters and then calculates a new string saying “Hello ____.” That is, the example sets a process variable as input — in BPM-speak — and then reads a different process variable to use as output.


Above you see my BPMN 2.0 diagram really is simple: it’s comprised of a start event, an end event, and a script task reading the input process variable string (“name”) and setting a new process variable (“welcomeText”) to be consumed later.

First, I defined an input process variable as a data element in the properties window of the overall BPM2 process.


One thing I should mention is that the tooling didn’t let me actually specify the string datatype for the incoming type. I had to manually edit the XML file (which is on my Github repo below), but I think it’s just that I’m a little new to the tooling — not that it’s impossible.

Next, I defined the following script task, which reads the process variable named “name.”



I saved the file as say_hello.bpmn in my Maven project’s resources directory.

Now embed the jBPM execution engine

Remember, I don’t want to deploy the BPMN file into a standalone server. I want to flip it around and embed the server. We can do that with just a few lines of Java code. Before we get too far into this, the JBoss documentation says that my approach is “not recommended for real application development but more for try outs.” Instead, they recommend using the RuntimeEngine to give you finer-grained control over your execution. For now, I’ll leave it to you to explore the distinction.

Under this scenario, we just need to create an object that has access to the BPM execution engine and then create a session from that engine. Specifically, the first step is to set up our KieBase, which has the execution engine inside it, and feed it the BPM workflow (documented above). Then we get a reference to a KieSession. KieBase is a relatively heavyweight operation but creating new sessions is pretty lightweight.

Next we’re going to set our process variables on the session and start the workflow (while holding a reference to the ProcessInstance).

Notice the typecast in there? It’s from the kie-based ProcessInstance to the jBPM process instance from the org.jbpm package, which is useful in later steps.

Finally, we extract the “output” of the BPM process by getting access to the workflow’s process variables after the workflow completes as follows:

I don’t like all the typecasts, but this is my first cut. It works, and it’s pretty fast. Comments? All the code is on Github here.

warningAn important caution about this approach: One initial comment you may have is that running a process in this way will cause a lot of problems if you’re trying to run a long-running process or take advantage of the full suite of options in BPMN. I know, I know. But I’m imagining a microservices-like use case that’s pretty limited. By this I mean you’re going to run mostly quick, short orchestrations (likely of other microservices) and you don’t need to incorporate human interaction in the process nor do you need to even store the state of the process as it runs. In short, you’re getting a very limited suite of BPM services, but that’s ok for this use case.

Leave a Reply

Your email address will not be published. Required fields are marked *