jBPM Installation

Chapter 2. Installation

2.1. The distribution

2.2. Required software

2.3. Getting started quickly

2.4. Install scripts

2.5. Library dependencies and configuration files

2.6. JBoss

2.7. Tomcat

2.8. Signavio web based process editor

2.9. User webapp

2.10. Database

2.10.1. Creating or dropping the database schema

2.10.2. Upgrading an existing database

2.11. Graphical Process Designer (GPD)

2.11.1. Get Eclipse

2.11.2. Install the GPD plugin into eclipse

2.11.3. Configuring the jBPM runtime

2.11.4. Define the jBPM User Library

2.11.5. Adding jPDL 4 schema to the catalog

2.11.6. Importing the Examples

2.11.7. Adding deployment with ant

2.1. The distribution

Unzip the jBPM download (jbpm-4.X.zip) to some location on your hard drive. You'll see following subdirectories:

• doc: User guide, javadocs and developers guide
• examples: Example processes that are used in the user guide
• install: Installation scripts for several environments
• lib: Third party libs and some special jBPM libraries
• src: Source files
• migration: see developers guide
• jbpm.jar: The jBPM main library archive

2.2. Required software

jBPM requires a JDK (standard java) version 5 or higher.
http://java.sun.com/javase/downloads/index.jspTo execute the ant scripts, you'll need apache ant version 1.7.0 or higher:
http://ant.apache.org/bindownload.cgi

2.3. Getting started quickly

The demo setup is the simplest way to get started. This section describes the steps to complete the demo setup.
If you have previously downloaded jboss-5.0.0.GA.zip, you can drop it in the ${jbpm.home}/install/downloads directory. Otherwise the script will download it for you, but it will take some time (depending on your connection). The same is holds for eclipse-jee-galileo-win32.zip (or eclipse-jee-galileo-linux-gtk(-x86_64).tar.gz on Linux and eclipse-jee-galileo-macosx-carbon.tar.gz on Mac OSX)
Open a command prompt and go do directory ${jbpm.home}/install. Then run

ant demo.setup.jboss

or

ant demo.setup.tomcat

That will

• Install JBoss into the ${jbpm.home}/jboss-5.0.0.GA directory
• Install jBPM into that JBoss installation.
• Install hsqldb and start it in the background
• Create the DB Schema
• Start JBoss in the background.
• Create an examples.bar business archive from the examples and deploy it to the jBPM DB.
• Load the example users and groups from ${jbpm.home}/install/src/demo/example.identities.sql
• Install eclipse into ${jbpm.home}/eclipse
• Install the jBPM web console
• Install the Signavio web modeler
• Start eclipse

After this is done, JBoss (or Tomcat, depending on which demo.setup script you chose) will be running in the background. Once eclipse has started, you can continue to follow the instructions of Section 2.11, “Graphical Process Designer (GPD)” to start coding your jBPM business processes.
Or you can start modeling processes through the Signavio web editor.
Or surf to the jBPM console. You can login as one of the following users:

Table 2.1. Example console users:

Username	Password
alex	password
mike	password
peter	password
mary	password

Known console limitation: Currently, the timeout of the console is too tight for the reporting to initialize on slower machines. So the first time when you access the reporting the request will timeout and the console crashes. Logging out and login again works around this problem. It's being addressed as issue JBPM-2508

2.4. Install scripts

The jBPM download contains an install directory with an ant build.xml file in it. You can use that to install jBPM into your application environment.
It's best to stick to the installations and jBPM configuration files as done with these installation scripts. Customizing jBPM configuration files directly, is possible, but not supported.
To invoke the install script, open a command line and go to the ${jbpm.home}/install directory. With ant -p you can find out what each of these scripts can do. The scripts are parametrized with default values to get going quickly. The following list gives an overview of the available scripts:

