AdminConsole
Stateful journeys/InTouch Telematics
statefulgeofence case aggregate
InTouch · rule and case lifecycle

Fleet geofence exception

Create a governed zone, evaluate vehicle activity, suppress noise, raise an actionable case, and retire the rule safely.

Open implementation workshop Run verified appExplore lifecycle
Lifecycle state machine

Every state means something operational

A state is not a UI label. It determines which actor may act, what evidence exists, what may be retried, and how recovery proceeds.

01
draft

Draft

Geometry, rule semantics, asset scope, schedule, and notification policy are being validated.

02
active

Active

The versioned zone is deployed and evaluated against an explicit asset and schedule scope.

03
breached

Breached

A debounced enter, exit, dwell, or prohibited-presence event created an operational case.

04
acknowledged

Acknowledged

A named operator owns investigation, severity, and response deadline.

05
resolvedterminal

Resolved

The outcome and evidence are recorded without erasing the initiating activity.

06
retiredterminal

Retired

The zone no longer generates new cases but historical activities remain queryable.

Command → decision → event

Transitions are attributable and retry-safe

Commands express intent. The aggregate validates current state and invariants, commits one new version, and emits a fact in the same transaction.

Command & actorAllowed fromResultIdempotency strategy
publish_geofenceFleet administrator
draft
activegeofence.published

Key by internal rule ID and definition version.

record_breachTelematics service
activebreached
breachedgeofence.breached

Use provider activity identity plus rule version.

acknowledge_caseOperations controller
breached
acknowledgedgeofence_case.acknowledged

Deduplicate the operator action, not the underlying telemetry.

resolve_caseOperations controller
acknowledged
resolvedgeofence_case.resolved

Commit outcome, evidence references, and notification outbox atomically.

retire_geofenceFleet administrator
draftactive
retiredgeofence.retired

Reconcile provider deletion and internal retirement with one command key.

Durable records

Persist enough to recover and explain

Keep provider responses, business identity, state, events, and side-effect delivery distinct so each can be reconciled safely.

Geofence definition

Versioned geometry, schedule, assets, and rule policy.

ruleIdversionproviderIdgeometryHashassetScopestatus

Source activity

Immutable enter, exit, dwell, or presence evidence.

activityIdruleVersiondeviceIdeventTimeposition

Exception case

Human ownership, SLA, disposition, and notification state.

caseIdactivityIdsseverityownerstatusresolution
Non-negotiable rules

Protect truth at the aggregate boundary

  1. 1

    Geometry and coordinate reference are validated before publication.

  2. 2

    Every activity names the geofence definition version that evaluated it.

  3. 3

    Noise suppression never deletes raw source observations.

  4. 4

    One provider activity creates at most one operational case per rule version.

  5. 5

    Retirement stops new evaluation while preserving case and audit history.

Failure and recovery

Know what to do before it breaks

Recovery changes durable truth only through the same rules as normal operation. A timeout is an unknown outcome, not evidence that nothing happened.

GPS jitter creates repeated boundary crossings

Detect

Alternating activities occur inside the configured hysteresis time and distance.

Recover

Debounce into one case while retaining raw activities for review.

Rule update races with incoming activity

Detect

The activity cites an earlier provider or internal definition version.

Recover

Evaluate and display it under the cited version; never reinterpret history silently.

Provider deletion times out

Detect

Internal retirement is pending and provider reconciliation is unknown.

Recover

Retry the same delete identity and keep the rule visibly retiring until confirmed.

Notification delivery fails

Detect

The case exists but the notification outbox remains pending.

Recover

Retry independently and escalate by age; do not create another case.

Operational telemetry

Observe the journey, not merely HTTP status

Measure state age, event health, retries, reconciliation, and sensitive-data access alongside latency and error rate.

  • Activities per device and rule before and after debouncing
  • Case acknowledgement and resolution time
  • Rules with provider/internal version drift
  • Notifications pending, retrying, and dead-lettered
  • Geometry validation and publication failures
  • Retired rules still receiving activity
Grounded implementation

Contracts, repositories, workshops, tutorials, and runnable evidence

Only explicitly indexed evidence is linked. Empty sections are not backfilled with invented endpoints or package names.