Migration Tips - moving projects from JBoss BRMS 5 to JBoss BPM Suite 6

Getting ready for your migration?

Japanese translation (日本語訳)

This migration article will try to put into perspective the daunting task that any developer faces when asked to evaluate the move from one version of a product to another.

Introduction

We will try to put the aspects that need your attention, allowing you to evaluate your personal project for migration to the new Red Hat JBoss BPM Suite v6.

It should be understood that the JBoss BPM Suite 6 product represents a superset of the JBoss BRMS 6 product. Therefore, by covering the BPM example project we will automatically cover rule project assets as we go along.

For the rest of this article we will be using an existing JBoss BRMS 5 project that we migrated to JBoss BPM Suite 6, providing the links to the projects code base both before and after the migration:

• Before: JBoss BRMS 5 Customer Evaluation Demo
• After: JBoss BPM Suite 6 Customer Evaluation Demo

Please read the projects files for links to other articles describing requirements, products, and how to both install and run these demos in their respective IDE or product UI components. Also note the first demo project is more maturely documented at this time, the newer version will be expanding over time so check back regularly or feel free to submit any changes you feel could be of use.

Foundations

The backbone of the new JBoss BRMS & BPM Suite 6 products is based on using GIT as the repository for all your rule and process assets. Where as the older JBoss BRMS 5 product used a JCR repository based on Jackrabbit, we now seem to have the ability to migrate our projects into the new product with a single push of our project into a new repository.

Or is it not that simple?

Unfortunately it is not that easy. First you need to understand that the git backend is usable by all tools that support it. For example, the git CLI tooling you can use from your favorite shell work 100% with this repository. What is important to understand is that the current UI provided by the JBoss BRMS & BPM Suite products are not full git implementations. They currently interact in a very simplified way and when unable to interact will often just present an empty repository view.

To get the current product working correctly depends on adhering to the needed structure of your git repository. To ensure a project will be available in the products wonderful graphical interfaces, one should create an empty project within the UI with placeholder files for processes, rules, and whatever else you need. It is then a simple matter of running a git clone of this project into your favorite IDE to start migrating your project.

Once you have the project cloned, you can add your assets into the project in the correct locations based on the placeholder files. For example, I created an empty customer.bpmn2 file and added my customereval.bpmn2 file right next to it. I proceeded to then remove the old placeholder file and push this all into the repository. The UI of the product automatically picks up the changes and my process asset appeared for use in the designer.

Rules files import this same way without incident, other than that you will need to ensure your package name is aligned with your new project structure. The product has a UI that is tailored for a more business oriented user, therefore you can expect the old package naming of the customer evaluation demo, org.jbpm.customer.evaluation, to be more simplified. Ours turned out to be a simple package name of customer.evaluation so we adjusted this in our rules file and all was good.

The model for our project consists of two Java classes, or POJO's, a Request and a Person. These needed to be imported into the correct location for the form modeler component to identify, and they would not appear until the package name was corrected as discussed above.

There is a fundamental change in how you access your projects assets, so once you have the rules, processes, and your projects model in the product, this will be main available via a maven repository, built as a simple jar file. Below we will cover these details in the section Maven.

This means you can split your project into the code project that leverages your rules, events, and processes and the actual artifacts themselves. They will be contained in a project that deploys a jar that you leverage in your application code. Your unit tests will reside in your applications code project and leverage the generated jar dependencies.

The API's

The core API of the products has been fully refactored. You have to migrate everything you did to interact with the core of rules, events, and processes.

Eventually.

For now, you can use the provided backwards compatibility found in the knowledge-api.jar provided just for the projects that want to ride the old waves. Currently it can be found in the deployable-generic.zip, but that could change as the product approaches general availability (GA) status.

As for the other half of your enterprises code base, the unit tests that leveraged the jbpm-test.jar will need to be refactored. This jar does not provide for any backwards compatibility and we had to rewrite our existing unit tests. The good news is that the code is simplified, making your unit tests cleaner and easier to understand.

