Overview

AUTO-TOW-019, Select Nearest Qualified Operator, compares candidate towing operators using proximity, certification match, current job load, safety history, and customer rating.

Decision ID

AUTO-TOW-019

Decision Name

Select Nearest Qualified Operator

Decision Preparation Model

auto-towing-select-nearest-qualified-opera-auto-tow-019 version 1.0.0

Default Profile

balanced

Runnable Scenario

standard

Catalog

DKR-AUTO-RUNTIME-001, version 13.9.3

API Compatibility

7.4.0 or later Prepared Criteria Mode execution flow

5-Minute Quick Path

First working request →

Understanding This Decision

Select Nearest Qualified Operator helps a towing operation compare available candidate operators before dispatching one to an incident. The decision is useful when dispatch teams need a repeatable recommendation that balances proximity, qualification fit, operator workload, safety history, and recent customer service performance.

Criteria

Criterion IDs are intentionally stable machine identifiers. Display labels are for users; request values should be keyed by canonical criterionId.

Data Preparation Guide

Constraint Processing

This decision currently has no catalog-defined hard constraints. All validated candidates proceed to criteria-based ranking.

{
  "constraintSummary": {
    "definedConstraintCount": 0,
    "activeConstraintCount": 0,
    "eligibleOptionCount": 3,
    "excludedOptionCount": 0,
    "eligibleOptions": [
      "OPTION-001",
      "OPTION-002",
      "OPTION-003"
    ],
    "excludedOptions": []
  }
}

const constraints = decisionDetail.constraints || [];
if (constraints.length === 0) {
  // No catalog-defined hard constraints.
  // Submit all validated candidates for criteria-based ranking.
}

const summary = response.constraintSummary;
const excluded = response.decisionResult?.excludedOptions || [];

Excluded candidates do not participate in ranking because hard constraints are evaluated before scoring. For AUTO-TOW-019, no candidates are excluded by catalog-defined constraints because Decision Catalog currently defines none for this decision.

Decision Preparation Model

The published Decision Preparation Model validates and transforms illustrative Business Data into the canonical criteria required by AUTO-TOW-019 before Decision Service applies ranking.

Profile ID

auto-towing-select-nearest-qualified-opera-auto-tow-019

Version

1.0.0

Options Path

$.towRequests

Option ID Path

$.optionId

Display Name Path

$.name

{
  "requestContext": {
    "sourceSystem": "automotive-profile-factory",
    "correlationId": "factory-auto-tow-019"
  },
  "towRequests": [
    {
      "optionId": "TOW-019-01",
      "name": "Select Nearest Qualified Operator Option 1",
      "assessment": {
        "proximityScore": 44.0,
        "certificationMatchScore": 43.0,
        "safetyHistoryScore": 17.0,
        "customerRatingScore": 17.0
      },
      "resource": {
        "allocation": {
          "currentJobLoad": 27.0
        }
      }
    },
    {
      "optionId": "TOW-019-02",
      "name": "Select Nearest Qualified Operator Option 2",
      "assessment": {
        "proximityScore": 48.0,
        "certificationMatchScore": 59.0,
        "safetyHistoryScore": 62.0,
        "customerRatingScore": 25.0
      },
      "resource": {
        "allocation": {
          "currentJobLoad": 23.0
        }
      }
    }
  ]
}

{
  "optionId": "TOW-019-01",
  "name": "Select Nearest Qualified Operator Option 1",
  "values": {
    "proximity_score": 44.0,
    "certification_match_score": 43.0,
    "current_job_load": 27.0,
    "safety_history_score": 17.0,
    "customer_rating_score": 17.0
  }
}

Profiles and Scenarios

This example selects a Profile for evaluation emphasis and a Scenario for operating context. Discover both from the selected Decision Catalog definition.

Business Data Mode

Start here when your application has operational data. DecisioQ applies the published Decision Preparation Model to produce the required criteria.

