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, a full installer (which already contains a lot of the dependencies that are necessary during the installation) and a minimal installer (which only contains the installer and will download all dependencies). 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. Go into the install folder and run:
ant install.demo
This will:
- Download JBoss AS
- Download Eclipse
- Install the jBPM web tooling into JBoss AS
- Install the jBPM and Drools Eclipse plugin
- Install the BPMN2 Eclipse Modeler
This could take a while (REALLY, not kidding, we are downloading an application server, an
Eclipse installation, etc. Even if you already downloaded the full installer you still need to
download the right eclipse version for your operating system). 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 a download didn't succeed (for example due to a connection issue), delete the file
in question from the jbpm-installer/lib folder and run the script again).
Once the demo setup has finished, you can start playing with the various components by starting the demo setup:
ant start.demo
This will:
- Start the H2 database
- Start the JBoss AS
- Start Eclipse
After successfully installing and starting these components, you can optionally also download and install the dashboard web application, which can be used to monitor your process instances. To do so, run:
ant install.dashboard.into.jboss
Once everything is started, you can start playing with the jBPM Eclipse and web tooling, as explained in the next three sections.
If you only want to try out the Eclipse tooling in the demo setup (and not the web tooling), you can use the alternative commands:
ant install.demo.eclipse ant start.demo.eclipse
If you only want to try out the web tooling in the demo setup (and not the Eclipse tooling), you can use the alternative commands:
ant install.demo.noeclipse ant start.demo.noeclipse
The following screencast gives an overview of how to run a simple demo process in Eclipse. It shows you:
- How to import a sample "performance evaluation" project into your workspace, containing
- a sample BPMN2 process for requesting a performance evaluation
- a sample JUnit test class to start the process
- How to start the process
Figure 2.1.
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:
- How to start a new process
- How to look up the current status of a running process instance
- How to look up your tasks
- How to complete a task
- How to generate reports to monitor your process execution
Figure 2.2.
You can always contact the jBPM community for assistance.
IRC: #jbpm at chat.freenode.net
Email: jbpm-dev@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 temporarly 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, Guvnor and the Designer. 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.