JBoss.orgCommunity Documentation
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:
Java: http://java.sun.com/javase/downloads/index.jsp
Ant: http://ant.apache.org/bindownload.cgi
To check whether Java and Ant are installed correctly, type the following commands inside a command prompt:
java -version
ant -version
This should return information about which version of Java and Ant you are currently using.
First of all, you need to download the installer and unzip it to your local file system. There are two versions
full installer - which already contains a lot of the dependencies that are necessary during the installation
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. The demo install will setup all the web tooling (on top of WildFly) and Eclipse tooling in a pre-configured setup. Go into the jbpm-installer folder where you unzipped the installer and (from a command prompt) run:
ant install.demo
This will:
Download WildFly application server
Configure and deploy the web tooling
Download Eclipse
Install the Drools and jBPM Eclipse plugin
Install the Eclipse BPMN 2.0 Modeler
Running this command could take a while (REALLY, not kidding, we are for example downloading an Eclipse installation, even if you downloaded the full installer, specifically for your operating system).
The script 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:
Start H2 database server
Start WildFly application server
Start Eclipse
Now wait until the process management console comes up:
http://localhost:8080/jbpm-console
It could take a minute to start up the application server and web application. If the web page doesn't show up after a while, make sure you don't have a firewall blocking that port, or another application already using the port 8080. You can always take a look at the server log jbpm-installer/wildfly-8.1.0.Final/standalone/log/server.log
Finally, if you also want to use the DashBuilder for reporting (which is implemented as a separate war), you can now also install this:
ant install.dashboard.into.jboss
Once everything is started, you can start playing with the Eclipse and web tooling, as explained in the following sections.
If you only want to try out the web tooling and do not wish to download and install the Eclipse tooling, you can use these alternative commands:
ant install.demo.noeclipse
ant start.demo.noeclipse
Similarly, if you only want to try out the Eclipse tooling and do not wish to download and install the web tooling, you can use these alternative commands:
ant install.demo.eclipse
ant start.demo.eclipse
Now continue with the 10-minute tutorials. Once you're done playing and you want to shut down the demo setup, you can use:
ant stop.demo
If at any point in time would like to start over with a clean demo setup - meaning all changes you did inside the web tooling and/or saved in the database will be lost, you can run the following command (after which you can run the installer again from scratch, note that this cannot be undone):
ant clean.demo
Open up the process management console:
http://localhost:8080/jbpm-console
It could take a minute to start up the AS and web application. If the web page doesn't show up after a while, make sure you don't have a firewall blocking that port, or another application already using the port 8080. You can always take a look at the server log jbpm-installer/jboss-as-7.1.1.Final/standalone/log/server.log
Log in, using krisv / krisv as username / password.
Using a prebuilt Evaluation example, the following screencast gives an overview of how to manage your process instances. It shows you:
Figure 3.1.
The workbench supports the entire life cycle of your business processes: authoring, deployment, process management, tasks and dashboards.
The following screencast gives an overview of how to use the Eclipse tooling. It shows you:
Figure 3.2.
You can import the evaluation project - a sample included in the jbpm-installer - by selecting "File -> Import ...", select "Existing Projects into Workspace" and browse to the jbpm-installer/sample/evaluation folder and click "Finish". You can open up the evaluation process and the ProcessTest class. To execute the class, right-click on it and select "Run as ... - Java Application". The console should show how the process was started and how the different actors in the process completed the tasks assigned to them, to complete the process instance.
You could also create a new project using the jBPM project wizard. The sample projects contain a process and an associated Java file to start the process. Select "File - New ... - Project ..." and under the "jBPM" category, select "jBPM project" and click "Next". Give the project a name and click "Next". You can choose from a simple HelloWorld example or a slightly more advanced example using persistence and human tasks. If you select the latter and click Finish, you should see a new project containing a "sample.bpmn" process 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 ProcessTest.java and select "Run As - Java Application".
The workbench by default brings two sample playground repositories (by cloning the jbpm-playground repository hosted on GitHub). In cases where this is not wanted (access to Internet might not be available or there might be a need to start with a completely clean installation of the workbench) this default behavior can be turned off. To do so, change the following system property in the start.jboss target to false in the build.xml:
-Dorg.kie.demo=false
Note that this will create a completely empty version of the workbench. To be able to start modeling processes, the following elements need to be created first:
The workbench web application is using the "default" security domain for authenticating and authorizing users (as specified in the WEB-INF/jboss-web.xml inside the WARs).
The application server is configured by default to use properties files for specifying users. Note that this is for demo purposes only (as passwords and roles are stored in simple property files). The security domain is configured in the standalone.xml configuration file as follows:
<security-domain name="other" cache-type="default">
<authentication>
<login-module code="UsersRoles" flag="required">
<module-option name="usersProperties" value="${jboss.server.config.dir}/users.properties"/>
<module-option name="rolesProperties" value="${jboss.server.config.dir}/roles.properties"/>
</login-module>
</authentication>
</security-domain>
By default, these configuration files contain the following users:
Table 3.1. Default users
Name | Password | Workbench roles | Task roles |
---|---|---|---|
admin | admin | admin,analyst | |
krisv | krisv | admin,analyst | |
john | john | analyst | Accounting,PM |
mary | mary | analyst | HR |
sales-rep | sales-rep | analyst | sales |
jack | jack | analyst | IT |
katy | katy | analyst | HR |
salaboy | salaboy | admin,analyst | IT,HR,Accounting |
Authentication can be customized by editing the authentication and configuration files in the jbpm-installer/auth folder and/or by changing the standalone-*.xml files in the jbpm-installer folder. Note that you need to rerun the installer to make sure the modified files are copied and picked correctly.
By default, the jbpm-installer uses an H2 database for persisting runtime data. In this section we will:
modify the persistence settings for runtime persistence of process instance state
test the startup with our new settings!
You will need a local instance of a database, in this case we will use MySQL.
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 used in this quickstart, create a single user:
If you end up using different names for your user/schemas, please make a note of where we insert "jbpm" in the configuration files.
If you want to try this quickstart with another database, a section at the end of this quickstart describes what you may need to modify.
The following files define the persistence settings for the jbpm-installer demo:
There are multiple standalone.xml files available (depending on whether you are using JBoss AS 7.1.1 or JBoss EAP 6.1.1 and whether you are running the normal or full profile). The full profile is required to use the JMS component for remote integration. Best practice is to update all standalone.xml files to have consistent setup but most important is to have standalone-full-as-7.1.1.Final.xml properly configured as this is used by default by the installer.
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.
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.xml
:
This file is the configuration for the standalone JBoss application server. When the
installer installs the demo, it copies these files to the standalone/configuration
directory in the JBoss server directory.
We need to change the 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>
Starting the demo
We've modified all the necessary files at this point. Now would be a good time to make sure your database is started up as well!
The installer script copies this file into the jbpm-console WAR before the WAR is installed on the server. If you have already run the installer, it is recommended to stop the installer and clean it first using
ant stop.demo
and
ant clean.demo
before continuing.
Run
ant install.demo
to (re)install the wars and copy the necessary configuration files. Once you've done that, (re)start the demo using
ant start.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
#postgresql
db.name=postgresql
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 the demo setup makes use of Hibernate auto DDL generation capabilities to build up the complete database schema, including all tables, sequences, etc. This might not always be welcomed (by your database administrator), and thus the installer provides DDL scripts for most popular databases.
Table 3.2. DDL scripts
Database 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 the timer service should be configured with Quartz database job store. See the section on timers for additional details.
This can be used to initially create the database schema, but it can also serve as the basis 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.3. jBPM installer available targets
Target | Description |
---|---|
clean.db | cleans up database used by jBPM demo (applies only to H2 database) |
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 |
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).
For all other questions, try contacting the jBPM community as described in the Getting Started chapter.