Getting Started

This page describes the fastest way to get jbpm up and running on your system, including the demo webapplication.

Required software

jBpm 2.0 is tested on a Windows XP machine with following software packages installed :

Getting jBpm

The easiest way to get the latest released sources is from the sourceforge download site.

To get the latest sources from cvs, provide this information to you cvs-client :

  • Connection type: pserver
  • User: anonymous
  • Password:
  • Host: cvs.sourceforge.net
  • Port: 2401 (which is the default)
  • Repository path: /cvsroot/jbpm
  • Label: :pserver:anonymous@cvs.sourceforge.net:/cvsroot/jbpm
Then checkout module jbpm2.

Installation

  1. unzip jbpm to a folder of your choice
  2. update the configs in build.properties to your environment with your favorite text editor
  3. in directory ${jbpm.home} run 'ant configure.jboss.3.2.3+'. (the same task works for jboss-3.2.5) That creates a jbpm configuration ${jboss.home}/server/jbpm which is basically a copy of the 'all' configuration. The only difference is that 2 files are added to the deploy directory : jbpm-db-service.xml and jbpm-ds.xml
  4. start the jbpm configuration of jboss with '%JBOSS_HOME%/bin/run.bat -c jbpm'.
  5. in directory ${jbpm.home}/web run 'ant deploy'. This will build and deploy the web application to the jboss configuration that we've just created.
  6. in directory ${jbpm.home}/web run 'ant deploy.process.archives'. This deploys the demo payraise process to the jbpm database in jboss. Since this is normally your first jbpm access to the database, this will also create the jbpm tables automatically.
  7. surf to http://localhost:8080/jbpm

The process archive input

Now you can take a look at the process archive that served as the input for jbpm. You can find the process archive at ${jbpm.home}/web/target/payraiseprocess.par. Open it with winzip or any other similar tool that knows how to open jar (java archive) files.
+ processdefinition.xml
+ forms.xml
+ forms
   + evaluating.form
   + request.form
   + treat.form
   + update.erp.form
   + payraise.gif
contents of the payraiseprocess.par

processdefinition.xml contains the formal description of the process. in the jPdl xml language. That file is used by the core engine. All the other files are used by the webapplication to create a web interface for the process. forms.xml specifies the relation between the different states in the process and the forms. The forms contain the html for the forms.

Directory structure

The directory structure of the sub projects core, tools & ejb complies with the maven directory layout http://maven.apache.org/reference/dirlayout.html Note that only ant is used for the build process. We just use the same directory structure as in a maven project. The most important part is that in every subdir src/java contains the java source files that will be packaged and src/test/java contains all unit test related source files.
  • core: is the sub module for the jbpm.core.jar package
  • web: is the sub module for the jbpm.war package
  • ejb: is the sub module for the jbpm.ejb.jar package
  • doc: contains all the documentation available for jbpm
  • lib: contains all the used libraries and their licenses
  • example: contains a template project for developing processes

Overview of the jBpm packages

