Service recommendation rules

A service recommendation rule tells xMatix which part or job to recommend when an inspection answer crosses a limit: for example, "when the brake pad question is answered Red, recommend one brake pad set". Rules are set up once by an administrator against the questions of a checklist template. Each time a technician saves an answer to one of those questions on a service order, service opportunity or estimate, the matching rules raise service recommendations on that document for its asset. The advisor then accepts or declines them with the customer.

Overview

A rule has two halves:

• Trigger: the question it watches (Checklist Template Line) and the answer that fires it, either a RAG Value (Red, Amber or Green) or a numeric range (Value Greater Than, Value Less Than).
• Recommendation: what to propose when it fires: the Item, the Quantity and the Recommendation Type.

Rules do not belong to a template version or a document. One question can have several rules, for example one for Amber and another for Red, or two items for the same answer.

When to use it

• You run health checks or inspection checklists on service jobs and want the follow-up work proposed automatically instead of typed in by the advisor.
• You want a measured reading (tread depth, battery voltage, pad thickness) to propose a part only when it is outside a range.
• You want a free-text observation to always raise a recommendation for review.

For work that follows from a customer's complaint rather than from an inspection answer, use the complaint item catalogue instead. See complaints and fault codes.

How xMatix handles it

When rules are checked

Rules are checked on the server whenever a checklist answer is saved:

• A new answer (a new checklist line) is checked against every rule for its question. Each matching rule adds one recommendation.
• A changed answer is checked again when its RAG value, numeric value, text value, data type, label, name, question or owning record changes. Recommendations for rules that still match are refreshed. New matches add recommendations. Recommendations whose rule no longer matches are removed, unless they have already been invoiced (utilised).
• A deleted answer removes the recommendations it raised, except utilised ones.

Changing only the Decimal Value or the Remarks of an answer does not re-check the rules.

Rules are read at the moment the answer is saved. Editing or deleting a rule does not change recommendations that already exist. They catch up only when their answer is next changed.

Which answers a rule matches

What a rule matches depends on which trigger fields you fill in:

As soon as either number is filled in, the RAG Value is ignored. A rule cannot combine a colour with a range. Create two rules for that.

Number rules read only the answer's Numeric Value. Answers to Decimal or Currency questions, and the readings typed on the Health Check tab, are kept in other columns and never fire a number rule. See where each answer is kept.

The Health Check tab saves every answer as a colour: Critical is Red, Warning is Amber and Good is Green. Health-check questions therefore need RAG rules.

What the recommendation carries

Each recommendation raised by a rule gets:

• Name: the rule's Recommendation Type. When the rule has no type, the name of the checklist answer is used instead.
• Item, Quantity, Recommendation Type and Is Mandatory from the rule;
• the answer's reading: Condition (its RAG value), Numeric Value, Text Value and Value Type (the question's data type);
• links to the checklist answer, to the service order, opportunity or estimate the answer was given on, and to that document's Asset.

When the answer changes later, the recommendation's item, type, reading and mandatory flag are refreshed from the rule. Its Quantity is refreshed only if it is empty or zero, so a quantity the advisor corrected is kept.

xMatix recognises "the same recommendation" by its Item and Recommendation Type. If you change the item or type on a rule, the next change to an answer removes the old recommendation (unless it is utilised) and raises a new one.

Is Mandatory

Is Mandatory marks the work as required. The recommendation then shows as Required on the document's Service Recommendations card instead of Optional. Unlike a mandatory complaint item, a mandatory rule does not accept the recommendation or add a line by itself. The advisor still ticks it. The field is not on the shipped rule forms; see Configuration.

Prerequisites

• A checklist template whose questions are used on service orders, opportunities or estimates. See checklist templates and checklists on service orders.
• For number rules: the question's Data Type is Numeric.
• For a rule with no trigger values: the question's Data Type is Text.
• The items you want to recommend exist in the item master.
• Access to the Service Recommendation Rule entity (see Permissions). The list is not in any app's navigation as shipped; you open it from the app launcher.

Procedure

Step 1 — Open the rules list

No shipped app has an entry for service recommendation rules. Open the app launcher (the grid icon beside the logo), type Service Recommendation Rule and choose it.

If your administrators use the list often, give it a permanent place:

1. Go to Setup → Design Studio → Apps and open the app your service administrators use, such as the Service Settings App.
2. Use Manage Items to add Service Recommendation Rule to the app's navigation.

