Complaints and fault codes

A complaint is a symptom from your workshop's catalogue of things customers report ("engine overheating"), and a complaint fault code is one diagnosed cause under it ("coolant leak", "thermostat stuck"). Both are master data that an administrator or service manager maintains; 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 — or AI Mechanic picks them from what the technician says.

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.
• Jobs point at the catalogue. A complaint line stores a link to the complaint and fault record, not a copy of their text, so renaming a complaint or fault changes how it reads on every job that uses it.
• AI Mechanic chooses from the catalogue. When AI Mechanic captures a job's complaints from what the technician says or types, it can only pick complaints and fault codes that already exist — it never creates new ones. Here Applicable To Item and Applicable To Item Group do matter: it offers a fault only when it fits the item of the job's asset (see With AI Mechanic).

Prerequisites

• To maintain complaints, you have an app that lists Complaints. In the shipped navigation that is Service → Settings, group Customer Care.
• To fill Applicable To Item or Applicable To Item Group on a fault code, the item or item group exists in the catalogue.
• Your security profile allows creating and editing Complaint and Complaint Fault records (see Permissions).

Procedure

Step 1 — Create the complaint

Go to Service → Settings and choose Complaints under Customer Care (or open /Complaint). The All Complaints list shows Name, Code, Description and the created and modified stamps. Select New, and fill the dialog:

• Name — required; the symptom as advisors should read it, for example Engine overheating.
• Complaint Code — optional; your short code, for example ENG-OH.
• Description — optional; the symptom in the customer's own words, for example Temperature gauge goes into the red after 15 minutes of riding. AI Mechanic shows this text as the complaint's title, so write it the way a technician would say it.

Save. The complaint is added to the list. Open it to see its record page, with Name and Complaint Code in the header and two tabs, Related and Details. Complaints are not numbered automatically; the name is what you type.

Step 2 — Open the complaint's fault list

On the complaint's record page, open the Related tab. It lists the complaint's fault codes in the Complaint Faults list, and further down the complaint lines that jobs have recorded against this complaint.

Step 3 — 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 4 — 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. Scope a fault only when it truly belongs to that product range: AI Mechanic then stops offering it on jobs for other items.

Step 5 — 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 6 — Record the complaint and 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 7 — Change or correct a complaint or fault

To change the diagnosis on a job, edit the complaint line and choose a different Complaint Fault Code. To correct the catalogue:

• A complaint — open it and select Edit in the header, or use the row's Edit action in All Complaints. The dialog shows Name, Complaint Code and Description. Description is not shown on the record page itself; you see it in the list and in this dialog.
• A fault code — open it from the complaint's Complaint Faults list and select Edit, or use the row's Edit action in the list.

Edits to a name or code show on every job that uses the record, because jobs point at the record rather than copying its text.

Step 8 — Delete a complaint or fault code

Select Delete on the record page, or the row's Delete action in the list. A deleted complaint or fault code is no longer offered in the pickers.

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. Before deleting a complaint, check its Related tab: if jobs have recorded it, consider renaming it instead (for example Obsolete — Engine overheating) so service history keeps a readable complaint. A complaint's fault codes are not deleted with it.

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 6. The mobile app reads complaints and fault codes from the device first, so the pickers also work offline once the data has synced.

With AI Mechanic

Where AI Mechanic is switched on, its complaint step turns what the technician says or types ("the scooter overheats, coolant is leaking at the hose") into proposed complaint lines for the job. Each proposal reads Complaint: … followed by the complaint's codes, for example Code ENG-OH · Fault ENG-OH-01 Coolant leak. The technician reviews the proposals and saves them; saved proposals become complaint lines on the job's service order and raise recommendations exactly as in Step 6.

What AI Mechanic can choose from:

• Existing complaints only — up to 200, taken in Complaint Code order. It never creates a complaint or a fault code.
• The complaint's title is its Description, or its Name when there is no description, or its Complaint Code when neither is set.
• Fault codes under those complaints whose Applicable To Item and Applicable To Item Group fit the job: a fault scoped to an item is offered only when the job's asset is that item, and one scoped to an item group only when the asset's item is a member of the group. Unscoped faults are always offered. When the job has no asset item, no fault is filtered out.
• A fault always stays with its own complaint. If the proposal names a fault from a different complaint, the fault is dropped and only the complaint is proposed.

Fields

Complaint

