DEV Community: Puria Moradi

A Practical Data Model for Safer Boiler Service Requests

Puria Moradi — Wed, 02 Sep 2026 23:17:42 +0000

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:

Customers can answer the questions without opening the boiler.
Safety-critical observations are separated from ordinary symptoms.
The original customer wording is preserved.
Routing data is structured enough for filtering and assignment.
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"
  }
}

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);

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"
}

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.

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.

A Safe, Structured Workflow for Logging Boiler Faults Before Calling a Technician

Puria Moradi — Wed, 02 Sep 2026 22:16:15 +0000

When a residential boiler stops working, the first instinct is often to reset it repeatedly or search the error code and order the first component mentioned online. That approach loses useful evidence and can turn a small diagnostic task into an expensive parts-swapping exercise.

A better approach is to treat the appliance as a system that produces observable signals. You do not need to open the casing or touch gas and electrical components. You only need a repeatable way to capture the context in which the problem occurs.

Start with a minimal incident record

Create one note for each incident and capture:

the complete boiler model;
the displayed error code;
system pressure while cold;
system pressure after heating starts;
whether domestic hot water works;
whether every radiator is affected;
the time between startup and failure;
unusual sound, smell, leakage, or vibration;
recent maintenance or component replacement.

This is similar to writing a useful bug report. “It does not work” is hard to reproduce. “Heating stops after four minutes, hot water still works, pressure rises from 1.2 to 2.4 bar, and error X appears” gives a technician a much better starting point.

Separate the operating modes

Residential combination boilers commonly serve two different user-visible functions: domestic hot water and space heating. Test and report them separately.

If hot water works but radiators remain cold, the diagnostic path is different from a complete shutdown. If only one radiator is cold, the issue may be local to that branch rather than the boiler itself. Recording these distinctions reduces unnecessary inspection and prevents unrelated components from being blamed.

Preserve the original error state

Take a photo of the display before performing a permitted reset. Note what the boiler was doing when the code appeared. Did the error occur immediately, during ignition, after several minutes of heating, or only when a hot-water tap was opened?

One reset performed according to the manufacturer’s user instructions may clear a temporary stop. Repeated resets are not a repair strategy. They may remove the exact state that needs to be observed.

Record pressure as a time series

A single pressure reading is useful, but a small time series is better:

08:00 — system cold — 1.2 bar
08:20 — heating active — 1.8 bar
12:00 — heating off — 1.1 bar
Next morning — system cold — 0.7 bar

This does not diagnose the component. It shows the pattern. A technician can then investigate the relevant parts of the sealed heating circuit with appropriate tools.

Do not keep adding water merely to hide a recurring pressure loss. If the system repeatedly needs adjustment, the underlying cause still exists.

Capture sound and location

“The boiler is noisy” is too broad. Describe the sound and when it happens:

clicking during ignition;
a boiling or kettling sound after heating starts;
vibration from the casing or nearby pipework;
a sudden knock when the burner stops;
continuous pump-like noise with cold radiators.

A short video can be more useful than a long verbal explanation, provided it can be recorded without approaching a leak, hot surface, or unsafe electrical area.

Use a simple decision tree

You can organize the observations without diagnosing internal components:

Is there a gas smell, burning smell, major leak, or severe noise? Stop and follow the appropriate emergency procedure.
Is the display on and is an error code visible? Photograph it.
Does domestic hot water work?
Does space heating work?
Are all radiators affected or only one zone?
Is pressure stable between cold and operating conditions?
Did the issue begin after maintenance, power interruption, or a settings change?

The output of this decision tree is a compact incident report, not a DIY repair instruction.

Localized documentation matters

Model naming, error-code presentation, service coverage, and the information requested during booking can vary by market. For Persian-language users, this Iran Radiator service guide provides a local intake reference. A useful request should include the model, error code, pressure reading, neighborhood, and whether the issue affects hot water, heating, or both.

Define the service outcome

The end of a service visit should produce more than “the boiler is running.” Ask for:

the observed cause;
the tests performed;
the action taken;
the identity and condition of any replaced component;
separate parts and labor costs;
warranty scope and duration;
a test of both hot-water and heating modes.

After the visit, keep recording pressure and behavior for several days. If the fault returns, you now have before-and-after data rather than a vague description.

Safety boundary

The logging workflow is intentionally external and observational. It does not include removing the cover, measuring live electrical circuits, changing gas settings, modifying a flue, or bypassing safety controls. Those tasks require qualified personnel and appropriate instruments.

If there is a suspected gas leak, burning smell, significant water leak near electrical parts, or any sign of unsafe combustion, stop normal troubleshooting and follow the relevant emergency guidance for your location.

Conclusion

Good boiler diagnostics begin with a reproducible report. Separate hot water from heating, preserve the error state, record pressure over time, identify which radiators are affected, and document recent changes. This small amount of structured data helps a qualified technician test the right systems first and reduces the risk of speculative component replacement.