The list opens with the All Service Recommendation Rules view: Name, Recommendation Type, Item, Quantity, Checklist Template Line, RAG Value, Value Greater Than, Value Less Than and Complaint.

Step 2 — Create a rule

1. In the Service Recommendation Rules list, select New.
2. In the Recommendation panel:
   • type a Name (required to save; it is replaced by a number, see Business rules);
   • choose a Recommendation Type, usually Health Check for inspection work;
   • choose the Item to recommend;
   • enter the Quantity to recommend.
3. In the Trigger panel:
   • choose the Checklist Template Line, the question this rule watches;
   • fill in either a RAG Value or one or both of Value Greater Than and Value Less Than. Leave all three empty only for a Text question.
   • leave Complaint empty. It has no effect (see Fields).
4. Select Save.

The rule opens on its record page. The header shows the Complaint and Checklist Template Line. The Recommendation and Trigger panels show the values you entered, and System Information shows who created and last changed it. The rule applies to the next answer saved for that question. Answers already given are not re-checked.

Step 3 — Cover more than one answer

Create one rule per trigger. Common patterns:

• Amber and Red on the same question. Two RAG rules: Amber recommends an inspection or adjustment item, Red recommends the replacement part.
• A graded reading. One rule with Value Less Than 2 for a replacement, and another with Value Greater Than 2 and Value Less Than 4 for "monitor" advice. Remember the limits never match themselves: a reading of exactly 2 fires neither.
• Several items for one finding. Two rules with the same trigger and different items.

Step 4 — Change or retire a rule

1. Open the rule from the list and select Edit in the header.
2. Change the fields and select Save. The same range checks apply as when you create a rule.
3. To retire a rule, select Delete in the header (or delete it from the list).

Existing recommendations are not touched by the change. A recommendation raised by a deleted rule disappears only when its answer is next changed, if no other rule raises the same item and type. Recommendations already invoiced are never removed.

Step 5 — Check the rule works

1. Open a test service order whose asset is set and which has the checklist or health check that asks the question.
2. Answer the question with a value that should fire the rule, and save.
3. Open the order's Service Recommendation tab.

Expected result: a row named after the rule's Recommendation Type shows the rule's item, with Risk taken from the answer's colour and Requirement Optional (or Required when the rule is mandatory). Change the answer so it no longer matches and save: the row disappears.

Fields

The fields of the shipped create form, in form order.

The record page shows Recommendation Type, Item and Quantity under Recommendation, and Checklist Template Line, RAG Value, Value Greater Than and Value Less Than under Trigger.

Business rules

• Numbering. The Service Recommendation Rule Name Setting numbers new rules: the Name you type is replaced with a number from the SRR series.
• Range check on save. When both limits are filled in, the save is refused if they are equal or the lower one is above the upper one. Neither describes a reading that could ever match.
• One limit is fine. A single Value Greater Than or Value Less Than is an open-ended range and is always accepted.
• No check on the trigger shape. A rule with a RAG value and a limit saves, but behaves as a number rule. A rule with no trigger on a non-Text question saves, but never fires.
• Evaluation happens on every save of a checklist answer, as described under When rules are checked. Rules have no active flag or dates. To stop a rule, delete it.
• Utilised recommendations are permanent. Re-checking an answer never removes a recommendation that has been invoiced.

Example

A two-wheeler workshop uses a Periodic Service health check with the question Brake pads (front).

1. The service administrator creates three rules for that question:
   • Health Check, Item Brake Pad Set – Front, Quantity 1, RAG Value Red.
   • Health Check, Item Brake Adjustment, Quantity 1, RAG Value Amber.
   • Health Check, Item Brake Cleaner, Quantity 1, RAG Value Red.
2. The rules are saved as SRR numbers.
3. On a service order, the technician marks Brake pads (front) as Critical on the Health Check tab and saves.
4. The Service Recommendation tab now lists two rows under Health Check: Brake Pad Set – Front and Brake Cleaner, both with Risk High.
5. After a second look the technician changes the answer to Warning. The two Red recommendations disappear and Brake Adjustment appears, with Risk Moderate.

Training

Practice exercise

In a sandbox:

