DecisioQ Fleet Vehicle Management Developer Integration Manual

How software developers should incorporate DecisioQ into fleet management, telematics, dispatch, maintenance, fuel, driver, compliance, and vehicle lifecycle systems.

Fleet Vehicle Management Industry Edition

Contents

1. Purpose and Scope

2. Fleet Vehicle Management Reference Architecture

3. Core Fleet Decision Templates

4. Data Mapping: Fleet Entities to DecisioQ Inputs

5. API Integration Pattern

6. Implementation Walkthrough: Vehicle Assignment

7. Maintenance, Repair, and Replacement Decisions

8. Driver Assignment, Safety, and Compliance

9. Telematics and Real-Time Event Integration

10. Fuel, Charging, and Route Optimization

11. Lifecycle, Procurement, and Fleet Planning

12. User Interface and Workflow Integration

13. Security, Auditability, and Governance

14. Performance and Reliability

15. Testing Strategy

1. Purpose and Scope

This manual explains how software developers in the Fleet Vehicle Management industry should embed DecisioQ into operational software systems. It is written for teams building or maintaining fleet management platforms, dispatch systems, telematics portals, maintenance applications, route planning systems, fuel management systems, driver mobile applications, and enterprise logistics integrations.

DecisioQ should be used when a fleet workflow requires transparent, repeatable, weighted, multi-criteria decision-making. It should not replace the fleet management system, telematics platform, ERP, or maintenance system. Instead, DecisioQ acts as a configurable decision layer that ranks alternatives, explains recommendations, and preserves a decision audit trail.

Best-fit fleet decisions

• Which vehicle should be assigned to a job, route, delivery, service call, or branch based on capability, location, utilization, and maintenance status?
• Which driver should be assigned when availability, certifications, hours of service, safety score, route familiarity, and overtime risk all matter?
• Which vehicles should receive preventive maintenance first when downtime, mileage, engine hours, diagnostic codes, and workshop capacity conflict?
• Which vehicle should be repaired, replaced, retired, redeployed, or remarketed?
• Which fueling, charging, routing, or vendor option best balances cost, service level, compliance, and operational risk?
• Which compliance or safety event should be escalated to a supervisor, routed to training, or automatically approved?

2. Fleet Vehicle Management Reference Architecture

A typical integration places DecisioQ behind the fleet application service layer. Operational systems collect fleet context, normalize it into decision criteria, send a decision request to DecisioQ, receive ranked alternatives with scores and rationale, then persist the selected result in the system of record.

Recommended logical flow

Job, vehicle, driver, route, maintenance, telematics, fuel, and compliance context
|
v
Fleet application service normalizes operational data
|
v
DecisioQ decision request with templateCode, criteria, alternatives, and metadata
|
v
Ranked recommendation with score, rationale, selected alternative, and auditId
|
v
FMS / TMS / mobile app applies result, records override if any, and stores audit link

3. Core Fleet Decision Templates

4. Data Mapping: Fleet Entities to DecisioQ Inputs

Developers should create a mapping layer that converts fleet records and telemetry into normalized decision criteria. Avoid sending raw table structures. Each criterion should have a business-readable name, unit, score direction, weight owner, and allowed value range.

5. API Integration Pattern

Use a Fleet Decision Adapter service inside your platform. The adapter centralizes authentication, retries, schema validation, decision logging, telemetry correlation, and response normalization. Dispatch, maintenance, mobile, and reporting modules should call the adapter rather than calling DecisioQ directly.

Request payload pattern

POST /api/decisions/evaluate
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "templateCode": "FLEET_VEHICLE_ASSIGNMENT",
  "criteria": [
    { "name": "distanceToJobKm", "weight": 20, "direction": "lowerIsBetter" },
    { "name": "vehicleCapability", "weight": 25, "direction": "higherIsBetter" },
    { "name": "maintenanceReadiness", "weight": 20, "direction": "higherIsBetter" },
    { "name": "utilizationBalance", "weight": 10, "direction": "higherIsBetter" },
    { "name": "fuelOrChargeReadiness", "weight": 10, "direction": "higherIsBetter" },
    { "name": "slaRisk", "weight": 15, "direction": "lowerIsBetter" }
  ],
  "alternatives": [
    { "id": "UNIT-104", "values": { "distanceToJobKm": 7.2, "vehicleCapability": 96, "maintenanceReadiness": 92, "utilizationBalance": 74, "fuelOrChargeReadiness": 88, "slaRisk": 8 } },
    { "id": "UNIT-118", "values": { "distanceToJobKm": 3.4, "vehicleCapability": 82, "maintenanceReadiness": 61, "utilizationBalance": 90, "fuelOrChargeReadiness": 70, "slaRisk": 18 } },
    { "id": "UNIT-133", "values": { "distanceToJobKm": 11.0, "vehicleCapability": 99, "maintenanceReadiness": 98, "utilizationBalance": 66, "fuelOrChargeReadiness": 95, "slaRisk": 10 } }
  ],
  "context": {
    "correlationId": "optional",
    "attributes": {}
  }
}

