JBoss.orgCommunity Documentation
This guide will assist you in installing and running a demo setup of the various components of the jBPM project. If you have any feedback on how to improve this guide, if you encounter problems, or if you want to help out, do not hesitate to contact the jBPM community as described in the "What to do if I encounter problems or have questions?" section.
This script assumes you have Java JDK 1.6+ (set as JAVA_HOME), and Ant 1.7+ installed. If you don't, use the following links to download and install them:
First of all, you need to download the installer. There are two versions
In general, it is probably best to download the full installer: jBPM-{version}-installer-full.zip
You can also find the latest snapshot release here (only minimal installer) here:
https://hudson.jboss.org/jenkins/job/jBPM/lastSuccessfulBuild/artifact/jbpm-distribution/target/
The easiest way to get started is to simply run the installation script to install the demo setup. Simply go into the install folder and run:
ant install.demo
This will:
This could take a while (REALLY, not kidding, we are downloading an application server and Eclipse installation, even if you downloaded the full installer). The script however always shows which file it is downloading (you could for example check whether it is still downloading by checking the whether the size of the file in question in the jbpm-installer/lib folder is still increasing). If you want to avoid downloading specific components (because you will not be using them or you already have them installed somewhere else), check below for running only specific parts of the demo or directing the installer to an already installed component.
Once the demo setup has finished, you can start playing with the various components by starting the demo setup:
ant start.demo
This will:
Once everything is started, you can start playing with the Eclipse tooling, jBPM console, as explained in the next three sections.
If you do not wish to use Eclipse in the demo setup, you can use the alternative commands:
ant install.demo.noeclipse ant start.demo.noeclipse
jbpm console started by installer will by default bring in sample processes from jbpm demo repository that is cloned from origin hosted on github. In some cases where access to Internet is not available or there is a need to start completely clean installation of jbpm console the default behavior can be turned off. To do so following system property needs to be added to startup script (build.xml -> start.jboss target) or to standalone.xml:
-Dorg.kie.demo=false
with this there will not be any organizational unit nor repository created. To be able to start modeling processes user needs to create:
Open up the process management console:
http://localhost:8080/jbpm-console
Log in, using krisv / krisv as username / password. The following screencast gives an overview of how to manage your process instances. It shows you:
Figure 3.1.
The following screencast gives an overview of how to integrate Web Console and Eclipse. It shows you:
Figure 3.2.
You could also create a new project using the jBPM project wizard. This sample project contains a simple HelloWorld BPMN2 process and an associated Java file to start the process. Simply select "File - New - jBPM Project" (if you cannot see that (because you're not in the jBPM perspective) you can do "File - New ... - Project ..." and under the "jBPM" category, select "jBPM project" and click "Next"). Give the project a name and click "Finish". You should see a new project containing a "sample.bpmn" process and a "com.sample.ProcessMain" Java class and a "com.sample.ProcessTest" JUnit test class. You can open the BPMN2 process by double-clicking it. To execute the process, right-click on ProcessMain.java and select "Run As - Java Application". You should see a "Hello World" statement in the output console. To execute the test, right-click on ProcessTest.java and select "Run As - JUnit Test". You should also see a "Hello World" statement in the output console, and the JUnit test completion in the JUnit view.
In this quickstart, we are going to:
modify the persistence settings for the process engine
test the startup with our new settings!
You will need a local instance of a database, in this case MySQL in order to complete this quickstart
First though, let's look at the persistence setup that jBPM uses. In the demo, and in general, there are following types of persistent entities used by jBPM:
“persistent entities” in this context, are java classes that represent information in the database.
In the MySQL database that I use in this quickstart, I've created single user:
If you end up using different names for your user/schemas, please make a note of where we insert "jbpm" in the configuation files.
If you want to try this quickstart with another database, I've included a section at the end of this quickstart that describes what you may need to modify.
The following files define the persistence settings for the jbpm-installer demo:
There are two standalone.xml files available as jbpm allows to use JMS component for integration and thus requires standalone-full.xml to be configured. Best practice is to update both to have consistent setup but most important is to have standalone-full-as-7.1.1.Final.xml properly configured.
Do the following:
# default is H2 # H2.version=1.3.168 # db.name=h2 # db.driver.jar.name=${db.name}.jar # db.driver.download.url=http://repo1.maven.org/maven2/com/h2database/h2/${H2.version}/h2-${H2.version}.jar #mysql db.name=mysql db.driver.module.prefix=com/mysql db.driver.jar.name=${db.name}-connector-java.jar db.driver.download.url=https://repository.jboss.org/nexus/service/local/repositories/central/content/mysql/mysql-connector-java/5.1.18/mysql-connector-java-5.1.18.jar
db/jbpm-persistence-JPA2.xml
:
This is the JPA persistence file that defines the persistence settings used by jBPM for both the process engine information, the logging/BAM information and task service. The installer ant script moves this file to the expanded web console war before the war is installed on the server. So if you have already tried with default settings (H2) best would be to clean and install it again
ant clean.demo
this time it will be much faster as it does not have to download anything.
In this file, you will have to change the name of the hibernate dialect used for your database.
The original line is:
<property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>
In the case of a MySql database, you need to change it to:
<property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/>
For those of you who decided to use another database, a list of the available hibernate dialect classes can be found here.
standalone-as-7.1.1.Final.xml and standalone-full-as-7.1.1.Final.xml
:
This file is the configuration for the standalone JBoss AS 7 server. When the
installer installs the demo, it moves these files to the standalone/configuration
directory in the jboss server directory
We need to change datasource configuration in standalone.xml
so that the jBPM process engine can use our MySQL database
The original file contains the following lines:
<datasource jndi-name="java:jboss/datasources/jbpmDS" enabled="true" use-java-context="true" pool-name="H2DS"> <connection-url>jdbc:h2:tcp://localhost/runtime/jbpm-demo</connection-url> <driver>h2</driver> <pool></pool> <security> <user-name>sa</user-name> <password></password> </security> </datasource> <drivers> <driver name="h2" module="com.h2database.h2"> <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class> </driver> </drivers>
Change the lines to the following:
<datasource jndi-name="java:jboss/datasources/jbpmDS" pool-name="MySQLDS" enabled="true" use-java-context="true"> <connection-url>jdbc:mysql://localhost:3306/jbpm</connection-url> <driver>mysql</driver> <pool></pool> <security> <user-name>jbpm</user-name> <password>jbpm</password> </security> </datasource> <drivers> <driver name="mysql" module="com.mysql"> <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class> </driver> </drivers>
Start the demo
We've modified all the necessary files at this point. Of course, this would be a good time to start your database up as well!
If you haven't installed the demo yet, do that first: If you have already installed and run the demo, it can't hurt to reinstall the demo:
ant clean.demo; ant install.demo
alternatively
ant install.demo.noeclipse
After you've done that, you can finally start the demo using the following command:
ant start.demo
alternatively
ant start.demo.noeclipse
If you're done with the demo, you can stop it using this command:
ant clean.demo; ant stop.demo
Problems?
If this isn't working for you, please try the following:
If you decide to use a different database with this demo, you need to remember the following when going through the steps above:
standalone/deployments
directory.
# default is H2 # H2.version=1.3.168 # db.name=h2 # db.driver.jar.name=${db.name}.jar # db.driver.download.url=http://repo1.maven.org/maven2/com/h2database/h2/${H2.version}/h2-${H2.version}.jar
#postresql db.name=postresql db.driver.module.prefix=org/postgresql db.driver.jar.name=${db.name}-jdbc.jar db.driver.download.url=https://repository.jboss.org/nexus/content/repositories/thirdparty-uploads/postgresql/postgresql/9.1-902.jdbc4/postgresql-9.1-902.jdbc4.jar
db.name
property in build.properties
to the name of the downloaded jdbc driver jar you placed in db/drivers
.
<driver>
information in
the <datasource>
section of standalone.xml
so
that it refers to the name of your driver module (see next step). For example:
<driver>postgresql</driver>
standalone.xml
is the
<drivers>
section of the
<datasources>
(note the plural: drivers,
datasources). We need to do the following with this file:
<drivers> <driver name="postgresql" module="org.postgresql"> <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class> </driver> </drivers>
db.driver.module.prefix
property
in build.properties
to the same “value” you used for the module name
in standalone.xml
. In the example above, I used
“org.postgresql
” which means that I should then use
org/postgresql
for the db.driver.module.prefix
property.
db/${db.name}_module.xml
file. As an example you can use db/mysql_module.xml, so just make a copy of it and:
db.driver.module.prefix
property above<module xmlns="urn:jboss:module:1.0" name="com.mysql"> <resources> <resource-root path="mysql-connector-java.jar"/> </resources>Change those lines to look like this, for example:
<module xmlns="urn:jboss:module:1.0" name="org.postgresql"> <resources> <resource-root path="postgresql-9.1-902.jdbc4.jar"/> </resources>
By default demo setup makes use of Hibernate auto ddl generation capabilities to build up complete data base schema including all tables, sequences, etc for given data base. This is not always welcome and thus installer provides DDL scripts for most popular data base
Table 3.1. DDL scripts
Data base name | Location |
---|---|
db2 | jbpm-installer/db/ddl-scripts/db2 |
derby | jbpm-installer/db/ddl-scripts/derby |
h2 | jbpm-installer/db/ddl-scripts/h2 |
hsqldb | jbpm-installer/db/ddl-scripts/hsqldb |
mysql5 | jbpm-installer/db/ddl-scripts/mysql5 |
mysqlinnodb | jbpm-installer/db/ddl-scripts/mysqlinnodb |
oracle | jbpm-installer/db/ddl-scripts/oracle |
postgresql | jbpm-installer/db/ddl-scripts/postgresql |
sqlserver | jbpm-installer/db/ddl-scripts/sqlserver |
sqlserver2008 | jbpm-installer/db/ddl-scripts/sqlserver2008 |
DDL scripts are provided for both jBPM and Quartz schemas although Quartz schema DDL script is only required when timer service should be configured with Quartz data base job store. See Timer Service section for additional details.
This can be used to initially create data base schema but it can serve as base for any optimization that needs to be applied - such as indexes, etc.
jBPM installer ant script performs most of the work automatically and usually does not require additional attention but in case it does, here is a list of available targets that might be needed to perform some of the steps manually.
Table 3.2. jBPM installer available targets
Target | Description |
---|---|
clean.db | cleans up data base used by jBPM demo (applies only to H2 data base) |
clean.demo | cleans up entire installation so new installation can be performed |
clean.demo.noeclipse | same as clean.demo but does not remove eclipse |
clean.eclipse | removes eclipse and its workspace |
clean.generated.ddl | removes DDL scripts generated if any |
clean.jboss | removes application server with all its deployments |
clean.jboss.repository | removes repository content for demo setup (guvnor maven repo, niogit, etc) |
download.dashboard | downloads jBPM dashboard component (BAM) |
download.db.driver | downloads db driver configured in build.properties |
download.ddl.dependencies | downloads all dependencies required to run DDL script generation tool |
download.droolsjbpm.eclipse | downloads drools and jbpm eclipse plugin |
download.eclipse | downloads eclipse distribution |
download.jboss | downloads Jboss Application Server |
download.jBPM.bin | downloads jBPM binary distribution (jBPM libs and its dependencies) |
download.jBPM.console | downloads jBPM console for JBoss AS |
install.dashboard.into.jboss | installs jBPM dashboard into JBoss AS |
install.db.files | installs db driver as JBoss module |
install.demo | installs complete demo environment |
install.demo.eclipse | installs Eclipse with all jBPM plugins, no server installation |
install.demo.noeclipse | similar to install.demo but skips eclipse installation |
install.dependencies | installs custom libraries (such as work item handlers, etc) into the jbpm console |
install.droolsjbpm-eclipse.into.eclipse | installs droolsjbpm eclipse plugin into eclipse |
install.eclipse | install eclipse IDE |
install.jboss | installs JBoss AS |
install.jBPM-console.into.jboss | installs jBPM console application into JBoss AS |
You can always contact the jBPM community for assistance.
IRC: #jbpm at chat.freenode.net
Email: jbpm-user@lists.jboss.org
Some common issues are explained below.
Q: What if the installer complains it cannot download component X?
A: Are you connected to the internet? Do you have a firewall turned on? Do you require a proxy? It might be possible that one of the locations we're downloading the components from is temporarily offline. Try downloading the components manually (possibly from alternate locations) and put them in the jbpm-installer/lib folder.
Q: What if the installer complains it cannot extract / unzip a certain jar/war/zip?
A: If your download failed while downloading a component, it is possible that the installer is trying to use an incomplete file. Try deleting the component in question from the jbpm-installer/lib folder and reinstall, so it will be downloaded again.
Q: What if I have been changing my installation (and it no longer works) and I want to start over again with a clean installation?
A: You can use ant clean.demo to remove all the installed components, so you end up with a fresh installation again.
Q: I sometimes see exceptions when trying to stop or restart certain services, what should I do?
A: If you see errors during shutdown, are you sure the services were still running? If you see exceptions during restart, are you sure the service you started earlier was successfully shutdown? Maybe try killing the services manually if necessary.
Q: Something seems to be going wrong when running Eclipse but I have no idea what. What can I do?
A: Always check the consoles for output like error messages or stack traces. You can also check the Eclipse Error Log for exceptions. Try adding an audit logger to your session to figure out what's happening at runtime, or try debugging your application.
Q: Something seems to be going wrong when running the a web-based application like the jbpm-console. What can I do?
A: You can check the server log for possible exceptions: jbpm-installer/jboss-as-{version}/standalone/log/server.log (for JBoss AS7) or jbpm-installer/jboss-as-{version}/server/default/log/server.log (for earlier versions).
For all other questions, try contacting the jBPM community as described in the Getting Started chapter.