JBoss.orgCommunity Documentation

Chapter 3. jBPM Installer

3.1. Prerequisites
3.2. Downloading the Installer
3.3. Demo Setup
3.4. 10-Minute Tutorial using the Workbench
3.5. 10-Minute Tutorial using Eclipse
3.6. Configuration
3.6.1. Playgrounds
3.6.2. Workbench Authentication
3.6.3. Using your own database
3.6.4. jBPM database schema scripts (DDL scripts)
3.6.5. jBPM installer script
3.7. Frequently Asked Questions

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.

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:

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

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

Note

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

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

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

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

The following files define the persistence settings for the jbpm-installer demo:

Do 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:

  • 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>

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

TargetDescription
clean.dbcleans up database used by jBPM demo (applies only to H2 database)
clean.democleans up entire installation so new installation can be performed
clean.demo.noeclipsesame as clean.demo but does not remove Eclipse
clean.eclipseremoves Eclipse and its workspace
clean.generated.ddlremoves DDL scripts generated if any
clean.jbossremoves application server with all its deployments
clean.jboss.repositoryremoves repository content for demo setup (guvnor Maven repo, niogit, etc)
download.dashboarddownloads jBPM dashboard component (BAM)
download.db.driverdownloads DB driver configured in build.properties
download.ddl.dependenciesdownloads all dependencies required to run DDL script generation tool
download.droolsjbpm.eclipsedownloads Drools and jBPM Eclipse plugin
download.eclipsedownloads Eclipse distribution
download.jbossdownloads JBoss Application Server
download.jBPM.bindownloads jBPM binary distribution (jBPM libs and its dependencies)
download.jBPM.consoledownloads jBPM console for JBoss AS
install.dashboard.into.jbossinstalls jBPM dashboard into JBoss AS
install.db.filesinstalls DB driver as JBoss module
install.demoinstalls complete demo environment
install.demo.eclipseinstalls Eclipse with all jBPM plugins, no server installation
install.demo.noeclipsesimilar to install.demo but skips Eclipse installation
install.dependenciesinstalls custom libraries (such as work item handlers, etc) into the jBPM console
install.droolsjbpm-eclipse.into.eclipseinstalls droolsjbpm Eclipse plugin into Eclipse
install.eclipseinstall Eclipse IDE
install.jbossinstalls JBoss AS
install.jBPM-console.into.jbossinstalls 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.