Configuring INUBIT in the ibis.xml File

Configuration file

<inubit-installdir>/inubit/server/ibis_root/conf/ibis.xml

<Properties version="4.1">
  <Property name="LocalMaintenanceMode" type="Boolean">false</Property>
  <Property name="Database" type="Map">
    <Property name="driverClass">org.h2.Driver</Property>
    <Property name="jdbcUrl">jdbc:h2:${ibis.root.directory}/ibis_data/database/ibis;MVCC=TRUE</Property>
    <!-- Encrypted password and/or user name
      To get your encrypted password and/or user name use the CLI client.
      Example:
        cd path/to/inubit_installation/server/process_engine/bin
        ./startcli.sh -\-encryptString myPassword
      Insert the encrypted password and/or user name as values into the corresponding
      property tags and set the
      attribute encrypted="false" to encrypted="true".
      Example:
        <Property name="user" type="EncryptedString" encrypted="true">AES-ZKEFCtfXeLAmGUdQ2zomyA==</Property>
        <Property name="password" type="Password" encrypted="true">AES-ZKEFCtfXeLAmGUdQ2zomyA==</Property>
    -->
    <Property name="user" type="EncryptedString" encrypted="false">sa</Property>
    <Property name="password" type="Password" encrypted="false"></Property>
    <Property name="socketTimeoutInMillisecs" type="Long">180000</Property>
    <Property name="checkoutTimeoutInMillisecs" type="Long">120000</Property>
    <Property name="driverProperties" type="Map"/>
    <Property name="minPoolSize" type="Integer">5</Property>
    <Property name="maxPoolSize" type="Integer">30</Property>
  </Property>
  <Property name="DataSourceLocation">java:/comp/env/jdbc/IBISDB</Property>
  <Property name="RuntimeDataBackupStore">FILE</Property>
  <Property name="RuntimeDataCacheXMXPercentage" type="Integer">25</Property>
  <!-- Retry happens based on number of retries configured below -->
  <Property name="noOfRetries" type="Integer">3</Property>
  <!-- Retry interval value should be given in milliseconds-->
  <Property name="retryInterval" type="Long">2000</Property>
  <Property name="MaxEntriesInMemoryLimit" type="Map">
    <Property name="Workflow_Data_Version" type="Integer">-1</Property>
    <Property name="Module_Data_Version" type="Integer">-1</Property>
  </Property>
  <Property name="indexEnabled" type="Boolean">false</Property>
</Properties>xml

Configuring the Database in the ibis.xml File

Usage

Set the parameters for database access

Properties

Property type

type=Map

Possible values

Map

Indicates that this property can contain further sub-properties as structure

Database driver

driverClass=oracle.jdbc.OracleDriver

Possible values

Oracle driver
MS SQL driver
MySQL driver

JDBC URL

jdbcUrl=jdbc:oracle:thin:@oracle:1521:InubitDB

Possible values

Oracle JDBC URL
MS SQL JDBC URL
MySQL JDBC URL

For MySQL before version 5.7, it is only possible to communicate over TLS 1.2 when adding the property enabledTLSProtocols=TLSv1.2 to the database URL.

Username

User=<Username>
encrypted="{true|false}"text

true: The specified username is encrypted.

false: The specified username is not encrypted and is replaced by the encrypted username the first time the server starts. The attribute encrypted="true" is set automatically.

Refer to Encrypting Usernames and Passwords via CLI

Password

password=<Password>

encrypted="{true|false}"

true: The specified password is encrypted.

false: The specified password is not encrypted and is replaced by the encrypted password the first time the server starts. The attribute encrypted="true" is set automatically.

Refer to Encrypting Usernames and Passwords via CLI

Socket timeout

socketTimeoutInMillisecs=180000

For configuration of the timeout for the socket connection between the JDBC driver and database. The value determines both, the connect and read timeout. The default value is 180'000 ms (3 minutes).

Connection timeout for connection pooling

checkoutTimeoutInMillisecs=120000

For configuration of the timeout for waiting for the provision of a database connection for the database connection pool. The default value is 120'000 ms (2 minutes).

Number of database connections

minPoolSize=5
maxPoolSize=30text

These two parameters determine how many database connections must be used at a minimum as well as how many can be used simultaneously. The default values are 5 and 30.

Remove abandoned database connections

removeAbandoned={true|false}

true

A database connection is removed once the timeout configured in the removeAbandonedTimeout property has expired.
false (default)

Database connections are not removed even if they are not used for some time.

Timeout to Remove abandoned database connections

removeAbandonedTimeout=21600

If the removeAbandoned property is set to true, a database connection is removed once the timeout in seconds configured in the removeAbandonedTimeout property has expired. By default, the removeAbandonedTimeout property is set to 21'600 seconds (6 hours).

The value should be set to the longest running query your applications might have.

Valid connection check

CheckValidConnection={true|false}

true: In case of an invalid connection, the next connection from the pool is selected automatically.

By default, this property is set to true. To disable the property, set it to false.

When this property is enabled, the performance may be slightly affected.

Database query retry and retry delay

noOfRetries=3
retryInterval=2000text

In case of cache database errors, the query execution can be retried for a number of times specified in noOfRetries. Each retry will happen after a delay of time specified in retryInterval (in milliseconds).

For MSSQL deadlocks, the following applies:

In case of frequent deadlocks in the MSSQL database, you can try to increase the number of retries and the delay between each retry.

The default values for these properties for MSSQL are 3 retries and 2000 milliseconds retry interval.

