Employee Behavioral Monitoring

TitanGrid integrates with external employee tag-reader services to provide a secondary layer of real-time activity monitoring. While your biometric terminals track attendance entries/exits, the Monitoring Service tracks ongoing "liveness" throughout the shift.

The Ingestion Pipeline

The monitoring service operates asynchronously from the core biometric engine. External tag-readers distributed across the facility post status updates directly to the system_monitoring table via a RESTful API.

State Logic

• active: Received when the tag reader confirms the employee's proximity.
• missing: Automatically assigned by the background engine if the last active timestamp exceeds the pre-configured heartbeat timeout period (e.g., 30 minutes).
• inactive: Explicitly set if the employee logs out of the portal or confirms their shift conclusion via the dashboard.

API Integration

External services must authenticate via a service-level API token. The payload is kept lightweight to ensure minimal overhead for the external tag-reading hardware.

POST /api/system/monitoring/ingest/

{
  "emp_id": "EMP-9042",
  "timestamp": "2026-06-07T08:15:00Z",
  "state": "active"
}

{
  "status": "accepted",
  "monitor_id": 10092,
  "msg": "State telemetry recorded"
}

Data Integrity Rules

1. Heartbeat Requirement: To maintain an active state, the tag-reader must hit the endpoint at least once every 10 minutes.
2. Auto-Timeout: The background processing daemon runs a cron job every 5 minutes. Any emp_id that has not provided a telemetry push within the threshold is automatically toggled to missing status, triggering an alert if the employee is still officially clocked in.
3. Event Reconciliation: When the biometric terminal registers a clock_out event, the system automatically forces the behavioral state to inactive, regardless of the last tag-reader ping, ensuring that the behavioral data never interferes with actual payroll time logs.