BONITA Workflow System (1.7 version): Configuration & Installation Instructions

Bonita Workflow System is a J2EE based application that takes advantage of JOnAS Application Server. Bonita installation instructions are oriented to both non-experimented and professionals J2EE users. In this context we propose you two differents ways to install and configure Bonita within your JOnAS application server: typical installation and custom installation.

Table of Contents:

1.- Prerequisites

2.- Download Bonita

3.- Environmental settings

4.- Typical configuration

5.- Custom configuration

6.- Installing & Running Bonita

7.- Bonita Documentation

    2.- Download Bonita & extract files

    You can download Bonita Workflow System module in the download area of Bonita Home Page. After that you can extract bonita file downloaded: bonita-v1.7.zip or bonita-v1.7.tar.gz.

    Previous operation should creates the bonita directory with this "basic" structure:

         \--bonita-v1.7
            +--src:
               +--main
                   +--ejb
                   +--client
               +--struts
               +--resources
               +--etc
            +--lib\ext
    * After compilation and deploy Bonita Workflow System, the following directory will be created:
            +--build

    3.- Environmental settings

    Next variables are used to deploy Bonita:

    $JAVA_HOME - JDK 1.4+ home (eg: c:\jdk1.4\ or /jdk1.4)
    $JONAS_ROOT - Jonas version home (eg: c:\JONAS_4_6_3\ or /JONAS_4_6_3)
    $ANT_HOME - jakarta ant home (eg: c:\apache-ant-1.6\ or /apache-ant-1.6)
    $BONITA_HOME - your Bonita home install directory

  • You can use a JONAS_BASE for Bonita configuration and deployment. If you don't have JONAS_BASE, JONAS_BASE takes the value of your JONAS_ROOT variable.

  • Edit $BONITA_HOME/.ant.properties file and set the values of your host and web port.

  • Bonita allows jabber instant message notifications, so if you have a jabber server, set your jabber properties in $BONITA_HOME/.ant.properties file and turn the "jabber.enabled" property to true (if not, keep default values).

  • This version is configured for RMI JRMP protocol.

    4.- Typical configuration

    Oriented to non-experimented JOnAS users, following lines explains the basic instructions to configure Bonita with JOnAS application server. This installation replace default JOnAS configuration files by pre-configured Bonita files, so take a look at Custom installation if you have some applications using JOnAS or if you want to configure yourself JOnAS config files for Bonita.

      Bonita-JOnAS configuration

    • Run "ant config" at $BONITA_HOME/ in order to copy pre-configured Jonas files for Bonita.
      *Note: This operation will delete the following files at $JONAS_BASE/conf:
                jaas.config,
                jonas-realm.xml,
                jonas.properties,
                server.xml,
                MailSession1.properties,
                carol.properties,
                a3servers.xml

    • *Note: This command also copies bonita log configuration file (log4j.properties) into your $J0NAS_BASE\conf directory. You can edit this file and sets your favorite path for bonitaLog.txt and bonitaTrace.txt files. By default, bonitaTrace.xml and bonitaLog.xml files will be created in your $BONITA_HOME directory.

      Database Configuration for Jonas

    • This version uses (by default) the hsqldb JOnAS-4 embedded database. You have to do nothing else to configure Bonita with this database. Go to Installing & Runnig Bonita if hsqldb is your choice.

    • If you want to configure Bonita to run with your favorite database, you can take a look at the different samples files at $JONAS_ROOT/conf/ directory for MySQL, mckoi, oracle...

    • Copy your database driver jar file into $JONAS_BASE\lib\ext directory (you can find drivers for mysql, postgres and mckoi databases at $BONITA_HOME/lib/ext directory). If you use another database driver (ex. Oracle) you have to update "pathelement" attribute in $BONITA_HOME\build.xml file in order to launch clients and tests.

      *Important: Bonita uses this bonita.properties file in order to deploy the application, so your file have to have the same name. We have tested Bonita with hsql, postgres, mysql, Oracle and mckoi databases, so if you have problems with others just contact us !!

    • Go to Installing & Running Bonita for complete installation.

    5.- Custom configuration

    Oriented to JOnAS experimented users, this installation let you configure Bonita and JOnAS as you want.

      JOnAS configuration files

      The next files should be modified in order to deploy and run Bonita in JOnAS:

    • $JONAS_BASE/conf/jonas.properties:

      - Add bonita datasource name: jonas.service.dbm.datasources bonita

      - Set mail service name: jonas.service.mail.factories MailSession1

    • $JONAS_BASE/conf/a3servers.xml:

      - Set the hostname value (localhost by default) at line: server id="0" name="S0" hostname="localhost"
      This value must be the same you define in $BONITA_HOME\.ant.properties for "bonita.host" attribute.

    • $JONAS_BASE/conf/carol.properties:

      - Set the value of jrmp URL: carol.jrmp.url=rmi://localhost:1099

      Host name and port name values must be the same you have defined in $BONITA_HOME\.ant.properties file for "bonita.host" and "jrmp.port" properties.

    • $JONAS_BASE/conf/jaas.config:

      - Add following lines at the end of this file: bonita resources

    • $JONAS_BASE/conf/jonas-realm.xml:

      - Add bonita realm: bonita realm

    • $JONAS_BASE/conf/server.xml:

      - Add next lines after Realms definition bonita context
      In this file you have to configure also the Tomcat port number for non-SSL connections. This port is used by Bonita in order to access bonita web services and/or to use bonita web interface. This value (9000 by default) should be the same as "bonita.port" property included in $BONITA_HOME\.ant.properties file.

    • Add bonita datasource to your $JONAS_BASE/conf/ directory.

      - This sample file for hsql db is the default datasource configuration file for Bonita. You can take a look at JOnAS documentation to obtain more information about how configure JOnAS datasources.
      Note that the name of this datasource file (without .properties extension) must be the same you have defined in file jonas.property file (at datasources names).

    • Database driver

      - Copy your database driver jar file into $JONAS_BASE\lib\ext directory (you can find drivers for mysql, postgres and mckoi databases at $BONITA_HOME/lib/ext directory). If you use another database driver (ex. Oracle) you have to update "pathelement" attribute in $BONITA_HOME\build.xml file in order to launch clients and tests.

    • Set your mail configuration at $JONAS_BASE/conf/MailSession1.properties

      - Change the following line: mail.factory.name mailSession_1 by this one: mail.factory.name Mail. More information about JOnAS mail configuration here

    • Set your Jabber configuration in $BONITA_HOME/.ant.properties

      - If you wish to allow Jabber instant message notifications, then you will need to switch the value of "jabber.enabled" to true and modify the following properties to match your configuration: "jabber.host", "jabber.port", "jabber.user", "jabber.password".

    • Resources

      - Run "ant resource" at $BONITA_HOME/ in order to copy some additional libraries to JOnAS lib\ext.
      This command also copies bonita log configuration file (log4j.properties) into your $J0NAS_BASE\conf directory. You can edit this file and sets your favorite path for bonitaLog.txt and bonitaTrace.txt files. By default, bonitaTrace.xml and bonitaLog.xml files will be created in your user.dir directory.

    6.- Installing & Running Bonita

    Once Bonita is configured as well (see at Typical or Custom configuration), you can install and deploy Bonita in your system.

      Compile and deploy Bonita in JOnAS

    • To generate files with xdoclet, compile all sources and deploy the application, execute:

      - $BONITA_HOME/ant

    • To start jonas server:

      - $JONAS_ROOT/bin/nt/jonas start // Windows systems

      or

      - $JONAS_ROOT/bin/unix/jonas start // Unix systems

      * NOTE: ALL BONITA TABLES ARE CREATED AUTOMATICALLY BY THE SYSTEM AT THE DEPLOYMENT.

      Running Bonita

    • To Initialize Bonita environment:

      - $BONITA_HOME/ant initDB

    • Bonita Web Interface sample is available at:

      - http://${hostname}:{portnumber}/bonita

      * Note: This Web interface is only a basic example that use Struts Framework, JSP and JSTL pages in order to show one of the possible Workflow Integration scenarios.

    • Try launching manager.jnlp application (Java Web Start application):

      - http://{hostname}:{portnumber}/manager/manager.jnlp (Login = admin, password = toto)

    • To execute the manager client application from the command line:

      - $BONITA_HOME/ant manager (Login = admin, password = toto)

      * Note: The manager application (Worklist application + GraphEditor application) use Bonita Web Services calls. See $BONITA_HOME/doc/user-guide.pdf for additional information about this application.

    • Bonita Workflow System Web Services list available at:

      - http://{hostname}:{portnumber}/bonita_ws (Login = admin, password = toto)


    7.- Bonita Documentation

  • Look at Bonita Quick Start User Guide document for a Bonita introduction.

  • Bonita API javadoc for workflow project definfition and execution.

  • First version of Bonita Application Programming Interface document is also available.

  • An introduction to the simple web application based on Xforms: Bonita Forms Generator .

  • Get inside Bonita features looking at Bonita API samples source code at $BONITA_HOME/src/main/client/hero/client/samples

  • Bonita's log/trace visualization is possible using log4j chainsaw application. Type "ant chainsaw" from your $BONITA_HOME directory for application execution and then load bonitaTrace.xml or/and bonitaLog.xml files.
    Bonita log and trace settings (Rolling, MaxBackupIndex and MaxFileSize) can be configured at $JONAS_BASE/conf/log4j.properties file.

  • The Bonita-historic directory will be created (after first execution) into $BONITA_HOME to save terminated instances and cooperative projects