Chapter 3. Persistence Setups

3.1. Configuring Persistence for Business Central

Red Hat JBoss BRMS 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:

  1. Prepare your database:

    1. Go to the Product Downloads on the Customer Portal and select Red Hat JBoss BRMS.
    2. Download Red Hat JBoss BRMS 6.4.0 Supplementary Tools.
    3. Unzip jboss-brms-bpmsuite-6.4-supplementary-tools/ddl-scripts, for example into /tmp/ddl.
    4. 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
  2. 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.

  3. 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
    Note

    Always 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.

  4. Register the data source in Business Central:

    1. Open EAP_HOME/standalone/deployments/business-central.war/WEB-INF/classes/META-INF/persistence.xml.
    2. 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>
    3. Locate the <properties> tag and change the hibernate.dialect property, for example:

      <property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect" />

3.2. 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 the org.hibernate.loader category of the logger to ERROR in the standalone.xml file:

<logger category="org.hibernate.loader">
  <level name="ERROR"/>
</logger>