The complaint record page shows Name and Complaint Code in the header, the Related tab, and a Details tab with Key Information (Name, Complaint Code) and System Information. The New and Edit dialog holds Name, Complaint Code and Description.

Complaint Fault

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 complaint and every fault code. Neither name nor code has to be unique.
• 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. Complaints and fault codes are not numbered automatically; the name and code are 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.
• The service order line's Complaint Code is a note only. A service order line's record page has a Complaint Code field that picks a complaint. It is filled by hand, raises no recommendations and is not linked to the job's complaint lines; record complaints on the Complaints tab instead.

Example

A two-wheeler workshop sets up the complaint Engine overheating (Complaint Code ENG-OH, Description Temperature warning comes on while riding). 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. Under Service → Settings → Complaints, create a complaint Brake noise with Complaint Code BRK-N and a Description. Open it and confirm the Description is not on the record page but is in the Edit dialog. 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.
• Complaints live under Service → Settings → Customer Care → Complaints.
• Add fault codes from the complaint's Related tab → Complaint Faults → Quick Add.
• Name is required on both; codes are optional free text and need not be unique.
• A complaint's Description is AI Mechanic's title for it — write it in the customer's words.
• Applicable To Item and Applicable To Item Group narrow AI Mechanic's fault choices only; the job pickers ignore 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 and Complaint Fault in each security profile. For both, the shipped System Admin, Service, Standard User, Sales Manager and Sales Executive profiles grant full access (read, create, edit and delete). Because these profiles can also change the catalogue, consider removing create, edit and delete on Complaint and Complaint Fault from profiles whose users only record complaints, so the vocabulary stays consistent. Complaints and 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 complaints are maintained. In the shipped navigation, Complaints is in the Service Settings App, reached from Service → Settings, group Customer Care. Your administrator may have placed it elsewhere; the list is also at /Complaint. The shipped All Complaints view shows Name, Code, Description and the created and modified stamps.
• Complaint forms. The New/Edit dialog (Name, Complaint Code, Description) and the record page (header Name and Complaint Code; Details tab Name and Complaint Code) are ordinary layouts. If your team wants the description on the record page, add Description to the Key Information panel in the layout designer — see Design a form layout.
• No complaint numbering. The shipped Complaint Name Document Setting is inactive, so complaint names are typed. Leave it inactive: the name is what advisors pick on jobs.
• Writing complaints for AI Mechanic. AI Mechanic matches what the technician says against each complaint's Complaint Code and Description (or Name when there is no description) and each fault code's code and name, and it reads at most 200 complaints in Complaint Code order. Keep descriptions short and in the words customers use, give every complaint a code if the catalogue is large, and scope item-specific faults with Applicable To Item or Applicable To Item Group. Switching AI Mechanic on is covered in Service recommendations.
• 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.

AI Mechanic does not propose a complaint we have set up

AI Mechanic chooses only from existing complaints, and it reads at most 200 of them in Complaint Code order. If your catalogue is larger, complaints whose code sorts late may not be offered. Check that the complaint exists, that its Description (or Name) uses the words technicians actually say, and trim duplicate or unused complaints. You can always add the complaint line by hand on the service order's Complaints tab.

AI Mechanic proposes the complaint but not the fault

The fault is offered only when its Applicable To Item or Applicable To Item Group fits the item of the job's asset. Open the fault code and clear or correct those fields, or add the asset's item to the item group. A fault named under a different complaint is also dropped, so check that the fault sits under the complaint that was proposed.

I cannot see the complaint's description on its record page

The shipped record page shows only Name and Complaint Code. The description is in the All Complaints list and the Edit dialog. An administrator can add it to the record page in the layout designer.

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?

Only for AI Mechanic. When AI Mechanic captures complaints, it offers a fault scoped to an item only on jobs whose asset is that item, and a fault scoped to an item group only when the asset's item belongs to the group. The complaint-line picker on service orders and estimates and the field-visit picker do not filter by these fields, and no save checks them, so an advisor can still pick a model-specific fault on a job for another model. If advisors need to tell faults apart by model, also make the model clear in the fault's name.

Is a complaint the same as a customer case?

No. A complaint is an entry in your workshop's symptom catalogue, such as Engine overheating, used again and again on jobs. It has no customer, owner, status or due date of its own. When one customer raises a grievance that has to be tracked to resolution — with an owner, a status and response timers — log it as a case. A service job can still record the catalogue complaint on its Complaints tab, so the symptom is counted in service history, while the case tracks the customer conversation.

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