Keep informed?
Subscribe for our newsletter now!

Using BPMN 2.0 Models with jBPM 3 – A migration path and more

If you are using JBoss jBPM 3 in your current process automation projects you may face the problem, that some stakeholder (business, analysts, customers, marketing, …) ask for BPMN process models. And they often do for a good reason. But how do you get to that world? Do you have to throw away the jBPM 3 engine and start using a BPMN 2.0 Engine like Activiti? If yes, how could a migration path could look like?

But there are good news: Your are not the only one having this problem 🙂 Hence we already worked out strategies with some of our customers. One is to keep the jBPM 3 engine (at least for some time), but use BPMN 2.0 models anyway. Therefore we wrote a complete transformation and graphical tooling around it. And just in time for Christmas we open source it 🙂 And together with some other ideas this leads you towards a step by step migration strategy, so read on…

jBPM Process Definition Language

Just to bring everybody on the same page: The problem is, that JBoss jBPM 3 – a proven and pretty stable Open Source process engine we do projects with for around 7 years now – uses a proprietary XML language called jPDL. That wasn’t a problem when jBPM started, because at this time no fitting standard was available (only XPDL which was very weak and BPEL which just emerged and didn’t fit for reasons I want to skip here). But nowadays BPMN 2.0 is the accepted standard, so there is a demand for BPMN process models, at least if you want to gain transparency by modeling your processes. This is not only about nice pictures, it is about being able to use BPMN the right way, e.g. like we describe in our BPMN framework. And additionally, jBPM 3 is in maintenance mode, meaning it is not actively developed any further, so sooner or later you will be asked about a possible migration path.

How to get from jPDL (jBPM3) to BPMN 2.0?

The first thing everybody asks: Can I somehow import my jPDL processes into BPMN? Good question! Currently a XSLT-Transformation (jPDL -> BPMN 2.0) is developed by JBoss itself, but I am not yet sure, how powerful that will get. In our projects we choose another solution, which we are happier with than XSLT (and the XSLT wasn’t available at this time anyway). We implemented an own transformator in Java, using the jBPM 3 object model and creating a JSON file for the Signavio or Activiti Modeler, which then can export the BPMN 2.0 XML (sounds more complicated than it is, since we nicely integrated that in tooling, see below). The Java-Transformator supports basic transformations out of the box but allows for easy extensions in your project. So the goal was to be able to influence the resulting BPMN in every project easily, since for a couple of constructs there is not the one and only right way for transformation.

The transformator doesn’t preserve any layout information, in most cases the jPDL layouts wouldn’t be helpful anyway. In some cases we leveraged the Signavio Auto-Layout mechanism instead. But in all of our cases we did some manual adjustments afterwards, at least for the layout.

Throw away jBPM 3?

So we found a way to migrate process definitions to BPMN 2.0. Fine 🙂 But that is only part of the story. In a lot of jBPM projects business logic (or service calls) is attached to the process definition as so called ActionHandler’s or DecisionHandler’s (both Java Interfaces). How can we migrate them? Or how to embed a new engine in your environment, where you might have invested time to get going with jBPM 3? These are the hard tasks, and it is advisable to do them step by step.

So for our customers we didn’t migrate the engine immediately, but kept jBPM 3 for a while.

Use BPMN 2.0 to jPDL transformation

If we keep jBPM 3 the interesting question is how to get from the BPMN process model to the jPDL XML, which then is deployed on the jBPM 3 Engine. Surprise, surprise, we introduced a second transformation, from BPMN to jPDL. And this direction is much more important, meaning we invested much more time in it than the reverse direction. We successfully used it at customers in various processes. Hence, it is already pretty proven, even if not totally complete. But again, our focus was to make it easy extensible. It can be done by writing a small Java class being added to the mapping. This is done by customers themselves.

Extending this mapping with own magic

Defining a measuring point in Signavio Modeler in BPMN

Defining a measuring point in Signavio Modeler in BPMN

