AdminConsole
Tutorials/Advanced
Advanced2 hrREST + Web

Reconcile a complete InTouch trip lifecycle

Create provider identity, consume event-time telemetry, own exceptions, and close only after provider acknowledgement.

By the endA restart-safe connected trip with replay, late evidence, and closure reconciliation.
Real-world scenario

Build against an explicit contract

A logistics control tower must reconcile internal orders with provider trip and telemetry state across retries, late observations, exceptions, and closure.

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

A logistics control tower must reconcile internal orders with provider trip and telemetry state across retries, late observations, exceptions, and closure. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Bind identities before movement

Persist internal trip, provider trip, vehicle/device, route revision, idempotency request, and policy version in one aggregate.

InTouch Telematics · SDK or product slice
type AssetEvent = {
  id: string;
  assetId: string;
  occurredAt: string;
  type: "position" | "ignition" | "geofence.entered" | "geofence.exited";
  position?: { latitude: number; longitude: number; speedKph?: number };
};

export async function handleAssetEvent(event: AssetEvent) {
  // Idempotency matters: delivery may be retried.
  if (await events.exists(event.id)) return;
  await events.transaction(async () => {
    await events.record(event);
    await assets.apply(event.assetId, event);
  });
}
Step 3

Separate commands from observations

Send create/start/close through an outbox and reconcile acknowledgement; ingest telemetry/events with source/event/content identity and event-time ordering.

Step 4

Close through evidence

Require destination/route progress, resolved exceptions, delivery proof, and provider close acknowledgement; retain late evidence as a derived revision without reopening terminal state.

Step 5

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when duplicate commands and events have one effect; late telemetry cannot regress progress; ambiguous provider close is reconciled before terminal success. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

provider accepts command but response is lost

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

telemetry gap or route deviation

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

closure requested with open exception

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

duplicate commands and events have one effectlate telemetry cannot regress progressambiguous provider close is reconciled before terminal success

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 Connected fleet trip 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.