Job Time Tracking
Core Principle: Cumulative Hours
Jobs accumulate time from multiple sources simultaneously. Time is additive across all contributors.
Time Sources
| Source | Description | Tracking Mechanism |
|---|---|---|
| Machines | Equipment running on a job | Machine events (oee_machine_events) linked to the job |
| People | Workers clocked in on a job | Time entries (oee_time_entries) |
Concurrency
Multiple sources can contribute time to the same job at the same time:
- Multiple machines can work on the same job simultaneously
- Multiple people can work on the same job simultaneously
- Machines and people can work on the same job at the same time
There is no limit on the number of concurrent contributors.
Cumulative Hour Calculation
Hours from all contributors are summed to get total actual hours on a job:
Example: Mixed Contributors
Job-042: Product Widget-A (standard hours = 10)
Machine contributors:
CNC-001: 4 hours
CNC-002: 3 hours
─────────────────
Machine total: 7 machine-hours
Person contributors:
John: 2 hours
Sarah: 2 hours
Mike: 1 hour
─────────────────
Person total: 5 person-hours
Total actual hours: 12 hours
Efficiency: 10 / 12 = 83.3%
Example: Multiple People, Same Duration
When 3 people each work 2 hours on a job:
Person A: 2 hours
Person B: 2 hours
Person C: 2 hours
────────────────────
Total person-hours: 6 hours (NOT 2 hours)
The wall-clock time was 2 hours, but the job-hours (labor input) is 6. This is the correct measure for efficiency calculations because it represents the total labor investment.
Example: Machine-Only Station
At a station configured as machine-only (see Station Configuration):
Job-055: Product Gear-B (standard hours = 8)
Machine contributors:
Lathe-01: 5 hours
Lathe-02: 4 hours
─────────────────
Total actual hours: 9 machine-hours (no person-hours)
Efficiency: 8 / 9 = 88.9%
Time Entry Model
Person Time (oee_time_entries)
People clock in and out of jobs via time entries:
| Field | Description |
|---|---|
batch_id | Which job (per-station batch instance) the person is working on |
user_id | Which person |
start_ts | When they started working |
end_ts | When they stopped (NULL = still working) |
duration_override_minutes | Manual override of duration; otherwise derived from end_ts − start_ts |
tags | 'shift' for live clock-ins; 'labor' for retroactive gap-fills. Both count as Touch on the job |
A trigger (trg_prevent_station_equipment_time_entry) silently DROPs any insert where equipment_id IS NOT NULL AND user_id IS NULL and the equipment is a station — operator time on a station-job is always represented as (user_id NOT NULL, equipment_id NULL, batch_id = job.id). See Touch and Dwell for the full Touch model.
Machine Time (oee_machine_events)
Machines contribute time via batch events:
| Field | Description |
|---|---|
machine_id | Which machine |
job_id | Which job |
start_ts | When the machine started working on the job |
end_ts | When the machine stopped (NULL = still running) |
duration_minutes | Calculated duration |
Actual Hours for Efficiency
When calculating efficiency for a job:
actual_hours = (
-- Person-hours (Touch). Open entries (end_ts IS NULL) accrue from
-- start_ts up to NOW() unless a duration_override_minutes is set.
SELECT SUM(CASE
WHEN duration_override_minutes IS NOT NULL THEN duration_override_minutes / 60.0
WHEN end_ts IS NOT NULL THEN EXTRACT(EPOCH FROM (end_ts - start_ts)) / 3600.0
ELSE EXTRACT(EPOCH FROM (NOW() - start_ts)) / 3600.0
END)
FROM oee_time_entries
WHERE batch_id = _job_id AND user_id IS NOT NULL
) + (
SELECT SUM(duration_minutes / 60.0)
FROM oee_machine_events
WHERE id = _job_id AND event_type = 'batch' AND end_ts IS NOT NULL
)Both person-hours and machine-hours contribute to the actual hours denominator in the efficiency formula.
Downtime Interruptions
Job time tracks productive time, not elapsed time. Any period where a machine or station is down is excluded from the job’s tracked hours.
Machine Downtime
When a machine goes down (a downtime event is recorded against it), time tracking pauses on any job that machine is contributing to. The job’s tracked time excludes the downtime window. When the machine comes back up, time tracking resumes.
Other contributors to the same job (other machines, people) are unaffected — they continue accumulating time normally. Only the downed machine’s contribution pauses.
Station Downtime
When a station goes down, all jobs at that station pause. Every machine and person working on jobs at that station stops contributing time for the duration. Time tracking resumes for all contributors when the station comes back up.
Station downtime is broader than machine downtime — it affects every resource at the station, not just one machine.
Retroactive Downtime Adjustments
If a user updates a downtime event (changes its start or end time), the affected job time entries are recalculated to match the adjusted downtime window. This ensures job time always accurately reflects actual productive time, even when downtime records are corrected after the fact.
For example: if a downtime event originally recorded as 10:00-11:00 is corrected to 10:00-10:30, the affected jobs regain the 30 minutes (10:30-11:00) that were previously excluded.
See Events for details on downtime event types and how they are recorded against machines and stations.
Relationship to Cost Tracking
Time tracking data feeds into cost calculations:
- Person-hours x labor rate = labor cost
- Machine-hours x machine rate = machine cost
- Total cost enables profitability analysis per job, product, station, etc.