Tamaki MES Properties

This page consolidates all Spring configuration properties for Tamaki MES services.

Hibernate

Property	Default	Description
hibernate.jdbc.batch_size	50	Number of statements Hibernate will batch per roundtrip to the database. Increase to reduce network roundtrips; ensure your JDBC driver and DB support batching.

Notes

• Tuning: Start at 50–100. Validate with database metrics and profiling.
• Constraints: Consider triggers/sequences that may affect batching semantics.

Db

Driver-level connection properties that Tamaki MES requires on the Ignition database connection it uses, per database vendor. The properties are added only when the Allow Module to Manage Datasource gateway setting is enabled (it is off by default): the module then checks the datasource's Extra Connection Properties at startup (and when the MES datasource setting changes) and adds any required keys that are missing - exactly as if they were entered in the gateway web UI, including the automatic connection-pool restart. Keys you have set explicitly are never overridden; a differing explicit value is kept and logged as a warning. While the setting is disabled the module never modifies the connection; it only logs a startup warning if required properties are missing.

Property	Default	Description
db.extra_connection_properties.mssql	sendStringParametersAsUnicode=false	Required properties for Microsoft SQL Server connections (semicolon-separated key=value pairs).
db.extra_connection_properties.mysql	(empty)	Required properties for MySQL connections.
db.extra_connection_properties.mariadb	(empty)	Required properties for MariaDB connections.
db.extra_connection_properties.postgresql	(empty)	Required properties for PostgreSQL connections.

Notes

• Why sendStringParametersAsUnicode=false on SQL Server: the Microsoft JDBC driver sends string parameters as nvarchar by default, while Tamaki MES key columns are varchar. Under SQL Server collations the resulting implicit conversion prevents index seeks, so every keyed UPDATE scans an entire index under update locks. With many active OEE locations this causes severe lock contention and recurring deadlocks (Transaction ... was deadlocked on lock resources). Setting the property restores index seeks (measured: a point lookup drops from hundreds of logical reads to 3). Microsoft's own driver documentation recommends this setting for varchar-based schemas, which is what Tamaki MES creates.
• The properties are applied to the database connection selected as the MES datasource in the Tamaki MES gateway settings, not to other Ignition database connections.
• On redundant gateways, only the master node applies changes; the configuration synchronizes to the backup automatically.
• If you intentionally need a conflicting driver setting, set it explicitly in the gateway's Extra Connection Properties field - the module will respect it - or simply leave Allow Module to Manage Datasource disabled.

Unicode behavior on SQL Server (sendStringParametersAsUnicode=false)

With this property, string values are converted on the client, before they are sent, into the database collation's code page (code page 1252 for the common SQL_Latin1_General_CP1_CI_AS). Characters that exist in that code page - all ASCII plus Western-European characters such as é ü ñ ° ± µ ² ³ € ™ and curly quotes - are unaffected. Characters outside it - ≥ ≤ ≠ Δ →, Greek μ pasted from datasheets, macrons (ā ē ī ō ū), Cyrillic, CJK, emoji - are silently replaced with ?. No error is raised and nothing is logged; the write succeeds.

What this means per column type:

• varchar columns (all Tamaki MES tables): no new data loss. A varchar column under a non-UTF-8 collation physically cannot store these characters, so they were already being lost at storage time under the old setting. The only visible change: characters that previously degraded to a close ASCII look-alike (ā stored as a) are now stored as ?.
• nvarchar/nchar columns: real change. These store full Unicode, so under the old setting such values round-tripped intact. With the property, new writes through this connection store ? for out-of-code-page characters, and search parameters containing such characters stop matching (WHERE col = 'Δ-line' is sent as '?-line' and finds nothing). Reading existing rows is unaffected - stored data is never modified.

Example - a comment written into an nvarchar column through this connection:

	Stored value
Old (driver default)	Seal temp must be ≥ 135 °C (Δ ± 2°)
With the property	Seal temp must be ? 135 °C (? ± 2°)

Tamaki MES itself creates no nvarchar columns, so MES data is unaffected. The risk is the rest of the connection: the property changes driver behavior for everything using that database connection - named queries, scripts, tag history, alarm journal, audit profiles, other modules. Note that current Ignition 8.1 versions create their audit log and alarm journal tables with nvarchar columns on SQL Server, and customer/integration tables (ERP XML payloads, etc.) often use nvarchar too. For this reason we recommend a dedicated database connection for Tamaki MES.