To prevent a shutdown of the INUBIT Process Engine due to temporary database connectivity issues, a so-called leaky bucket mechanism can be configured, refer to Configuring Database Connectivity Loss Tolerance.

Allow using more than one schema (for MySQL 8 only, not recommended)

nullCatalogMeansCurrent={true|false}

If a database user has access to more than one schema: Add the extra parameter nullCatalogMeansCurrent=true to the database URL.

Limiting the Size of the Runtime Data Cache

Usage

Maximum allowable percentage of runtime data in the Java memory

Property

RuntimeDataCacheXMXPercentage=25

Memory Mode for Runtime Data

Usage

Determines how the runtime data is to be stored

Property

RuntimeDataBackupStore={FILE|DB|NONE}

Possible values

FILE (default)

Runtime data is stored in the file system .
DB

Runtime data is stored in the database.
NONE

Runtime data is not stored.

Configuring Retry and Retry Delay for the Cache Database

Usage

Set the parameters for cache database access

Property

noOfRetries=3
retryInterval=2000text

The default values are 3 retries and 2000 ms delay.

Configuring the Maintenance Mode

Usage

Configuring the maintenance mode of the Process Engine on startup.

Property

LocalMaintenanceMode=true | false

Possible Values

true

The local maintenance mode is activated.
false

The local maintenance mode is deactivated.

Configuring Memory for Version Data

Usage

This configuration is used to optimize the utilization of the available RAM by the INUBIT. Currently, this option is available only for module and workflow version data.

Properties

This setting determines the maximum number of process versions the Process Engine can store in memory (cache) at any time. Since multiple users and groups interact with the system, all their process versions contribute to this limit.

The system uses the Least Frequently Used (LFU) algorithm to manage the cache efficiently. This indicates that the least-accessed version will be deleted to make space for new versions when the cache reaches to its maximum.

<Property name="MaxEntriesInMemoryLimit" type="Map">
    <Property name="Workflow_Data_Version" type="Integer">-1</Property>
    <Property name="Module_Data_Version" type="Integer">-1</Property>
</Property>xml

MaxEntriesInMemoryLimit: Maximum entries in memory limit
Module_Data_Version: [1..n|-1] : Number of all module versions in cache
Workflow_Data_Version: [1..n|-1] : Number of all workflow versions in cache

Possible Values

-1: [Unlimited (default value)] : Cache capacity is set to unlimited.

This might result in issues with memory.

1..n: Cache capacity is set to this value. This indicates the maximum number of versions (module/workflow) loaded into memory at any point in time. This should be adjusted based on the system’s available memory and versions accessed during the process engine’s lifetime.

Timestamp Indexing on Infinispan

Usage

Controls the indexing behavior for timestamp columns in Infinispan tables.

Property

indexEnabled={true|false}

true: Enables indexing of Infinispan tables.

false: Disables indexing of Infinispan tables.

By default, this property is set to false. This keeps an existing INUBIT system backwards compatible. Indexing must be explicitly switched on and the system can be monitored.

If the parameter is set to `false` after indexing is applied, it will not trigger deindexing, because indexing has already been activated.

If you want to drop the index from existing Infinispan tables, follow these steps:

Set the property to false in ibis.xml after shutting down the Process Engine:
<Property name="indexEnabled" type="Boolean">false</Property>
Execute the appropriate SQL queries to drop the timestamp index from all ISPN tables based on your database type:
- MariaDB/MySQL
  ALTER TABLE <Database Name>
  DROP INDEX <Database Name>_timestamp_index;
- PostgreSQL
  DROP INDEX <Database Name>_timestamp_index;
- Microsoft SQL
  DROP INDEX <Database Name>_timestamp_index ON <Database Name>;
- Oracle
  DROP INDEX IDX_<Database Name>;
  
  Example: For a table named ISPN_EDI_RULES in MySQL/MariaDB:
  ALTER TABLE ISPN_EDI_RULES
  DROP INDEX ISPN_EDI_RULES_timestamp_index;
  
  These queries must be run on all the tables with the ISPN_ prefix.

Configuring the ClusterDebug

ClusterDebug={true|false}

true

Hint: The log level can be changed after booting in the Workbench via Administration → Logging → Trace.

When the server is restarted, it logs again at the DEBUG log level because ClusterDebug is true.
false

Hint: The log level can be changed after booting in the Workbench via Administration → Logging → Trace.

When the server is restarted, it logs again at the ERROR log level because ClusterDebug is false.

Configuring the iterationCount

The PBKDF2 (Password Based Key Derivation Function 2) user account password encryption algorithm uses an iterationCount to determine the number of times the hash algorithm is applied during the key derivation process. The iterationCount in PBKDF2 represents the number of times a pseudorandom function (such as HMAC-SHA256) is applied to a password to derive a secure key. The default value for iterationCount in ibis.xml is 20000.

Higher iterationCount: The hash function (such as HMAC-SHA256) is used more frequently during the key derivation process when the iterationCount is higher.

Advantages:
- Increased Security: Makes brute force and password cracking attempts more expensive for attackers.
- Key Strengthening: The derived key is protected against precomputed attacks (like rainbow tables) because each derivation is linked to the unique salt and the number of iterations.
Disadvantages:
- Slow down response times
- Decrease throughput
- Cause a short term spike in CPU and disk use
Lower iterationCount: The hash function is used less frequently when the iterationCount is lower.

Advantages:

Useful for low power devices or high traffic systems where speed is critical.

Disadvantages:

Decreased Security: Improves password cracking and brute force attacks quicker for attackers.