{
  "decisionId": "AUTO-TOW-019",
  "businessData": {
    "requestContext": {
      "sourceSystem": "automotive-profile-factory",
      "correlationId": "factory-auto-tow-019"
    },
    "towRequests": [
      {
        "optionId": "TOW-019-01",
        "name": "Select Nearest Qualified Operator Option 1",
        "assessment": {
          "proximityScore": 44.0,
          "certificationMatchScore": 43.0,
          "safetyHistoryScore": 17.0,
          "customerRatingScore": 17.0
        },
        "resource": {
          "allocation": {
            "currentJobLoad": 27.0
          }
        }
      },
      {
        "optionId": "TOW-019-02",
        "name": "Select Nearest Qualified Operator Option 2",
        "assessment": {
          "proximityScore": 48.0,
          "certificationMatchScore": 59.0,
          "safetyHistoryScore": 62.0,
          "customerRatingScore": 25.0
        },
        "resource": {
          "allocation": {
            "currentJobLoad": 23.0
          }
        }
      }
    ]
  }
}

Download Business Data request

Prepared Criteria Mode

Use this mode when your application already calculates decision-ready values keyed by authoritative criterion IDs. Prepared Criteria go directly to the decision.

Download Prepared Criteria request

For Prepared Criteria Mode, send decisionId, selected profile/scenario IDs, and option values keyed by canonical criterion ID.

{
  "decisionId": "AUTO-TOW-019",
  "profileId": "balanced",
  "scenarioId": "standard",
  "algorithm": "TOPSIS",
  "weightStrategy": "Expert",
  "runSensitivity": false,
  "requestContext": {
    "correlationId": "auto-tow-019-demo-001"
  },
  "options": [
    {
      "optionId": "OPTION-001",
      "name": "Operator North Zone",
      "values": {
        "proximity_score": 88,
        "certification_match_score": 88,
        "current_job_load": 1,
        "safety_history_score": 88,
        "customer_rating_score": 88
      }
    },
    {
      "optionId": "OPTION-002",
      "name": "Operator Central Zone",
      "values": {
        "proximity_score": 80,
        "certification_match_score": 80,
        "current_job_load": 3,
        "safety_history_score": 80,
        "customer_rating_score": 80
      }
    },
    {
      "optionId": "OPTION-003",
      "name": "Operator East Zone",
      "values": {
        "proximity_score": 72,
        "certification_match_score": 72,
        "current_job_load": 5,
        "safety_history_score": 72,
        "customer_rating_score": 72
      }
    }
  ]
}

Execute

curl -X POST "https://dde.vinquery.com/api/v1/decide" \
  -H "Authorization: Bearer ${DECISIOQ_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: auto-tow-019-demo-001" \
  --data @auto-tow-019-execute.json

The Decision Service validates the request, retrieves authoritative criteria, constraints, profiles, scenarios, and validation metadata from Decision Catalog, applies hard constraints, ranks eligible options, and returns the decision result plus execution metadata.

Understanding the Result

The successful response includes both the deterministic decisionResult and a top-level explanation object. The explanation adds context but does not select, rerank, recalculate, or override the ranking.

{
  "service": "decisioq",
  "version": "7.6.3",
  "requestId": "0HNE...",
  "operation": "Decide",
  "success": true,
  "decisionType": "AUTO-TOW-019",
  "decisionVersion": "13.9.3",
  "timestampUtc": "2026-07-18T00:00:00Z",
  "decisionResult": {
    "winner": "OPTION-001",
    "confidence": 72.4,
    "ranking": [
      {
        "optionId": "OPTION-001",
        "score": 0.8421,
        "breakdown": {
          "proximity_score": 0.25,
          "certification_match_score": 0.25,
          "current_job_load": 0.20,
          "safety_history_score": 0.15,
          "customer_rating_score": 0.15
        },
        "normalizationBreakdown": {}
      }
    ],
    "excludedOptions": []
  },
  "explanation": {
      "summary": "The selected towing operator provided the strongest overall dispatch fit.",
      "whyRecommended": "It combined strong proximity and certification match with low current job load, strong safety history, and strong customer rating.",
      "keyDrivers": [],
      "tradeoffs": [],
      "competitors": [],
      "sensitivitySummary": "Sensitivity analysis was not included in this response.",
      "scenarioSummary": "The standard dispatch scenario was selected.",
      "risks": [],
      "nextSteps": [],
      "assumptions": []
  },
  "constraintSummary": {
    "definedConstraintCount": 0,
    "activeConstraintCount": 0,
    "eligibleOptionCount": 3,
    "excludedOptionCount": 0,
    "eligibleOptions": [
    "OPTION-001",
    "OPTION-002",
    "OPTION-003"
    ],
    "excludedOptions": []
  },
  "warnings": [],
  "requestContext": {
    "correlationId": "auto-tow-019-demo-001"
  }
}

