Complaints and fault codes

A complaint fault code is the diagnosed cause behind a reported complaint: the complaint says what the customer noticed ("engine overheating"), and each of its fault codes names one thing the workshop can find wrong ("coolant leak", "thermostat stuck"). Fault codes are master data that an administrator or service manager maintains under each complaint; service advisors and technicians then pick a complaint and, optionally, one of its fault codes when they record the complaint on a service order, a service estimate, a service opportunity or a field visit.

Overview

Three records work together:

On a job, the advisor or technician adds a complaint line that names a complaint and, optionally, a Complaint Fault Code. Saving that line is what turns the catalogue into service recommendations for the job.

For individual customer grievances with an owner, a status and response timers, use cases instead — complaints and fault codes are a vocabulary, not a ticket.

When to use it

• You want technicians to record why a vehicle or asset needed work, not only what the customer said.
• One symptom has several possible causes and each cause needs different parts — fault codes let the recommended parts follow the diagnosis.
• You want the same fault vocabulary on the workshop job card and in the field app, so service history can be compared across jobs.

If every occurrence of a complaint always needs the same parts, you do not need fault codes: a complaint item with no fault code applies to every job that records that complaint.

How xMatix handles it

• A fault code belongs to one complaint. When you add a complaint line on a service order or estimate, the Complaint Fault Code list shows only the fault codes recorded under the complaint you picked. The field app does the same.
• Recommended parts follow the fault. When a complaint line is saved, xMatix looks at the complaint items of its complaint. An item with no fault code is recommended for every fault; an item with a fault code is recommended only when the line names that same fault code. A line with no fault code therefore gets only the fault-independent items.
• Changing the fault re-checks the recommendations. If someone later changes the complaint or the fault code on a complaint line, xMatix adds the recommendations that now apply and removes those that no longer do — except recommendations that were accepted by a person, already turned into a document line, or already used.
• Mandatory items go straight onto the job. A complaint item marked Is Mandatory is accepted automatically and its document line is raised when the complaint line is saved, so the advisor does not have to tick it.
• The recommendation text names the fault. Each generated recommendation carries remarks in the form Complaint : … Fault : … Recommended Qty : …, so the advisor can see which diagnosis suggested the part.

Prerequisites

• The Complaint the fault belongs to already exists. Complaints are in the Service Settings App under Customer Care → Complaints in the shipped navigation.
• To fill Applicable To Item or Applicable To Item Group, the item or item group exists in the catalogue.
• Your security profile allows creating and editing Complaint Fault records (see Permissions).

Procedure

Step 1 — Open the complaint

Open the Service Settings App, choose Complaints under Customer Care, and open the complaint the fault explains. The complaint record has two tabs, Related and Details; the Related tab lists the complaint's fault codes in the Complaint Faults list.

Step 2 — Add a fault code

In the Complaint Faults list, select Quick Add. A one-line entry row opens with three fields:

• Name — required; the fault as people should read it, for example Coolant leak.
• Fault Code — the short code your workshop uses, for example ENG-CL-01.
• Applicable To Item — optional; the single item this fault applies to.

Save the row. The new fault code is linked to the complaint you have open and appears in the list straight away. Repeat for each fault the complaint can have.

Step 3 — Scope it to an item group (optional)

Applicable To Item Group is not on the Quick Add row. To set it, open the fault code from the list, select Edit, fill Applicable To Item Group in Key Information, and save.

Step 4 — Link the parts the fault needs

Add complaint items to the same complaint for the parts and labour the fault needs: choose the Item, enter the Quantity, set Is Mandatory if the part must always be fitted, and pick this fault in Complaint Fault Code. Leave Complaint Fault Code empty for items that every fault under the complaint needs.

Step 5 — Record the fault on a job

On a service order, open the Complaints tab and select New. Pick the Complaint, then pick one of its fault codes in Complaint Fault Code (it is optional), and save. The recommendations for the line appear on the service order's Service Recommendation tab; mandatory items are already on the Lines tab.

Step 6 — Change or correct a fault

To change the diagnosis on a job, edit the complaint line and choose a different Complaint Fault Code. To correct the master record, open the fault code from the complaint's Complaint Faults list and select Edit, or use the row's Edit action in the list. Edits to the fault code's Name or Fault Code show on every job that uses it, because jobs point at the record rather than copying its text.

Step 7 — Delete a fault code

Select Delete on the fault code record, or the row's Delete action in the Complaint Faults list. Before deleting a fault code, check that no complaint item still names it — those items would otherwise need a new Complaint Fault Code to keep recommending their parts for that diagnosis.

