OEE Calculation Configuration

Overview

The OeeCalculationConfiguration entity controls which locations have OEE metrics pre-computed and for which period types. Each row represents one (location, period_type) pair. The periodic backfill job reads all enabled configurations, uses latest_calculation_timestamp to determine where it left off, generates up to num_rows_per_cycle new OeeCalculationRecord rows for completed periods, then advances latest_calculation_timestamp to the end_date of the last record generated.

Unlike OeeCalculationRecord entities, which are historical snapshots that persist independently, configurations are live configuration. A configuration has no meaning without its location, so it carries a real database-level foreign key on location_id and is removed when its location is deleted.

Table Structure

The following table outlines the SQL columns for the oee_calculation_configurations table, providing a brief description of each, along with sample data where applicable.

Column	Type	Uniqueness	Description	Example
id	String (ULID)	Unique	Unique identifier for the entity.	01JAP8RJBN-8ZTPXSGY-J9GSDPE1
enabled	Boolean		If the entity is enabled or not.	true
created_date	DateTime		Date the entity was created.	2025-01-15T08:00:00Z
created_by	String		Person who created the entity.	TamakiMES
modified_date	DateTime		Date the entity was last modified.	2025-01-15T08:00:00Z
modified_by	String		Last person to modify the entity.	TamakiMES
notes	String		Notes about the entity.	This entity has these extra notes
spare1	String		First spare column for additional context.	some extra context 1
spare2	String		Second spare column for additional context.	some extra context 2
spare3	String		Third spare column for additional context.	some extra context 3
location_id	String (ULID)	Unique with period_type	References the location this configuration targets. Database-level foreign key constraint. Required.	01JAP8R5RT-3FPXQABY-7KQZT6VF
period_type	String (Enum)	Unique with location_id	Granularity of the records this configuration generates (HOUR, DAY, WEEK, MONTH, SHIFT). Required.	HOUR
latest_calculation_timestamp	Instant		End time of the most recently generated OeeCalculationRecord for this configuration. Null means no records have been generated yet. Updated by the backfill job after each cycle.	2025-01-15T08:00:00Z
num_rows_per_cycle	Integer		Maximum number of OeeCalculationRecord rows to generate per scheduled job cycle. Default 1.	1
week_start_day	String (Enum)		The day of the week that marks the start of a WEEK period. Only meaningful when period_type is WEEK. Default MONDAY.	MONDAY
num_days_delay	Integer		Number of days after a period closes before the backfill job considers it eligible for calculation. Prevents premature calculation when late data is expected. Default 1.	1

Field Details

Foreign key

location_id carries a database-level foreign key constraint to the locations table with ON DELETE NO ACTION, consistent with all other foreign keys in the project. Cascade deletion of configurations when a location is deleted is enforced at the JPA/service layer, following the same pattern as Location.children. This differs from oee_calculation_records, which intentionally omits the constraint so that historical snapshots survive location deletion.

Unique constraint

The combination of (location_id, period_type) is unique. At most one configuration may exist per location per period type.

latest_calculation_timestamp

Tracks backfill progress. The periodic job uses this as its starting point: the next period to generate begins at latest_calculation_timestamp. When null, the job searches for latest OeeCalculationRecord for this configuration and starts from there.

Setting this field to an earlier date triggers a targeted backfill of historical data. The job will regenerate (or fill gaps in) records from that point forward, up to num_rows_per_cycle records per cycle, until it catches up to the current time.

num_rows_per_cycle

Caps how much work one job cycle performs for this configuration. For HOUR period type, a value of 24 catches up one calendar day per cycle. Setting a high value (e.g., 200) alongside an old latest_calculation_timestamp allows rapid backfilling of months of historical data. The job always stops early if the next period's end_date would exceed the current time — no records are generated for periods that have not yet closed.

week_start_day

The day of the week that marks the start of a WEEK period. Only meaningful when period_type is WEEK. Accepted values are Java DayOfWeek enum names: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY. Defaults to MONDAY.

num_days_delay

Number of days after a period closes before the backfill job considers it eligible for calculation. A value of 1 means the job will not calculate a period until at least 1 day after it ends, giving time for late-arriving data to be recorded. Must be >= 1. Defaults to 1.