• demo.setup.jboss: installs jboss, installs jbpm into jboss, starts jboss, creates the jBPM DB schema, deploys examples, loads example identities, installs and starts eclipse
• demo.setup.tomcat: installs tomcat, installs jbpm into tomcat, starts tomcat, creates the jBPM DB schema, deploys examples, loads example identities, installs and starts eclipse
• clean.cfg.dir: Deletes the ${jbpm.home}/install/generated/cfg folder.
• create.cfg: Creates a configuration in ${jbpm.home}/install/generated/cfg based on the current parameters.
• create.jbpm.schema: creates the jbpm tables in the database
• create.user.webapp: Generates a basic webapp in ${jbpm.home}/install/generated/user-webapp
• delete.jboss: Deletes the JBoss installation
• delete.tomcat: Deletes the Tomcat installation
• demo.teardown.jboss: Drops the jbpm db schema and stops jboss
• demo.teardown.tomcat: Stops tomcat and then the hsqldb server (if needed)
• drop.jbpm.schema: Drops the jbpm tables from the database
• get.eclipse: Downloads eclipse if it is not available
• get.jboss: Downloads a JBoss AS which was tested against the current jBPM version if it is not available
• get.tomcat: Downloads tomcat which was tested against the current jBPM version if it is not available
• hsqldb.databasemanager: Starts the hsqldb database manager
• install.eclipse: Unzips eclipse, downloads eclipse if it is not available
• install.jboss: Downloads JBoss if its not available and then unzips it
• install.jbpm.into.jboss: Installs jBPM into JBoss
• install.tomcat: Downloads tomcat to ${tomcat.distro.dir} if its not available and then unzips tomcat
• install.jbpm.into.tomcat: Installs jBPM into tomcat
• install.examples.into.tomcat: Deploys all the example processes
• install.signavio.into.jboss: Installs signavio into jboss
• install.signavio.into.tomcat: Installs signavio into tomcat
• load.example.identities: Loads the example users and groups into the database
• reinstall.jboss: Deletes the previous jboss installation and re-installs jboss
• reinstall.jboss.and.jbpm: Deletes the previous jboss installation and re-installs jboss and installs jbpm in it
• reinstall.tomcat: Deletes the previous tomcat installation and re-installs tomcat
• reinstall.tomcat.and.jbpm: Deletes the previous tomcat installation and re-installs tomcat and installs jbpm in it
• start.eclipse: Starts eclipse
• start.jboss: Starts jboss and waits till jboss is booted, then lets jboss run in the background
• start.tomcat: Starts Tomcat and waits till it is booted, then lets Tomcat run in the background
• stop.jboss: signals jboss to stop, but doesn't wait till its finished
• stop.tomcat: Signals Tomcat to stop, but doesn't wait till its finished
• upgrade.jbpm.schema: Upgrades the jBPM tables in the database to the current version

To specify your jdbc properties that are used in the scripts above (eg.DB schema generation), the easiest is to update the appropriate properties file in directory ${jbpm.home}/install/jdbc. The appropriate properties file will be loaded by the scripts that are DB related.
Also following properties are customizeable

• database : Default value is hsqldb. Alternative values are mysql, oracle and postgresql
• jboss.version : Default value is 5.0.0.GA. Alternative value is 5.1.0.GA

To customize the values for these properties, just use -D like this

ant -Ddatabase=postgresql demo.setup.jboss

Alternatively you can specify the customized values in ${user.home}/.jbpm4/build.properties

2.5. Library dependencies and configuration files

We provide support for installations of jBPM through our automatic ant scripts. Those scripts will put the right libs and the right configuration files in the right location for you. If you want to create your own installation of jBPM in your application, see the developers guide for more information.

2.6. JBoss

The target install.jbpm.into.jboss will install jBPM into your JBoss 5 installation. Navigate to the install directory and run ant -p for more details. This install script will install jBPM as a JBoss-wide service so that all applications can use the same jBPM ProcessEngine.
Specify property -Djboss.home=PathToYourJBossInstallation to customize the path to your JBoss installation.
In JBoss, the ProcessEngine can be obtained from JNDI with new InitialContext().lookup("java:/ProcessEngine"). The same ProcessEngine can be obtained with Configuration.getProcessEngine()

2.7. Tomcat

The target install.jbpm.into.tomcat will install jBPM into your JBoss 5 installation.

2.8. Signavio web based process editor

The targets install.signavio.into.jboss and install.signavio.into.tomcat will install the Signavio web based process editor into JBoss or Tomcat respectively.

2.9. User webapp

If you want to deploy jBPM as a part of your web application, use the install target create.user.webapp. That will create a web application with jBPM in it, in the location ${jbpm.home}/install/generated/user-webapp.
In case you deploy your app on JBoss or another appserver that has the jta.jar classes, then you need to delete the ${jbpm.home}/install/generated/user-webapp/WEB-INF/lib/jta.jar

2.10. Database

The install script is also capable of performing database operations such as creating the schema, if you are installing jBPM for the first time, or upgrading the database used with a previous version to the current schema. Dropping the schema is an option as well.
The prerrequisite for any database operation is to specify your database connection parameters in ${jbpm.home}/install/jdbc.

2.10.1. Creating or dropping the database schema

To create the schema, run target create.jbpm.schema in the ${jbpm.home}/install directory. Apart from creating tables and constraints, the mentioned target will initialize table JBPM4_PROPERTY with the current engine version (key db.version) and the ID generator base value (key next.dbid).
To drop the schema, simply run target drop.jbpm.schema. Be aware that this operation will destroy any data present in the jBPM tables.

2.10.2. Upgrading an existing database

To upgrade, run target upgrade.jbpm.schema in the ${jbpm.home}/install directory.
Upgrading is a two-fold operation. The foremost step is to add any extra tables, columns or constraints that were introduced in newer versions. Afterwards, seed data is inserted.
Between 4.0 and 4.1, table JBPM4_VARIABLE got a new column CLASSNAME_ used to support setting process variables to values of custom types mapped with Hibernate. This column is nullable and left uninitialized since the feature was not operational in 4.0.
From 4.1 to 4.2 the upgrade procedure got more interesting.

