Maintenance Reminders Blueprint
Define maintenance tasks that trigger notifications when a tracked vehicle crosses a configured odometer, engine hours, or time threshold, with automatic repeat reminders at regular intervals for o…
| Feature | maintenance-reminders |
| Category | Workflow |
| Version | 1.0.0 |
| Tags | gps, tracking, maintenance, odometer, service, reminder, fleet |
| YAML Source | View on GitHub |
| JSON API | maintenance-reminders.json |
Actors
| ID | Name | Type | Description |
|---|---|---|---|
fleet_admin | Fleet Administrator | human | Creates and manages maintenance task definitions per device or group |
pipeline | Maintenance Event Handler | system | Evaluates each incoming position against all active maintenance definitions for the device |
mechanic | Maintenance Team | human | Receives maintenance reminders and records service completion |
Fields
| Name | Type | Required | Label | Description |
|---|---|---|---|---|
name | text | Yes | Name of the maintenance task (e.g. Oil change, Tyre rotation, Annual inspection) | |
tracking_type | select | Yes | The metric to track: odometer (metres), hours (milliseconds), or a time field (server_time, devic… | |
start_value | number | Yes | The tracking metric value at which the first reminder fires | |
period_value | number | No | Interval at which the reminder repeats after the initial trigger; zero means fire once only | |
device_id | hidden | No | Device this maintenance task applies to (or inherited from group) |
Rules
- rule_1: The first reminder fires when the tracking metric crosses start_value (previous value < start_value <= current value)
- rule_2: If period_value > 0, subsequent reminders fire each time the metric increases by another period_value interval beyond start_value
- rule_3: Interval boundary crossing is detected mathematically; if a large GPS gap causes multiple intervals to be skipped, a reminder fires for the current crossing only
- rule_4: Maintenance definitions can be assigned to individual devices, to groups (inherited by all devices in the group), or to a user account
- rule_5: Only the latest position for each device is evaluated; outdated positions do not trigger maintenance reminders
- rule_6: A reminder event stores the maintenance task ID and the current tracking value so the service record can be annotated with the relevant mileage or hours
Outcomes
No_threshold_crossed (Priority: 3)
Given:
- current tracking value has not crossed any maintenance boundary
Result: No reminder generated; maintenance is not yet due
Periodic_reminder_fired (Priority: 8)
Given:
- current tracking value has crossed a period boundary beyond start_value
- period_value > 0
- position is the latest for the device
Then:
- create_record target:
event— Repeat maintenance reminder event recorded - emit_event event:
maintenance.due
Result: Repeat reminder fired; next service interval boundary has been reached
Initial_reminder_fired (Priority: 10)
Given:
- previous tracking value < start_value
- current tracking value >= start_value
- position is the latest for the device
Then:
- create_record target:
event— Maintenance reminder event recorded with type = maintenance, maintenance_id, current tracking value - emit_event event:
maintenance.due
Result: Maintenance reminder event stored; notification dispatched to assigned users
Errors
| Code | Status | Message | Retry |
|---|---|---|---|
MAINTENANCE_DEVICE_NOT_FOUND | 404 | The device referenced does not exist | No |
MAINTENANCE_NOT_FOUND | 404 | The specified maintenance definition does not exist | No |
Events
| Event | Description | Payload |
|---|---|---|
maintenance.due | A maintenance threshold has been reached for a tracked vehicle | device_id, maintenance_id, maintenance_name, tracking_type, current_value, threshold_value |
Related Blueprints
| Feature | Relationship | Reason |
|---|---|---|
| odometer-tracking | required | Odometer values are the primary trigger metric for distance-based maintenance |
| engine-hours-tracking | recommended | Engine hours provide an alternative maintenance trigger for equipment tracked by running time |
| gps-position-ingestion | required | Each position update drives the maintenance threshold evaluation |
AGI Readiness
Goals
Reliable Maintenance Reminders
Define maintenance tasks that trigger notifications when a tracked vehicle crosses a configured odometer, engine hours, or time threshold, with automatic repeat reminders at regular intervals for o…
Success Metrics:
| Metric | Target | Measurement |
|---|---|---|
| processing_time | < 5s | Time from request to completion |
| success_rate | >= 99% | Successful operations divided by total attempts |
Constraints:
- performance (negotiable): Must not block dependent workflows
Autonomy
Level: semi_autonomous
Human Checkpoints:
- before making irreversible changes
Escalation Triggers:
error_rate > 5
Tradeoffs
| Prefer | Over | Reason |
|---|---|---|
| reliability | speed | workflow steps must complete correctly before proceeding |
Coordination
Protocol: orchestrated
Consumes:
| Capability | From | Fallback |
|---|---|---|
odometer_tracking | odometer-tracking | degrade |
gps_position_ingestion | gps-position-ingestion | degrade |
Safety
| Action | Permission | Cooldown | Max Auto |
|---|---|---|---|
| initial_reminder_fired | autonomous | - | - |
| periodic_reminder_fired | autonomous | - | - |
| no_threshold_crossed | autonomous | - | - |