How-To Do This

How to build FieldService

Build customer, service-area, scheduling, job, estimate, approval, evidence, and follow-up operations for field teams.

FieldService is a field-service management pattern. This guide turns the product concept into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Define the outcome before the screens

Move one customer request through triage, scheduling, assignment, field execution, evidence, authorization, payment, and follow-up while keeping dispatchers, technicians, managers, and customers inside their own experience and data scope.

1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

Relationship rule: Keep Contacts, Calendar, Work Orders, files, conversations, payments, and Inbox attention canonical in their first-class modules, linked to the service request and customer graph.

2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

• Dispatcher queue and service-area calendar.
• Customer, site, and equipment history.
• Technician work-order workspace with mobile evidence capture.
• Estimate and manager/customer approval page.
• Closeout, payment state, and follow-up workspace.

Use Puck for the normal visual experience. Keep stable block identity when using Monaco advanced JSON mode so future template upgrades can merge safely.

3. Set access before adding automation

• Create User Types for dispatcher, technician, manager, and customer experiences.
• Scope work by DataRole, assigned technician/team, customer, and Location.
• Protect pricing, payment, customer, and site fields independently.
• Require explicit authority for assignment, estimate approval, charge initiation, closeout, and reopen.

User Type menus establish eligible page routes for each audience. They do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

4. Add the core workflows

• Inbound request -> triage -> service-area and priority routing.
• Approved scope -> schedule and assign technician/resource.
• Field arrival -> checklist, readings, notes, photos, and status transitions.
• Estimate -> authorized approval -> tenant-controlled charge intent.
• Closeout -> customer notice, receipt/evidence, and scheduled follow-up.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

5. Connect channels and outside systems

• Receive email, SMS, forms, and authenticated API requests through the Universal Inbox.
• Use Calendar, mapping, inventory, accounting, payment, and messaging connectors as needed.
• Put specialized estimating or device logic behind a declared appliance endpoint.

Use managed connections, OAuth connectors, inbound endpoints, and webhooks. Put specialized SDKs or private processing behind a declared appliance endpoint; never expose provider credentials to a page.

6. Add AI as a governed layer

Use permitted service history, manuals, text, images, and readings to answer field questions and prepare summaries or estimates. Keep chargeable, customer-facing, and state-changing work inside explicit approval and action contracts.

• Retrieve only the technician's permitted customer, asset, and job evidence.
• Cite the exact source record, file, page, image, or reading.
• Bind suggestions to the current work-order/activity version.
• Require configured approval before creating an estimate, message, charge, or material state transition.

AI and retrieval must apply CanAiReadRecords, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

7. Ship one complete vertical slice

Recommended first release: Accept one service request, schedule and assign it, complete a field checklist with photo evidence, approve an estimate, close the work order, and schedule customer follow-up.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

8. Validate, package, and operate

• Test cross-location, unassigned-technician, customer, and field-level denials.
• Test schedule conflicts and stale work-order versions.
• Prove duplicate requests, charge intents, and follow-up retries are idempotent.
• Trace request, work, approval, payment reference, evidence, and follow-up by correlation ID.

Publish a reviewed exact version as a template when the pattern is reusable. If you sell it, complete the marketplace preparation checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

Built-in data path: React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.