Checking your database for affected columns

List every Unicode-capable column in the database (none of these = nothing to consider):

SELECT s.name AS schema_name, t.name AS table_name, c.name AS column_name, ty.name AS data_type
FROM sys.columns c
JOIN sys.tables  t  ON t.object_id = c.object_id
JOIN sys.schemas s  ON s.schema_id = t.schema_id
JOIN sys.types   ty ON ty.user_type_id = c.user_type_id
WHERE c.system_type_id IN (231, 239, 99)  -- nvarchar, nchar, ntext
  AND t.is_ms_shipped = 0
  AND t.name NOT LIKE 'DATABASECHANGELOG%'
ORDER BY s.name, t.name, c.name;

For any column of interest, check whether it already holds characters the code page cannot represent (replace table/column names):

SELECT COUNT_BIG(*) AS rows_checked,
       SUM(CASE WHEN CONVERT(nvarchar(max), CONVERT(varchar(max), x.v)) COLLATE Latin1_General_BIN2
                 <> x.v COLLATE Latin1_General_BIN2 THEN 1 ELSE 0 END) AS values_at_risk,
       MIN(CASE WHEN CONVERT(nvarchar(max), CONVERT(varchar(max), x.v)) COLLATE Latin1_General_BIN2
                 <> x.v COLLATE Latin1_General_BIN2 THEN LEFT(x.v, 80) END) AS example_value
FROM (SELECT CAST(my_column AS nvarchar(max)) AS v
      FROM dbo.my_table WHERE my_column IS NOT NULL) x;

values_at_risk = 0 means no Unicode content has ever been written to that column - the property changes nothing for it in practice. If a Tamaki MES table appears in the first query's output, the schema was modified outside the module; restore the column to its original varchar type (check values_at_risk first - the conversion itself degrades any Unicode content found).

If you need full Unicode text on SQL Server and the index-seek behavior, create the MES database with a UTF-8 collation (SQL Server 2019+, e.g. Latin1_General_100_CI_AS_SC_UTF8): the driver then sends parameters as UTF-8 and storage is lossless, with no performance penalty.

Options if other tables on the connection need Unicode

1. Give Tamaki MES a dedicated database connection (recommended - see the link above) and keep the shared connection on the driver default.
2. Set sendStringParametersAsUnicode=true explicitly in the datasource's Extra Connection Properties - the module respects explicit values and only logs a warning. Note this re-enables the deadlock-prone scan behavior for MES tables on SQL Server collations.
3. Leave the Allow Module to Manage Datasource gateway setting disabled (or blank db.extra_connection_properties.mssql while it is enabled).

Transaction

Property	Default	Description
transaction.retry.max_attempts	3	Maximum retry attempts for transient transactional failures.
transaction.retry.backoff_delay_ms	500	Backoff delay between retries (milliseconds).
transaction.retry.backoff_delay_multiplier	2	Multiplier applied to the previous delay for exponential backoff.

Notes

Effective delay sequence is backoff_delay_ms * multiplier^(attempt-1) until max attempts.

Import

Property	Default	Description
import.batch_size	1000	Number of records committed per batch when importing data (materials, equipment, OEE configs, etc.).
import.batch_flush_delay_ms	5000	Delay between batch flushes during import (milliseconds) to throttle database load on large imports.

Cache

Property	Default	Description
cache.default_expiry_ms	600000	Time to live for cache entries in milliseconds.
cache.max_heap_entries	10000	Maximum number of entries in cache per entity type.
cache.max_disk_size_mb	100	Maximum size of overflow disk cache in megabytes.
cache.disk_persistence_path	tamakimes/cache	Path to location of disk cache.
cache.equipment.enabled	true	Enable caching of equipment lookups. Disable any region to read that entity straight from the database.
cache.equipment_class.enabled	true	Enable caching of equipment class lookups.
cache.material.enabled	true	Enable caching of material lookups.
cache.material_class.enabled	true	Enable caching of material class lookups.
cache.department.enabled	true	Enable caching of department lookups.
cache.location.enabled	true	Enable caching of location lookups.
cache.unit_of_measure.enabled	true	Enable caching of unit of measure lookups.
cache.unit_of_measure_conversion.enabled	true	Enable caching of unit of measure conversion lookups. Disable to always read conversions from the database.
cache.production_order.enabled	true	Enable caching of production order detail reads. Disable for high-churn workloads where stale reads are unacceptable.
cache.production_order.expiry_ms	30000	Time to live for production order cache entries in milliseconds. Kept short because production orders change frequently; bounds how stale a cached read can be.