Response payload pattern

{
  "decisionId": "DQ-20260625-001244",
  "templateCode": "FLEET_VEHICLE_ASSIGNMENT",
  "selectedAlternativeId": "UNIT-104",
  "recommendation": "Assign Unit 104",
  "rankedAlternatives": [
    { "id": "UNIT-104", "score": 91.7, "rank": 1, "rationale": "Best balance of capability, maintenance readiness, proximity, and SLA risk." },
    { "id": "UNIT-133", "score": 88.3, "rank": 2, "rationale": "Excellent readiness but farther from the job." },
    { "id": "UNIT-118", "score": 74.9, "rank": 3, "rationale": "Closest vehicle, but maintenance readiness creates avoidable risk." }
  ],
  "audit": {
    "correlationId": "JOB-884219",
    "templateVersion": "3.1",
    "evaluatedAtUtc": "2026-06-25T18:10:42Z"
  },
  "context": {
    "correlationId": "optional",
    "attributes": {}
  }
}

6. Implementation Walkthrough: Vehicle Assignment

1. Detect an assignment event from dispatch, TMS, mobile workflow, or automated route planner.
2. Load job requirements, customer SLA, depot, time window, cargo, equipment, and route constraints.
3. Query eligible vehicles from the fleet system and exclude unavailable, reserved, unsafe, or non-compliant units.
4. Enrich each vehicle with live GPS, maintenance status, fuel/charge readiness, utilization, and capability values.
5. Call DecisioQ using the FLEET_VEHICLE_ASSIGNMENT template.
6. Display the ranked recommendation with rationale in the dispatcher UI or automatically assign if policy allows.
7. Persist decisionId, selected vehicle, rank list, input snapshot, and any dispatcher override reason.
8. Publish a domain event such as FleetDecisionCompleted for reporting and analytics.

C# adapter example

public sealed class DecisioQFleetClient
{
    private readonly HttpClient _http;

    public DecisioQFleetClient(HttpClient http)
    {
        _http = http;
    }

    public async Task<DecisionResult> EvaluateVehicleAssignmentAsync(
        FleetDecisionRequest request,
        CancellationToken cancellationToken)
    {
        using var response = await _http.PostAsJsonAsync(
            "/api/decisions/evaluate",
            request,
            cancellationToken);

        response.EnsureSuccessStatusCode();

        return await response.Content.ReadFromJsonAsync<DecisionResult>(
            cancellationToken: cancellationToken)
            ?? throw new InvalidOperationException("DecisioQ returned an empty response.");
    }
}

7. Maintenance, Repair, and Replacement Decisions

Fleet maintenance decisions should combine technical condition, cost, downtime, warranty, safety, and operational impact. DecisioQ is most valuable when a simple threshold is insufficient, such as deciding whether to repair an older asset, outsource a repair, defer a non-critical PM, or replace a vehicle.

8. Driver Assignment, Safety, and Compliance

Driver-related decisions must be explainable and auditable. Do not use DecisioQ to bypass legal or company eligibility rules. First apply hard exclusions such as invalid license, missing endorsement, expired medical card, or HOS violation. Then use DecisioQ to rank eligible drivers.

9. Telematics and Real-Time Event Integration

Telematics systems generate frequent events. Developers should avoid calling DecisioQ for every raw sensor event. Instead, aggregate, filter, and classify events before invoking decision templates. Use event severity, confidence, and business impact to decide when a decision is needed.

• Use streaming processors to aggregate events such as repeated harsh braking, extended idling, low state of charge, or recurring fault codes.
• Call DecisioQ when a decision is required: escalate, ignore, notify driver, schedule maintenance, reroute, or remove the asset from service.
• Include timestamp, asset, driver, location, event confidence, and source system metadata for auditability.
• Throttle duplicate events and use correlation IDs to avoid repeated escalation for the same root cause.
• Separate safety-critical hard rules from weighted decision ranking. For example, out-of-service criteria should be enforced before recommendation ranking.

10. Fuel, Charging, and Route Optimization

11. Lifecycle, Procurement, and Fleet Planning

