Published on Bonita Documentation (http://documentation.bonitasoft.

com)

Database configuration
Product version:
6.3
Product edition:
Teamwork
Efficiency
Performance
Database usage
Business Data data sources
Default h2 database
Database creation
Specify db vendor
Add the database driver
Configure the datasource
Change to another database (not default h2)
Specific database configuration - PostgreSQL
Specific database configuration - MS SQL
Specific configuration database- MySQL
Specific configuration database - Oracle DB

Database usage
Bonita BPM Engine uses a database to store information about deployed processes definition,
processes configuration, history of process execution, users, etc. One database schema is
required by Bonita to store all information.
Connection to the database is through Hibernate (version 4.2). This provides a level of
abstraction between Bonita and DBMS. Bonita comes with a set of optimized initialization
scripts for the supported DBMSs.

Business Data datasources

In the new feature Business Data Management, two new datasources have been added:
BusinessDataDS, NotManagedBizDataDS. Use the standard method to change the default
h2 database to a replacement by changing the datasources configuration. You will need to
make the new business datasource point to an alternative database too, if necessary.
For better performance, Bonita uses the JEE application server data source feature. Data
sources usually offer connection pooling, which significantly improves performance.

Bonita also relies on the JTA (Java Transaction API) JEE service. This service is not available
in a standard Tomcat setup because it is not a full JEE application server. In order to get JTA
support in Tomcat, Bonita includes the Bitronix library.
Bonita BPM Engine use two data sources:
Hibernate data source
Used to store Java objects in a database.
Uses transaction provided by JTA.
Uses Hibernate for conversion between Java object to SQL queries.
Sequence data source
Used to get unique id for persisted objects.
Does not use JTA.
Does not use Hibernate (only runs standard SQL queries).

Default h2 database
Bonita BPM Studio, and the Tomcat and JBoss bundles come with a default h2 database
included in the package.
h2 is suitable for testing only. For production purposes, you should modify the configuration to
use another database.
In order to configure Bonita BPM to work with your DBMS, you will need to perform the
following steps:
Database creation
Specify the database vendor
Add the database driver
Configure data source
Remove h2
DBMS specific configuration

Database creation
Warning: Some databases require specific configuration, which must be done before you
complete your installation. If you do not complete the specific configuration for your database,
your installation may fail.
Note: You will need to have already created a new "Bonita" database that you can name as
you like, as long as you remember to "point to it" in your configuration file.

Configure Bonita to work with another database

The first step in configuring Bonita with another DBMS would be to create a new database
(schema).
In order to do so, make sure you have a DBMS user account that has sufficient privileges.

Note: the new Bonita database name you use will be needed in the following configuration
steps.
Also note that owner of the new schema must have following privileges:
CREATE TABLE
CREATE INDEX
SELECT, INSERT, UPDATE, DELETE on created TABLE
Note: CREATE TABLE and CREATE INDEX are no longer required after first start.
See also Set up a database schema with SQL Server 2012
See also Create a schema (Transact-SQL)

Specify the database vendor

Bonita BPM Engine and your application server need to know which type of DBMS you are
using. This must be set as an environment variable,db.vendor, in the application server
configuration.
For Tomcat, edit setenv.sh (for Linux) or setenv.bat (for Windows) and modify the
DB_OPTS. For example: set DB_OPTS="Dsysprop.bonita.db.vendor=mysql"
For JBoss, edit server\default\deploy\properties-service.xml and set the
value of sysprop.bonita.db.vendor. For example:
sysprop.bonita.db.vendor=postgres
For other application servers, either use a setenv file as with Tomcat, or set the variable
as described in the application server documentation.
The possible settings for db.vendor are:
Database vendor

Property value

MySQL

mysql

MS SQL

sqlserver

PostgreSQL

postgres

Oracle database

oracle

h2 (default for testing, not for production)

h2

It is also possible to set db.vendor in the bonita-platform.properties file of your

bonita_home, but this is not recommended. The default setting in bonitaplatform.properties is db.vendor=${sysprop.bonita.db.vendor:h2}
This means that db.vendor is set to the value of the system property if it is set, or to h2
otherwise. If you set the database vendor explicitly in bonita-platform.properties, you
also need to set it as an environment variable for your application server. For simplicity and to
avoid error, we strongly recommend that you configure the db.vendor only in an environment

variable, and you do not change bonita-platform.properties.

Add the database driver

Download
First you need to download the JDBC driver for your database system. Use links below to
download the driver directly.
Database vendor

Download link

MySQL

download

Microsoft SQL Server

download

PostgreSQL (use "Current Version")

download

Oracle Database

download

