AdminConsole
Tutorials/Intermediate
Intermediate45 minREST

Rank responders with a distance matrix

Batch eligible origins, interpret unreachable pairs, apply deterministic tie-breaks, and keep dispatch explainable.

By the endAn explainable ETA-based dispatch shortlist rather than a straight-line guess.
Real-world scenario

Build against an explicit contract

An emergency dispatcher must rank capable available responders by network ETA without exceeding matrix bounds or hiding unreachable candidates.

A Mappls developer projectA restricted REST applicationFixture data with no production credentialsA request, aggregate, or correlation ID strategy
Step 1

Define the user and system contract

An emergency dispatcher must rank capable available responders by network ETA without exceeding matrix bounds or hiding unreachable candidates. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Filter before routing

Select only capable, active, jurisdiction-eligible resources with fresh positions; cap the candidate set and retain the eligibility reasons.

Routes & Navigation · SDK or product slice
val route = MapplsDirections.builder()
  .origin("MMI000")
  .destination("MMI001")
  .profile(DirectionsCriteria.PROFILE_DRIVING)
  .resource(DirectionsCriteria.RESOURCE_ROUTE)
  .steps(true)
  .build()

route.enqueueCall(object : Callback<DirectionsResponse> {
  override fun onResponse(call: Call<DirectionsResponse>, response: Response<DirectionsResponse>) {
    val primaryRoute = response.body()?.routes()?.firstOrNull()
  }
  override fun onFailure(call: Call<DirectionsResponse>, error: Throwable) = Unit
})
Step 3

Build a bounded matrix

Use one resolved incident destination, batch origins within documented limits, choose the correct vehicle profile, and preserve input/output index identity.

Step 4

Rank with policy, not ETA alone

Exclude unreachable/stale pairs, then apply ETA, workload, capability priority, and deterministic tie-breaks; store the matrix request time and chosen explanation.

Step 5

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when every ranked unit was eligible before routing; unreachable pairs remain explicit; the dispatch decision is reproducible from evidence. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

candidate telemetry is stale

Fail fast with a typed, user-safe outcome and preserve the original request identity.

matrix returns partial/unreachable pairs

Keep the last verified state, mark freshness honestly, and retry only within the documented idempotency boundary.

incident changes while ranking is in flight

Reconcile durable local and provider evidence before declaring success or issuing a compensating command.

Never turn uncertainty into success

Timeout after a stateful command is an unknown outcome. Query by provider/idempotency identity or wait for authoritative events; do not blindly retry a new command.

Acceptance criteria

Definition of done

every ranked unit was eligible before routingunreachable pairs remain explicitthe dispatch decision is reproducible from evidence

REST production checks

Credentials never reach a browser or mobile bundleTimeout, retry, and idempotency policies are explicitCoordinates, addresses, and identifiers have data-retention rulesEvery operation is attributable in logs and usage reporting
Grounded implementation

Continue from source, contracts, and a full app

These links resolve to repository-derived evidence; unsupported package names and endpoints are not filled in from guesswork.

Study the complete Coordinated incident response state machine
Tutorial complete

Run it, break it, then observe it

Start with fixture credentials, execute the failure plan, and use request logs, usage, webhook evidence, and operational metrics before promoting traffic.