For both these jars, you can add them to your maven dependencies once these are made available. We have included and example internal repository where the maven dependencies are found, purely for your information in the migrated customer evaluation project.

The RestAPI has also changed. It will require some work to re-engineer your custom user interfaces that you might have created. The RestAPI provides you with access to the following areas:

• Jobs
• Repositories
• Organizational units
• Projects
• Process instances, with or without vars (start, variables, details, abort, signal)
• Work items (complete, abort)
• History to view process instance completed
• Comprehensive task interface

You can find documentation on this online at the Customer Portal.

JCR to GIT tooling

There is a community tool for migration of existing JCR repositories to the GIT repository format. At this time there was nothing to test but it is being exercised in the productization process.

Will this be the hammer that makes all your migrations look like a nail waiting to be hit?

Stay tuned for more on this as it has yet to be included in the early Beta releases.

Maven details

JBoss BRMS & BPM Suite products maintain a maven repository that you can add to your project for accessing the rules, events, and process project dependencies. Just add the following to your project pom file and you will be ready to locate dependencies:

   guvnor-m2-repo
   Guvnor M2 Repo
   http://localhost:8080/business-central/maven2/

As an example, assume that we have defined our customer evaluation project properly with a GAV (GroupID, ArtifactId, Version), we can then add the dependency for the version 1.0 jar as follows:

      customer
      evaluation
      1.0

Finally, the most important tip here is to never clone your repository from the filesystem, but always use the running product git URI. Referring to our running example of the customer evaluation demo, you would clone that outside of the product using CLI or your favorite IDE by accessing the project under:

# Never use the filesystem directly as it is not monitored by the product,
# so this is a bad practice: 
#
#    git clone file://{path-to-repo}/.niogit/customer.git
#
# This is the best practice, for example using git from a shell:
#
$ git clone git://localhost/customer

Cloning into 'customer'...
remote: Counting objects: 562, done
remote: Finding sources: 100% (562/562)
remote: Getting sizes: 100% (435/435)
remote: Compressing objects:  89% (388/432)
remote: Total 562 (delta 24), reused 72 (delta 21)
Receiving objects: 100% (562/562), 59.21 KiB, done.
Resolving deltas: 100% (198/198), done.

Task updates

The JBoss BRMS 5 product provided a task server that was bridged from the core engine by using, most commonly, the messaging system provided by HornetQ.

The new JBoss BPM Suite product will provide only support for the task server running locally, so no more messaging to be setup. To help you bridge the gap until you can migrate this in your current architecture, there is a helper or utility method, LocalHTWorkItemHandler. It can be found in the source code (separate download) if you want to investigate further at
jbpm-human-task/jbpm-human-task-workitems/src/main/java/org/jbpm/services/task/wih/util/LocalHTWorkItemHandlerUtil.java

Furthermore, the TaskService API is part of the public API, so there are just a few things to keep in mind when migrating:

• package changes will cause a bit of refactoring your imports
• some API changes will cause refactoring of methods

Customer evaluation demo

As most customers have created custom interfaces and interacted extensively with the human task component, expect to have some work here to migrate this area of your architecture if using tasks in your processes.

Migration in practice

Looking specifically at the project customer evaluation, we wanted to migrate a simple application that contains rules, a model, a unit test, and a process. This migration would provide factual evaluation as to the ease with which various aspects of the application could be migrated.

Here we would like to present the findings and point you to the project results (ongoing) of the migrated customer evaluation demo.

Unit Tests

We started with the unit tests and updated the pom.xml file to point to the internal production maven repository and included just the dependencies for the knowledge-api, plus the jbpm-test jar. This code snippet shows just the generic entries for the necessary jars, leaving out the exact version that is set as a property for the current release. You will also note that we leave out the repository entry that will be set to the maven repository you have the product dependencies stored in.

   org.jbpm
   jbpm-test
   ${bpm-suite-version}
   test

   org.drools
   knowledge-api
   ${bpm-suite-version}
   compile

