Bos 5.5 Bundle Installation Guide 2

Bonita Open Solution
Version 5.4.2
BOS Bundle Installation Guide

“How to” install BOS-Tomcat or BOS-JBoss bundle
(option: with external database)
“How to” install BOS bundles
Contents
Overview ..................................................................................................................................... 3
Part 1. Requirements for installing BOS ........................................................................................ 3
Part 2. Install BOS-Tomcat bundle and configure if needed for external database .......................... 4
2.1 Install the BOS-Tomcat bundle ............................................................................................... 4
2.2 Configure the BOS-Tomcat bundle for use with MySQL ......................................................... 6
Part 3. Install BOS-JBoss bundle and configure if needed for external database .......................... 12
3.1 Install the BOS-JBoss bundle ................................................................................................. 12
3.2 Configure BOS-JBoss bundle for use with MySQL................................................................. 13
BOS 5.4 – HowTo Install BOS bundles www.bonitasoft.com | © BonitaSoft S.A. page 2
Bonita Open Solution

“How to” install a BOS bundle
with or without an external database
Overview
In this document, Bonita Open Solution is referred to as BOS.
This “How to” guide contains instructions for installing a BOS-bundle and covers the
configuration of your bundled application server for MySQL. (You can however, adapt this
process to any database with an existing Hibernate dialect
(http://docs.jboss.org/hibernate/core/3.6/reference/en-US/html/session-
configuration.html#configuration-optional-dialects).
The simplest, fastest installation of BOS for a server environment, can be made using the
BOS-bundle, with the default H2 database provided.
Note: We do not recommend the use of a simple bundle installation using the default H2
database for production. This document describes how to change the connection from the
default H2 database to an external database (MySQL), which is a production-friendly option.
This document has 3 parts:
Part 1 General requirements for BOS installation
Part 2 Install BOS-Tomcat bundle and configure. The simple bundle installation with the
default H2 database is fully described in Part 2.1. Follow Part 2.2 to configure the bundle to
use a different, external database.
Part 3 Install BOS-JBoss bundle and configure. The simple bundle installation with the
default H2 database is fully described in Part 3.1. Follow Part 3.2 to configure the bundle to
use a different, external database.
Part 1. Requirements for installing BOS
You will need Java Runtime Environment 5 (or Java SE Development Kit 5) or above to install
BOS. (http://www.java.com/en/download/manual.jsp or
http://www.oracle.com/technetwork/java/javase/downloads/index.html)
Be sure that JRE or JDK is installed correctly and JAVA_HOME and JRE_HOME variables are
defined (with different values).
Part 2. Install BOS-Tomcat bundle and configure if needed for external database
2.1 Install the BOS-Tomcat bundle
Download the BOS-Tomcat bundle from the BonitaSoft website

(http://www.bonitasoft.com/products/BPM_download.php). If you are using BOS
Subscription Pack, download the BOS-Tomcat bundle specific to BOS-SP.
Unzip the BOS-Tomcat bundle in the folder of your choice.
This location path will be referenced as <TOMCAT_HOME> in the following sections of this
document.
Choose a location close to the root directory, for example

c:\BOS on windows
/opt/BOS on linux
Note: Avoid spaces and special characters in the folder path.
2.1.1 Launch and verify BOS-Tomcat bundle installation with H2 database
Note: If you will be using only the default H2 database, validate your installation now.
If you will be using an external database, such as MySQL, skip this step and continue to 2.2,
Configure the BOS-Tomcat bundle for use with MySQL.
 On Windows, go to <TOMCAT_HOME>\bin\ and click on startup.bat.

 On Linux, go to <TOMCAT_HOME>/bin/ and click on startup.sh script.
Point your web browser to http://<SERVERADDRESS>:8080/bonita.
Note: Be sure to replace <SERVERADDRESS> with a fully qualified domain name (FQDN) or
the IP address of the server. Avoid using localhost for <SERVERADDRESS> .
You should be able to access the Bonita User Experience login page:
You can log in with one of the following usernames and a single password:
 Username: admin, john, jack, or james
 Password: bpm
Note: If you are unable to reach the log-in page shown above, consult the log files in
<TOMCAT_HOME>\logs.
2.2 Configure the BOS-Tomcat bundle for use with MySQL
2.2.1 Set up 2 databases in MySQL to be used with the BOS-Tomcat bundle
Create 2 databases in MySQL:
 bonita_journal
 bonita_history
2.2.2 Configure the access privileges for MySQL
Create a dedicated user and password:

 User login: bonita
 password: bpm
Note: this can be changed later.
Grant this user all privileges to access the bonita_journal and bonita_history databases.
2.2.3 Modify the BOS configuration files for use with MySQL
In order to configure BOS for use with a database other than H2, you will need to edit 2
properties configuration files and 1 data source configuration file.
2.2.3.1 Edit the 2 Properties files
The 2 properties files are:

 bonita_journal.properties
 bonita_history.properties
To edit them, you will:

1. de-activate the H2 properties in:
o H2 bonita-journal.properties
o H2 bonita-history.properties
2. activate the MySQL properties in:

o MySQL bonita-journal.properties
o MySQL bonita-history.properties
These modifications are shown below.
1. de-activate H2 properties for bonita-journal.properties located at:

<TOMCAT_HOME>\bonita\server\default\conf\bonita-journal.properties
by adding a hash (#) at the beginning of the original line to de-activate H2:
original line:
hibernate.dialect [] org.hibernate.dialect.H2Dialect
result after change in green:

#hibernate.dialect [] org.hibernate.dialect.H2Dialect
original line:
hibernate.connection.shutdown [] true

#hibernate.connection.shutdown [] true
original line:
bonita.hibernate.interceptor []
org.ow2.bonita.env.interceptor.H2DescNullFirstInterceptor

#bonita.hibernate.interceptor []
2. Do the same for the H2 bonita-history.properties file, located at:

<TOMCAT_HOME>\bonita\server\default\conf\bonita-history.properties
3. Activate MySQL properties for the bonita-journal.properties file, located at:

<mysql_home>\bonita\server\default\conf\bonita-journal.properties
by deleting the hash (#) at the beginning of the original line, to activate MySQL.
original line:
#hibernate.dialect []
org.hibernate.dialect.MySQL5InnoDBDialect

hibernate.dialect []
original line:

original line:
#bonita.hibernate.interceptor []
org.ow2.bonita.env.interceptor.MySQLDescNullFirstInterceptor

bonita.hibernate.interceptor []
4. Do the same for the H2 bonita-history.properties file located at:

<mysql_home>\bonita\server\default\conf\bonita-history.properties
2.2.3.2 Edit the data source file
Modify the BOS-Tomcat data source configuration file called context.xml, to change the data
base configuration from H2 (by default) to MySQL.
To do this, change the driverClass and jdbcUrl parameters for your configuration in the
Resources named bonita/default/journal and bonita/default/history.
Locate the data source configuration file called context.xml:

<TOMCAT_HOME>\conf\context.xml
1. Replace the configuration for the bonita/default/journal
Locate the Resource tag for bonita/default/journal and as shown below, replace the
default H2 driverClass and jdbcUrl parameters with MySQL parameters:
original H2 lines:
<Resource
name="bonita/default/journal"
auth="Container"
type="com.mchange.v2.c3p0.ComboPooledDataSource"
factory="org.apache.naming.factory.BeanFactory"
description="DB Connection"
driverClass="org.h2.Driver"
jdbcUrl="jdbc:h2:file:
${BONITA_HOME}/server/default/work/databases/bonita_jour
nal.db;FILE_LOCK=NO;MVCC=TRUE;DB_CLOSE_ON_EXIT=TRUE"
result after change with new MySQL line in green:

<Resource
name="bonita/default/journal"
auth="Container"
driverClass="com.mysql.jdbc.Driver"
jdbcUrl="jdbc:mysql://localhost:3306/bonita_journal?dont
TrackOpenResources=true"
2. Replace the configuration for bonita/default/history
Locate the Resource tag for bonita/default/history and as shown below, replace the
default H2 driverClass and jdbcUrl parameters with the MySQL parameters:
original H2 line:
<Resource
name="bonita/default/history"
auth="Container"
driverClass="org.h2.Driver"
jbcUrl="jdbc:h2:file:${BONITA_HOME}/server/default/work/d
atabases/bonita_history.db;FILE_LOCK=NO;MVCC=TRUE;DB_CLOS
E_ON_EXIT=TRUE"
result after change with new MySQL line in green:

<Resource
name="bonita/default/history"
auth="Container"
driverClass="com.mysql.jdbc.Driver"
jdbcUrl="jdbc:mysql://localhost:3306/bonita_history?dont
TrackOpenResources=true"
Note: Remember to set the user and password in your data source configuration in order to
match the “user and “password” you set (with full access rights) during 2.2.2 Configure the
access privileges for MySQL.
2.2.4 Download and install the MySQL driver
Download the MySQL driver (http://dev.mysql.com/downloads/connector/j/).
Extract the mysql-connector-java-5.1.15-bin.jar file from the downloaded .zip file and install
into: <TOMCAT_HOME>\lib\bonita
Remove the file h2-1.2.139.jar from this location to avoid conflicts.
2.2.5 Add the license file (for SP version only)
Copy your SP license file to: <TOMCAT_HOME>\bonita\server\licenses.
2.2.6 Validate the database re-configuration
Start Tomcat
 On Windows, go to <TOMCAT_HOME>\bin\ and click on startup.bat.

 On Linux, go to <TOMCAT_HOME>/bin/ and click on startup.sh script.
If you have no error messages, you can connect to BOS.
Connect to BOS

 Password: bpm
Note: If you are unable to reach the log-in page shown above, please consult the log files.
(see 2.2.7, Log errors).
2.2.7 Log errors
With your database server and web container running, point your web browser to
http://<SERVERADDRESS:port>/bonita/.
<TOMCAT_HOME>\logs.
Check your database log for errors also.
2.2.8 Troubleshooting
Here are some potential issues and possible explanations:
Behavior Possible explanation

Unable to create datasource instance context.xml contains error (property is missing)
check your datasource definition (eg Tomcat)
ClassNotFoundException: com.mysql.jdbc.Driver forgot to add jdbc drivers
Access denied: Connections could not be wrong username password specified in
acquired from the underlying database! context.xml
Part 3. Install BOS-JBoss bundle and configure if needed for external database
3.1 Install the BOS-JBoss bundle
Download the BOS-JBoss bundle from the BonitaSoft website

(http://www.bonitasoft.com/products/BPM_download.php). If you are using BOS
Subscription Pack, download the BOS-JBoss bundle specific to BOS-SP.
Unzip the BOS-JBoss bundle in the folder of your choice.
This location path will be referenced as <JBOSS_HOME> in the following sections of this
document.
Choose a location close to the root directory, for example

c:\ on windows
/opt/BOS on linux
Note: Avoid spaces and special characters in folder path.
3.1.1 Launch and verify your BOS-JBoss bundle installation with H2 database
Note: If you will be using only the default H2 database, validate your installation now.
If you will be using an external database, such as MySQL, skip this step and continue to 3.2,
Configure the BOS-JBoss bundle for use with MySQL.
 On Windows, go to <JBOSS_HOME>\bin\ and click on run.bat.

 On Linux, go to <JBOSS_HOME>\bin\ and click on run.sh script.
 Password: bpm
<JBOSS_HOME>\logs.
3.2 Configure BOS-JBoss bundle for use with MySQL.
3.2.1 Set up 2 databases in MySQL to be used with the BOS-JBoss bundle
Create 2 databases in MySQL:
 bonita_journal
 bonita_history
3.2.2 Configure the access privileges for MySQL databases
Create a dedicated user and password:
 User login : bonita

 Password: bpm
Note: this can be changed later.
Grant this user all privileges to access the bonita_journal and bonita_history databases.
3.2.3 Modify the BOS configuration files for use with MySQL
In order to configure BOS for use with a database other than H2, you will need to
Edit 2 properties configuration files and 1 data source configuration file.
3.2.3.1 Edit the 2 Properties files
The 2 properties files are:

 bonita_journal.properties
 bonita_history.properties
To edit them, you will:

1. de-activate the H2 properties in:
o H2 bonita-journal.properties
o H2 bonita-history.properties
2. activate the MySQL properties in:

o MySQL bonita-journal.properties
o MySQL bonita-history.properties
These modifications are shown below:
1. de-activate H2 properties for bonita-journal.properties located at:

<JBOSS_HOME>\bonita\server\default\conf\bonita-journal.properties
by adding a hash (#) at the beginning of the original line to de-activate H2:
original line in:

hibernate.dialect [] org.hibernate.dialect.H2Dialect

#hibernate.dialect [] org.hibernate.dialect.H2Dialect
original line:

original line:
bonita.hibernate.interceptor

#bonita.hibernate.interceptor
2. Do the same for the H2 bonita-history.properties file, located at:

<JBOSS_HOME>\bonita\server\default\conf\bonita-history.properties
3. Activate MySQL properties for the bonita-journal.properties file located at:

<mysql_home>\bonita\server\default\conf\bonita-journal.properties
by deleting the hash (#) at the beginning of the original line, to activate MySQL.
original line:
#hibernate.dialect []

hibernate.dialect []
original line:

original line:
#bonita.hibernate.interceptor

bonita.hibernate.interceptor
3. Do the same for the bonita-history.properties file located at:

<mysql_home>\bonita\server\default\conf\bonita-history.properties
3.2.3.2 Create the data source file
Move and modify the BOS-JBoss data source configuration file called mysql-ds.xml, to
change the database configuration from H2 to MySQL.
To do this, locate the data source configuration file called mysql-ds.xml:

<JBOSS_HOME>\docs\examples\jca\mysql-ds.xml.
and copy it into
<JBOSS_HOME>\server\default\deploy
From this location, remove <JBOSS_HOME>\server\default\deploy\h2-ds.xml file.
Modify the content of the mysql-ds.xml file as shown below.
original lines:
<?xml version="1.0" encoding="UTF-8"?>



<datasources>
<local-tx-datasource>
<jndi-name>MySqlDS</jndi-name>
<connection-url>jdbc:mysql://mysql-
hostname:3306/jbossdb</connection-url>
<driver-class>com.mysql.jdbc.Driver</driver-class>
<user-name>x</user-name>
<password>y</password>
<exception-sorter-class-
name>org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSort
er</exception-sorter-class-name>




<metadata>
<type-mapping>mySQL</type-mapping>
</metadata>
</local-tx-datasource>
</datasources>
Result after changes in green. Note that you need to copy part of the file and modify it so
you have configuration for both bonita/default/journal and bonita/default/history (shown in
solid green at the end of the file below).
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<no-tx-datasource>
<jndi-name>bonita/default/journal</jndi-name>
<connection-
url>jdbc:mysql://<serverIPaddress>:3306/bonita_journal</connection-
url>
<user-name>bonita</user-name>
<password>bpm</password>
name>org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter</exc
eption-sorter-class-name>

<new-connection-sql>some arbitrary sql</new-connection-sql>
-->


<metadata>
</metadata>
</no-tx-datasource>
<no-tx-datasource>
<jndi-name>bonita/default/history</jndi-name>
<connection-
url>jdbc:mysql://<serverIPaddress>:3306/bonita_history</connection-
url>
<user-name>bonita</user-name>
<password>bpm</password>
name>org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter</exc
eption-sorter-class-name>

<new-connection-sql>some arbitrary sql</new-connection-sql>
-->


<metadata>
</metadata>
</no-tx-datasource>
</datasources>
Note: Remember to set the user and password in your data source configuration in order to
match the “user and “password” you set (with full access rights) during 3.2.2 Configure the
access privileges for MySQL.
3.2.4 Download and install the MySQL driver
Download the MySQL driver (http://dev.mysql.com/downloads/connector/j/)
Extract the mysql-connector-java-5.1.15-bin.jar file from the downloaded .zip file and install
into: <JBOSS_HOME>\lib\bonita
Remove the file h2-1.2.139.jar from this file to avoid conflicts.
3.2.5 Add the license file (for SP version only)
Copy your SP license file to: <JBOSS_HOME>\bonita\server\licenses.
3.2.6 Validate the database re-configuration installation
Start JBoss
 On Windows, go to <JBOSS_HOME>\bin\ and click on startup.bat.

 On Linux, go to <JBOSS_HOME>/bin/and click on startup.sh script.
If you have no error messages, you can connect to BOS.
Connect to BOS

 Password: bpm
<JBOSS_HOME>\logs.
Check the MySQL database log for errors also.
3.2.7 Log errors
With your database server and web container running, point your web browser to
http://<SERVERADDRESS:port>/bonita/.
Check the web server logs for errors: <JBOSS_HOME>\logs
Check your database log for errors also.
3.2.8 Troubleshooting
Here are some potential issues and possible explanations:
Behavior Possible explanation

Unable to create datasource instance mysql-ds.xml contains error (property is missing)
check your datasource definition (eg JBoss)
ClassNotFoundException: com.mysql.jdbc.Driver forgot to add jdbc drivers
Access denied: Connections could not be wrong username password specified in mysql-
acquired from the underlying database! ds.xml

Bos 5.5 Bundle Installation Guide 2

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Bos 5.5 Bundle Installation Guide 2

Uploaded by

Copyright:

Available Formats

Bonita Open Solution

BOS Bundle Installation Guide

Bonita Open Solution

In this document, Bonita Open Solution is referred to as BOS.

This document has 3 parts:

Part 1 General requirements for BOS installation

Part 1. Requirements for installing BOS

2.1 Install the BOS-Tomcat bundle

Download the BOS-Tomcat bundle from the BonitaSoft website

Unzip the BOS-Tomcat bundle in the folder of your choice.

Choose a location close to the root directory, for example

Note: Avoid spaces and special characters in the folder path.

2.1.1 Launch and verify BOS-Tomcat bundle installation with H2 database

 On Windows, go to <TOMCAT_HOME>\bin\ and click on startup.bat.

Point your web browser to http://<SERVERADDRESS>:8080/bonita.

2.2.1 Set up 2 databases in MySQL to be used with the BOS-Tomcat bundle

Create 2 databases in MySQL:

2.2.2 Configure the access privileges for MySQL

Create a dedicated user and password:

Note: this can be changed later.

2.2.3.1 Edit the 2 Properties files

The 2 properties files are:

To edit them, you will:

2. activate the MySQL properties in:

These modifications are shown below.

1. de-activate H2 properties for bonita-journal.properties located at:

result after change in green:

result after change in green:

result after change in green:

2. Do the same for the H2 bonita-history.properties file, located at:

3. Activate MySQL properties for the bonita-journal.properties file, located at:

result after change in green:

result after change in green:

result after change in green:

4. Do the same for the H2 bonita-history.properties file located at:

2.2.3.2 Edit the data source file

Locate the data source configuration file called context.xml:

1. Replace the configuration for the bonita/default/journal

result after change with new MySQL line in green:

2. Replace the configuration for bonita/default/history

result after change with new MySQL line in green:

2.2.4 Download and install the MySQL driver

Download the MySQL driver (http://dev.mysql.com/downloads/connector/j/).

Remove the file h2-1.2.139.jar from this location to avoid conflicts.

2.2.5 Add the license file (for SP version only)

Copy your SP license file to: <TOMCAT_HOME>\bonita\server\licenses.

2.2.6 Validate the database re-configuration

 On Windows, go to <TOMCAT_HOME>\bin\ and click on startup.bat.

If you have no error messages, you can connect to BOS.

Point your web browser to http://<SERVERADDRESS>:8080/bonita.

 Username: admin, john, jack, or james

2.2.7 Log errors

Check your database log for errors also.

Here are some potential issues and possible explanations:

Behavior Possible explanation

3.1 Install the BOS-JBoss bundle

Download the BOS-JBoss bundle from the BonitaSoft website

Unzip the BOS-JBoss bundle in the folder of your choice.

Choose a location close to the root directory, for example

Note: Avoid spaces and special characters in folder path.

 On Windows, go to <JBOSS_HOME>\bin\ and click on run.bat.

Point your web browser to http://<SERVERADDRESS>:8080/bonita.

 Username: admin, john, jack, or james

3.2 Configure BOS-JBoss bundle for use with MySQL.