Service recommendations

A service recommendation is a piece of advised work for an asset: a part or job that an inspection, a complaint or an advisor says should be done. The customer accepts or declines it on the service order or service opportunity. Recommendations sit between diagnosis and billing. A checklist answer or a complaint raises them. The advisor reviews them with the customer on the document's recommendations tab. Each accepted recommendation becomes an ordinary line on the job, and the invoice run then marks it as used.

Overview

Each recommendation records:

• what is recommended: the Item and a Quantity;
• for which asset: the Asset it concerns;
• why: the observed Condition (Red, Amber or Green), the reading behind it (Value Type, Text Value, Numeric Value), the Recommendation Type that names its source, and Recommendation Remarks;
• where it came from and went to: the checklist line or complaint line that raised it, and the service order, opportunity or estimate line it became;
• the decision: Is Accepted, Is Rejected and Is Utilized, plus whether the work is required (Is Mandatory).

The decision is taken from the document, not from the recommendation record. The service order's Service Recommendation tab and the service opportunity's Recommendation tab both host the Service Recommendations card, where you tick the work the customer accepts.

When to use it

• At reception and during inspection. Show the customer what the health check and their complaints call for, and record what they agree to.
• When advising future work. Create a recommendation by hand against the asset, for example a part that will be due soon, so that it comes up on the asset's next job.
• When reviewing declined or deferred work. The Service Recommendations list is the register of everything ever advised, by asset.

How xMatix handles it

Where recommendations come from

Which recommendations a document offers

The recommendations card on a service order lists two groups:

• Open recommendations for the order's asset: not accepted, rejected or utilised, and not yet linked to any service order, service order line, estimate or estimate line. In practice these are the hand-made ones, plus those raised on a service opportunity that were never decided there.
• Every recommendation already linked to this order, whatever its state: the ones its own checklists and complaints raised, accepted and rejected ones included.

A service opportunity works the same way. In addition, its open group leaves out anything already linked to another opportunity.

A recommendation raised by a checklist or a complaint is linked to the document that raised it from the start. It is therefore not offered again on the asset's later orders, even when nobody decided it. Only unlinked recommendations follow the asset from job to job. A document without an asset shows an empty card.

Accepting

When you save a tick on the card, the recommendation is marked Is Accepted and a new line is added to the document:

• Service order: a service order line with the recommendation's Item. Its Quantity is the recommendation's Quantity when above zero, otherwise its Numeric Value when above zero, otherwise 1. The line also carries the Recommendation Type and a link back to the recommendation, and it is priced like any other line.
• Service opportunity: an opportunity line with the recommendation's Item and Quantity. The recommendation is then linked to the opportunity and to the new line.

Mandatory complaint items skip the tick. When the complaint line is posted, their recommendations are accepted automatically and the line is added to the service order (or, when there is none, the opportunity, then the estimate). The card shows them as Required.

Rejecting

Clearing the tick on an accepted recommendation and saving rejects it. The line its acceptance added is withdrawn and the link to it is cleared. The recommendation stays on this document's card, unticked. Rejection is refused while the service order line is allocated, picked or invoiced.

Utilisation

Running Invoice or Selective Invoice on a service order marks every recommendation behind a line of that order as Is Utilized and links it to the order and line. This includes lines that this particular invoice run did not bill. A utilised recommendation is never offered again and cannot be deleted.

Prerequisites

• The service order or opportunity has an Asset. Without one the card is empty.
• For checklist-driven recommendations: service recommendation rules exist for the checklist template lines.
• For complaint-driven recommendations: complaint items are set up for the complaint, optionally per fault code.
• Your security profile grants Recommendation (Get Service Recommendation) and Post Service Recommendation on Service Order, and the matching pair on Opportunity. See Permissions.

Procedure

Step 1 — Open the recommendations card on the job

Open the service order and select the Service Recommendation tab. On a service opportunity, select the Recommendation tab. The Service Recommendations card lists the recommendations, grouped under coloured bars by Recommendation Type. Each row shows:

• Name;
• Items: the item and its type;
• Risk: High for Red, Moderate for Amber, Low for Green;
• Type;
• Requirement: Required for mandatory work, Optional otherwise.

Ticked rows are already accepted. Use the column headers to sort or filter. The card refreshes by itself when a checklist answer or a recommendation changes.

Step 2 — Record what the customer accepts

1. Select Edit on the card. The tick boxes become active.
2. Tick each recommendation the customer accepts. The header box ticks every row.
3. Select Save. Save stays disabled until you change at least one tick. Cancel puts the ticks back as they were.

Each newly ticked recommendation adds a line to the order's Lines tab (or to the opportunity's lines), with the quantity described under Accepting. Price, tax and contract cover are worked out as for any line you add yourself. Open the line to see its Recommendation panel, with the Recommendation Type and the link back.

Step 3 — Withdraw an acceptance

1. Select Edit on the card.
2. Clear the tick on the accepted recommendation.
3. Select Save.

The recommendation is now rejected and the line it added is removed from the order. This works only while that line has not been allocated, picked or invoiced. Otherwise saving fails with Cannot reject a service recommendation whose service order line is already transacted. Remove the allocation or picking first.