Inventory

Property	Default	Description
inventory.data_collection.execution_interval_ms	250	Interval between inventory data collection executions (milliseconds).

Notes

• Align with PLC tag update rates to avoid stale reads.

OEE

Property	Default	Description
oee.data_collection.execution_interval_ms	250	Interval between OEE data collection executions (milliseconds).
oee.data_collection.flush_check_interval_ms	10000	Frequency to check whether buffered OEE data should be flushed to the database (milliseconds).
oee.data_collection.prune_records_cron	0 0 0 * * ?	Cron expression for pruning old OEE records. Uses Spring Cron Format. The default value is Daily at Midnight.
oee.data_collection.logs.throttling.threshold	10	The maximum number of errors to show within the throttling window before suppressing them.
oee.data_collection.logs.throttling.window_ms	5000	The logs throttling window (milliseconds). Duplicate logs inside this window will be suppressed.
oee.alarms.alarm_flush_interval_ms	10000	Interval between OEE alarm flush operations (milliseconds).
oee.pruning.batch_size	1000	Number of OEE records deleted per pruning batch.
oee.pruning.batch_delay_ms	500	Delay between pruning batches to reduce DB load (milliseconds).
oee.heal.faulted_records.enabled	true	Enables the scheduled job that repairs faulted OEE state, mode, and OEE records.
oee.heal.faulted_records.cron	0 0 0 * * ?	Cron expression for the faulted-record healing job. Uses Spring Cron Format. The default value is Daily at Midnight.
oee.heal.faulted_records.batch_size	200	Number of faulted record IDs fetched per location, per record type, per healing batch.
oee.heal.faulted_records.max_per_run	1000	Soft cap on the number of records healed per record type (state/mode/OEE) per scheduled run.
oee.heal.faulted_records.parallelism	4	Number of locations healed in parallel during a single healing run.

Notes

• Execution Interval

  • Lower → collects data more frequently, more CPU/memory use.
  • Higher → collects data less frequently, less CPU/memory use, risk of missing short-lived events.

• Flush Check Interval

  • Lower → more DB writes.
  • Higher → fewer DB writes, higher crash-loss risk.

• Flush Check Interval needs to be larger than Execution Interval

• Mismatch causes wasted flushes (too frequent) or buffer growth (too slow).

Operation

Property	Default	Description
operation.data_collection.execution_interval_ms	250	Interval between operation data collection executions (milliseconds).

Shift

Property	Default	Description
shift.data_collection.expression_schedule_evaluation_interval_ms	500	Interval for evaluating expression-based shift schedules (milliseconds).
shift.data_collection.ignition_schedule_evaluation_interval_ms	10000	Interval for evaluating Ignition-bound shift schedules (milliseconds).

Expression

Property	Default	Description
expression.health_check.min_batch_size	5	Minimum number of expressions evaluated per health check cycle.
expression.health_check.scan_interval_ms	3000	Interval between expression health check scans (milliseconds).
expression.health_check.max_log_expressions	10	Max number of expressions logged when anomalies are detected.
expression.logs.throttling.window_ms	5000	The logs throttling window (milliseconds). Duplicate logs inside this window will be suppressed.

Tracegraph

Property	Default	Description
tracegraph.max_nodes	10000	Maximum number of nodes visited during a trace to prevent runaway traversal.
tracegraph.max_depth	100	Maximum traversal depth for trace graph operations.

Additional Logging

Property	Default	Description
logs.diagnostics	true	Whether or not to enable additional diagnostic logging.

Tree Search

Property	Default	Description
tree.search.max_results	1000	Maximum number of nodes returned by tree search components (Material, Location, Personnel, Downtime Reason, etc.).