Troubleshooting field service

Every field-service outcome is decided by a small predicate over stored records. This page lists, per symptom, the exact checks in the order the platform applies them — so a diagnosis reads the deciding record rather than guessing from a screenshot. It stays text-only on purpose: a generic list view does not show why routing, booking or location failed.

Queued work stays Pending

The route applies these gates in order and stops at the first that empties the pool:

The queue's Agent pool (resource group) contains the expected resource.
The Resource is Active and has a linked User.
The resource's presence is Available and fresh — renewed within the last five minutes. A browser that closed without going offline leaves an Available row that expires and reads as Offline; the supervisor snapshot shows the effective status.
On a Skill-based queue only, and only when the route supplied a skill: a Resource Skill with exactly that Name and Proficiency Level of at least 1. Skill Id, Is Active, Start Date and End Date are not consulted. On other models the skill argument is ignored.
Open load (Assigned plus Accepted items) plus 1 fits within the presence record's Max Work Items (default 5).

Also check: an inactive queue is not refused by the route service, so a rule or telephony route still pointing at it keeps producing Pending items; a decline or transfer-to-queue re-routes without the original skill; supervisor reassign and transfer-to-resource skip every gate. Ties between equal candidates are broken by internal id — do not read a documented priority into the winner. Record queue, item, candidates, presence timestamp and load at the same moment.

A booking slot or candidate is missing

First identify the path the screen uses:

The web and mobile Booking Wizard (product demos, opportunities) reads Branch Time Slots and Branch Time Slot Bookings and computes remaining capacity in the client.
The appointment-scheduling API (bookable resources, appointment slots, holds) is called by no shipped screen yet.

For a missing branch slot: the slot must be Active (an unticked Active flag is stored empty and refused as inactive), on the right branch, with the exact Transaction Type the wizard asks for, and any item, item-group, service-type or service-job-type scope must match. Remaining capacity is the weekday capacity (or Maximum Capacity when the weekday is empty) minus the booking row's Capacity Utilized. The server never refuses an over-capacity reservation, so two bookings for the last place both succeed; reproduce a last-slot race on the exact channel before claiming otherwise.

For a missing appointment candidate: the bookable resource must be active, of the requested kind, inside its effective window, and either branch-less or on the slot's branch; a person requirement with a skill needs an active Resource Skill whose catalog Skill name matches (no proficiency, no dates, no working hours). Capacity counts overlapping Hard resource bookings — including the type's buffers — against Concurrent Capacity. Holds refuse a full slot and expire after the configured lifetime (default 10 minutes), but hold-to-booking conversion has no caller.

Dispatch console availability looks wrong

The console classifies each resource for the selected day from Resource Availability plus Leave Requests:

Availability type is matched by substring: "leave", "half", "holiday", "week" (Weekend shows as Week off). Anything else — including Absent — is classified present.
Any Leave Request overlapping the day marks the resource on leave unless its status contains "reject" or "cancel"; approval is not required.
A resource with no row is inferred Absent only when someone else has data that day; otherwise no marker is shown.
Optimize day and Get candidates skip leave, holiday and week-off lanes only — not half day or absent.

Compare the resource, local date, stored availability type and overlapping leave status. If a lane should not receive work, move the assignment by hand and correct the source record; the optimizer is a placement helper, not an attendance boundary.

If Gantt drops reassign but never set a time, the console has no scheduleStartField configured. If Optimize day places nothing, the visible window is full on every available lane, or there is no unassigned work in scope. If a card shows a 90-minute block for everything, the console has no duration field.

The dispatch map is empty or stale

Check in this order:

The console has a location configuration (geoMode with its fields); without it the Map view is not offered at all.
Location tracking is enabled in the mobile app settings; off or absent means the app never captures.
The technician granted background ("Always") location permission — without it check-in itself is blocked — and is checked in and not paused.
The device has synchronized: read the last upload time and the freshness badge (live within 15 minutes, tracking within 60, off grid after 24 hours).

Points may arrive without a check-in reference, so correlate with attendance by resource and time. Points are stamped with a 90-day purge date, but the retention sweep only purges soft-deleted rows and location points are never soft-deleted — verify your deployment's actual purge process before promising a retention period.

A time-sheet stage is refused or the order's work flags look wrong

Work stages live on the service order time sheet, not the order: Start, Pause (needs a pause reason) and End on selected lines. The legal order per line is Start → (Pause → Start) → End; "already started", "already ended" and "cannot end before start" are the rejections. The service order's Is Work Started / Paused / Ended flags are derived from all* lines on the sheet, so one unfinished line keeps the order out of Work Ended. The StartWork, PauseWork and EndWork actions declared on the service order itself have no server implementation and fail if invoked — use the time-sheet actions. Stages are online-only server actions; a device that was offline cannot backfill a start time.

A new record did not receive a Partner Resource

Only Lead, Opportunity and Product Demo inserts run the rule service; Quote and Service Order do not. For a supported insert, check:

Partner Account and Branch scope on the record match a Partner Resource (branch-less resources match any branch).
A unique Assignment Sequence Number per candidate; the lowest matching wins.
The exact stored Rule Success Criteria text: All Rules Are Met (also the meaning of an empty value), Any Rule Is Met or Always (No Criteria). Any other value silently skips that resource. All-rules and any-rules with no rules both fail.
Rule field names resolve on the inserted entity's own properties; an unresolved name evaluates false.
The rule's stored Operation is one of equals, notEqual, lessThan, greaterThan, lessOrEqual, greaterOrEqual. The shipped Operation picklist offers only Equal, which the engine does not recognise — so with shipped metadata a criteria-based rule can never succeed, and the Rule Success Criteria picklist stores inactive concatenated values (AllRulesAreMet) that also do not match.
Numeric ordering works for double, int and long properties only; decimal fields support equals/not-equal by text.

Until the picklists are corrected in your tenant, the working configuration is a Partner Resource whose stored criteria text is exactly Always (No Criteria), placed last by sequence as the fallback.

What to capture for escalation

Capture, as text or an authorized export: the entity and document id, timestamp and timezone, partner and branch, expected and actual resource, queue and routing model, each candidate's presence status and timestamp, load and Max Work Items, the exact skill-name value, availability date, type and leave status, console scope and window, last location upload time, and for time sheets the line ids and their current stage. A workspace screenshot rarely contains the predicate that decided the result.