1. Open Service Recommendation Rule from the app launcher (Step 1).
2. Pick a Numeric question from a checklist used on service orders. Create a rule: Recommendation Type Health Check, any part as Item, Quantity 2, Value Less Than 3.
3. Try to create a second rule with Value Greater Than 5 and Value Less Than 5.
4. On a test service order with an asset, answer the question with 2.5 on a checklist that saves numeric answers, and save.

Expected result: step 3 is refused with a message that the range is exclusive at both ends. After step 4 the order's Service Recommendation tab lists the part with quantity 2. Answer 3 instead and the row is removed.

Quick reference

• One rule = one question + one trigger + one item.
• Trigger is a colour or a numeric range, never both. Numbers win.
• Limits are exclusive: Less Than 3 does not fire at 3.
• No trigger at all = any text answer to a Text question.
• Health Check answers are colours: Critical = Red, Warning = Amber, Good = Green.
• Number rules need Numeric questions.
• Set Recommendation Type and Quantity, or the recommendation gets a poor name and quantity.
• Rule changes apply to answers saved afterwards.
• Complaint work is set up in the complaint item catalogue, not here.

Permissions

Because so many shipped profiles can edit rules, consider removing create, edit and delete from profiles that should only answer checklists. See security profiles.

Configuration

• Navigation. The list is found through the app launcher. To give it a menu entry, add the entity to an app in Setup → Design Studio → Apps (Step 1).
• Numbering. The Service Recommendation Rule Name Setting (series SRR, six-digit counter) sets the rule names. Change the series or format in document numbering.
• Recommendation Type values. The picklist ships with Health Check, Past, Complaint and IOT. Add values in the entity's picklist settings if you want more groups on the card. See picklists.
• Is Mandatory on the form. To let administrators mark rules as required, add Is Mandatory to the rule's create and view layouts with the layout designer. You may also remove the unused Complaint field there.
• The questions. Data types and question wording live on the checklist template. A rule follows its question, so changing a question's data type changes which rules can fire. See checklist templates.
• Where answers are captured. The service order's Health Check tab and checklist widgets save the answers the rules read. See checklists on service orders.

Common problems

"Value Greater Than and Value Less Than are both …"

Both limits hold the same number. Nothing is both above and below one number, so the rule could never fire. Widen the band or clear one of the limits.

"Value Greater Than (…) is above Value Less Than (…)"

The limits are the wrong way round. Swap them, or clear one.

A rule never raises a recommendation

Check, in this order:

1. The rule names the Checklist Template Line that was actually answered. A copy of the template has its own questions.
2. For a number rule, the question is Numeric and the answer was not given on the Health Check tab.
3. For a RAG rule, no limit is filled in.
4. The reading is strictly inside the limits, not equal to one of them.
5. The answer was saved after the rule was created. Change and save the answer again to re-check it.
6. The document has an Asset. Without one the card on the document shows nothing.

Recommendations appear for every text answer

The rule has no RAG value and no limits, so it fires on any text answer to a Text question. Add a trigger, or delete the rule.

The recommendation is called after the checklist question

The rule has no Recommendation Type. Set one; existing recommendations take the new name when their answer is next changed.

I changed a rule but old recommendations still show the old item

Rules apply when answers are saved. Existing recommendations are refreshed only when their answer changes.

Common questions

Can a rule fire from a complaint?

No. The Complaint field on the rule form is not used. Recommendations from complaints come from the complaint item catalogue: each complaint, optionally narrowed to a fault code, lists the items it usually needs and whether they are mandatory. See complaints and fault codes.

Do rules work on the field app?

Yes. Rules run on the server when an answer is saved, wherever it was captured. A health check saved from the field app raises the same recommendations as one saved on the web.

Can I make a recommendation be accepted automatically?

Not from a rule. Is Mandatory only marks the row as Required on the card, and the advisor still ticks it. Automatic acceptance exists only for mandatory complaint items.

Does a rule have to be activated?

No. Rules have no active switch, start date or end date. A rule applies from the moment it is saved to every answer saved afterwards for its question, on every service order, opportunity and estimate. To stop a rule, delete it. Recommendations it already raised stay until their answer is next changed, and invoiced ones stay for good.

Related topics

• Service recommendations: accepting, declining and invoicing the work rules raise
• Checklists on service orders
• Checklist templates: questions and data types
• Complaints and fault codes: complaint-driven recommendations
• Document numbering
• Service Recommendation Rule reference
• Service Recommendation — entity reference