On a field visit

When a visit activity is configured to capture complaints, the web visit drawer and the mobile app show a complaint section: pick a Complaint, then an optional Fault code, and add remarks. Changing the complaint clears the fault you had picked, because fault codes are scoped to their complaint. The fault list shows each fault's Fault Code, falling back to its name when no code is set. On submit, every row becomes a complaint line on the visit's service order, which raises recommendations exactly as in Step 5. The mobile app reads complaints and fault codes from the device first, so the pickers also work offline once the data has synced.

Fields

The Complaint Fault record page shows a header with Complaint, Name and Applicable To Item, then Key Information and System Information panels.

Business rules

• Name is required on every fault code.
• Fault codes are scoped to a complaint in the pickers: the complaint line's Complaint Fault Code list and the field app's fault picker show only the faults of the selected complaint.
• A complaint item's fault must belong to the item's own complaint. Saving a complaint item whose Complaint Fault Code belongs to a different complaint is refused with: Complaint Fault '…' belongs to a different complaint. Pick a fault code defined under this complaint, or leave it empty to apply the item to every fault.
• Matching on a job: a complaint item applies to a complaint line when they share the complaint and the item either has no fault code or has the line's fault code. Complaint items with no Item are skipped.
• Re-pointing a complaint line (new complaint or new fault code) adds the newly applicable recommendations and removes the ones that no longer apply, unless a person accepted them, they already have a document line, or they were used. An automatically accepted mandatory recommendation is removed with its line, unless that line has already moved on (invoiced, allocated, picked or confirmed).
• Deleting a complaint line removes the recommendations it generated, on the same terms.
• No numbering. Fault codes are not numbered automatically; the Fault Code is whatever you type.
• Not copied to claims. Service-order lines and claim lines each have their own fault field, filled by hand. Generating claim lines from a service order does not copy the complaint or fault.

Example

A two-wheeler workshop sets up the complaint Engine overheating (Complaint Code ENG-OH). Under it, the service manager adds two fault codes with Quick Add: Coolant leak (Fault Code ENG-OH-01) and Thermostat stuck (Fault Code ENG-OH-02).

Then they add three complaint items to Engine overheating:

A customer brings in a scooter that runs hot. The advisor opens the service order, adds a complaint line with Engine overheating and no fault yet. Coolant is added to the job's lines automatically (mandatory), and nothing else is suggested.

The technician finds a split hose and edits the complaint line to Complaint Fault Code Coolant leak. A recommendation for Radiator hose, quantity 1, appears with the remarks Complaint : Engine overheating Fault : Coolant leak Recommended Qty : 1. The advisor accepts it with the customer. Had the technician picked Thermostat stuck instead, the thermostat would have been suggested and the hose would not.

Training

Practice exercise

In a sandbox tenant:

1. Create a complaint Brake noise and, on its Related tab, add two fault codes with Quick Add: Worn pads and Warped disc.
2. Add a complaint item for brake pads (quantity 1, not mandatory) with Complaint Fault Code Worn pads.
3. Try to add a second complaint item under a different complaint that points at Worn pads.
4. On a draft service order with an asset, add a complaint line Brake noise with fault Worn pads, then change the fault to Warped disc.

Expected result: step 3 is refused with the "belongs to a different complaint" message; in step 4 the brake-pad recommendation appears for Worn pads and disappears again when you switch to Warped disc (as long as you have not accepted it).

Quick reference

• A complaint is the symptom; a fault code is the diagnosed cause under it.
• Add fault codes from the complaint's Related tab → Complaint Faults → Quick Add.
• Name is required; Fault Code is optional free text.
• Applicable To Item and Applicable To Item Group are descriptive — nothing filters or checks them.
• Complaint items with no fault code apply to every fault; with a fault code, only to that fault.
• Changing a job's fault code re-checks its recommendations; accepted or used ones stay.
• Mandatory complaint items go onto the job lines without anyone ticking them.
• The field app's fault picker shows the Fault Code and works offline after sync.

Permissions

Access is the standard entity permission on Complaint Fault in each security profile. The shipped System Admin, Service, Standard User, Sales Manager and Sales Executive profiles grant full access (read, create, edit and delete). Fault codes are shared under the default record-sharing settings for the entity, so whether a user sees fault codes owned by others follows your record security configuration.

