Small steps with big feet
Tutorial: Running the BPMN 2.0 Hello World example on MySQL (with Maven)
Last week, I showed you how to get a ‘BPMN 2.0 Hello World’ up and running with the latest release of Activiti. Today, we’ll take the very same example a step further and make it run on MySQL and mavenize it all.
Interested in just the code? Just scroll down to the bottom of the post or click here.
Prerequisites
The required stuff remains the same: Eclipse (or any other IDE) with a Maven plugin (I’m using m2eclipse), Java and Ant.
Project creation
We’re just creating a vanilla Maven project. I’ve used the Eclipse wizard (New -> Maven Project), but some commandline-magic should also do the trick.The end result should look like this in Eclipse:
Dependencies
To run our Hello World example on MySQL, we’ll need two dependencies:
- The Activiti engine jar, obviously
- The MySQL database driver
Accordingly, the pom.xml looks like this:
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>be.jorambarrez.tutorial</groupId>
<artifactId>helloworld</artifactId>
<version>1.0</version>
<dependencies>
<dependency>
<groupId>org.activiti</groupId>
<artifactId>activiti-engine</artifactId>
<version>5.0.alpha4</version>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>5.1.13</version>
</dependency>
</dependencies>
<repositories>
<repository>
<id>activiti.repo</id>
<url>http://maven.alfresco.com/nexus/content/repositories/activiti/</url>
</repository>
</repositories>
</project>
The process
The Hello world process is the same as the one we’ve used in the previous article.
The corresponding XML also remains the same. Call it hello-world.bpmn20.xml and add it to src/main/resources.
<?xml version="1.0" encoding="UTF-8"?>
<definitions id="definitions"
xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
targetNamespace="http://www.activiti.org/bpmn2.0">
<process id="helloWorld">
<startEvent id="start" />
<sequenceFlow id="flow1" sourceRef="start" targetRef="script" />
<scriptTask id="script" name="HelloWorld" scriptFormat="groovy">
<script>
System.out.println("Hello world")
</script>
</scriptTask>
<sequenceFlow id="flow2" sourceRef="script" targetRef="theEnd" />
<endEvent id="theEnd" />
</process>
</definitions>
Running the process
To run the process, we’ll be using the same main method as in the original article: bootstrap the engine, deploy the process and run it:
// Bootstrap
ProcessEngine processEngine = new DbProcessEngineBuilder()
.configureFromPropertiesResource("activiti.properties")
.buildProcessEngine();
ProcessService processService = processEngine.getProcessService();
// Deployment
processService.createDeployment()
.addClasspathResource("hello-world.bpmn20.xml")
.deploy();
// Run
processService.startProcessInstanceByKey("helloWorld");
The only thing that’s left to do, is add an activiti.properties file to src/main/resources that now points to a MySQL database. Alternatively, you could also use the cfg.create Ant target which is in the setup script of the Activiti distribution (see previous article).
database=mysql
jdbc.driver=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://192.168.1.102:3306/activiti
jdbc.username=activiti
jdbc.password=activiti
db.schema.strategy=create
Note that we’re setting the schema creation strategy to ‘create‘, since want to create the schema the first time we run our code. If you want to rerun your code afterwards, be sure to change it it ‘check-version‘.
Also, don’t forget to create the schema ‘activiti’ in MySQL and to add the user ‘activiti’ with enough permissions in MySQL.
Now just run it. The output should be non-surprising:
With that difference that we now actually are running on the MySQL database! See the proof on the following picture:
Download the source of this tutorial
The source for this tutorial can be downloaded as a ZIP file here. Just import it into Eclipse, point it your MySQL config and enjoy the ride!
Tutorial: a BPMN 2.0 Hello World With Activiti 5.0.alpha4 in 5 steps
With the 5.0.alpha4 release just out of the door, I thought it was time to demonstrate how easy it is to get started with the latest version of Activiti. Note That I’m not using the demo setup here, if you want that, check out my previous article.
In this tutorial, I’ll show you how we’ll run a very simple “Hello-World”-ish BPMN 2.0 business process on Activiti. From there on, you should be able to explore all the capabilities of Activiti, only limited by your imagination. In a later article, I’ll show you how to run this hello world app on MySQL.
Prerequisites
To follow this tutorial you’ll need
- Eclipse (or any other Java IDE)
- Ant
- 5 minutes of your time
Step 0: unzip the distribution
If you haven’t got it already, download the alpha4 release from the Activit website. Unzip this file.
Step 1: create a DB schema
Boot up an in-memory H2 database, that is shipped with the Activiti distribution:
cd activiti-5.0.alpha4/setup/
ant h2.install h2.start
You can now create the Activiti schema:
ant db.create
The result should look like this:
If you want, you can now inspect the database schema:
cd activiti-5.0.alpha4/apps/h2
java -cp h2*.jar org.h2.tools.Server -web
(I’m sorry for that last line, we’ll create an ant target to start up the web console in the next release)
Open your browser, and go to http://localhost:8082. Enter jdbc:h2:tcp://localhost/activiti in the field ‘JDBC URL’, leave all the rest as it is and click ‘connect’. You should see the Activiti schema in all its glory:
Step 2: Setup project
Open up Eclipse, and create a new Java project.
Add all the libraries from activiti-5.0.alpha4/lib/ to your classpath. You don’t need them all actually, but for speed we’ll just take the easy path here.
Step 3: Generate a configuration
The Activiti engine needs a small configuration file to run in a standalone way (ie not within a dependency container such as Spring for example). This config file can be generated from the terminal.
cd activiti-5.0.alpha4/setup
ant cfg.create
(The config file generator takes as input the build.properties and the build.${your_databae}.properties files. Tweaking these is content for a later blogpost!)
A config file and a jar with the same file is generated for you in the folder activiti-5.0.alpha4/setup/build/activiti-cfg and activiti-5.0.alpha4/setup/build/activiti-cfg.jar. Add this jar file to your project in Eclipse.
Step 4: Create the Hello World BPMN 2.0 process
The process we’ll model is very simple: a start and stop event, with a Hello-World step in between.
Granted, it can hardly be called a ‘business process’, but all things start small!
The XML representation of this process looks as follows. Add this XML file to your project and call it ‘hello_world.bpmn20.xml:
<?xml version="1.0" encoding="UTF-8"?>
<definitions id="definitions"
xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
targetNamespace="http://www.activiti.org/bpmn2.0">
<process id="helloWorld">
<startEvent id="start" />
<sequenceFlow id="flow1" sourceRef="start" targetRef="script" />
<scriptTask id="script" name="HelloWorld" scriptFormat="groovy">
<script>
System.out.println("Hello world")
</script>
</scriptTask>
<sequenceFlow id="flow2" sourceRef="script" targetRef="theEnd" />
<endEvent id="theEnd" />
</process>
</definitions>
You can see here that our ‘hello world’ step is basically the execution of a Groovy script saying hello to the world. Note that the id of the process is ‘helloWorld’.
Step 5: run it
All that is left now, is actually running the process. Create a new class in your project and add a main method.
First, boot up the process engine:
ProcessEngine processEngine = new DbProcessEngineBuilder()
.configureFromPropertiesResource("activiti.properties")
.buildProcessEngine();
ProcessService processService = processEngine.getProcessService();
You can see that we’re constructing the process engine using our generated configuration file. The process engine gives access to different services (such as taskService, processService, etc.), as you can see on the last line.
To run the process, it first need to be ‘deployed’ to the engine. Deploying means that the process is parsed and stored in the Activiti database:
processService.createDeployment()
.addClasspathResource("hello-world.bpmn20.xml")
.deploy();
And now we can execute the process, using the id of the process as ‘key’:
processService.startProcessInstanceByKey("helloWorld");
Which gives as output the following:
Next stop: uber-BPM-powers
And that’s all thats needed to run your first BPMN 2.0 Hello World process!
Of course, this is only the start of a very interesting journey. Best place to get familiar with the capabilities of Activiti and BPMN 2.0, is to check out our userguide.
Stay tuned for articles that will build further on this example (eg. using Maven, MySQL and enhancing the process) !
Screencast: Getting Started with Activiti 5.0.alpha2
I’m extremely happy to announce that Activiti 5.0.alpha2 just has been released!
Key feature of this release is the taskform functionality, many thanks to Erik Winlof for implementing them! Nothing could give it more credit than a screencast.
In this screencast, you”ll be able to enjoy:
- Setting up the Activiti environment using the demo setup script. As you’ll see, only 27 seconds are needed. That’s about the time it takes to pour a cup of coffee (if you’re fast).
- The Activiti Probe, REST, Modeler and Explorer webapps.
- The new taskform functionality. In the screencast, the vacation request BPMN 2.0 example is used. Check out our userguide to learn everything about taskforms and the example process.
Don’t forget to put on your speakers and to check the movie out in fullscreen!
Reactions to the Activiti launch
Monday morning, the world witnessed the birth of Activiti. And people saw that it was good. The stream of blogs, newsposts and tweets was unstoppable.
I tried to keep track of every item that appeared online, which was almost a fulltime job. But now the dust has settled (a bit), here is a list of interesting reactions to the Activiti launch.
Blogs
For a tech audience, blogs are the no. 1 news sources. Here’s a pick of what I’ve seen passing by in the blogosphere. Do let me know if I missed one!
- Tom’s blog, which triggered the start of the rollercoaster ride.
- Bernd Rucker from Camunda obviously had a post ready for the German market
- John Newton, CTO of Alfresco, explains in-depth the business reasons and opportunities behind the Activiti iniative.
- Sandy Kemsley, renowned BPM analyst, wrotea an objective analysis of the Activiti platform. She is eager to see how Activiti will evolve. And we won’t dissapoint her.
- BPM expert Scott Francis of BP3 wrote a very motivating blogpost. He actually downloaded the distribution and played with it. Let me quote him a few times here
- “Did I mention that the whole stack ran just fine, natively, on my Mac as well as a Windows VM?”
- “The documentation is already pretty comprehensive, and gets down to no-nonsense details (not true for many commercial products).”
- “I think the market is ripe for an open source BPM platform that leverages standard underlying technologies and is built from the beginning to allow for cloud-based deployment”
- “We may end up investing some time in the project ourselves.”
- The 451 Group posted a spot-on business analysis of the announcement, and let me quote them:
Activiti is likely to shake-up the BPM market with a ubiquitous project that supports the BPMN 2.0 standard from the Object Management Group.
- Peter Hilton from Lunatech Research, hits the nail on the head:
business processes and work-flow are aspects of most business software and integrating embeddable BPM will be a key element in reducing the cost of business software development.
- Theo Priestly asks the question everybody wanted to ask: “has the fight for open-source dominance begun?”
- Of course this was also great news for Alfresco users, as described on an Alfresco & Share blog.
- Infoworld focusses on the licence reasoning behind Activiti, and justly questions the value of GPL
- And Khaled Ben Driss, made sure that the French speaking countries had their share of the news:
- “Bravo pour cette initiative, à la sauce Apache, une licence business friendly …”
But the Activiti announcement wasn’t rainbows and puppies for a few, which led to the post from Active Endpoints. Thanks for the recognition guys! I was surprised to see that they see us as competitor 
. I really like the picture (reminded me of one of my favourite cartoons):-) Anyway, I can’t put it more obvious then Sandy Kemsley did:
Activiti BPM : it’s neither fish nor fowl – stinging commentary on view that BPEL is dead, by a BPEL-based vendor
The heartbeat of the internet, Twitter, was (and is) buzzing of the announcement. At the time of writing, I counted around 250-300 tweets directly related to Activiti. I didn’t check for typos or querying on alfresco, personal names, etc, which would even up that number.
A small selection:
-
(vtri) Looking forward to see how Activiti kicks on within #Alfresco. Always felt jBPM wasn’t growing to its potential. Could be very exciting…
-
(stephan007) Tom Baeyens joins Alfresco and launches #Activiti http://bit.ly/aNAcM7 (via @tombaeyens) ;o)
-
(protocol7) Great to see @tombaeyens and @jbarrez working in the open again. And Activiti seems destined for ASF, even better #activiti
- (akuckartz) Tried activiti.org BPMN 2.0 implementation demo. First impression: it works!
- (SphericalN) bpm just got interesting with the launch of alfresco’s http://www.activiti.org/index.html – well as interesting as bpm can get
- (protocol7) But Activiti is pretty much jBPM so I would think many will move over
- (claudiabia) Very excited about the news of new BPM – #Activiti… Can’t wait to see it integrated with #Alfresco
- (rami22) Im so excited for #Alfresco #Activiti project can’t wait to download it tomorrow and play with it
- (david_syer) Pleased to see #activiti http://bit.ly/dwKbgp project announcements. Good stuff there for #spring users looking for workflow features.
- (andrkoel) Activiti: looks like the next version of jbpm with a better license and a better community
- (mjasay) Alfresco hires Red Hat’s jBPM team, partners w/ VMware’s SpringSource to deliver a cool Business Process Mgmt solution
- (sfrancisatx) wow. i step away from the computer for a few hours and the blog hits are nearing our daily record again. lots of interest in activiti #bpm
News sites
After the official Alfresco press release, many news sites picked it up quite quickly. Every google query I do seems to produce even more results, so in the end I stopped tracking them. For what it’s worth, here my list:
The H, Techworld, CNBC, BusinessWire, ZDnet, Forbes, ItWorld.com, CMSWire, BPMEnterprise, NetworkWorld, ReduxOnline, Boston BusinessNews, Heise.de, CMSReport.com, StreetInsider, Yahoo Finance, FierceContentManagement, EarthTimes, NewsBlaze, San Francisco City and Press, CentralDaily, SunHerald, iStockAnalyst, PR-inside, Sys-con, Dailyfinance.com, Ameritrade, EuroInvestor.co.uk, and many, many more (I have twenty or something more copied locally, but by now you’ll know the press release by heart )
The curtains are pulled: Alfresco launches Activiti
After some weeks of silence, we can now finally pull the curtains … and reveal Activiti to the world!
Activiti is a super-fast and rock-solid BPM and workflow engine that natively runs BPMN 2.0. It’s completely open-source (Apache licence) and embeddable in any Java environment.
Tom and I joined Alfresco about two months ago, and we’ve kept ourselves quite busy. So together with this announcement, I’m proud to present the first alpha release of Activiti. Go and play with it while it’s hot!
Activiti is all about what made jBPM great, and taking giant leaps from there. Tom nicely summarizes it in his blogpost. A lot more information can be found on the Activiti website.
Official Alfresco press release: click here.
Regards,
Joram
Alive and Kicking!
You may have seen the Open letter to the jBPM community explaining that Tom and I step down from the jBPM project. We just want to let you know that we’re alive and kicking. We’re building a new BPM platform that’s architected for new IT requirements. It will be Apache licensed and it will run BPMN 2.0 natively. I can assure you …. exciting times are ahead!
That’s all we can share at this point. Stay tuned for more updates on ‘the what and the how’ very soon!
Native BPMN 2.0 execution with the freshly released jBPM 4.3
Happy 2010 to all the folks who read this blog! I’m extremely pleased to start this year with a bang by announcing that jBPM 4.3 has been released!
As we announced last month, the major achievement of this release is the native BPMN 2.0 execution on top of the PVM. See the announcement itself for more information, examples and a shiny movie.
The main goal of the first release of our BPMN 2.0 implementation was to implement the ‘basic’ part of the specification. Using the basic constructs, one should already get quite an impression how BPMN 2.0 can be used in practice with jBPM. We’re extremely proud that we’ve managed to include the BPMN 2.0 implementation as an integral part of the jBPM framework. This means that no database or API changes are required when you want to start using BPMN 2.0 with jBPM. Heck, enabling BPMN 2.0 in jBPM requires one single line of configuration. Just check the example of the previous BPMN 2.0 blogpost to see all this sweetness.
The complete distribution zip file can be found on http://sourceforge.net/projects/jbpm/files/
This distribution includes quite a few examples to get you started. The developers guide that is shipped with the distribution also contains a whole new chapter about how to implement BPMN 2.0 processes using jBPM 4.3. The content of the documentation is detailed and people with no prior BPMN 2.0 knowledge should be able to understand it without much problems. See the subdirectory /doc/devguide to find this guide. Or you can take a look online(link to my own version, online doc on docs.jboss.org isn’t yet updated due to past holiday season – but this can change any moment now).
To finish up, let me quote one of our prominent Community Users, Bernd Rücker:
“2010: the year of BPMN 2.0″
Of course, BPMN 2.0 isn’t the only thing we’ve been doing the last two months. Check our JIRA for a complete changelog. Most noteworthy new features are the ejb and jms invocation for JPDL – features that are easy to leverage for a future jBPM BPMN 2.0 release …
As always, thanks for reading!
Upcoming review ‘jBPM Developer Guide’ by Mauricio Salatino
Building an open source framework sure is a rewarding experience. You see community people logging issues, contributing patches, answering forum posts, joining the community days, etc.
And sometimes there is a crazy enthusiast user who sacrifices *a lot* of his free time to write a jBPM book. Heck, writing a jBPM book has been a long-lived dream for me … but some things always seem to come between that dream and reality (you know, like building a BPMN 2.0 implementation on top of jBPM). But that’s probably just an excuse, I know.
Writing a book takes a lot of time and effort and it’s an adventure that’s not to be taken light-heartedly. So many, many, many kudos to Mauricio Salatino for writing the just released “jBPM Developers Guide”! Just click on the book cover on the left to get more information or to order your own copy.
The people of Packt publishing were so kind to send me a review copy of this book, which I received this morning (see picture below). So expect a review coming up soon (I’m going to give it a thorough reading).
jBPM goes BPMN!
For those who follow the jBPM internal discussions a bit, the marriage of jBPM and BPMN will come as no surprise. Since this summer we’re coding away at a native BPMN2 implementation on top of our Process Virtual Machine (PVM), and you might have seen tweets or forum posts passing by where the term ‘BPMN’ pops up. However, the only proof were some classes in our SVN trunk …. until now!
In this post I’ll give you a sneak peek of our current BPMN2 execution effort which will be documented, QA’d and incorporated in the jBPM 4.3 release (scheduled January 1st). Many thanks go out to our community members Ronald Van Kuijk and Bernd Rücker, who have contributed a significant amount of ideas and code (and in fact, still are contributing to the BPMN2 implementation now as we speak). This is open-source power at its fullest…
Happy times indeed!
What is BPMN2?
Basically, the Business Process Modeling Notation (BPMN) started out a pure graphical notation standard for business processes, maintained by the Object Management Group (OMG). Version 2.0, which currently is in beta, adds execution semantics to the specification and this is of course where it gets interesting for jBPM.
The primary benefit of BPMN2 is that it is a standard accepted by the IT industry, which means that process models become portable (graphical and execution-wise) across process engines such as jBPM. Since process executions are the raison-d-être of jBPM, it is only natural we are now investing in BPMN2. People who are familiar with JPDL (the current native language of jBPM) will have generally no difficulties in learning the BPMN2 language, as many constructs and concepts are shared. In fact, from a high-level point of view, BPMN2 and JPDL are in concept solving the same problem (which is a biiiiig difference with BPEL – but that’s a story I’ll let other tell).
Of course, this is just the nutshell explanation. You can find a lot more information in our wiki.
Enough talking … show me how it works!
The business process we’re going to implement looks as follows (click to enlarge – created using the wonderful editor from our friends at Signavio).
You might recognize this example, since we’ve also implemented it in JPDL as an example in our distribution.
The business process is simple: an employee can start a new process and make a request for a certain amount of vacation days. After the request task has been completed, the manager will find a verification task in its tasklist. The Manager can now decide to accept or reject this request. Depending on the outcome (that’s the little rhombus on the outgoing transitions, or better said ‘sequence flow’ as it is called in BPMN. It means that there is a condition that must be true to follow it), a rejection message is send or the process ends.
As is the case with JPDL, BPMN2 uses an XML language to define the process definition. Our business process looks like this in BPMN2 XML:
<?xml version="1.0" encoding="UTF-8"?>
<definitions id="vacationRequest"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schema.omg.org/spec/BPMN/2.0 BPMN20.xsd"
xmlns="http://schema.omg.org/spec/BPMN/2.0"
typeLanguage="http://www.w3.org/2001/XMLSchema"
expressionLanguage="http://www.w3.org/1999/XPath"
targetNamespace="http://jbpm.org/example/bpmn2/vacation_request"
xmlns:jbpm="http://jbpm.org/bpmn2">
<process id="vacationRequestProcess" name="BPMN2 Example process">
<startEvent id="start" />
<sequenceFlow id="flow1" name="fromStartToRequestVacation"
sourceRef="start" targetRef="requestVacation" />
<userTask id="requestVacation" name="Request Vacation"
implementation="other">
<potentialOwner resourceRef="user" />
<rendering id="requestForm">
<jbpm:form>request_vacation.ftl</jbpm:form>
</rendering>
</userTask>
<sequenceFlow id="flow2"
name="fromRequestVacationToVerifyRequest" sourceRef="requestVacation"
targetRef="verifyRequest" />
<userTask id="verifyRequest" name="Verify Request"
implementation="other">
<potentialOwner resourceRef="manager" />
<rendering id="verifyForm">
<jbpm:form>verify_request.ftl</jbpm:form>
</rendering>
</userTask>
<sequenceFlow id="flow3" name="fromVerifyRequestToEnd"
sourceRef="verifyRequest" targetRef="theEnd">
<conditionExpression xsi:type="tFormalExpression">
${verificationResult == 'OK'}
</conditionExpression>
</sequenceFlow>
<sequenceFlow id="flow4"
name="fromVerifyRequestToSendRejectionMessage" sourceRef="verifyRequest"
targetRef="sendRejectionMessage">
<conditionExpression xsi:type="tFormalExpression">
${verificationResult == 'Not OK'}
</conditionExpression>
</sequenceFlow>
<scriptTask id="sendRejectionMessage" name="Send rejection Message"
scriptLanguage="bsh">
<script>
<![CDATA[System.out.println("Vacation request refused!");]]>
</script>
</scriptTask>
<sequenceFlow id="flow5"
name="fromSendRejectionMessageToEnd" sourceRef="sendRejectionMessage"
targetRef="theEnd" />
<endEvent id="theEnd" name="End" />
</process>
</definitions>
Most of the constructs are straightforward, certainly if you’re coming from a JPDL background. Do note that the Resource construct isn’t correctly implemented (yet), but that should be solved for the 4.3 release. Also note that you already can add taskforms to your user tasks (see line 33-35 for example).
Also interesting to note is the way how the outcome of the user task is used is for guiding the flow through the process (line 41 and 49). We could have used an exclusive gateway to do the same (which is also already implemented), but we’re using formal expressions on the outgoing sequence flows coming from the user task, just to show you we can.
That’s cool … but I’m a Java developer!
Rest assured: everything that makes jBPM a blessing to use is here to stay. Tom has put a tremendous effort in the jBPM PVM and we now are reaping the fruits of his work. BPMN2 is implemented on top of the PVM, which means that many things come for free: database persistency, database transactions, the service and query API’s, etc. it all just works.
So, when we want to test a business process, we use the same Java approach which we always had with jBPM:
public class VacationProcessTest extends JbpmTestCase {
protected void setUp() throws Exception {
super.setUp();
NewDeployment deployment = repositoryService.createDeployment();
deployment.addResourceFromClasspath("vacationrequest.bpmn.xml")
String deployId = deployment.deploy();
registerDeployment(deployId);
}
public void testRequestRejected() {
ProcessInstance pi = executionService.startProcessInstanceByKey("vacationRequest");
// After process start, peter (employee)
// should be a candidate for the task
Task requestTasktask = taskService.createTaskQuery()
.candidate("peter").uniqueResult();
assertNotNull(requestTasktask);
// After this task is completed,
// a manager (eg alex) is be able to see a 'verify' task
TaskQuery verifyTaskQuery = taskService.createTaskQuery()
.candidate("alex");
assertNull(verifyTaskQuery.uniqueResult());
taskService.completeTask(requestTasktask.getId());
Task verifyTask = verifyTaskQuery.uniqueResult();
assertNotNull(verifyTask);
// When completing the verification task,
// we also need to store the result of the decision
// (will be done through the taskform normally)
Map<String, Object> vars = new HashMap<String, Object>();
vars.put("verificationResult", "not OK");
taskService.completeTask(verifyTask.getId(), vars);
// With a rejection, we should see
// the 'sendRejectionMessage' task in the history log
HistoryActivityInstance hai = historyService.createHistoryActivityInstanceQuery()
.activityName("sendRejectionMessage").uniqueResult();
assertNotNull(hai);
assertProcessInstanceEnded(pi);
}
}
So what you’re seeing here is
- Testing BPMN2 business processes in pure Java code that everybody understands
- in a way which is exactly the same as for JPDL
- and using the very same API which we are all familiar with
- and using the very same database schema as before!
What’s there not to like? In my opinion, the argument of the same API is really really really powerful. The PVM is showing its power at its fullest! To configure your jBPM installation for BPMN2, you just have to add this line to your jbpm.cfg.xml file:
<import resource="jbpm.bpmn.cfg.xml" />
Conclusion: using BPMN2 processes in your application with jBPM is extremely easy. Everything you know about embedding and configuring jBPM is just as before … except that you’re now using a portable and standard process language.
What else?
A lot. Just check our wiki to see what’s planned for the 4.3 release. When talking in pure BPMN2 constructs, these are all planned for next month: Exclusive Gateway (XOR), Parallel gateway (AND), Service Task (Java based), Manual Task, Receive Task (Java only), Script Task, User Task, None start event, None end event, Terminate end event, Sequence Flow, Conditional Sequence flow, Formal expression, Interface (Java), Resource + ResourceParameter. More is possible, if we go to bed a bit later than usual
To finish this sneak peek, here is a screencast of our jBPM console executing the BPMN2 example process which is described above. In this screencast, you’ll see Peter (the employee) requesting 5 days of vacation using our business process. After he finishes the request task, he logs out. Mike, a manager, now logs in and finds the vacation request in his task list. He rejects the request since there is too much work. Peter will now be notified with a rejection message (for this demo, just a printout to the console). The forms you see are using the same taskform mechanism which I described earlier.
The last part of the screencast shows that the reporting functionality, which was already available for JPDL, also works for the BPMN2 processes. Even better, since the PVM defines a shared database schema, reports can aggregate data based on JPDL and BPMN2 processes without any problem!
Until next post!
Joram
New feature in jBPM 4.2: Auto-upgrade your jBPM installation
Introduction
With the 4.2 release coming close (somewhere beginning next week), I feel is time to write about one the new nice features of this particular release.
As a software engineer, I’m always eager to try out a new release when of one of the products/frameworks/… I use on a daily basis hits the shelves. I’ve also learned that I’m not alone on this matter and that it is a common thing among developers to have this burning itch to try out new stuff. But with every new release it’s also always keeping fingers crossed and hoping that everything stays working as it was without actually having the system blow up in your face.
With a new jBPM release, there are three ‘change-areas’ which could disrupt your current system:
* API changes. As I wrote a few months ago, starting from jBPM 4.0, there is a new API. Our policy is is to keep changes to the API (extremely) limited and deprecate any to-be-changed operations for two or three releases before actually replacing them completely. This means you have plenty of time do execute the change. So no blow-up on this front.
* JPDL schema changes. A New jBPM release often means additional features, which could lead to jPDL schema changes that make existing process definitions incompatible with the latest release. This issue has been addressed in the upcoming 4.2 release: old process definitions will remain backwards compatible with newer releases of the engine. Not a single change to your precious process definitions will be needed when upgrading your jBPM4 installation. So for example process definitions coded in 4.1 style will be deployable to a 4.7 engine. For more info, see the Jira issue. So again, no fear for blow-ups here.
* Database changes. Since jBPM uses a relational database as a persistence mechanism for processes, tasks, audit history, etc… new features in the engine can lead to changes in the database. We try to keep these changes as limited as possible, but sometimes they are simply needed to evolve. Of course, with every release we indicate which changes need to be done to the database, but if you skip a few releases before you upgrade this tends to become cumbersome.
It’s this last point which I want to demonstrate in this post. The 4.2 and every subsequent release have a new mechanism on board to determine the current version of the database schema and update it to the fresh release automatically.
Setting up the ‘old’ data
We’ll start by downloading and unzipping an older release of jBPM, jBPM4.1:
[jbarrez@jenova 4.2_upgrade]$ unzip jbpm-4.1.zip
We’ll now create the jBPM schema using one of the install task shipped in the distribution. Since I’m using a MySQL database, I first need to update the jdbc properties that the install script will be using:
[jbarrez@jenova 4.2_upgrade]$ your-favourite-editor jbpm-4.1/install/jdbc/mysql.properties
and change it to my local database:
We can now create the schema in my local database (notice how we just need to add the ‘database‘ parameter, the script will then take the connection properties from the mysql.properties file we’ve just edited):
[jbarrez@jenova 4.2_upgrade]$ cd jbpm-4.1/install/ [jbarrez@jenova install]$ ant create.jbpm.schema -Ddatabase=mysql Buildfile: build.xml [echo] database......... mysql [echo] tx............... standalone [echo] mail.smtp.host... localhost [echo] current dir = /home/jbarrez/dev/blog/4.2_upgrade/jbpm-4.1 create.jbpm.schema: [echo] creating jbpm schema in db jdbc:mysql://localhost:3306/jbpmExecuting resource: /home/jbarrez/dev/blog/4.2_upgrade/jbpm-4.1/install/src/db/jbpm.mysql.create.sql 79 of 79 SQL statements executed successfully BUILD SUCCESSFUL Total time: 3 seconds
Which gives us a fresh jBPM 4.1 schema in our database:
We now use a basic ‘Hello World’ process definition:
<process name="helloWorld" xmlns="http://jbpm.org/4.0/jpdl">
<start>
<transition to="display hello world" />
</start>
<custom name="display hello world" class="be.jorambarrez...DisplayHelloWorld">
<transition to="theEnd" />
</custom>
<end name="theEnd" />
</process>
… to start a process instance through the jBPM API:
public static void main(String[] args) {
ProcessEngine processEngine = new Configuration().buildProcessEngine();
RepositoryService repoService = processEngine.getRepositoryService();
ExecutionService executionService = processEngine.getExecutionService();
NewDeployment deployment = repo.createDeployment()
.addResourceFromClasspath("process.jpdl.xml");
deployment.deploy();
executionService.startProcessInstanceByKey("helloWorld");
}
The debug log shows us the actual execution trace, where our ‘Hello World’ message is displayed between the engine logs.
17:53:15,219 FIN | [ProcessDefinitionImpl] creating new execution for process 'helloWorld' 17:53:15,224 FIN | [DefaultIdGenerator] generated execution id helloWorld.1 17:53:15,229 FIN | [ExecuteActivity] executing activity(25788693) 17:53:15,229 FIN | [ExecuteActivity] executing activity(display hello world) Hello World! 17:53:15,230 FIN | [ExecuteActivity] executing activity(theEnd) 17:53:15,230 FIN | [ExecutionImpl] execution[helloWorld.1] ends with state ended
Upgrading in one minute
Suppose now that we take this process to production. Life is happy and peace. But then comes a new jBPM release. The developer hands start to itch again … So we take the jBPM 4.2 distribution and unzip it:
[jbarrez@jenova 4.2_upgrade]$ unzip jbpm-4.2.zip
And we change the dependencies of our little Hello World project, by either replacing the 4.1 jar with the 4.2 jar in the build path. Or if you are using Maven:
<dependency> <groupId>org.jbpm.jbpm4</groupId> <artifactId>jbpm-jpdl</artifactId> <version>4.2</version> </dependency> <repositories> <repository> <id>jboss</id> <url>http://repository.jboss.com/maven2</url> </repository> </repositories>
Of course, since we are adventurous developers, we don’t care about upgrading and just run our Hello World process with the new jBPM version. However, the new upgrade check will now kick in:
Exception in thread "main" org.jbpm.api.JbpmException: jBPM DB schema not in sync with library version: no JBPM4_PROPERTIES table. Run the upgrade target first in the install tool. at org.jbpm.pvm.internal.cmd.CheckDbCmd.execute(CheckDbCmd.java:54) at org.jbpm.pvm.internal.svc.DefaultCommandService.execute(DefaultCommandService.java:42) at org.jbpm.pvm.internal.tx.StandardTransactionInterceptor.execute(StandardTransactionInterceptor.java:54) at org.jbpm.pvm.internal.svc.EnvironmentInterceptor.executeInNewEnvironment(EnvironmentInterceptor.java:53) at org.jbpm.pvm.internal.svc.EnvironmentInterceptor.execute(EnvironmentInterceptor.java:40) at org.jbpm.pvm.internal.svc.RetryInterceptor.execute(RetryInterceptor.java:55) at org.jbpm.pvm.internal.svc.SkipInterceptor.execute(SkipInterceptor.java:43) at org.jbpm.pvm.internal.cfg.ProcessEngineImpl.checkDb(ProcessEngineImpl.java:177) at org.jbpm.pvm.internal.cfg.ProcessEngineImpl.buildProcessEngine(ProcessEngineImpl.java:170) at org.jbpm.api.Configuration.buildProcessEngine(Configuration.java:140) at be.jorambarrez.jbpm4.upgrade.Main.main(Main.java:15)
As you can see in the stacktrace, during the creating of the jBPM ProcessEngine a check on the database schema will take place (tech detail: it uses the JBPM4_PROPERTIES table and some other checks to do this). And since the exception is thrown during ProcessEngine creation, this also stops us from executing processes in a old schema – which is a good thing.
So we follow the instructions of the exception above and run the upgrade script. Don’t forget to change the database properties (as we did above).
[jbarrez@jenova install]$ ant upgrade.jbpm.schema -Ddatabase=mysql Buildfile: build.xml [echo] database......... mysql [echo] tx............... standalone [echo] mail.smtp.host... localhost upgrade.jbpm.schema: [echo] upgrading jbpm schema... ... // *snip* Hibernate setup etc 12:30:02,501 INF | [DbHelper] --- Executing DB Commands ------------------------- 12:30:02,501 INF | [DbHelper] create table JBPM4_PROPERTY ( KEY_ varchar(255) not null, VERSION_ integer not null, VALUE_ varchar(255), primary key (KEY_) ) type=InnoDB 12:30:02,544 INF | [DbHelper] --- Result: 0 -------------------------- 12:30:02,544 INF | [DbHelper] alter table JBPM4_HIST_DETAIL drop index IDX_HDETAIL_HACTI 12:30:02,564 INF | [DbHelper] --- Result: 0 -------------------------- 12:30:02,564 INF | [DbHelper] alter table JBPM4_HIST_DETAIL drop index IDX_HDETAIL_HPROCI 12:30:02,578 INF | [DbHelper] --- Result: 0 -------------------------- 12:30:02,578 INF | [DbHelper] alter table JBPM4_HIST_DETAIL drop index IDX_HDETAIL_HVAR 12:30:02,595 INF | [DbHelper] --- Result: 0 -------------------------- 12:30:02,596 INF | [DbHelper] alter table JBPM4_HIST_DETAIL drop index IDX_HDETAIL_HTASK 12:30:02,610 INF | [DbHelper] --- Result: 0 -------------------------- 12:30:02,611 INF | [DbHelper] create index IDX_HSUPERT_SUB on JBPM4_HIST_TASK (SUPERTASK_) 12:30:02,625 INF | [DbHelper] --- Result: 0 -------------------------- 12:30:02,736 INF | [PropertyImpl] nextDbid is initialized to 4 12:30:02,740 INF | [Upgrade] jBPM DB upgrade completed successfully. 12:30:02,740 INF | [SessionFactoryImpl] closing 12:30:02,741 INF | [DriverManagerConnectionProvider] cleaning up connection pool: jdbc:mysql://localhost:3306/jbpm BUILD SUCCESSFUL Total time: 4 seconds
The output of the script show us that some upgrades were done: a new table was created, some indexes were altered and some colum values were updated.
When we now retry running the Hello World process, everything works fine:
12:41:19,275 FIN | [DatabaseIdComposer] generated execution id helloWorld.10010 12:41:19,279 FIN | [ExecuteActivity] executing activity(28678425) 12:41:19,279 FIN | [ExecuteActivity] executing activity(display hello world) 12:41:19,280 FIN | [ExecuteActivity] executing activity(theEnd) 12:41:19,280 FIN | [ExecutionImpl] execution[helloWorld.10010] ends with state ended Hello World!
And if you pay close attention to the logs, you’ll see that the schema check is OK now:
12:41:18,687 INF | [CheckDbCmd] jBPM version info: library[4.2], schema[4.2]
NOTE: if you got a grumpy DBA: the jBPM distro also ships with plain .sql files to use for upgrading the schema, which you can hand over to him/her.
Conclusion
And that’s it, folks. We’ve got API stability, backwards schema compatibility and as I just showed you, upgrading the database takes only a minute of your time… leaving more time for you to actually code business processes!
QA
To finish the post, I just want to show you a screenshot from our Hudson continuous integration job. Since the upgrade feature is extremely important for us, we test it against all our supported databases and JDK versions. The test job that is executed is actually very close related to the explanation of the previous section. With every new release, this configuration matrix will continue to grow. Which means that in every future release are certain of backwards compatibility and upgradeability.
Happy jBPM coding!