Results of migration unit test.

Once these dependencies are in your project you can then begin the refactoring needed to change your current unit tests into the ones you will find working in the projects folder.

This includes an entry to eventually pull in the jar compilation of the product hosted artifacts, see the comments inline within the pom.xml file.

The initial setup used to involve a KnowledgeBase and a StatefulKnowledgeSession.

This has been reduced to just setting up a session strategy and RuntimeEngine.

# The createRuntimeManager() method and getRuntimeEngine() method are 
# both part of the provided testing harness found in JbpmJUnitBaseTestCase
# class that you can extend all unit tests off of.
#
createRuntimeManager(Strategy.SINGLETON, resources);
RuntimeEngine runtime = getRuntimeEngine(ProcessInstanceIdContext.get());

Where the older unit tests had to manipulate the sessions, we now have a streamlined case for each unit test.

@Test
public void underagedCustomerEvaluationTest() {
 // setup of a Person and Request.
 Person underagedEval = getUnderagedCustomer();
 Request richEval = getRichCustomer();

 // Map to be passed to the startProcess.
 Map params = new HashMap();
 params.put("person", underagedEval);
 params.put("request", richEval);

 // Fire it up!
 System.out.println("=========================================");
 System.out.println("= Starting Process Underaged Test Case. =");
 System.out.println("=========================================");

 KieSession ksession = runtime.getKieSession();
 ksession.insert(underagedEval);
 ProcessInstance pi = ksession.startProcess("org.jbpm.customer-evaluation", params);
 ksession.fireAllRules();

 // Finished.
 assertProcessInstanceCompleted(pi.getId(), ksession);
 assertNodeTriggered(pi.getId(), "Underaged");
 ksession.dispose();

 System.out.println("======================================");
 System.out.println("= Ended Process Underaged Test Case. =");
 System.out.println("======================================");
}

You will find the completely migrated unit test in the project src/test/java/CustomerEvaluationTest.java and can run this as a JUnit test.

From IDE to UI

The final step would be to import the existing rule, two Java classes that make up our domain model, and the BPMN2 process.

Designer with imported process.

To achieve this we started our JBoss BPM Suite and create a new repository and project. We then created empty placeholder files for the process and rule.


Back in our IDE we cloned the project with git clone git://localhost/customer and proceeded to locate the exact files we had inserted. We then removed these and added our existing rule and process files. After pushing them back into the project, they appeared in the UI project explorer. They only needed adjustments to the packaging as that had changed when we created our project, from a long package name to just customer.evaluation.

Importing the model was the same story, first creating an empty model via the form modeller
component and then replacing the file with our two java objects. Once the packages were adjusted to match the project definition, they appeared in the UI.

Form modeller with imported model.

The form modeller creates objects with annotations and our objects currently do not have them. This is causing some issues when we try to run the process (which builds and deploys). The JBoss BPM Suite attempts to generate a user task form to submit the initial process variables, but as they are objects and not the string fields we are provided, this fails.

Conclusions

These are the early days of JBoss BRMS & BPM Suite products, so an early look at the migration possibilities is just that, an early look. This is not the definitive guide to migrations, but a summary of the areas that will be affected and what you can expect based on a small sample application.

The issues around annotations on our model, dealing with importing a model, packaging paths all seem to be worth investigating further. This should be taken care of once the final documentation is provided for the product.

Note that the projects/customer-evaluation-demo is intended to be imported into your JBoss Developer Studio and interact with the running project in the BPM Suite. This is currently a work in progress, so watch for progress updates as the final product launch approaches.

We will continue to migrate our other demo projects and follow up with updates of what is encountered along these lines. Each project will be more complicated and involve exercising more and more of the product functionality, integration, and usability.

Japanese translation (日本語訳)