Step 4 — Decline a recommendation that was never accepted

The card cannot record a decline for a row that was never ticked, because it only sends rows whose tick changed. To record that the customer declined:

1. Open the recommendation from the Service Recommendations list (or from the Name link in the list).
2. In the Controls panel, tick Is Rejected and save.

A rejected recommendation is never offered on another document. You can also tick it and save on the card (accept), then clear the tick and save again (reject). That briefly adds the line and then removes it.

Step 5 — Create a recommendation by hand

1. Open the Service Settings App and choose Service Recommendations (or go to /ServiceRecommendation).
2. Select New.
3. Enter Name (required), and choose the Item and the Asset.
4. Under Conditions, optionally set Condition, Value Type and Recommendation Type, and record the reading in Text Value or Numeric Value.
5. Select Save.

The record page opens. The create form has no Quantity field. Set Quantity and Recommendation Remarks in place on the record page, in the Recommendation Details panel, before the recommendation is accepted. Otherwise a service order line gets the Numeric Value or 1 (see Accepting), and an opportunity refuses the line (see Common problems). The new recommendation is unlinked, so it appears on the next service order or opportunity raised for that asset.

Step 6 — Review recommendations for an asset

Open the Service Recommendations list. The All Service Recommendations view shows Name, Asset, Item, Value Type, Recommendation Type, Is Utilized, Condition and the audit columns. Search or filter by asset to see everything ever advised for it.

Open a row to see the record page:

• the header shows Asset and Checklist Line;
• Key Information holds the item, asset, reading and type;
• Recommendation Details holds the quantity, labels and remarks;
• Controls holds the decision flags;
• Related Documents holds the opportunity and estimate links;
• System Information holds the audit stamps.

The service order link is not shown on the seeded record page. Open the order instead, or follow the line's Recommendation panel from the order side.

Step 7 — Use recommendations in the field app

The field app shows the same Service Recommendations card on a service order and a service opportunity. Tap Edit, tick or clear rows, and tap Save. The rules are the same as on the web: a tick accepts and adds a line, and clearing an accepted tick rejects it. Where AI Mechanic is switched on, its Recommendations step lists suggestions with ✓ and ✗ buttons and adds the accepted ones to the job with Add n to job.

Fields

Is Mandatory (shown as Required on the card) is set from the rule or complaint item and is not on the seeded record form.

Business rules

• Locked fields. Asset and Checklist Line cannot be changed after the first save. The save fails with Key fields are not editable once the related objects are added.
• Delete. A utilised recommendation cannot be deleted: Cannot delete a utilized service recommendation. Deleting a checklist line removes its unutilised recommendations. Deleting a complaint line removes its recommendations, and the lines that mandatory items added, unless those lines have moved on (invoiced, posted, allocated or picked).
• Accept and reject are exclusive. Accepting clears Is Rejected. Rejecting clears Is Accepted, withdraws the created service order or opportunity line, and clears the line links. The document link stays, so the row remains visible on that document's card.
• Re-accepting a rejected recommendation adds a fresh line.
• Only new acceptances add lines. A recommendation that is already linked to a service order line (or opportunity line) never gets a second one.
• Checklist re-evaluation. Changing a checklist answer updates its recommendations in place: item, type, reading and condition, plus quantity only if none was set. It adds recommendations for newly matching rules and removes ones whose rule no longer matches, unless they are utilised.
• Complaint reconciliation. Re-pointing a complaint line drops suggestions that no longer apply, unless they were accepted by hand or already have a line. Mandatory ones are dropped together with their line while that line is untouched.
• Utilisation happens on Invoice or Selective Invoice for every recommendation behind any line of the order.

Example

A workshop receives a scooter for its periodic service.

1. The advisor opens service order SO-0412 for the asset. The health check checklist asks for brake pad thickness. A recommendation rule on that line says: below 3 (mm), recommend 1 Brake Pad Set, type Health Check.
2. The technician records 2.4. On save, a recommendation Health Check for Brake Pad Set appears on the Service Recommendation tab, with Risk taken from the answer's condition and Requirement Optional.
3. The customer's complaint "Brake noise" with fault "Worn disc" is posted on the Complaints tab. Its complaint items raise two more recommendations: Brake Disc (optional, quantity 1) and Brake Fluid (mandatory, quantity 1). The Brake Fluid line is added to Lines immediately and shows as Required.
4. The customer agrees to the pads but declines the disc. The advisor selects Edit, ticks Brake Pad Set and selects Save. A Brake Pad Set line with quantity 1 appears on Lines. To record the declined disc, the advisor opens the Brake Disc recommendation and ticks Is Rejected.
5. After the work, Invoice runs. The Brake Pad Set and Brake Fluid recommendations become Is Utilized.

Training

Practice exercise

In a sandbox with an asset that has no open orders:

1. Create a recommendation by hand: Name Wiper blades due, Item any part, Asset your test asset. On the record page set Quantity to 2.
2. Create a service order for the same asset and open its Service Recommendation tab.
3. Select Edit, tick Wiper blades due, and select Save.
4. Clear the tick again and select Save.

