Chapter 3. jBPM Installer

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

Tip

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.

3.2. Downloading the Installer

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/

3.3. Demo Setup

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 JBoss AS) 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 JBoss AS
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).

Tip

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 the JBoss AS
Start Eclipse

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

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

3.4. 10-Minute Tutorial using the Workbench

Open up the process management console:

http://localhost:8080/jbpm-console

Note

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

Using a prebuilt Evaluation example, the following screencast gives an overview of how to manage your process instances. It shows you:

How to build and deploy a process
How to start a new process instance
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 3.1.

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.
- In this screencast, the Evaluation project inside the jbpm-playground repository is used.
The project explorer shows all available artefacts:
- evaluation: business process describing the evaluation process as a sequence of tasks
- evaluation-taskform: process form to start the evaluation process
- PerformanceEvaluation-taskform: task form to perform the evaluation tasks
To make a process available for execution, you need to successfully build and deploy it first. To do so, open up the Project Editor (from the Tools menu) and click Build & Deploy.
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 - lists all available process definitions
- Process Instances - lists all active process instances (allows to show completed, aborted as well by changing filter criteria)
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:
- Process model - to visualize current state of the process
- Process variables - to see current values of process variables
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.
To see the tasks that have been assigned to you, choose the "Tasks" menu option on the top bar and select "Task List" (you may need to click refresh to update your task view). The personal tasks table should show a "Performance Evaluation" task reserved for you. After starting the task, you can complete the task, which will open up the task form related to this task. You can fill in the necessary data and then complete the form and close the window. After completing the task, you could check the "Process Instances" once more to check the progress of your process instance. You should be able to see that the process is now waiting for your HR manager and project manager to also perform an evaluation. You could log in as "john" / "john" and "mary" / "mary" to complete these tasks.
After starting and/or completing a few process instances and human tasks, you can generate a report of what has happened so far. Under "Dashboards", select "Process & Task Dashboard". This is a set of see predefined charts that allow users to spot what is going on in the system. Charts can be fully customized as well, as explained in the Business Activity Monitoring chapter.

3.5. 10-Minute Tutorial using Eclipse

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
- Import the evaluation project (included in the jbpm-installer)
- Open the Evaluation.bpmn process
- Open the com.sample.ProcessTest Java class
- Execute the ProcessTest class to run the process
How to create a new jBPM project (including sample process and JUnit test)

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".

3.6. Configuration

3.6.1. Playgrounds

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:

Organizational unit
Repository (new or clone existing one)
Project

3.6.2. Workbench Authentication

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.

3.6.3. Using your own database

Tip

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:

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=${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:
- Please double check the files you've modified: I wrote this, but still made mistakes when changing files!
- Please make sure that you don't secretly have another (unmodified) instance of JBoss AS running.
- If neither of those work (and you're using MySQL), please do then let us know.

3.6.3.4. Using a different database

If you decide to use a different database with this demo, you need to remember the following when going through the steps above:

Change the JDBC URLs, usernames and passwords, and Hibernate dialect lines to match your database information in the configuration files mentioned above.
In order to make sure your driver will be correctly installed in the JBoss AS 7 server, you can do one of two things. Both ways are explained here.
- Install the driver JAR as a module, which is what the install script does.
- Otherwise, you can modify and install the downloaded JAR as a deployment. In this case you will have to copy the JAR yourself to the standalone/deployments directory.
If you choose to install driver as JBoss module, please do the following:
- Disable default H2 driver 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
                
```
- Copy one of the example configs (mysql or postgresql)
```
#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
              
```
- Change the db.name property in build.properties to the name of the downloaded jdbc driver JAR you placed in db/drivers.
- Change the <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>
```
- Further on in standalone.xml is the <drivers> section of the <datasources> (note the plural: drivers, datasources). We need to do the following with this file:
  - Change the name of the driver to match the name in the last step,
  - Give an appropriate name to the module,
  - And fill in the correct name of the XA datasource class to use.
  For example:
```
<drivers>
  <driver name="postgresql" module="org.postgresql">
      <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
  </driver>
</drivers>
              
```
- Change the 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.
- 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:
  - Change the name of the module to match the db.driver.module.prefix property above
  - Change the name of the module resource to the name of the JDBC driver JAR that was downloaded.
  The top of the original file looks like this:
```
<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>
```

3.6.4. jBPM database schema scripts (DDL scripts)

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.

3.6.5. jBPM installer script

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

3.7. Frequently Asked Questions

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.