Monday, April 29, 2013

Try the jBPM Console NG (Beta)! (for developers)


Hi everyone out there! This is another post about the jBPM Console NG. After 6 months of heavy work I'm happy to be writing this post for the developers community to try it out. On this post I will be explaining how to build the application from the sources. The main idea behind this is to know how to set up your environment and modify the application while your testing it. You will basically learn all you need to know to contribute with the project.

Introduction

The jBPM Console NG aims to provide a Task & Process Management collaborative environment to facilitate the adoption of the BPM Suite in a company. Downloading the sources and compiling the application will allow you to try the application and modify it in the case that you want to extend it or fix bugs. The application is under the Apache License V2 so it can be used and modified according with this license.

Working with the Source Code

The first step in order to get everything running is to get the source code using GIT. This are the things that you need to have installed in your computer in order to proceed:
  • JDK 6
  • Maven 3.x
  • Git
  • Any IDE (Eclipse, IntelliJ, Netbeans) with the maven plugin installed
  • JBoss Application Server 7.1.1 (optional)
Once you get all these tools installed we can proceed to get the source code from the github repository:
In order to get a "Clone" of the repository to work you must from the terminal:
git clone https://github.com/droolsjbpm/jbpm-console-ng.git

Once it's done, you can compile the source code, here you have two alternatives:
1) Compile the project for development purposes with:
mvn clean install

2) Compile the project to generate the distribution wars for JBoss and Tomcat + the documentation
mvn clean install -PfullProfile

Sit back and relax! The first time that you do this step Maven requires to download tons of libraries, so you will need to wait.

Running the application in Hosted Mode

Once the project is compiled, the jbpm-console-ng-showcase can be executed in what GWT calls "Hosted Mode" (also known as Developer Mode)
In order to start up the application in hosted mode you should do the following:
1) The jBPM Console NG Showcase contains the final application distribution code:
cd jbpm-console-ng-showcase/

2) Run in hosted mode using the GWT Maven Plugin
mvn gwt:run

This will start up a Jetty + the GWT Development Mode screen which will allow you to copy the URL where the application is hosted for you to try it:
GWT Hosted Mode
GWT Hosted Mode
Copying the URL (http://127.0.0.1:8888/org.jbpm.console.ng.jBPMShowcase/jBPM.html?gwt.codesvr=127.0.0.1:9997) into your browser (For hosted mode you need to have the GWT plugin installed in your browser, don't worry it's automatically installed if you don't have it) will open the application. I strongly recommend to use Firefox for development mode or Chrome (usually slower), because for developing we scope the compilations to work on FF and Chrome (gecko browsers).

Running the application in JBoss AS  7

Now if you want to deploy the application on JBoss, you need to go the the second compilation option (-PfullProfile) which will take some extra time to compile the application for all the browsers and all the languages (English, Spanish, etc.). In order to deploy the application to your jboss as 7 instance you will need to move the war file generated inside the jbpm-console-ng/jbpm-console-ng-distribution-wars/target/jbpm-console-ng-jboss-as7.war into the <jboss-as>/standalone/deployments directory and then rename the war file to jbpm-console-ng.war. The name of the application will be used as the root context for the application.
For the JBoss you also need to do some configurations for the users and roles. Inside the jBPM Console NG you will need to have set up the users that will be available for your installation. Those are handle by JBoss Security Domains. In order to set up the security domains, you need to do the following:
1) Edit the <jboss_as>/configuration/standalone.xml and add a new security domain:

<security-domain name="jbpm-console-ng" cache-type="default">
 <authentication>
   <login-module code="UsersRoles" flag="required">
     <module-option name="usersProperties"   value="${jboss.server.config.dir}/users.properties"/>
     <module-option name="rolesProperties" value="${jboss.server.config.dir}/roles.properties"/>
     </login-module>
   </authentication>
</security-domain>

2) add the users.properties and roles.properties files
content of the user.properties file:
maciek=Merck
salaboy=salaboy
katy=katy
john=john
content of the roles.properties file:

maciek=jbpm-console-user,kie-user,analyst,HR,PM,Reviewer
salaboy=jbpm-console-user,user,analyst,PM,IT,Reviewer
katy=jbpm-console-user,HR
john=jbpm-console-user,Accounting
The only requirement for the roles file is to include the jbpm-console-user role for all the users.
Note that this is the simplest way of configuring a security domain, but you can go for more advanced options, like configuring the security domain to use an LDAP server or a Database to authenticate your users and roles. (https://docs.jboss.org/author/display/AS7/Security+subsystem+configuration)
Then you are ready to go, you can start jboss with:
1) Go into the bin directory:
cd <jboss-as>/bin/
2) Start the application server:
./standalone.sh

On Openshift

