JBoss.orgCommunity Documentation

Chapter 3. Installer

3.1. Prerequisites
3.2. Download the installer
3.3. Demo setup
3.3.1. Control options
3.4. 10-Minute Tutorial: Using the jBPM Console
3.5. 10-Minute Tutorial: Integrate Eclipse and Web tooling
3.6. Using your own database with jBPM
3.6.1. Introduction
3.6.2. Database setup
3.6.3. Configuration
3.6.4. Using a different database
3.7. jBPM data base schema scripts (DDL scripts)
3.8. jBPM installer script
3.9. What to do if I encounter problems or have questions?
3.10. Frequently asked questions

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:

Java: http://java.sun.com/javase/downloads/index.jsp

Ant: http://ant.apache.org/bindownload.cgi

First of all, you need to download the installer. 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. Simply go into the install folder and run:

ant install.demo

This will:

This could take a while (REALLY, not kidding, we are downloading an application server and Eclipse installation, even if you downloaded the full installer). 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 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:

Once everything is started, you can start playing with the Eclipse tooling, jBPM console, as explained in the next three sections.

If you do not wish to use Eclipse in the demo setup, you can use the alternative commands:

    ant install.demo.noeclipse
    ant start.demo.noeclipse
    

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


  • 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. You will see a process form where you need to fill in the necessary information to start the process. In this case, you need to fill in your username "krisv" and a reason for the request, after which you can complete the form and close the window. After process form window is closed process instance details panel will be shown. 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 for you. You can complete this task by selecting it and clicking the "View" button. This will open the task form for performance evaluations. 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". By default, you will see predefined set of charts that allow to directly spot what is going on in the system. Charts can be customized as well which will be described in following chapters.

The following screencast gives an overview of how to integrate Web Console and Eclipse. It shows you:

  • How to create new project inside web console
  • How to create new process inside web console
  • How to import an existing project into your workspace
  • How to apply changes in Eclipse
  • How to push back changes done in Eclipse to Web Console

Figure 3.2. 


You could also create a new project using the jBPM project wizard. This sample project contains a simple HelloWorld BPMN2 process and an associated Java file to start the process. Simply select "File - New - jBPM Project" (if you cannot see that (because you're not in the jBPM perspective) you can do "File - New ... - Project ..." and under the "jBPM" category, select "jBPM project" and click "Next"). Give the project a name and click "Finish". You should see a new project containing a "sample.bpmn" process and a "com.sample.ProcessMain" Java class 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 ProcessMain.java and select "Run As - Java Application". You should see a "Hello World" statement in the output console. To execute the test, right-click on ProcessTest.java and select "Run As - JUnit Test". You should also see a "Hello World" statement in the output console, and the JUnit test completion in the JUnit view.

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

There are two standalone.xml files available as jbpm allows to use JMS component for integration and thus requires standalone-full.xml to be configured. Best practice is to update both to have consistent setup but most important is to have standalone-full-as-7.1.1.Final.xml properly configured.

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)
      #postresql
      db.name=postresql
      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.2. jBPM installer available targets

TargetDescription
clean.dbcleans up data base used by jBPM demo (applies only to H2 data base)
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) 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.