Users who record complaints on jobs need read access to Complaint Fault to pick a fault code, on the web and in the field app; the people who maintain the catalogue also need create, edit and delete. To reach complaints in the first place, the user also needs an app that lists Complaints (the Service Settings App in the shipped navigation) and read access to the Complaint entity.

Configuration

• Where fault codes are maintained. Complaint Fault has no navigation entry of its own; it is reached from each complaint's Related tab. To give a team a flat list of all fault codes, add the entity to an app's navigation (see Create an entity, the step on adding it to an app) and use the All Complaint Faults view, which shows Complaint Fault Code Name, Applicable To Item, Complaint and Fault Code.
• Forms. The Quick Add row (Name, Fault Code, Applicable To Item) and the record page (Key Information: Name, Fault Code, Applicable To Item, Applicable To Item Group) are ordinary layouts. Add fields such as Complaint to the record page, or Applicable To Item Group to the Quick Add row, in the layout designer — see Design a form layout.
• The complaint-line fault picker is limited to the selected complaint by a lookup filter on the complaint line's Complaint Fault Code field (Related Complaint Fault Code). Keep it active; without it the picker offers every fault code in the tenant, and a fault from another complaint matches no complaint items.
• The parts catalogue is the complaint items under each complaint — the Item, Quantity, Is Mandatory and Complaint Fault Code you set there decide what is recommended for each fault. How advisors then accept and post recommendations is covered in Service recommendations.
• Field visits. The complaint section appears only on visit activity types configured to capture complaint lines against the visit's service order. The pickers load up to 200 complaints and 500 fault codes, sorted by name.
• Loading fault codes in bulk. However you load them, fill Complaint on every fault code, or it will never be offered on a complaint line.

Common problems

The fault code I added does not appear when I record a complaint

The complaint-line picker shows only fault codes whose Complaint is the complaint on the line. Open the fault code and check its Complaint field — fault codes imported or created outside the complaint's Complaint Faults list may have none, or the wrong one. Adding faults with Quick Add from the complaint avoids this.

"Complaint Fault '…' belongs to a different complaint"

You are saving a complaint item whose Complaint Fault Code is a fault under another complaint. Pick a fault code defined under the item's own complaint, or leave the field empty so the item applies to every fault of that complaint.

I picked a fault code but no parts were recommended

Check the complaint items of the complaint on the line: there must be one with no fault code or with exactly this fault code, and it must have an Item. Complaint items with no Item are skipped.

After changing the fault code, an old recommendation is still there

Recommendations that someone accepted, that already have a line on the job, or that were used are kept when the fault changes, so work that was agreed with the customer is not removed silently. Reject or remove it from the service order's Service Recommendation tab if it is no longer wanted.

The fault picker in the field app is empty

The mobile app reads fault codes from the device. Sync the app while online, then reopen the activity. Also check that a complaint is picked first — the fault list follows the selected complaint — and that your profile can read Complaint Fault records.

Common questions

What is the difference between a complaint and a fault code?

A complaint is what the customer reports — the symptom, such as Engine overheating. A fault code is what the technician finds — the cause, such as Coolant leak. Every fault code sits under exactly one complaint, and one complaint can have many fault codes. On a job you always record the complaint, and you add the fault code once the diagnosis is known. Using both lets the parts xMatix recommends follow the diagnosis: parts that every cause needs go on the complaint, and parts specific to one cause go on that fault code.

Do I have to pick a fault code on every complaint line?

No. The fault code is optional on complaint lines, on service orders, estimates, opportunities and field visits. A line without a fault code still records the complaint and still gets the recommendations for complaint items that have no fault code. Adding the fault code later — once the technician has diagnosed the problem — adds the fault-specific recommendations at that point. That makes it practical to log the complaint at reception and fill in the fault after inspection, without re-entering anything.

Does Applicable To Item restrict which jobs can use the fault code?

No. Applicable To Item and Applicable To Item Group record which product the fault concerns, for reference and reporting, but no picker filters by them and no save checks them. A fault code scoped to one model can still be picked on a job for another model. If you need separate faults per model, create separate fault codes with names that make the model clear.

Can I reuse one fault code under several complaints?

Not as a single record: a fault code has one Complaint. If the same cause explains two symptoms — a stuck thermostat can cause both overheating and poor heating — create one fault code under each complaint. Give them the same Fault Code text if you want to report on them together; the code is free text and does not need to be unique.

Related topics

• Service recommendations — how the suggestions raised from complaints are accepted and posted
• The service order lifecycle — where complaint lines are recorded
• Service claims
• Service configuration
• Complaint Fault — entity reference
• Complaint — entity reference