Expected result: after step 2 the recommendation is listed. After step 3 a line for the part with quantity 2 is on Lines, and the recommendation drops off the card because it is now linked to that line. Open the recommendation from the list: Is Accepted is ticked. To practise step 4, use a recommendation raised by this order's checklist or complaint, which stays on the card. Clearing its tick removes the line and ticks Is Rejected.

Quick reference

• Decide recommendations on the document's tab: Edit → tick → Save.
• A tick adds a line. Clearing an accepted tick rejects it and removes the line.
• An undecided row can't be declined from the card. Tick Is Rejected on the record.
• Line quantity = Quantity, else Numeric Value, else 1.
• Mandatory complaint items are accepted automatically.
• Checklist and complaint recommendations stay with the document that raised them. Hand-made ones follow the asset.
• Invoicing marks the order's recommendations utilised, and utilised ones can't be deleted.
• No asset on the document means an empty card.

Permissions

The shipped Standard User, Sales Executive, Sales Manager and System Admin profiles hold the four action grants. The shipped Service profile has full entity access but no action grants, so its users see an empty card and cannot save ticks until an administrator adds the grants. Action grants are on the profile's Actions tab. See security profiles.

Configuration

• Checklist rules. Recommendation rules (checklist template line, RAG value or numeric bounds, item, quantity, recommendation type, mandatory) decide what a checklist answer recommends. See service recommendation rules.
• Complaint items. The complaint catalogue (item, quantity, optional fault code, mandatory) decides what a complaint recommends. See complaints and fault codes.
• Recommendation Type values. The picklist ships with Health Check, Past, Complaint and IOT. The complaint engine always writes Complaint.
• Navigation. Add the Service Recommendation entity to the Service app, or any other app, in Design Studio if advisors need the list. Grant app visibility on the security profile.
• Where the card appears. The Service Recommendations card is a layout widget on the service order View layout (Service Recommendation tab) and the service opportunity View layout (Recommendation tab), on web and mobile. Keep it there, or place it on another tab, with the layout designer.
• Nudges. Sense AI can raise Open service recommendations on a service order, with an Accept recommendation button, and Quote follow-up on accepted recommendation. See nudges.
• AI Mechanic. Off by default. An administrator switches it on in Setup → Feature Hub → Sense AI (setting AI Mechanic), and users also need a Sense AI seat. Its recommendation sources are set per profile in Setup → AI Studio → AI Mechanic.

Common problems

The recommendations tab is empty

The order or opportunity has no Asset, nothing has been raised for it yet, or your profile lacks the Recommendation (GetServiceRecommendation) action grant. Set the asset, check the rules and complaint items, or ask an administrator to add the grant.

A recommendation from the last visit doesn't show on the new order

Recommendations raised by a checklist or a complaint stay linked to the document that raised them, so later orders don't offer them. Open the earlier order to decide them, or create a new recommendation by hand for the asset.

Saving the card does nothing

The card shows no error when the save fails, for example for a missing action grant or a refused rejection. It stays in edit mode. Check the grant, then try again. To see the server's message, make the same change on the recommendation's record page.

"Cannot reject a service recommendation whose service order line is already transacted."

The line added by the acceptance has been allocated, picked or invoiced. Cancel the allocation or picking first. An invoiced line can't be withdrawn.

"Quantity should not be less than 0" when accepting on an opportunity

The recommendation's Quantity is 0 or empty, and opportunity lines take that quantity as it is. Set Quantity on the recommendation's record page, then tick it again.

The created line has a strange quantity

The recommendation had no Quantity, so the line took the Numeric Value (the inspection reading). Set Quantity on the recommendation before accepting, or correct the line.

I ticked Is Accepted on the record but no line was created

Lines are created only from the document's card (or a nudge or AI Mechanic). Accept it from the service order or opportunity instead.

"Cannot delete a utilized service recommendation."

The work has been invoiced. The record is the audit trail and stays.

Common questions

Why does the list contain rows without an asset?

The nightly field-sales job stores its outlet suggestions ("likely to buy" and suggested order quantities) in the same table. Those rows belong to an outlet, not an asset. Service never offers them, and they are refreshed every night. Filter the list by Asset to see only service work.

Do recommendations expire?

No. A recommendation stays as it is until it is accepted, rejected or utilised. Review the list from time to time and tick Is Rejected on advice that no longer applies.

Can an estimate offer recommendations?

Not directly. An estimate has no recommendations card. A recommendation reaches an estimate line when a mandatory complaint item is posted on the estimate, or when an estimate is built from an order or opportunity line that came from a recommendation, which keeps the link.

Which lines count as utilised?

Every line of the invoiced service order that came from a recommendation, as soon as Invoice or Selective Invoice runs on the order. That includes lines a selective run left for later.

Related topics

• Service recommendation rules: setting up checklist-driven recommendations
• Checklists on service orders
• Complaints and fault codes: complaint items
• The service order lifecycle
• Service order lines
• Estimates and invoicing
• Nudges
• Service Recommendation reference