I want to give you a quick example to make it more concrete. In a customer project we defined measuring points in the process, at these points an event will be sent to the so called Process Control Center (typical scenario). For sending these event there is a pre-defined jBPM3 ActionHandler doing it. The measuring point is modeled as intermediate event and a boolean property “measuringpoint” is set to true in Signavio (as shown in the screen-shot). This can be used during the Tranformation process and the ActionHandler with the correct configuration is added to the resulting jBPM process. You can see as well, that in that step we validate constructs of the BPMN model. If the name of the measuring point doesn’t match the conventions, an validation error is thrown. The following source code shows the implementation of this extension, as you can see it is a very easy Java code that can be hooked into the transformation:

public class MeasuringPointPattern extends OryxPattern {
  public Node modifyJpdl3(Node node, Shape shape) {
    if (BPMN20.NONE_INTERMEDIATE_EVENT.equals(shape.getStencilId()) &&
"true".equals(shape.getProperty("measuringpoint"))) {
      String name = shape.getProperty("name");
      if (name == null || !name.startsWith(MP_PREFIX)) {
        roundtrip.addMappingValidationError(shape, "The name of the None Intermediate Event '" + shape.getProperty("name") + "' does not start with '" + MP_PREFIX + "'."));
      String mpName = name.substring(PREFIX.length());
      Event event = node.addEvent(new Event(Event.EVENTTYPE_NODE_ENTER));
      Delegation delegation = new Delegation(ACTION_HANDLER_CLASS_NAME);
      delegation.setConfiguration("" + mpName + "");
      Action action = new Action(delegation);
    return node;

As a result, customers, departments or even projects may influence the mapping. There is no need to change anything in the “core” transformer.

Graphical tooling for using the transformation

The transformation from BPMN 2.0 to jBPM can be used in different ways. The easiest is to call the transformation via command line or in own Java code:

TransformationPerformer transform = new TransformationPerformer();
// add the patterns you need
transform.addJsonPattern(new Bpmn20JsonPattern());
transform.addJsonPattern(new MeasuringPointPattern());

// Fire it. In the background the Activiti Cycle Signavio Connector is used to read the process from the Signavio or Activiti Modeler
  signavioUrl, signavioUser, signavioPassword, sourceModelId, outputfileJson, outputfileXml, outputfileLog); 

The Cycle Plug-In can show Validation Errors graphically

The Cycle Plug-In can show Validation Errors graphically

But often you want to have more sophisticated tooling. What we did is to include the Mapping as Plug-in in Activiti Cycle. Since Cycle can browse the Signavio Process Repository as well as the Signavio Explorer, the Cycle GUI can be used as entry point for modeling. This allows to add the jBPM transformation as a view and a couple of actions on the fly. Especially interesting is, that by doing so you don’t need an additional Web-GUI, since you just use the tooling you would use anyway.

Additionally it adds a graphical view on transformation warnings and errors, as you can see in the screen-shot on the right. We created an extended Maven project wizard as well, to create technical projects that automatically contain the jBPM process definition (I described the Maven Wizard briefly in my previous blog post about Cycle already).

Forward Engineering

Adding jBPM Action Handler to BPMN process model in Signavio Modeler

Adding jBPM Action Handler to BPMN process model in Signavio Modeler

The customers using that transformation and tooling currently go for a pure forward engineering approach. Meaning: All information which results in the jBPM process must exist in the BPMN model already, like shown for ActionHandlers in the screen-shot on the right. We added the possibility to easily overwrite a jBPM process model if the BPMN has changed. In Cycle we remember the link between the BPMN model (e.g. in the Signavio Repository) and the jBPM XML (e.g. in the SVN). So it is easy to overwrite the model by one click. And we currently work on notification if models have changed as well. We even generate Java class stubs for ActionHandlers or ServiceAdpaters (see below), if they don’t exist in the project yet.

We currently roll out that tooling into production at one customer, so it is already more than a nice toy. The customer expects to gain speed in the development process and especially lower the learning curve for using BPMN for executable processes and the transformation to jBPM.

Next step: Removing jBPM 3

The next migration step would be to really remove jBPM 3 and introduce a BPMN 2.0 Engine. Therefore the business logic (or service calls) attached to the process definition as ActionHandler’s or DecisionHandler’s must be migrated as well. That is actually the harder part and IMHO cannot be done in the same way in all cases. And it always depends on the target engine. Let’s at least assume you migrate at least to a Java Engine like Activiti, where we have extensions available to call Java code directly. If you have an engine only capable of communication with WebServices it gets really complicated.

With the Java capabilities you could maybe think of some kind of Adapter class, calling your existing and untouched “legacy” jBPM 3 ActionHandlers. Maybe possible, but in our projects we choose another option:

Writing Process Engine independent Service Adapters

We transformed all existing jBPM 3 ActionHandlers into some easy Java POJOs, we call “Adapter”. We currently have three basic types:

  • ServiceAdapter: Calling Services via EJB, JMS,…
  • GatewayAdapter: Making decisions
  • JavaAdapter: Arbitrary Java code

These Adapters have some Injection mechanism for process variables and are then completely independent of the Process Engine. They can even be tested easier (no jBPM ExecutionContext must be mocked). Actually we are currently improving the Adapter concept a lot and add additional features in the infrastructure around them (like asynchronous communication, correlation of responses, supporting different technologies like EJB or WS without the need of changing the Adapter code, calling a Registry, …). Together with a customer we plan to create an own open source project for that soon, so I will for sure blog about this in more detail. If you are interested, drop me an email, it would be interesting to hear your requirements.

But back to our topic. These Adapters now could be used in as well jBPM3 and e.g. Activiti, the only thing you need is a generic Binding class calling the Adapter in the concrete Engine specific way. But this has to be done once for all processes and in the case of our Adapter framework are even provided by us for jBPM 3 and Activiti 🙂 And it is a pretty thin layer, which is easy to write.

OK, it is effort to migrate all ActionHandlers to Adapters, but it was really worth it, since the resulting code is engine independent once and for all. And since we took the opportunity to clean up and refactor a lot of code in that step, even the quality improved. And the Adapter concept forced us to define the code in a pretty clean and readable way, where no jBPM 3 hacks were allowed any more 😉

Adding ServiceAdapters to BPMN process model

Service Adapter in the BPMN lead to special code generated for jBPM

Service Adapter in the BPMN lead to special code generated for jBPM

As described above, we now add the ServiceAdapters to our BPMN process models, exchanging the jBPM ActionHandlers. In a first phase, we could even mix both possibilities, as long as we still run on jBPM3. As soon as we switch the Engine we exchanged the transformation to add the ServiceAdapters correctly e.g. to Activiti process definitions. This can be done once in the transformation, the BPMN process models as well as the Service Adapters keep untouched. You “just” have to exchange the Engine in your environment (which maybe is not that hard, if you used our Process Engine Abstraction Layer ;-)).

Migration Strategy

So in short we currently made good experiences with a migration strategy like this:

