BONITA Workflow Engine v3.1:
Configuration & Installation Instructions
You have download the "light version" of Bonita Workflow system including
the Bonita workflow engine and J2EE related services. A packaged solution including graphical tools to define,
to execute and to administrate workflow processes is available to donwload at ObjectWeb forge
Hereafter you will find configuration and installation instructions to set up the Bonita engine on top of
either JOnAS or JBoss application servers.
Table of Contents:
1.- Prerequisites
-
Installation of the application
server:
-
Installation of JDK 1.4 or 1.5.
-
Installation of jakarta
ant (version up to 1.6.5) environment.
-
Installation of your favorite
Database (see in your application server documentation if the database is
supported. Click
here for JOnAS and
here for JBoss.).
2.- Download
Bonita & Extract files
You can download Bonita
Workflow System module from the download
area of Bonita Web Site. After that you can extract the downloaded Bonita
file: bonita_engine_X.Y.Z.zip or bonita_engine_X.Y.Z.tar.gz.
Previous operation should create the bonita directory with this
"basic" following structure:
\--bonita_engine_X.Y.Z
+--src
+--main
+--ejb
+--client
+--struts
+--resources
+--etc
+--lib
+--ext
+--doc
* After compilation and Bonita Workflow System deployment, the following
directory will be created:
+--build
3.- JOnAS application server settings
This section describes the settings that need to be brought when JOnAS is the
selected application server. Please note that Bonita has been optimized for
this application server, which makes it the best choice. Installation
instructions are oriented to both non-experimented and professional 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. In both cases the
following 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_8_6\ or /JONAS_4_8_6)
$ANT_HOME - jakarta ant home (eg: c:\apache-ant-1.6.5\ or
/apache-ant-1.6.5)
$BONITA_HOME - your Bonita home install directory
-
You can use a JONAS_BASE for
Bonita configuration and deployment. If you don't have a 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.
3.1.- Typical configuration
Oriented to non-experimented
JOnAS users, following lines explain the basic instructions to
configure Bonita with JOnAS application server. This installation
replaces default JOnAS configuration files by pre-configured Bonita
files, so take a look at Custom
installation if you
want to configure yourself the 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 overwrite the following files at
$JONAS_BASE/conf, so you will need to back them up beforehand:
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
has to have the same name. We have tested Bonita with HSQLDB, PostgreSQL, MySQL, Oracle
and Mckoi databases, so if you have problems with others just contact
us !!
Go to Installing & Running Bonita
for complete installation.
3.2.- Custom configuration
Oriented to JOnAS experimented
users, this installation lets you configure Bonita and JOnAS as you
want. 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
HSQLDB 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.
Go to Installing & Running Bonita for
complete installation.
4.- JBoss application server settings
This section describes the settings that
need to be brought when JBoss is the target application server. JBoss support
is currently experimental. As a consequence, performances may be lower than in
JOnAS application server. The following variables are used to deploy Bonita:
$JAVA_HOME - JDK 1.4+ home (eg: c:\jdk1.4\ or /jdk1.4)
$JBOSS_HOME - JBoss installation location (eg: c:\jboss-4.0.4.GA or /jboss-4.0.4.GA)
$ANT_HOME - jakarta ant home (eg: c:\apache-ant-1.6.5\ or
/apache-ant-1.6.5)
$BONITA_HOME - your Bonita home install directory
4.1.- Bonita-JBoss configuration
Edit $BONITA_HOME/build.xml to change the
following line :
<property name="deploy.server" value="jonas"/>
to
<property name="deploy.server" value="jboss"/>
This property specifies the target application server. Run "ant config" at
$BONITA_HOME/ in order to copy pre-configured JBoss files for Bonita.
*Note: This operation will overwrite some JBoss configuration files, so you will
perhaps need an installation backup beforehand.
4.2.- Database Configuration for JBoss
Bonita is configured to run by default
with HSQLDB database. Although this database system is great for test and
demonstration purpose, it is recommanded to use another one in an
operating environment. To help doing so, Bonita comes with sample PostgreSQL
configuration files. To enable them, you need to add the
"-Ddeploy.database=postgresql" parameter when running the previous "ant config"
command. This will override the default HSQLDB settings. One of the installed
files is $JBOSS_HOME/server/default/deploy/postgres-ds.xml. Some entries, such
as host name, user name and password should be customized to match your
environment.
Go to Installing & Running Bonita for
complete installation.
5.- Installing &
Running Bonita
Once Bonita is propertly configured
(see previous sections for more details), you can proceed to install and
deploy Bonita in your system.
5.1.- To compile and deploy Bonita in the application server:
-
To generate files with
XDoclet, compile all sources and deploy the workflow engine + the Web Interface
sample and the JavaWebStart Workflow Editor sample application, execute:
- $BONITA_HOME/ant
To generate files with
XDoclet, compile all sources and deploy the workflow engine without web samples,
execute:
- $BONITA_HOME/ant light-main
-
Start the application server:
- For JOnAS :
%JONAS_ROOT%\bin\n\jonas start in Windows systems or
$JONAS_ROOT/bin/unix/jonas start in Unix systems.
- For JBoss :
%JBOSS_HOME%\bin\run in Windows systems or
$JBOSS_HOME/bin/run in Unix systems
* NOTE: ALL BONITA TABLES ARE CREATED AUTOMATICALLY BY THE SYSTEM AT
THE DEPLOYMENT.
-
To Initialize Bonita database with the default user (admin/toto):
- $BONITA_HOME/ant
initDB
-
Bonita's log/trace visualization is
possible using the 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 in JOnAS and
$JBOSS_HOME/server/default/conf/log4j.xml in JBoss.
-
The Bonita-historic directory will be created (after first execution) into $BONITA_HOME to save terminated instances and cooperative projects
5.2.- Running Bonita
-
To execute the Workflow editor sample
client application from the command line:
- $BONITA_HOME/ant
manager (Login = admin, password = toto)
* Note: The Workflow editor sample (composed by the Worklist application + GraphEditor
application) is a sample application that illustrates how to interact with Bonita through the Web Services API. See
$BONITA_HOME/doc/user-guide.pdf for additional information about this sample application.
-
If you are not familiar with the Bonita APIs just take a look to the samples java clients available at $BONITA_HOME/src/main/client/hero/client/samples
-
For a complete review of the workflow patterns in Bonita please take a look at $BONITA_HOME/src/main/client/hero/client/samples/patterns
-
The Bonita Web Services APIs are available at:
-
http://{hostname}:{portnumber}/bonita_ws (Login = admin, password =
toto)
In the case you have installed the web applications during the Bonita installation ("ant" task rather than "ant light-main"),
you should also have access to the following sample applications:
-
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.
-
To launch the Java Web Start version of the Workflow Editor sample, just run the manager.jnlp
application:
-
http://{hostname}:{portnumber}/manager/manager.jnlp (Login = admin,
password = toto)
|