In order to deploy the application into openshift you need to obviously have an openshift account. Once you set up your account you will need to do almost the same configurations as in the JBoss Application. In the openshift git repository that you clone, you will have a specific dir to apply this configuration:
.openshift/config
There you will find the standalone.xml file and you can place the users.properties and roles.properties files.
So in the standalone.xml file you will need to configure the security domains as we did before and add the users.property and roles.properties files.
Besides this configuration you will need to set up a system property for storing the knowledge repository:

<system-properties>
  <property name="org.kie.nio.git.dir" value="~/jbossas-7/tmp/data"/>
</system-properties>

The Application

Now you are ready to use the application, so if you point your browser to the URL provided by the hosted mode or to http://localhost:8080/jbpm-console-ng/ you will be able to access the login form.
As you will see, before entering the application you will need to provide your credentials. Once you are in the application is divided in:
Cycle
Cycle
In the Authoring section you will be able to access to the Process Designer to model your business processes. The Process Management section will allow you to list the available Business Processes and Start new instances, and also monitor those instances. The Work Section will enable you to access the Task Lists (Calendar and Grid View)  to work on the tasks assigned to you. In order to use the BAM section you will need to deploy the BAM dashboard application but I will describe that in a future post.
Feel free to try it out and write a comment back if you find something wrong.

Contributions

Your feedback means a lot, but if you want to contribute, you can fork the jbpm-console-ng repository in github: https://github.com/droolsjbpm/jbpm-console-ng/
I will appreciate if you can test the Task Lists and Process Management screens and write feedback in this post, so I can iteratively improve what we have. I will be writing another post to describe the screens and also to list a set of small tasks that you can contribute back.

Friday, April 05, 2013

Score DRL: faster and easier in OptaPlanner

For OptaPlanner (= Drools Planner) 6.0.0.Beta1, I 've replaced the ConstraintOccurrence with the much more elegant ConstraintMatch system. The result is that your score DRL files are:
  • much faster
  • easier to read and write
  • far less error-prone, because they make it a lot harder to cause score corruption
Let's look at the results first, before we look at the code readability improvements.

Faster

"Show me the benchmarks!"

The average calculate count - which is the number of scores OptaPlanner calculates per second - has risen dramatically.
  • N queens: +39% calc count for 256 queens
  • Cloud balance: +27% calc count on average
  • Vehicle routing: +40% calc count on average
  • Course scheduling: +20% calc count on average
  • Exam scheduling: +23% calc count on average
  • Nurse rostering: +7% calc count on average

However, this doesn't necessarily imply a dramatic improvement in result, especially if the old result is already (near) optimal. It means you can get the exact same result in far less time. But - as with all other performance improvements - gives no promise for significantly better results in the same time. It does helps when scaling out.
  • Cloud balance: +0.58% feasible soft score on average in 5 minutes
  • Vehicle routing: +0.14% feasible soft score on average in 5 minutes
  • Course scheduling: +2.28% feasible soft score on average in 7 minutes
  • Exam scheduling: +0.53% feasible soft score on average in 7 minutes
Several of the 30 Vehicle routing datasets were already solved optimally in 5 minutes, so these drag the average down, despite the high vehicle routing speedup.

All benchmarks use the exact same Drools and OptaPlanner version, so these numbers show only the improvements of the ConstraintMatch change. There are several other improvements in 6.0.

How does the average calculate count scale?

Here are a some charts comparing the old ConstraintOccurrence with new ConstraintMatch. The new ConstraintMatch's current implementation hasn't been fully optimized, so it's sometimes referred to being in "slow" mode (even though it's faster).

CloudBalance:

Vehicle routing:

Course scheduling:

Exam rostering:


Easier

"Show me the code!"

For starters, the accumulateHardScore and accumulateSoftScore rules are removed. Less boilerplate :) Next, each of the score rule's RHS (= then side) is simpler:

Before:
    rule "conflictingLecturesSameCourseInSamePeriod"
        when
            ...
        then
            insertLogical(new IntConstraintOccurrence("conflictingLecturesSameCourseInSamePeriod", ConstraintType.HARD,
                    -1,
                    $leftLecture, $rightLecture));
    end


After:
    rule "conflictingLecturesSameCourseInSamePeriod"
        when
            ...
        then
            scoreHolder.addHardConstraintMatch(kcontext, -1);
    end


Notice that you don't need to repeat the ruleName or the causes (the lectures) no more. OptaPlanner figures out it itself through the kcontext variable. Drools automatically exposes the kcontext variable in the RHS, so you don't need any extra code for it. Also, the limited ConstraintType enum has been replaced by a Score type specific method, to allow OptaPlanner to better support multilevel score types, for example HardMediumSoftScore and BendableScore.

You also no longer need to hack the API's to get a list of all ConstraintOcurrence's: the ConstraintMatch objects (and their totals per constraint) are available directly on the ScoreDirector API.