DecisioQ can support long-horizon fleet decisions where finance, operations, maintenance, and sustainability criteria compete. The best pattern is to run lifecycle evaluations periodically and store results for fleet planning dashboards.

12. User Interface and Workflow Integration

Fleet users need fast, understandable recommendations. The UI should show the recommendation, score, ranked alternatives, major criteria drivers, and override controls without overwhelming dispatchers or drivers.

Recommended dispatcher UI pattern:
1. Primary recommendation: Assign Unit 104 to Job 884219.
2. Confidence/score: 91.7.
3. Rationale: Best balance of capability, readiness, proximity, and SLA risk.
4. Alternatives: Unit 133, Unit 118, manual assignment.
5. Key criteria comparison: distance, maintenance readiness, fuel/charge, utilization, SLA risk.
6. Override action: require reason and authorization for high-risk overrides.
7. Audit link: open DecisioQ decision record from the FMS job history.

13. Security, Auditability, and Governance

14. Performance and Reliability

• Use synchronous DecisioQ calls for interactive decisions such as dispatch assignment or maintenance triage when a user is waiting.
• Use asynchronous queues for batch lifecycle planning, nightly replacement analysis, vendor scorecards, and compliance review jobs.
• Cache relatively static attributes such as vehicle capacity, certification requirements, depot policy, vendor scorecards, and template metadata.
• Do not rely on stale cache for live data such as GPS, HOS, fault status, fuel/charge state, or active job assignment.
• Define fallback behavior for DecisioQ unavailability: manual review, last-known policy snapshot, or safe default assignment rules.
• Monitor decision latency, error rate, acceptance rate, override rate, and business outcome metrics by template and depot.

15. Testing Strategy

16. Deployment Checklist

• Create DecisioQ templates for vehicle assignment, driver assignment, PM priority, repair-vs-replace, fuel/charging, route exception, vendor selection, and compliance escalation.
• Build a Fleet Decision Adapter that centralizes authentication, retries, validation, logging, and response normalization.
• Document every criterion name, unit, score direction, weight owner, default value, and data source.
• Apply hard exclusions before calling DecisioQ for safety, compliance, and legal eligibility requirements.
• Store decisionId and input snapshots in the FMS job, work order, route, or asset history table.
• Enable role-based overrides and require reason codes for operationally sensitive decisions.
• Pilot one decision template with one depot or fleet segment before enterprise rollout.
• Create dashboards for recommendation acceptance, override reasons, downtime impact, SLA improvement, utilization, and cost savings.

17. Recommended First Implementation Roadmap

Appendix A - Example Decision Template Definitions

Template: FLEET_DRIVER_ASSIGNMENT
Purpose: Rank eligible drivers for a route, vehicle, or job after hard eligibility rules are applied.
Alternatives: Eligible drivers only.
Criteria:
distanceToDepotKm weight 15 lowerIsBetter
hoursRemaining weight 20 higherIsBetter
certificationMatch weight 20 higherIsBetter
safetyScore weight 15 higherIsBetter
routeFamiliarity weight 10 higherIsBetter
workloadBalance weight 10 higherIsBetter
overtimeRisk weight 10 lowerIsBetter
Required audit metadata:
jobId, routeId, depotId, dispatcherId, sourceSystem, decisionPolicyVersion

Template: FLEET_REPAIR_VS_REPLACE
Purpose: Recommend whether to repair, replace, retire, redeploy, or extend the life of a vehicle.
Alternatives: Repair, replace, retire, redeploy, extend lease, sell.
Criteria:
repairEstimate weight 20 lowerIsBetter
vehicleAgeMonths weight 10 lowerIsBetter
lifecycleCost weight 20 lowerIsBetter
downtimeDays weight 15 lowerIsBetter
resaleValue weight 10 higherIsBetter
replacementAvailability weight 10 higherIsBetter
operationalCriticality weight 15 higherIsBetter

Appendix B - Developer Best Practices

• Keep DecisioQ criteria business-readable and stable. Avoid cryptic database column names in templates.
• Apply hard legal, safety, and compliance exclusions before weighted ranking.
• Do not hard-code decision weights in fleet application code. Store weights in DecisioQ templates so business owners can govern them.
• Use live data only when it materially changes the decision. Aggregate noisy telematics events before invoking decision templates.
• Persist input snapshots and template versions for all dispatch, maintenance, compliance, and lifecycle decisions.
• Design for human override, but make overrides visible, reviewable, and measurable.
• Use correlation IDs consistently across FMS, TMS, telematics, maintenance, mobile, and DecisioQ logs.

End of Manual