How-To Do This

How to build AssetOps

Build customer, location, asset, inspection, work-order, technician, parts, and service-history operations.

AssetOps is a asset and field operations 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

Connect each physical asset to its customer/site hierarchy, current condition, inspections, service work, technicians, parts, documents, photos, and complete maintenance history.

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: Use parent/child and typed relationships for customer → site → asset/component, then attach inspections, issues, work, people, files, and invoices to their canonical records.

2. Build the working screens

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

• Operations dashboard and work queue.
• Customer/site/asset 360-degree detail.
• Mobile-friendly inspection and issue capture.
• Dispatcher schedule and technician assignment.
• Work-order execution with parts, photos, signature, and closeout.

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

• Scope technicians and managers by assigned work, team, customer, and location.
• Protect customer, warranty, invoice, and sensitive site fields separately.
• Define who may inspect, dispatch, close, reopen, or approve chargeable work.

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

• Scheduled/due asset → inspection task.
• Failed reading/check → issue → work-order rule.
• Work order → assignment, schedule, SLA, and customer notification.
• Technician closeout → required evidence validation → asset history.
• Recurring condition → maintenance suggestion for human review.

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

• Use mobile forms/files for readings, signatures, photos, and offline-tolerant field capture where supported.
• Connect approved inventory, accounting, calendar, mapping, or messaging providers.
• Ingest device/telemetry events through authenticated, deduplicated endpoints or an appliance service.

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, readings, manuals, images, and inspection evidence to summarize condition and prepare maintenance work. Do not let a prediction silently change asset state or schedule chargeable service.

• Preserve visual inspection evidence and source metadata.
• Relate the model's evidence to the exact asset and service event.
• Express recommendations with confidence and maintenance horizon.
• Require approval for work creation/scheduling according to policy.

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: Create one customer, site, and asset; complete a mobile inspection; turn one failed check into a work order; assign and close it with photo evidence.

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 location and assignment restrictions in list, search, and detail views.
• Test duplicate telemetry and inspection submissions.
• Require closeout evidence and valid state transitions.
• Trace each maintenance suggestion to readings and history.

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.