Note that if you run on Linux, JDBC driver might also be available in the distribution packages
repository. On Ubuntu and Debian you can for example install the libpostgresql-jdbcjava package to get the PostgreSQL JDBC Driver (install in /usr/share/java ).

Add JDBC driver to application server

The way to install the JDBC driver depend on the application server and the way this one is
installed:
Tomcat 6 or 7
Bonita Tomcat bundle: in the bundle folder add the driver to the lib/bonita
folder.
zip distribution: in the Tomcat folder add the driver to the lib/bonita folder.
Ubuntu/Debian package: add the driver to /usr/share/tomcat6/lib or
/usr/share/tomcat7/lib.
Windows as a service: add the driver to C:\Program Files\Apache
Software Foundation\Tomcat 6.0\lib or C:\Program Files\Apache
Software Foundation\Tomcat 7.0\lib
JBoss 5.1
Bonita JBoss bundle: inside bundle folder add the driver to the
server/default/lib folder.
zip distribution: in the JBoss folder add the driver to the server//lib folder.

Configure the data source

As explained on the overview page, Bonita requires the configuration of two data sources.
The data source declaration will define how to connect to the DBMS. The following
information is required to configure the data sources:
Address of the DBMS server.
Port number of the DBMS server.
Database name.

User name to connect to the database.

Password to connect to the database.
JDBC Driver fully qualified class name (see table below).
XADataSource fully qualified class name (see table below).
Database
vendor

Driver class name

XADataSource class name

MySQL

com.mysql.jdbc.Driver

com.mysql.jdbc.jdbc2.optional.MysqlXAD

Microsoft
com.microsoft.sqlserver.jdbc.SQLServerDriver com.microsoft.sqlserver.jdbc.SQLServerX
SQL Server
PostgreSQL org.postgresql.Driver

org.postgresql.xa.PGXADataSource

Oracle
Database

oracle.jdbc.driver.OracleDriver

oracle.jdbc.xa.client.OracleXADataSource

h2 (not for
production)

org.h2.Driver

org.h2.jdbcx.JdbcDataSource

Tomcat
Configuration of data source for Tomcat is a little bit specific. As Tomcat doesn't support JTA
natively, one data source will be configured in the Bitronix configuration file and the other data
source will be configured in the standard Tomcat context configuration file.
JTA data source (managed by Bitronix)
Open /conf/bitronix-resources.properties file.
Remove or comment the lines regarding the h2 database.
Uncomment the line matching your DBMS.
Update the value for the following settings:
resource.ds1.driverProperties.user put your DBMS user name.
resource.ds1.driverProperties.password put your DBMS password.
resource.ds1.driverProperties.serverName put the address (IP or
hostname) of your DBMS server.
resource.ds1.driverProperties.portNumber put the port of your DBMS
server.
resource.ds1.driverProperties.databaseName put the database name.
Save and close the file.
Non-transactional data source
The second data source run SQL queries outside any transaction. To configure it:
Open /conf/Catalina/localhost/bonita.xml file.
Remove or comment the lines regarding h2 database.
Uncomment the line matching your DBMS.
Update following attributes value:
username with your DBMS user name.

password with your DBMS password.

url: note that URL include: DBMS server address, DBMS server port and
database name

Business Data data source configuration for Tomcat

Tomcat datasource configuration
For Business data data source, change the last 4 lines of the resource named
NotManagedBizDataDS found in Tomcat
folder/conf/Catalina/localhost/bonita.xml.

username="sa" password="" driverClassName="org.h2.Driver"

url="jdbc:h2:tcp://localhost:9091/business_data.db;MVCC=TRUE;DB_CLOSE_ON_EXIT
Bitronix configuration
For Business data data source (default name DS2 specific to business data), change the DS2
to DBMS value.
To do this:
Open /conf/bitronix-resources.properties file.
Update the value for the following settings:
resource.ds2.driverProperties.user put your DBMS user name.
resource.ds2.driverProperties.password put your DBMS password.
resource.ds2.driverProperties.serverName put the address (IP or
hostname) of your DBMS server.
resource.ds2.driverProperties.portNumber put the port of your DBMS
server.
resource.ds2.driverProperties.databaseName put the database name.
Save and close the file.
In addition, change the dialect in the following file: \server\platform\tenanttemplate\conf\bonita-server.properties
before changes (MySQL example):
businessdata.hibernate.dialect=org.hibernate.dialect.H2Dialect
after changes (MySQL example):
businessdata.hibernate.dialect=org.hibernate.dialect.MySQLDialect
Note: if the tenant is already created, then the user should change the /server/tenants/
/conf/bonita-server.properties as the business database configuration is at a tenant
level.