Sensitivity Analysis

runSensitivity is an optional execution flag supported by both Business Data Mode and Prepared Criteria Mode. Set it to true when the client wants recommendation-stability information in the same response. The sensitivity engine analyzes the prepared criteria produced by either input path, perturbs criterion weights by controlled factors, and reports whether the winner remains stable.

{
  "sensitivityResult": {
    "stableWinner": true,
    "winner": "OPTION-001",
    "mostSensitiveCriterion": "proximity_score",
    "confidence": 95,
    "criterionImpacts": {
      "proximity_score": 0.1842
    },
    "winnerChangeCounts": {
      "proximity_score": 0
    }
  }
}

Use sensitivity output to decide whether a recommendation is robust enough for automation or should be reviewed by a person.

Scenario Analysis

Use a published scenario only when it matches the operating context: standard, emergency_response, limited_capacity, severe_weather. Compare the winner, ranking gap, and key trade-offs with the baseline run.

Explanation of Decision Result

Every successful response includes a provider-neutral top-level explanation object. It explains the already-finalized deterministic result and does not change the ranking.

{
  "explanation": {
      "summary": "The selected towing operator provided the strongest overall dispatch fit.",
      "whyRecommended": "It combined strong proximity and certification match with low current job load, strong safety history, and strong customer rating.",
      "keyDrivers": [],
      "tradeoffs": [],
      "competitors": [],
      "sensitivitySummary": "Sensitivity analysis was not included in this response.",
      "scenarioSummary": "The standard dispatch scenario was selected.",
      "risks": [],
      "nextSteps": [],
      "assumptions": []
  }
}

Tracing and Logs

Use request identifiers to connect client, catalog, and execution activity during support or integration testing.

X-Request-Id

Optional client-supplied request ID. If omitted, the server generates one.

X-Correlation-Id

Optional client correlation value propagated from Decision Service to Decision Catalog.

requestContext.correlationId

Optional payload value echoed in the response and used for tracing.

configurationUsed

The authoritative effective weight strategy, ranking algorithm, profile, scenario, sensitivity setting, and source for each value.

diagnostics

Safe execution counts returned only when responseOptions.includeDiagnostics is true.

Integration Examples

These examples demonstrate the current DecisioQ flow:

1. Request jwtToken from https://identity.vinquery.com/connect/token.
2. Load AUTO-TOW-019 metadata from https://dks.vinquery.com/decisioncatalog/decisions/AUTO-TOW-019.
3. Execute a Prepared Criteria Mode at https://dde.vinquery.com/api/v1/decide.

Set these environment variables before running any companion example:

DECISIOQ_CLIENT_ID
DECISIOQ_CLIENT_SECRET

Optional:
DECISIOQ_IDENTITY_URL=https://identity.vinquery.com/connect/token
DECISIOQ_DKS_URL=https://dks.vinquery.com
DECISIOQ_DDE_URL=https://dde.vinquery.com

Download the source files directly:

Troubleshooting

Production Checklist

Next Steps

Review Decision Concepts for criteria, weights, profiles, scenarios, confidence, and sensitivity; use the API Guide for transport details; and return to the examples library to compare related workflows.