• A new table JBPM4_PROPERTY was introduced for storing engine-wide values.
• The jBPM version is saved in table JBPM4_PROPERTY under key db.version to allow for precise identification in future releases.
• The ID generation strategy is consistent across databases. The next available ID is calculated by querying all tables having an identifier column, and stored under key next.dbid in the JBPM4_PROPERTY table.
• The process language is set to jpdl-4.0 for all existing process definitions under key langid in table JBPM4_DEPLOYPROP. The jPDL parser employs the langid property to read process documents in a backwards-compatible manner.

2.11. Graphical Process Designer (GPD)

Eclipse is used as the platform to host the jPDL graphical process designer. This section will describe how to obtain and install Eclipse and how to install the GPD plugin in Eclipse.

2.11.1. Get Eclipse

You'll need Eclipse 3.5.0.
Use the demo setup or download eclipse manually: Eclipse IDE for Java EE Developers (163 MB).
The classic version of eclipse will not be sufficient as it does not have an XML editor. Eclipse for Java developers should also work.

2.11.2. Install the GPD plugin into eclipse

The installation of the GPD uses the Eclipse Software Update mechanism and is pretty straightforward. There is an archived update site included in the runtime installation of jBPM when you unzip it at install/src/gpd/jbpm-gpd-site.zip

To add the update site to eclipse:

• Help --> Install New Software...
• Click Add...
• In dialog Add Site dialog, click Archive...
• Navigate to install/src/gpd/jbpm-gpd-site.zip and click 'Open'
• Clicking OK in the Add Site dialog will bring you back to the dialog 'Install'
• Select the jPDL 4 GPD Update Site that has appeared
• Click Next... and then Finish
• Approve the license
• Restart eclipse when that is asked

Figure 2.1. Adding the GPD local archive site

2.11.3. Configuring the jBPM runtime

• Click Window --> Preferences
• Select JBoss jBPM --> jBPM 4 --> Runtime Locations
• Click Add...
• In the Add Location dialog, enter a name like e.g. jbpm-4.0 and then click Search...
• In the Browse For Folder dialog, select your jbpm home directory and click OK
• Click OK in the Add Location dialog

Figure 2.2. Defining jBPM Libraries

2.11.4. Define the jBPM User Library

This section shows how to define a user library for your workspace that is a placeholder for the jBPM library as well as its dependencies. If you create a new Java project, it will be sufficient to add this user library to the build path.

• Click Window --> Preferences
• Select Java --> Build Path --> User Libraries
• Click New...
• Type name jBPM Libraries
• Click Add JARs...
• Navigate to the 'lib' folder of your jBPM installation
• Select all jar files and click Open
• Select the jBPM Libraries entry
• Click Add JARs... again
• Select the jbpm.jar file in the root of your jBPM installation
• Click Open
• Select entry Source attachment under jbpm.jar
• Click Edit
• In dialog Source Attachment Configuration, click External Folder...
• Navigate to the src folder in your jBPM installation
• Click Choose
• Click OK twice to close all the open dialogs

Figure 2.3. Defining jBPM Libraries

2.11.5. Adding jPDL 4 schema to the catalog

In case you want to edit the process XML sources directly, it is best to specify your schema in the XML catalog. This will give you better code completion while editing the process sources.

• Click Window --> Preferences
• Select XML --> XML Catalog
• Click 'Add...'
• The 'Add XML Catalog Entry' dialog opens
• Click the button with the map-icon next to location and select 'File System...'
• In the dialog that opens, select file jpdl-4.0.xsd in the src directory of the jBPM installation root.
• Click 'Open' and close all the dialogs

Figure 2.4. Adding jPDL 4 schema to the Catalog

2.11.6. Importing the Examples

In this section we will import the examples project in the installation in Eclipse

• Select File --> Import...
• Select General --> Existing Projects into Workspace
• Click Next
• Click Browse... to select a root directory
• Navigate to the jBPM root installation directory
• Click OK
• The examples project is automatically found and selected
• Click Finish

After setting the jBPM User Libraries and importing the examples, all the examples can be run as JUnit tests. Right click on a test and select 'Run As' --> 'JUnit Test'.
You're all set to start playing with the coolest Java process technology!

2.11.7. Adding deployment with ant

You can leverage the eclipse ant integration to ease deployment of processes. We'll show you how it works with the examples. Then you can copy this practice in your own project. First, open up the Ant view.

• Select Window --> Show View --> Other... --> Ant --> Ant
• Then drag the build file build.xml in the examples project from the package explorer to the Ant view

For more information follow my Tutorial  online @ http://jbpmmaster.blogspot.com/