Business Data data source configuration for JBoss

To configure the data source for JBoss:
If you want to change the configuration of the engine database, modify the configuration of

two data sources: the XA data source called bonitaDS and the no-tx data source called
bonitaSequenceManagerDS
Open the /server/default/deploy/bonita-ds.xml file.
Remove or comment the 2 blocks regarding the h2 database ( and ) as above.
Go to Examples, and uncomment the line matching your DBMS.
Update value for the following settings in :
with your DBMS user name.
with your DBMS password.
with the address (IP or hostname), port of your DBMS server, and database name.
5. Update value for the following settings in :
with your DBMS user name.
with your DBMS password.
with the address (IP or hostname), port of your DBMS server, and database name.
Save
and close the file.
6.
1.
2.
3.
4.

In addition, change the dialect in the following file: \server\platform\tenanttemplate\conf\bonita-server.properties

before changes(MySQL example):
businessdata.hibernate.dialect=org.hibernate.dialect.H2Dialect
after changes (MySQL example):
businessdata.hibernate.dialect=org.hibernate.dialect.MySQLDialect
Note: if the tenant is already created, then the user should change the /server/tenants/
/conf/bonita-server.properties as the business database configuration is at a tenant
level.
If you want to change the configuration of the Business Data database, modify the
configuration of two data sources: the XA data source called BusinessDataDS and the no-tx
data source called NotManagedBizDataDS
Open the /server/default/deploy/bonita-ds.xml file.
Remove or comment the 2 blocks regarding the h2 database ( and ) as above.
Go to Examples, and uncomment the line matching your DBMS.
Update value for the following settings in :
with your DBMS user name.
with your DBMS password.
with the address (IP or hostname), port of your DBMS server, and database name.
5. Update value for the following settings in :
with your DBMS user name.
with your DBMS password.
with the address (IP or hostname), port of your DBMS server, and database name.
6. Save and close the file.
1.
2.
3.
4.

Change to another database (Not default h2)

Warning: If you use the default configuration for business data, do not remove h2. The
standard way to change the database from H2 to another has not changed.

If you want to change the default h2 database to another, you will need to go through the
following steps to remove h2.
Remove h2 listener, so that H2 is not started automatically.
Tomcat: comment out the H2 listener in the /conf/server.xml file.
JBoss: remove the mbean declaration in the
server/your_server_configuration/deploy/bonita-ds.xml file
Remove h2 jar files (bonita-jboss-h2-mbean-1.0.0.jar, bonita-tomcat-h2-listener1.0.1.jar, h2-1.3.170.jar)
Tomcat: files are located in: /lib or in /lib/bonita.
JBoss: files are located in: server//lib
To make sure that the H2 is not run, go to run.conf.batfile in /bin/ and in "set
Bonita OPTS", remove the part which refers to H2.

Specific database configuration - PostgreSQL

Before you start PostgreSQL, edit postgresql.conf and set a non-zero value for
max_prepared_transactions. The default value, 0, disables prepared transactions, which
is not recommended for Bonita BPM Engine. The value should be at least as large as the
value set for max_connections. See the PostgreSQL documentation for details.

Specific configuration - MS SQL

XA Transactions
MS SQL Server requires specific configuration in order to support XA transactions.
You can refer to MSDN for more information.
Here is the list of steps to perform:
1. Download the Microsoft SQL Server JDBC Driver 4.0 from Microsoft web site.
2. Install it (run the.exe).
3. Copy the sqljdbc_xa.dll from
%JDBC_DRIVER_INSTALL_ROOT%\sqljdbc_4.0\enu\xa\x64\ (x64 for 64 bit
version of Windows, x86 for 32 bit version of Windows) to
%SQLSERVER_INSTALL_ROO%\Instance_root\MSSQL10.MSSQLSERVER\MSSQL\Binn\.
4. Copy/paste the content of xa_install.sql file (located in
%JDBC_DRIVER_INSTALL_ROOT%\sqljdbc_4.0\enu\xa) to SQL Server Management
Studio's Query Editor.
5. Then execute it.
6. To confirm successful execution of the script, you should open the "Object Explorer" and
go to: Master > Programmability > Extended Stored Procedures.
7. Here you should have 12 new procedures with name starting with
dbo.xp.sqljdbc_xa_.
8. Next step is to assign the new role 'SqlJDBCXAUser' to the user who owns the Bonita
database.
9. Create a new Login (you may use the Microsoft SQL Management Studio)e.g. bonitadev

