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
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:
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:
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:
How to generate reports to monitor your process execution
The workbench supports the entire life cycle of your business processes: authoring, deployment, process management, tasks and dashboards.
The project authoring perspective allows you to look at existing repositories, where each project can contain business processes (but also business rules, data models, forms, etc.). By default, the workbench will download two sample playground repositories, containing examples to look at.
The project explorer shows all available artifacts:
To manage your process definitions and instances, click on the "Process Management" menu option at the top menu bar an select one of available options depending on you interest:
Process definitions panel allow you to start a new process instance by clicking on the "Play" button. The process form (as defined in the project) will be shown, where you need to fill in the necessary information to start the process. In this case, you need to fill the user you want to start an evaluation for (in this case use "krisv") and a reason for the request, after which you can complete the form. Some details about the process instance that was just started will be shown in the process instance details panel. From there you can access additional details:
The process instance that you just started is first requiring a self-evaluation of the user and is waiting until the user has completed this task.
The following screencast gives an overview of how to use the Eclipse tooling. It shows you:
How to import and execute the evaluation sample project
How to create a new jBPM project (including sample process and JUnit test)
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.
jBPM uses the Java Persistence API specification (v2) to allow users to configure whatever datasource they want to use to persist runtime data. As a result, the instructions below describe how you should configure a datasource when using JPA on JBoss application server (e.g. AS7, EAP6 or Wildfly8) using a persistence.xml file and configuring your datasource and driver in your application server’s standalone.xml , similar to how you would configure any other application using JPA on JBoss application server. The installer automates some of this (like copying the right files to the right location after installation).
By default, the jbpm-installer uses an H2 database for persisting runtime data. In this section we will:
You will need a local instance of a database, in this case we will use MySQL.
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:
Application server configuration
There are multiple standalone.xml files available (depending on whether you are using JBoss AS7, JBoss EAP6 or Wildfly8 and whether you are running the normal or full profile). The full profile is required to use the JMS component for remote integration, so will be used by default by the installer. Best practice is to update all standalone.xml files to have consistent setup but most important is to have standalone-full-wildfly-8.1.0.Final.xml properly configured as this is used by default by the installer.
Do the following:
Disable H2 default database and enable MySQL database in build.properties
# 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=mysql-connector-java-5.1.18.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
You might want to update the db driver jar name and download url to whatever version of the jar matches your installation.
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-full-wildfly-8.1.0.Final.xml :
Standalone.xml
and
standalone-full.xml
are 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.
Since the installer uses Wildfly8 by default as application server, you probably need to change
standalone-full-wildfly-8.1.0.Final.xml
.
We need to change the datasource configuration in standalone-full.xml
so that the jBPM process engine can use our MySQL database.
The original file contains (something very similar to) the following lines:
<datasource jta="true" jndi-name="java:jboss/datasources/jbpmDS" pool-name="H2DS" enabled="true" use-java-context="true" use-ccm="true">
<connection-url>jdbc:h2:tcp://localhost/~/jbpm-db;MVCC=TRUE</connection-url>
<driver>h2</driver>
<security>
<user-name>sa</user-name>
</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 jta="true" jndi-name="java:jboss/datasources/jbpmDS" pool-name="MySQLDS" enabled="true" use-java-context="true" use-ccm="true">
<connection-url>jdbc:mysql://localhost:3306/jbpm</connection-url>
<driver>mysql</driver>
<security>
<user-name>jbpm</user-name>
<password>jbpm</password>
</security>
</datasource>
and add an additional driver configuration:
<driver name="mysql" module="com.mysql">
<xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
</driver>
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:
Configuring the jBPM datasource in standalone.xml
:
After locating the java:jboss/datasources/jbpmDS
datasource, you need to provide the following properties specific to your database:
Change the name of the driver (which you’ll create next)
For example:
<datasource jta="true" jndi-name="java:jboss/datasources/jbpmDS" pool-name="PostgreSQLDS" enabled="true" use-java-context="true" use-ccm="true">
<connection-url>jdbc:postgresql://localhost:5432/jbpm</connection-url>
<driver>postgresql</driver>
<security>
<user-name>jbpm</user-name>
<password>jbpm</password>
</security>
</datasource>
Add an additional driver configuration:
db.driver.module.prefix
property in build.properties
(where forward slashes are replaced
by a point). In the example below, I used org/postgresql
as db.driver.module.prefix
which means that I should then use org.postgresql
as module name for the driver.For example:
+
<driver name="postgresql" module="org.postgresql">
<xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
</driver>
You need to change the dialect in persistence.xml to the dialect for your database, for example:
<property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect"/>
In order to make sure your driver will be correctly installed in the JBoss application server, there are typically multiple options, like install as a module or as a deployment. It is recommended to install the driver as a module for AS7, EAP6 and Wildfly8. For example, for AS7 both ways are explained here.
standalone/deployments
directory.If you choose to install driver as JBoss module (recommended), please do the following:
In build.properties
, disable the default H2 driver properties
# default is H2
# H2.version=1.3.168
# db.name=h2
# db.driver.jar.name=h2-${H2.version}.jar
# db.driver.download.url=http://repo1.maven.org/maven2/com/h2database/h2/${H2.version}/h2-${H2.version}.jar
Uncomment one of the other example configs (mysql or postgresql) or create your own:
#postgresql
db.name=postgresql
db.driver.module.prefix=org/postgresql
db.driver.jar.name=postgresql-9.1-902.jdbc4.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 a name for your database.db.driver.module.prefix
property to a name for the module of your driver. Note
that this should match the module property when configuring the driver in
standalone.xml
(where forward slashes in the prefix here are replaced by a point).
In the example above, I used org/postgresql
as db.driver.module.prefix
which means that
I should then use org.postgresql
as module name for the driver.db.driver.jar.name
property to the name of the jar that contains your database driver.db.driver.download.url
property to where the driver jar can be downloaded. Alternatively, you could manually download the jar yourself, and place it in the db/drivers
folder, using the same name as you specified in the db.driver.jar.name
property.Lastly, you’ll have to create the 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.jar.name
property.<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.
For all other questions, try contacting the jBPM community as described in the Getting Started chapter.