Administration
This page covers the controls an administrator owns: feature flags that switch Lite/Pro behavior, the permission model, the settings hub, notifications and automation, the AI-assist opt-in, and the two API surfaces. Configure these in Settings → Field Service and Settings → Roles.
Feature Flags (Lite / Pro)
Lite is the default. Pro surfaces stay hidden until their flag is on, so you can grow into them per tenant.
| Flag | Turns on | Mode |
|---|---|---|
module_field_service | The whole module (menu, screens, jobs, APIs) | — |
field_service_mode | Lite (SME) or Pro (multi-branch dispatch) | — |
field_service_customer_portal | The public self-service portal | Lite |
field_service_mobile_offline | The installable offline technician app | Lite |
field_service_dispatch_board | The drag-and-drop dispatch board — the Dispatch Board tab of the Dispatch Board page (the Calendar tab stays either way) | Pro |
field_service_sla | SLA policies and escalation — the SLA Policies tab of the Agreements page | Pro |
field_service_contracts | Service contracts and entitlements — the Service Contracts tab of the Agreements page | Pro |
field_service_route_recommendations | Route suggestions | Pro |
field_service.ai_assist | Optional AI assist (off by default) | — |
Sidebar entries for dispatch, contracts and SLA are gated by both their permission and their flag, so switching a flag off cleanly removes the surface.
Permissions
Field Service declares its own permissions (never in core), grouped under Operations: Field Service in the Roles editor. Keys are frozen once shipped — they are not renamed. Administrators bypass all checks.
| Area | Permission keys |
|---|---|
| Base access | field_service, field_service_create, field_service_update, field_service_delete |
| Requests | field_service_request |
| Work orders | field_service_workorder + _release, _schedule, _dispatch, _cancel, _reopen, _review, _approve |
| Dispatch (Pro) | field_service_dispatch |
| Commerce | field_service_quote (+ _discount_override), field_service_billing, field_service_payment (+ _void) |
| Parts | field_service_inventory (+ _reverse) |
| Workforce & location | field_service_technician, field_service_location_live, field_service_location_history |
| Planning | field_service_contract (+ CRUD), field_service_sla, field_service_maintenance (+ CRUD) |
| Administration | field_service_settings, field_service_audit_export |
| AI assist | field_service_ai, field_service_ai_approve |
field_service_location_live) and their historical route (field_service_location_history) are separate grants. Give them only to roles that operationally need them.Settings Hub
Field Service adds one entry to the core Settings components group, opening its own sub-tabs:
General
Mode, base defaults.
Numbering & Statuses
Number sequences and display labels for statuses.
Scheduling
Availability windows, skill/zone matching.
Mobile & Location
Offline app, sync thresholds, tracking.
Inventory
Parts, reservations and van stock behavior.
Billing
Billing hand-off and payment options.
Notifications
Which events notify whom.
Portal & Branding
Portal toggle, look and tokens.
Integrations
Sibling-module wiring and API access.
Data Retention
How long records and evidence are kept.
Settings changes are audited as update:fs_settings; audit exports are logged as export:fs_audit.
Notifications and Automation
The module raises notifications for the milestones a coordinator, technician or customer cares about: request received, quote ready/approved, appointment confirmed, technician dispatched/arriving, work completed, invoice issued, payment received, SLA at risk/breached, and stale technician sync.
Cron Jobs
Six scheduled jobs run per tenant. Each is idempotent, self-gates on module_field_service, and appears in php erpat cron:list.
| Slug | Does | Schedule |
|---|---|---|
fs_generate_maintenance | Creates due maintenance occurrences and materializes their work orders | Daily 01:30 |
fs_evaluate_sla | Marks active SLA instances at-risk or breached and notifies on breach | Every 15 min |
fs_appointment_reminders | Sends reminders for jobs starting within the reminder window | Hourly (:05) |
fs_expire_portal_tokens | Revokes customer-portal access tokens past their expiry | Daily 02:20 |
fs_stale_sync | Counts active devices that have not synced within the threshold | Hourly (:00) |
fs_purge_kiosk_shares | Retires shared-screen links that expired without any screen using them | Hourly (:25) |
Preventive maintenance won't duplicate jobs — occurrences use a unique key, so a re-run is safe.
AI Assist (Opt-In)
Optional AI assist can help triage requests, explain dispatch choices and suggest a diagnosis — always with a person approving. It is off by default and gated by strict controls.
- Opt-in flag — enable
field_service.ai_assistin Settings. - Data-privacy acknowledgement (DPA) — a user must accept the DPA before using AI; changes are audited as
dpa:fs_ai. - Redaction — personal data is redacted before anything is sent; full prompts are never stored.
- Human approval — AI never changes a work order, quote or invoice on its own. A person with
field_service_ai_approvereviews, approves and applies. - Tenant-isolated logs — interactions are logged to the tenant tables
fs_ai_interactions/fs_ai_usage, never the platform assist history.
The Two API Stacks
Field Service exposes two independent API surfaces. They serve different callers and use different auth.
Client / Integration API
/api/v1/field-service/* — machine-to-machine (OAuth client credentials). For partners, IoT intake, dashboards and back-office integrations.
Scopes: field_service:read (reads), field_service:write (writes).
Covers work orders, service-request intake, customer assets, the dispatch board and resource availability.
End-User API
/v1/api/field-service/* — the technician handheld and offline PWA. Every action binds to the signed-in user and requires the module to be enabled.
Purpose: job list, device register/heartbeat, the offline bootstrap/pull/push sync protocol, and resumable chunked attachments.
Sync is idempotent by operation id and uses optimistic concurrency by version number.
Full endpoint lists are in the Reference.
Shared Screens (Dispatch Kiosk)
The dispatch kiosk can run on a wall display that nobody signs in to. Sharing is off until you turn it on in Settings → Field Service → Dispatch Kiosk, and it needs the dispatch board to be enabled (Pro).
Setting a screen up
- Name the screen (for example “Lobby TV”) and press Generate link.
- Open that link on the screen itself — paste it, or scan the QR code with the screen’s own browser.
- Press Show the board on this screen. The screen is now paired and the link is finished.
The link is shown once. Only a fingerprint of it is stored, so it cannot be shown again afterwards — not from the app and not from a backup. If you lose one, generate another.
What makes it safe to hand out
One screen per link
Whoever opens it first gets the screen. Everyone else — including the same link opened again a moment later somewhere else — is refused, and told only that the link cannot be used.
Short window
An unused link dies on its own, five minutes by default. After that it is worth nothing wherever it was pasted, screenshotted or forwarded.
Nothing secret in the address bar
Once paired, the screen’s credential is held by the browser, not shown in the URL. Nobody reads it off the display, and it is not in the browsing history.
Tied to that device
The credential is bound to the browser that paired. Copied onto another machine, it stops working.
Revoke works by itself
The screen re-checks its access every refresh, so a revoked display blanks itself within a minute and says so. Nobody has to walk to it.
Read-only, and discreet
A shared screen can only look. By default it also hides customer names and job details and shows technicians by first name — you can turn that off when the screen is somewhere only staff can see.
Managing screens
The same tab lists every screen with its status (Waiting / Live / Expired / Revoked), the device that took it, when it paired, when it was last seen and when it expires. Revoke switches a screen off immediately; Delete removes the row. Screens also expire on their own (30 days by default) so a display that was unplugged, moved or sold does not stay authorised forever, and a cap limits how many can be live at once.
Generating, pairing, revoking and deleting are all written to the activity log (created:fs_kiosk_share, claimed:fs_kiosk_share, revoked:fs_kiosk_share, deleted:fs_kiosk_share). The link itself is never written to the log.
An hourly job, fs_purge_kiosk_shares, clears out links whose window closed without any screen taking them, so the list keeps describing real screens. It never touches a screen that actually paired — an expired or revoked pairing stays until you delete it.
Audit Trail
Sensitive actions write to the tenant's system activity log with a registered event key (action:component), so they surface in the audit views. Examples: converted:fs_service_request, dispatched:fs_work_order, approved:fs_work_order, reopened:fs_work_order (warning), discount_override:fs_quote (warning), invoiced:fs_billing_candidate, voided:fs_payment (warning), reversed:fs_part (warning), breached:fs_sla (critical) and the AI events. The complete list is in the Reference.