system.mes.oee.calculateOee

Description

Calculates OEE (Overall Equipment Effectiveness) metrics for a specific location within a date range.

This method uses the pre-computed OEE rollup record cache where available. It queries all cached records (any period type) that fall within the requested range, then uses a greedy coarse-to-fine strategy — preferring MONTH records, then WEEK, DAY, HOUR — to find the maximal contiguous block of coverage. The result is assembled from three parts: a raw calculation for any uncovered time before the cache block, the cached records themselves, and a raw calculation for any uncovered time after the cache block. If no usable cached records exist for the range, the entire result is calculated from raw event data.

To populate or refresh the cache, use rebuildCalculationRecords or configure an OeeCalculationConfiguration to have the background job build records automatically.

Permissions

This method requires the OEE.READ.CALCULATE permission.

Syntax

system.mes.oee.calculateOee(locationIdOrPath, startDate, endDate=None, unitOfMeasureName=None, calculateWithRollup=True)

Parameters

Parameter	Type	Nullable	Description
locationIdOrPath	String	False	The ULID or path of the location to calculate OEE for.
startDate	Date	False	The start date for the calculation period.
endDate	Date	True	The end date for the calculation period. Defaults to current time if omitted.
unitOfMeasureName	String	True	The unit of measure name for production calculations. Uses the location OEE configuration default if omitted.
calculateWithRollup	Boolean	True	When False, bypasses the pre-computed rollup table and forces a raw OEE calculation. Default True.

Returns

Returns a JSON object containing calculated OEE metrics.

Name	Type	Nullable	Description	Default Value
locationId	String	False	Identifier of the associated location where this OEE production record was captured	null
locationPath	String	True	Path of the location where this OEE production record was captured	null
startDate	Instant	False	Start date and time of the OEE production record	Instant.now()
endDate	Instant	True	End date and time of the OEE production record	null
totalDurationSec	Double	False	Total duration of the OEE production record in seconds	0.0
scheduledDurationSec	Double	False	Duration in seconds that the machine was scheduled to run during this record period	0.0
scheduledProductionModeEventCount	Integer	False	Total number of scheduled production mode events during this record period	0
scheduledDowntimeDurationSec	Double	False	Duration in seconds that the machine was scheduled to be in downtime during this record period	0.0
scheduledDowntimeModeEventCount	Integer	False	Total number of scheduled downtime mode events during this record period	0
unscheduledDowntimeDurationSec	Double	False	Duration in seconds that the machine was in unscheduled downtime during this record period	0.0
unscheduledDowntimeEventCount	Integer	False	Total number of unscheduled downtime mode events during this record period	0
runningDurationSec	Double	False	Duration in seconds that the machine was actively running during this record period	0.0
runningStateEventCount	Integer	False	Total number of running state events during this record period	0
blockedDurationSec	Double	False	Duration in seconds that the machine was in BLOCKED state during this record period	0.0
blockedStateEventCount	Integer	False	Total number of blocked state events during this record period	0
starvedDurationSec	Double	False	Duration in seconds that the machine was in STARVED state during this record period	0.0
starvedStateEventCount	Integer	False	Total number of starved state events during this record period	0
idleDurationSec	Double	False	Duration in seconds that the machine was in IDLE state during this record period	0.0
idleStateEventCount	Integer	False	Total number of idle state events during this record period	0
downtimeDurationSec	Double	False	Duration in seconds that the machine was in DOWNTIME state during this record period	0.0
downtimeStateEventCount	Integer	False	Total number of downtime state events during this record period	0
productionCount	Double	False	Total number of units produced during this record period	0.0
expectedProductionCount	Double	False	Expected number of units to be produced during this record period	0.0
averageStandardRate	Double	False	Average Standard Rate for the time period. Calculated as per minute	0.0
maximumStandardRate	Double	False	Maximum Standard Rate for the time period. Calculated as per minute	0.0
wasteCount	Double	False	Total number of waste units recorded during this period	0.0
goodCount	Double	False	Total number of good units recorded during this period	0.0
productionCountUnitOfMeasureId	String	True	Identifier of the unit of measure for the production count	null
productionCountUnitOfMeasureName	String	True	Name of the unit of measure for the production count	null
productionCountUnitOfMeasureSymbol	String	True	Symbol of the unit of measure for the production count	null
availability	Double	True	Availability metric (0.0 to 1.0)	1.0
teep	Double	True	Total Effective Equipment Performance (TEEP) metric (0.0 to 1.0)	1.0
performance	Double	True	Performance metric (0.0 to 1.0)	1.0
quality	Double	True	Quality metric (0.0 to 1.0)	1.0
oee	Double	True	Overall Equipment Effectiveness (OEE) metric (0.0 to 1.0)	1.0

Code Examples

from java.util import Date
import system.date

# Calculate OEE for the last 24 hours
locationPath = "Enterprise/Site/Area/Line1"
endDate = Date()
startDate = system.date.addHours(endDate, -24)

oeeResult = system.mes.oee.calculateOee(locationPath, startDate, endDate)

print("OEE Calculation Results:")
print("OEE:", oeeResult.get('oee', 0))
print("Availability:", oeeResult.get('availability', 0))
print("Performance:", oeeResult.get('performance', 0))
print("Quality:", oeeResult.get('quality', 0))

# Calculate OEE for a specific time range with unit of measure
startDate = system.date.parse("2024-10-01 00:00:00", "yyyy-MM-dd HH:mm:ss")
endDate = system.date.parse("2024-10-01 23:59:59", "yyyy-MM-dd HH:mm:ss")

oee_detailed = system.mes.oee.calculateOee(
    locationIdOrPath=locationPath,
    startDate=startDate,
    endDate=endDate,
    unitOfMeasureName="Parts"
)

print("\nDetailed OEE Results:")
print("Production Count:", oee_detailed.get('productionCount', 0))
print("Expected Production:", oee_detailed.get('expectedProductionCount', 0))
print("Total Duration (sec):", oee_detailed.get('totalDurationSec', 0))
print("Scheduled Duration (sec):", oee_detailed.get('scheduledDurationSec', 0))
print("Running Duration (sec):", oee_detailed.get('runningDurationSec', 0))

# Calculate OEE for current day (endDate defaults to now)
todayStart = system.date.midnight(Date())
oeeToday = system.mes.oee.calculateOee(locationPath, todayStart)

print("\nToday's OEE:", oeeToday.get('oee', 0))