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:

  1. Prepare your database:

    1. Go to the Product Downloads on the Customer Portal and select Red Hat JBoss BPM Suite.
    2. Download Red Hat JBoss BPM Suite 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. 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”.

Important

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:

  1. Prepare your database:

    1. Go to the Product Downloads on the Customer Portal and select Red Hat JBoss BPM Suite.
    2. Download Red Hat JBoss BPM Suite 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/postgres-dashbuilder-schema.sql
  2. Install the Java Database Connectivity (JDBC) driver onto your application plaform. For more information, see Section 3.1, “Configuring Persistence for Business Central”.
  3. Create a new data source in EAP_HOME/standalone/configuration/standalone.xml. For more information, see Section 3.1, “Configuring Persistence for Business Central”.
  4. Register the data source in Dashbuilder:

    1. Open EAP_HOME/standalone/deployments/dashbuilder.war/WEB-INF/jboss-web.xml.
    2. Change the <jndi-name> to the JNDI name of your data source, for example:

      <jndi-name>java:jboss/datasources/PostgresqlDS</jndi-name>
  5. Add the module dependency for the driver:

    1. Open the EAP_HOME/standalone/deployments/dashbuilder.war/WEB-INF/jboss-deployment-structure.xml file and locate the <dependencies> tag.
    2. Add the JDBC driver module, for example:

      <module name="org.postgres"/>

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:

  1. Open EAP_HOME/standalone/configuration/standalone.xml and locate the <system-properties> tag.
  2. 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 the org.hibernate.loader category of the logger to ERROR in the standalone.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 or lo data columns, from a PostgreSQL database. In Red Hat JBoss BPM Suite, the text columns hold large object as well. As vacuumlo does not analyze any other columns than oid or lo, active objects may be deleted.

To prevent vacuumlo from deleting active large objects, run the postgresql-jbpm-lo-trigger-clob.sql script:

  1. 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.
  2. Make sure that the user which runs the script has the TRIGGER privilege on the Red Hat JBoss BPM Suite tables and the USAGE privilege to allow the use of the PL/pgSQL procedural language.
  3. 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.