Chapter 3. Persistence Setups
3.1. Configuring Persistence for Business Central
Red Hat JBoss BPM Suite is configured to use an example data source with Java Naming and Directory Interface (JNDI) name java:jboss/datasources/ExampleDS
. The example data source is not suitable for production.
To change the data source:
Prepare your database:
- Go to the Product Downloads on the Customer Portal and select Red Hat JBoss BPM Suite.
-
Download
Red Hat JBoss BPM Suite 6.4.0 Supplementary Tools
. -
Unzip
jboss-brms-bpmsuite-6.4-supplementary-tools/ddl-scripts
, for example into/tmp/ddl
. Import the DDL script for your database into the database you want to use, for example:
psql jbpm < /tmp/ddl/postgresql/postgresql-jbpm-schema.sql
Issue the following command to install the Java Database Connectivity (JDBC) driver onto your application platform:
./jboss-cli.sh (no need to actually connect to the server) module add --name=org.postgresql --resources=/path/to/postgresql-jdbc-driver.jar --dependencies=javax.api,javax.transaction.api
For further information about deploying JDBC drivers, see Install a JDBC Driver as a Core Module of the Red Hat JBoss Enterprise Application Platform Administration and Configuration Guide.
Connect to the running server and create the driver and data source, for example:
./jboss-cli.sh --connect --controller=HOST:PORT /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=org.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource) xa-data-source add --driver-name=postgresql --password=SOME_PASSWORD --user-name=SOME_USERNAME --xa-datasource-properties=url=jdbc:postgresql://localhost:5432/jbpm --name=PostgresqlDS --jndi-name=java:jboss/datasources/PostgresqlDS
NoteAlways use a distributed (XA) data source with the JBoss BPM Suite persistence service.
In general, you should use an XA data source when multiple resources are involved in a single transaction. For example, if you are using a Java Messege Service (JMS) executor (which is used by default when asynchronous tasks are included) or timers based on Quartz, you should use an XA data source.
Register the data source in Business Central:
-
Open
EAP_HOME/standalone/deployments/business-central.war/WEB-INF/classes/META-INF/persistence.xml
. Locate the
<jta-data-source>
tag and change it to the JNDI name of your data source, for example:<jta-data-source>java:jboss/datasources/PostgresqlDS</jta-data-source>
Locate the
<properties>
tag and change thehibernate.dialect
property, for example:<property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect" />
-
Open
3.2. Configuring Persistence for Dashbuilder
Dashbuilder depends on the configuration of Business Central. Ensure that Business Central is configured according to Section 3.1, “Configuring Persistence for Business Central”.
On Unix-like systems override the default value of MySQL lower_case_table_names
from 0
(case sensitive) to 1
(case insensitive). The Red Hat JBoss BPM Suite KPI queries are written in lowercase, but the table names are in CamelCase. By changing the lower_case_table_names
property you prevent exceptions from occurring later on.
To change the database for Dashbuilder:
Prepare your database:
- Go to the Product Downloads on the Customer Portal and select Red Hat JBoss BPM Suite.
-
Download
Red Hat JBoss BPM Suite 6.4.0 Supplementary Tools
. -
Unzip
jboss-brms-bpmsuite-6.4-supplementary-tools/ddl-scripts
, for example into/tmp/ddl
. Import the DDL script for your database into the database you want to use, for example:
psql jbpm < /tmp/ddl/postgresql/postgres-dashbuilder-schema.sql
- Install the Java Database Connectivity (JDBC) driver onto your application plaform. For more information, see Section 3.1, “Configuring Persistence for Business Central”.
-
Create a new data source in
EAP_HOME/standalone/configuration/standalone.xml
. For more information, see Section 3.1, “Configuring Persistence for Business Central”. Register the data source in Dashbuilder:
-
Open
EAP_HOME/standalone/deployments/dashbuilder.war/WEB-INF/jboss-web.xml
. Change the
<jndi-name>
to the JNDI name of your data source, for example:<jndi-name>java:jboss/datasources/PostgresqlDS</jndi-name>
-
Open
Add the module dependency for the driver:
-
Open the
EAP_HOME/standalone/deployments/dashbuilder.war/WEB-INF/jboss-deployment-structure.xml
file and locate the<dependencies>
tag. Add the JDBC driver module, for example:
<module name="org.postgres"/>
-
Open the
3.3. Configuring Persistence for the Intelligent Process Server
It is best practice to use a separate server for Intelligent Process Server, not the same server as for Business Central. Also, if you want to use Business Central and Intelligent Process Server as separate execution engines, use different databases for them. If you want to use Business Central and Intelligent Process Server as unified execution engines for shared data, ensure that the configuration for them is exactly the same, including the database, scheduler, executor, and KJAR deployments. For more information, see Unified Execution Servers in the Red Hat JBoss BPM Suite Administration and Configuration Guide.
To change the database for the Intelligent Process Server:
-
Open
EAP_HOME/standalone/configuration/standalone.xml
and locate the<system-properties>
tag. Add the following properties:
-
org.kie.server.persistence.ds
: The JNDI name of your data source. org.kie.server.persistence.dialect
: The hibernate dialect for your database.For example:
<system-properties> <property name="org.kie.server.repo" value="${jboss.server.data.dir}"/> <property name="org.kie.example" value="true"/> <property name="org.jbpm.designer.perspective" value="full"/> <property name="designerdataobjects" value="false"/> <property name="org.kie.server.user" value="bpmsUser"/> <property name="org.kie.server.pwd" value="bpms123!"/> <property name="org.kie.server.location" value="http://localhost:8080/kie-server/services/rest/server"/> <property name="org.kie.server.controller" value="http://localhost:8080/business-central/rest/controller"/> <property name="org.kie.server.controller.user" value="kieserver"/> <property name="org.kie.server.controller.pwd" value="kieserver1!"/> <property name="org.kie.server.id" value="local-server-123"/> <!-- Data source properties. --> <property name="org.kie.server.persistence.ds" value="java:jboss/datasources/KieServerDS"/> <property name="org.kie.server.persistence.dialect" value="org.hibernate.dialect.PostgreSQLDialect"/> </system-properties>
-
3.4. Troubleshooting
- IBM DB2 database has problems with Dashbuilder
If you want to use an IBM DB2 database as the underlying data source for Business Central, increase the page size for the database. The default page size of 4 kB is not sufficient for the Dashbuilder table columns size.
When creating the database, force the page size to 16384 as in the example below:
Example 3.1. Adjusting Page Size
CREATE DATABASE dashb PAGESIZE 16384
This increase in page size for the underlying database must be performed before the Red Hat JBoss BPM Suite has been run for the first time.
- Non-English characters are not displayed in Dashbuilder
If you want to use UTF 8 to display non-English characters, set the encoding at the level of database for Dashbuilder to work correctly. For example, in MySQL, add the following to the server configuration file:
[mysqld] character-set-server=utf8 collation-server=utf8_general_ci
- Deadlocks occur with Microsoft SQL Server
- If you are using Microsoft SQL Server, make sure you have configured proper transaction isolation for your database. If you do not, you may experience deadlocks. The recommended configuration is to turn on ALLOW_SNAPSHOT_ISOLATION and READ_COMMITTED_SNAPSHOT by entering the following statements:
ALTER DATABASE <DBNAME> SET ALLOW_SNAPSHOT_ISOLATION ON ALTER DATABASE <DBNAME> SET READ_COMMITTED_SNAPSHOT ON
- Oracle 11 produces multiple warnings without any cause
When you use Oracle 11 as the data source, multiple warning (
WARN
) messages are produced in the logs without any corresponding Business Central activity being performed. This is expected behavior. To turn off these messages, set the level of theorg.hibernate.loader
category of the logger toERROR
in thestandalone.xml
file:<logger category="org.hibernate.loader"> <level name="ERROR"/> </logger>
- Vacuumlo deletes active large objects of Red Hat JBoss BPM Suite CLOB data
The vacuumlo utility program removes large objects, whose OIDs are not available in the
oid
orlo
data columns, from a PostgreSQL database. In Red Hat JBoss BPM Suite, thetext
columns hold large object as well. As vacuumlo does not analyze any other columns thanoid
orlo
, active objects may be deleted.To prevent vacuumlo from deleting active large objects, run the
postgresql-jbpm-lo-trigger-clob.sql
script:-
Download Red Hat JBoss BPM Suite 6.4.2 Supplementary Tools from the Red Hat Customer Portal. The script is located in the
ddl-scripts/postgresql/
directory. -
Make sure that the user which runs the script has the
TRIGGER
privilege on the Red Hat JBoss BPM Suite tables and theUSAGE
privilege to allow the use of the PL/pgSQL procedural language. Run the script to create triggers and and the
jbpm_active_clob
table:\i postgresql-jbpm-lo-trigger-clob.sql
After performing these steps,
jbpm_active_clob
is maintained by the trigger and CLOB references cannot be deleted by vacuumlo.-
Download Red Hat JBoss BPM Suite 6.4.2 Supplementary Tools from the Red Hat Customer Portal. The script is located in the