  • Migrate process models from jPDL to BPMN
  • Keep jBPM 3 and introduce forward engineering from BPMN models to jPDL
  • Test that everything still works
  • Migrate ActionHandlers to Engine Independent code (e.g. ServiceAdapters)
  • Test that everything still works
  • Migrate Engine by having a “phase out”-phase, where you run jBPM 3 and the new engine in parallel. Actually there are a lot of discussions going on, if that should be avoided by migrating running process instances to the new engine and make a hard cut. I think, phasing out is much easier and less error prone (and is actually not that hard to do), but maybe somebody proves me wrong in future 🙂

To be honest, none of our customers has already completely migrated. But hey, jBPM 3 is really stable, there is no time pressure for it, as soon as you can present BPMN process models to anybody asking for it 🙂

And where can I find this transformation and Cycle Plug-in?

We are currently releasing the transformation described and the Activiti Cycle Plug-in freely as Open Source on the camunda fox Cycle Plug-ins Page. The downloads will be available together with the release of Activiti Cycle 5.1 (1st of January 2011).

Already read?

Scientific performance benchmark of open source BPMN engines

Why BPMN is not enough

Decision Model and Notation (DMN) – the new Business Rules Standard. An introduction by example.

New Whitepaper: The Zero-Code BPM Myth

10 Responses

Leave a reply