system.mes.oee.calculateOeeByCalendarPeriod

Description

Calculates OEE (Overall Equipment Effectiveness) metrics broken down by time intervals for a specific location within a date range. Unlike calculateOeeByTimeInterval, the time intervals are snapped to natural time boundaries such as hourly or daily periods. This allows for efficient use of the pre-computed records cache, which can be configured using saveCalculationConfig.

Returns one OeeResultsDTO per calendar-aligned bucket for the given location, period type, bucket size, and date range. Each result spans exactly one bucket aligned to a calendar boundary — for example, periodType="HOUR" produces whole-hour results (01:00-02:00, 02:00-03:00, etc.) and periodType="DAY" produces midnight-to-midnight results.

periodsPerBucket controls how many calendar periods form one bucket. With the default of 1, each result covers one period (one hour, one day, etc.). However, with periodsPerBucket=4 and periodType="HOUR" for example, each result covers a 4-hour window anchored to the day boundary (00:00–04:00, 04:00–08:00, and so on).

The returned buckets always cover complete calendar periods. For example, hourly results with startDate=10:45 and endDate=11:15 return two buckets: 10:00–11:00 and 11:00–12:00.

For each bucket, the method tries the pre-computed record cache at the requested periodType first. On a miss it steps down through smaller granularities (MONTH → WEEK → DAY → HOUR) until a cached record is found. If no cached record exists at any granularity, the bucket falls back to a raw calculation.

Permissions

This method requires the OEE.READ.GET permission.

Syntax

system.mes.oee.calculateOeeByCalendarPeriod(locationIdOrPath, periodType, startDate, periodsPerBucket=1, endDate=None, unitOfMeasureName=None)

Parameters

Parameter	Type	Nullable	Description
locationIdOrPath	String	False	Location ID (ULID) or path.
periodType	String	False	Period granularity: "HOUR", "DAY", "WEEK", or "MONTH".
startDate	Date	False	Start of the query range. Snapped to the nearest calendar boundary if not already aligned.
periodsPerBucket	Integer	True	Number of base periods per bucket. For example, periodType="HOUR" with periodsPerBucket=4 produces 4-hour buckets anchored to the day. Defaults to 1.
endDate	Date	True	End of the query range (inclusive). Defaults to now if omitted.
unitOfMeasureName	String	True	Unit of measure name for production counts. Uses the location OEE configuration default if omitted.

Returns

A JSON list of OeeResultsDTO objects, one per calendar-aligned bucket.

Name	Type	Nullable	Description	Default Value
locationId	String	False	Identifier of the associated location.	null
locationPath	String	True	Path of the associated location.	null
startDate	Instant	False	Start of the bucket (calendar-aligned).	Instant.now()
endDate	Instant	True	End of the bucket.	null
totalDurationSec	Double	False	Total duration of the bucket in seconds.	0.0
scheduledDurationSec	Double	False	Duration scheduled for production in seconds.	0.0
scheduledProductionModeEventCount	Integer	False	Total number of scheduled production mode events.	0
scheduledDowntimeDurationSec	Double	False	Duration in scheduled downtime mode in seconds.	0.0
scheduledDowntimeModeEventCount	Integer	False	Total number of scheduled downtime mode events.	0
unscheduledDowntimeDurationSec	Double	False	Duration in unscheduled downtime mode in seconds.	0.0
unscheduledDowntimeEventCount	Integer	False	Total number of unscheduled downtime mode events.	0
runningDurationSec	Double	False	Duration the machine was actively running in seconds.	0.0
runningStateEventCount	Integer	False	Total number of running state events.	0
blockedDurationSec	Double	False	Duration in BLOCKED state in seconds.	0.0
blockedStateEventCount	Integer	False	Total number of blocked state events.	0
starvedDurationSec	Double	False	Duration in STARVED state in seconds.	0.0
starvedStateEventCount	Integer	False	Total number of starved state events.	0
idleDurationSec	Double	False	Duration in IDLE state in seconds.	0.0
idleStateEventCount	Integer	False	Total number of idle state events.	0
downtimeDurationSec	Double	False	Duration in DOWNTIME state in seconds.	0.0
downtimeStateEventCount	Integer	False	Total number of downtime state events.	0
productionCount	Double	False	Total units produced during the bucket.	0.0
expectedProductionCount	Double	False	Expected units to be produced during the bucket.	0.0
averageStandardRate	Double	False	Average standard rate for the bucket (units per minute).	0.0
maximumStandardRate	Double	False	Maximum standard rate for the bucket (units per minute).	0.0
wasteCount	Double	False	Total waste units recorded during the bucket.	0.0
goodCount	Double	False	Total good units recorded during the bucket.	0.0
productionCountUnitOfMeasureId	String	True	Identifier of the unit of measure for production count.	null
productionCountUnitOfMeasureName	String	True	Name of the unit of measure for production count.	null
productionCountUnitOfMeasureSymbol	String	True	Symbol of the unit of measure for production count.	null
availability	Double	True	Availability 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
teep	Double	True	Total Effective Equipment Performance (TEEP) metric (0.0 to 1.0).	1.0

Code Examples

from java.util import Date
import system.date

# Get daily OEE buckets for the past 7 days
location = "Enterprise/Site/Line1"
endDate = Date()
startDate = system.date.addDays(endDate, -7)

buckets = system.mes.oee.calculateOeeByCalendarPeriod(location, "DAY", startDate, endDate=endDate)
for bucket in buckets:
    print bucket['startDate'], "OEE:", bucket['oee']

# Get 4-hour buckets for the past 24 hours
startDate24h = system.date.addHours(endDate, -24)
buckets4h = system.mes.oee.calculateOeeByCalendarPeriod(
    location, "HOUR", startDate24h, periodsPerBucket=4, endDate=endDate
)
for bucket in buckets4h:
    print bucket['startDate'], "->", bucket['endDate'], "OEE:", bucket['oee']