core

  • produced file : core/target/jbpm.core.jar
  • is the complete jbpm workflow engine
  • runnable in a J2SE environment
  • accessible through an easy to use API
  • libs required by jbpm.core.jar :
    • lib/commons/*.jar
    • lib/hibernate/*.jar
    • database driver classes (e.g. lib/hsqldb/hsqldb.jar)

web

  • produced files : web/target/jbpm.war and web/target/payraiseprocess.par
  • is a web application that is created for 2 purposes :
    • rapid prototyping : with a simple xml-file and a few form files in the process archive, you can create a webapplication for your processes
    • as the basis for a custom web application : when you want to create a custom web application on top of your business processes, you can use the web submodule as a quickstart
  • requires a servlet container

ejb

  • produced file : ejb/target/jbpm.ejb.jar and ejb/target/jbpm.ejb.client.jar
  • is an ejb module that contains a wrapper for the execution service of jbpm
  • deployable on a (clustered) j2ee server (configuration instructions included)

Running the ejb module

As a prerequisite, make sure you've unpacked a clean jboss-3.2.3 and configured it as described in Installation.
  1. start your jboss with '${jboss.home}/bin/run.bat -c jbpm'
  2. open a console in directory ${jbpm.home}/ejb
  3. deploy the webapp with 'ant deploy'
  4. deploy the process archive with 'ant deploy.process.archives'
  5. execute the test (50 process executions) with 'ant test'. if you run this test from within eclipse or another testrunner, be sure to add the ${jboss.home}/client/jbossall-client.jar into the classpath.

Process development environment

The ${jbpm.home}/build.xml ant script contains a target to build a process development environment from the example directory. The process development environment (pde) is a project directory structure with a build script for developing process archives. The pde does not include facilities to execute processes other then for testing purposes.

As you know, the input of jBpm is a set of formal descriptions of your business processes. These formal descriptions are called process archives. The process development environment is a template project for creating such process archives.

To create a project from the template, perform the operations

  • update the property jbpm.pde to the directory where you want to create the process archive project
  • execute 'ant create.pde' in ${jbpm.home}
Now, lets take a look at the contents of the generated project...

src/process/exampleprocess.xml : is an xml file that represent the basic structure of a process definition. This file, together with other files, is packed in a zip file (or jar file) and that file is called a process archive.

src/java/... : are java classes that can be added to a process archive. The classes can be packed as part of the process archive. jBpm has several interfaces that can be seen as extension points of process definitions. In jBpm this is called the delegation mechanism and the implementations are called delegation classes. Typically, the delegation classes are included a the process archive are

src/test/java/... : are the test classes based on JUnit. The example shows how standalone JUnit tests can be created where one test executes one scenario of a business process. By default, the tests are run against an in-memory hypersonic database. Each time the tests are executed, the jBpm database tables are created in the empty in-memory database. This mechanism makes it really easy to execute tests because you do not have to set up a database and initialise it with the proper data.

build.xml : is an ant script file that contains the necessary targets to build, test and deploy the process archives. To see the process development environment in action, open a console in the home directory of your ${jbpm.pde} and run the ant target 'test' with the command ant test. After that, open the file ${jbpm.pde}/target/test-results/index.html in your favorite browser. (on a windows machine, this should pop-up automatically).

To learn about how to write the process descriptions, see The jPdl reference manual. Another way to learn about writing processes and using jBpm is to look at the tests as examples : see core/src/test/resources/process/*.xml for the processdefinition.xmls and see core/src/test/java/org/jbpm/service/*Test.java for the java code that uses the processes.

To create a project in eclipse for the process development environment perform following operations :

  • in eclipse, File --> New --> Project...
  • select Java, Java Project
  • click Next>
  • give the project a name (e.g. jbpm.pde) and optionally specify its location (e.g. C:\eclipse\workspace\jbpm.pde)
  • click Next>
  • In the tab 'Source', remove the folder jbpm.pde
  • In the tab 'Source', add the folders jbpm.pde/src/java, jbpm.pde/src/test/java, jbpm.pde/src/config and jbpm.pde/src/process
  • Set the default output folder to jbpm.pde/target/classes
  • In tab 'Libraries', click 'Add JARs'
  • In the 'JAR Selection' dialog box, open jbpm.pde/lib and select all libraries
  • Then click 'Finish'

To set up the junit testrunner in eclipse, perform the following operations :

  • If not already open, show view JUnit with Window --> Show View --> Other... --> Java --> JUnit
  • Open the file src/test/java/org/jbpm/example/ExampleProcessTest.java in the editor
  • In eclipse, Run --> Run...
  • In the tree-window 'Configurations:" select the root 'JUnit'
  • Click 'New'
  • Click 'Run'
  • Check the green bar in the JUnit window !

Ant targets

check out the docs of the ant scripts with 'ant -p' in dirs ${jbpm.home}, ${jbpm.home}/core, ${jbpm.home}/ejb and ${jbpm.home}/web

Support

Our preferred support mechanism is through the forums, *NOT* the mailing lists ! For more about support see the support page.