A Practical Data Model for Safer Boiler Service Requests

Boiler repair often starts with a vague message: “It stopped working,” “the radiators are cold,” or “the pressure keeps changing.” Those descriptions are valid from a homeowner’s perspective, but they are not enough to route a request, estimate urgency, or prepare a technician. A small, human-readable data model can turn the first contact into a structured service record without asking the customer to diagnose the appliance.

This article proposes a lightweight intake schema for heating-service teams. The design is useful for a web form, call-center application, CRM integration, or a simple internal API. Its purpose is not automated diagnosis. It captures observable facts, keeps safety decisions explicit, and gives the field technician a consistent starting point.

Design goals

A useful intake model should satisfy five requirements:

1. Customers can answer the questions without opening the boiler.
2. Safety-critical observations are separated from ordinary symptoms.
3. The original customer wording is preserved.
4. Routing data is structured enough for filtering and assignment.
5. Every update is auditable.

The distinction between observation and diagnosis matters. An error code is an observation. “The pump is broken” is a diagnosis unless a qualified technician has tested it. Storing those ideas in different fields prevents a telephone guess from becoming an assumed fact later in the workflow.

A compact JSON example

{
  "requestId": "SR-2026-004281",
  "createdAt": "2026-09-03T09:40:00Z",
  "customer": {
    "preferredContact": "phone",
    "serviceArea": "north-west district",
    "availabilityWindow": "14:00-18:00"
  },
  "appliance": {
    "category": "wall-mounted-combi-boiler",
    "brand": "Butaneh",
    "modelText": "customer-reported model label",
    "approximateAgeYears": 6
  },
  "observations": {
    "customerDescription": "Hot water turns cold after two minutes",
    "errorCodeText": null,
    "pressureBar": 1.2,
    "affectsHotWater": true,
    "affectsHeating": false,
    "startedAt": "2026-09-02T18:30:00+04:30",
    "frequency": "every-use"
  },
  "safety": {
    "gasOdor": false,
    "smoke": false,
    "burningSmell": false,
    "waterNearElectricalParts": false,
    "unusualLoudNoise": false
  },
  "consent": {
    "diagnosticVisitApproved": true,
    "repairApprovalStatus": "not-requested"
  }
}

Enter fullscreen mode Exit fullscreen mode

Treat safety as a routing decision

Safety answers should trigger a defined operational path. If a customer reports a gas odor, smoke, a burning smell, severe noise, or water near electrical components, the system should not display ordinary troubleshooting instructions. It should present the organization’s approved emergency guidance and place the request in a safety-review queue.

Do not ask customers to remove covers, adjust combustion components, test wiring, or manipulate gas fittings. The application can request visible information such as the displayed pressure or error text. It must not transfer the technical risk to the person reporting the fault.

One implementation pattern is a simple derived field:

const requiresSafetyReview = Object.values(request.safety).some(Boolean);

Enter fullscreen mode Exit fullscreen mode

That expression is intentionally conservative. A trained dispatcher can refine the response, but the software should never silently downgrade a positive safety report.

Preserve provenance

Service records change. A dispatcher may correct a model name, a technician may add measurements, and a customer may clarify that a symptom occurs only during hot-water use. Instead of overwriting the original values, attach provenance to important facts:

{
  "field": "observations.pressureBar",
  "value": 0.6,
  "source": "technician-measurement",
  "recordedAt": "2026-09-03T11:15:00Z",
  "actorId": "tech-184"
}

Enter fullscreen mode Exit fullscreen mode

This prevents a technician measurement from being confused with a customer reading. It also helps support staff understand why the routing decision changed.

Separate visit approval from repair approval

Agreeing to a diagnostic visit is not the same as approving a repair. Model these states independently. After inspection, the service record can add a quotation containing labor, parts, taxes, travel fees, and a validity period. Only then should the customer’s repair approval be recorded.

Useful states include not-requested, pending, approved, declined, and expired. Record the timestamp and approval channel. This approach reduces billing disputes and makes it clear whether extra work discovered during the visit requires new consent.

Make the handoff readable

Technicians should not need to interpret raw JSON on a phone. Generate a short field summary:

Wall-mounted combi boiler, approximately six years old.
Hot water becomes cold after two minutes; heating is unaffected.
No error code reported. Displayed pressure: 1.2 bar.
No safety warning selected. Symptom occurs on every use.
Customer is available from 14:00 to 18:00.

Enter fullscreen mode Exit fullscreen mode

The summary should link back to the full record and show when each fact was collected. Keep it descriptive. It must not invent a likely failed component.

For a Persian-language example of how customers can prepare model, location, error-code, and symptom details before contacting a service team, see the نمایندگی رسمی بوتان service page. The same intake principles apply regardless of the front-end language: collect observable facts, flag safety conditions, and confirm scope before work begins.

Validate without becoming hostile

Validation should catch impossible or incomplete values while allowing uncertainty. For example, a pressure field may accept unknown rather than forcing a number. Model text should remain free-form because labels can contain spacing, punctuation, and regional variants. Dates should be stored with time zones, and customer-facing timestamps should be rendered in the local format.

Avoid making photographs mandatory. Images can help when a label or display is readable, but users may have limited bandwidth or unsafe access to the appliance. A missing photo must not block a safety-related request.

Measure workflow quality

Once the model is stable, operational metrics become more reliable. Teams can measure the percentage of requests with a model, the time from intake to assignment, first-visit completion, repeat visits for the same symptom, quotation approval time, and warranty callbacks. These metrics evaluate the process, not the customer.

Review missing-field rates carefully. If many callers cannot answer a question, the label may be unclear or the field may not belong in initial intake. A good schema evolves from real conversations.

Conclusion

A structured boiler-service request is a coordination tool, not a diagnostic engine. The best model preserves the customer’s description, records visible facts, isolates safety signals, tracks consent, and keeps an audit trail. When the system produces a concise technician handoff without guessing at the fault, it improves routing and transparency while respecting the boundary between information collection and professional diagnosis.