10. Execute following command in SQL editor: USE master GO CREATE USER
'bonitadev', 'bonitadev' GO sp_addrolemember [SqlJDBCXAUser],
'bonitadev'
11. In Windows "Start" menu select Administrative Tools-> Services.
12. In "Services" window, make sure that the Distributed Transaction Coordinator service
is set to start automatically. If it's not yet started, start it.
13. Also make sure that the other services it depends on, namely "Remote Procedure Call"
and "Security Accounts Manager" are also set to start automatically.
14. Then run dcomcnfg command or go inside "Start" menu to Administrative Tools >
Component Services.
15. In the left navigation pane, navigate to Component Services > Computers > My
Computer > Distributed Transaction Coordinator
16. Select and right-click on Local DTC and thenProperties.
17. Click on Security tab. Ensure that the checkbox for Enable XA Transactions is
checked.
18. Click Apply then OK
19. Then stop and restart SQLServer.
20. Create BONITA_v6 database CREATE DATABASE BONITA_v6 GO
21. Set bonitadev as owner of BONITA_v6 database (use for example: 'Microsoft SQL
Management Studio')

Recommended configuration for lock management

Run the script below to avoid deadlock:
ALTER DATABASE BONITA_v6 SET SINGLE_USER WITH ROLLBACK IMMEDIATE
ALTER DATABASE BONITA_v6 SET ALLOW_SNAPSHOT_ISOLATION ON
ALTER DATABASE BONITA_v6 SET READ_COMMITTED_SNAPSHOT ON
ALTER DATABASE BONITA_v6 SET MULTI_USER
See MSDN.
Note about Hibernate configuration
Only the org.hibernate.dialect.SQLServerDialect Hibernate dialect is supported.
Hence org.hibernate.dialect.SQLServer2005Dialect and
org.hibernate.dialect.SQLServer2008Dialect dialects are not supported.

Specific configuration - MySQL

MySQL define a maximum packet size both on server side. The default value for this settings
should be fine in most standard use cases. If you get:
Error: 1153 SQLSTATE: 08S01 (ER_NET_PACKET_TOO_LARGE) Message: Got a
packet bigger than 'max_allowed_packet' bytes
you will need to adjust this setting.
On the MySQL server side, you need to update the file my.ini (for Windows) or my.cnf (for

Linux) to avoid the ER_NET_PACKET_TOO_LARGE problem. Look for max_allowed_packet

settings and adjust the value.
For more information, see the Mysql website.

Specific configuration - Oracle Database

Make sure your database is configured to use the AL32UTF8 character set. If your database
already exists, see the Oracle documentation for details of how to migrate the character set.
To use the transaction, (XADataSource) it requires extra privileges for the Oracle user used
by Bonita, and also specific settings for XA activation.
Important information for a successful connection
The procedure below is used to create the settings in order to enable the Bonita BPM to
connect to the Oracle Database.
It is assumed in the procedure that:
Oracle product is already installed and running
An 'Oracle' OS user is already created
A database already exists
The environment is already set:
ORACLE_HOME=/u01/app/oracle/product/11.2.0/dbhome_1 ORACLE_SID=...

1. Connect as the System Administrator

SQL query >
oracle@ubuntu:~$ sqlplus / as sysdba

1.1 Check that the following components exist and are valid:
SQL query >
select comp_name, version, status from dba_registry;
Comp_name

Version

Status

Oracle Database Catalog Views

11.2.0.1.0

VALID

Oracle Database Packages and Types

11.2.0.1.0

VALID

JServer JAVA Virtual Machine

11.2.0.1.0

VALID

Oracle XDK

11.2.0.1.0

VALID

Oracle Database Java Packages

11.2.0.1.0

VALID

OLAP Analytic Workspace

11.2.0.1.0

VALID

Oracle OLAP API

11.2.0.1.0

VALID

2. Add XA elements
SQL query >
@/u01/app/oracle/product/11.2.0/dbhome_1/javavm/install/initxa.sql
This only needs to be done once, after the installation of Oracle.

3. Create user to be used by the Bonita Engine and grant the proper rights
SQL query >
@/u01/app/oracle/product/11.2.0/dbhome_1/rdbms/admin/xaview.sql
The following queries must be done for each new user: i.e. one user = one database schema.
SQL query >
CREATE USER bonita IDENTIFIED BY bonita; GRANT connect, resource TO
bonita IDENTIFIED BY bonita; GRANT select ON
sys.dba_pending_transactions TO bonita; GRANT select ON
sys.pending_trans$ TO bonita; GRANT select ON sys.dba_2pc_pending TO
bonita; GRANT execute ON sys.dbms_system TO bonita; GRANT select ON
sys.v$xatrans$ TO bonita;

2014 Bonitasoft, Inc. All rights reserved.