A service contract definition (the Item Service Contract record) is the reusable set of terms behind a service contract you sell: how long cover lasts, the usage limits, the grace allowed past them, what is covered and who pays. You set it up once on the contract item. Each time that item is sold on an invoice against an asset, the definition creates an asset service contract, which is that asset's entitlement. Service orders, opportunities and quotes then name the definition, and xMatix checks the work against the asset's entitlement and the definition's rules.
Overview
A definition has four jobs:
- Create entitlements. When the contract item is sold, the definition's days, hours, readings and grace become the dates and limits of a new asset service contract, and its lines become the entitlement's scope.
- Check the job. A service order or opportunity that names the definition has its usage readings checked against the definition's usage band, and the asset's entitlement checked for lapse, single use and scope.
- Decide billing. The Contract Posting Treatment sets each covered line's Posting Type (invoice or claim), and Bill To Partner Account or BillingAccount decide who is invoiced.
- Fence the parts and labour. The definition's lines list what a service order line may charge to it. That part is documented on Contract definition lines.
When to use it
Create a definition for every service contract product you sell or give away with an asset: a free-service package, an extended warranty, an annual maintenance contract. Create a separate definition when the terms differ, for example a 1-year and a 3-year plan. The validity and limits are copied onto each entitlement when it is created, so a later change to the definition does not change entitlements that already exist.
How xMatix handles it
When the contract is sold. Entitlements are created by the invoice's inventory posting (the posting action, not a plain save), for each invoice line whose item has Item Type Service Contract and that names an asset. If the line has no asset, the asset of its package parent line is used. The line is matched to every definition where:
- the definition's Item is the line's item, or its SKU is the line's SKU; and
- the invoice date is on or after Date Effective From and on or before Date Effective Till (a blank date is open-ended).
Each matching definition creates its own entitlement, so two definitions on the same item give the asset two entitlements per sale. Is Active is not checked.
| Entitlement field | Taken from the definition |
|---|---|
| Activated Date | The invoice date |
| Due Date | Invoice date + From Days |
| Valid till date | Invoice date + To Days |
| Due in hours / valid till hours | Minimum Usage (Hours) / Maximum Usage (Hours) |
| Due on reading / valid till reading | Minimum Usage (Reading) / Maximum Usage (Reading) |
| Grace days, hours and reading | Copied unchanged |
| Scope lines | One per definition line, unless Restrict Asset Contract Lines Generation is on |
The entitlement's billing account, posting type and Populate Contract Lines switch are not copied.
When a job names the contract. The Service Contract on a service order or opportunity header, and the Item Service Contract on an opportunity, quote or service order line, point at a definition. On save, xMatix looks for the asset's entitlement under that definition that is not marked Is Utilized and has not lapsed, and links it. An entitlement has lapsed when the job's date (the failure date if recorded) is past its valid-till date plus grace days, or the job's hours or reading has reached its valid-till hours or reading plus grace. If the asset only has lapsed entitlements under the definition, the save is refused with the lapse reason. The switches below then add their checks.
Prerequisites
- The contract item exists with Item Type Service Contract. See Items.
- For the definition's lines: the part and labour items it covers exist.
- Your security profile grants the Item Service Contract entity (see Permissions).
Procedure
Step 1 — Open the contract item
Open the item and go to its Service tab. The first list there holds the item's service contract definitions. Select New in that list. The definition has no entry in a seeded app. To see every definition in one list, open the entity list directly, which shows the All Item Service Contract view (Name, Item, Service Type, Contract Posting Treatment, Is Active).
Step 2 — Fill in the header
The New form opens with these fields at the top:
- Name (required) — the name pickers show, for example Extended Warranty 2 Years. There is no numbering series.
- Service Type — Warranty Repairs or Paid Repairs. This is a label only (see Fields).
- BillingAccount — the payer for covered work, such as the manufacturer, if it is not the customer.
- Item — the contract item. Check that it names the item you are selling.
- Date Effective From and Date Effective Till — the invoice dates during which selling the item creates entitlements from this definition.
Step 3 — Set billing and use on the Basic Details tab
- Contract Posting Treatment — Generate Claims, Generate Invoices or Auto Generate Claims. Covered lines take this as their Posting Type.
- Single Use Contract — tick it if one job uses up the entitlement.
- Populate Contract Lines (Future Use) — leave it. Nothing reads it on the definition.
Step 4 — Set the limits on the Usage Limits tab
Fill in all three families. Each one becomes a limit on every entitlement this definition creates:
- Hours: Minimum Usage (Hours), Maximum Usage (Hours), Grace Usage (Hours).
- Reading (for example kilometres): Minimum Usage (Reading), Maximum Usage (Reading), Grace Usage (Reading).
- Days: From Days (when the service falls due), To Days (when cover ends), Grace Usage (Days).
Minimum Usage (Hours) must be greater than 0, and Maximum Usage (Hours) must be at least the minimum. The form refuses to save otherwise. Set To Days and Maximum Usage (Reading) to the real limits as well. Left at 0, every entitlement lapses the day after the sale, or as soon as a job records a reading (see Business rules).
Select Save. The record page opens with two tabs: Related and Details.
Step 5 — List what the contract covers
On the Related tab, select New in the lines list and add one line per covered part or labour item, with its quantity. This is described step by step in Contract definition lines. Without lines, the definition's posting treatment is never applied to a line (each blank Posting Type becomes Generate Invoices) and no scope is fenced.
Step 6 — Set the remaining controls on the Details tab
The Details tab groups the fields in panels: Contract Details, Controls, Validity, Usage (Days / Hours / Reading) and System Information. Fields edit in place here; Edit in the header reopens the New form in a dialog. Three fields are only on this tab:
- Weightage Invoice Charge Item (in Contract Details) — needed if this definition can be the second or third contract on a split service order line.
- Application To Type (in Contract Details) — the service order types whose lines may pick this definition.
- Bill To Partner Account (in Controls) — invoices covered work to the service order's partner account.
Is Active is also here. It has no effect (see Fields).
Step 7 — Sell the contract
Add the contract item to an invoice line with the customer's Asset, and run the invoice's inventory posting. One asset service contract per matching definition appears on the asset, with dates counted from the invoice date. Check it under the asset's service contracts before the customer's first visit.
Step 8 — Change or retire a definition
Edit the definition in place or with Edit. Changes apply to entitlements created from then on, and to the checks and billing of jobs saved afterwards, because those read the definition directly: the usage band, posting treatment, enforcement switches and billing accounts. Dates, limits, grace and scope already copied onto existing entitlements do not change; correct those on the asset service contract itself.
To stop selling a definition, set Date Effective Till to the last valid date. Do not rely on Is Active. Delete removes the definition from view (it is kept in the database). Any service order, opportunity or quote that still names it is then refused on its next save with Missing Contract. Please check if the Service Contract exists and try again.
Fields
Header (New form, top)
| Field | What it means | Notes |
|---|---|---|
| Name | The definition's name | Required. Typed by you. |
| Service Type | Warranty Repairs or Paid Repairs | A label only. No process or picker reads it. |
| BillingAccount | The payer for covered work | Used for invoices when Bill To Partner Account is off, and for claims. Not copied onto entitlements. |
| Item | The contract item whose sale creates entitlements | Pick an item with Item Type Service Contract. |
| Date Effective From | First invoice date that creates entitlements | Blank: no start limit. |
| Date Effective Till | Last invoice date that creates entitlements | Inclusive. Blank: no end. Existing entitlements keep their own dates. |
Basic Details tab
| Field | What it means | Notes |
|---|---|---|
| Contract Posting Treatment | How covered work is billed | Generate Claims, Generate Invoices, Auto Generate Claims. |
| Single Use Contract | One job uses up the entitlement | Enforced through the entitlement's Is Utilized, which nothing sets automatically. |
| Populate Contract Lines (Future Use) | Reserved | Not read. The working switch is on the asset service contract. |
Usage Limits tab
| Field | What it means | Notes |
|---|---|---|
| Minimum Usage (Hours) | Lower end of the hours band; the entitlement's due-in hours | Default 0, but must be greater than 0 to save. |
| Maximum Usage (Hours) | Upper end of the hours band; the entitlement's valid-till hours | Must be at least the minimum. |
| Grace Usage (Hours) | Extra hours before the entitlement lapses | Copied onto the entitlement. |
| Minimum Usage (Reading) | Lower end of the reading band; the entitlement's due-on reading | 0 means no lower bound in the band check. |
| Maximum Usage (Reading) | Upper end of the reading band; the entitlement's valid-till reading | Must be at least the minimum when set. 0 makes any recorded reading lapse the entitlement. |
| Grace Usage (Reading) | Extra reading before the entitlement lapses | Copied onto the entitlement. |
| From Days | Days from the sale to the due date | Contract-schedule campaigns remind customers against this date. |
| To Days | Days from the sale to the end of cover | Default 0, which ends cover on the day of sale. |
| Grace Usage (Days) | Extra days before the entitlement lapses | Copied onto the entitlement. |
Details tab only
| Field | What it means | Notes |
|---|---|---|
| Weightage Invoice Charge Item | The item used to bill this contract's share of a split line | Must differ from the line's own item. |
| Application To Type | Service order types whose lines may pick this definition | Dealer Expense, Warranty Service, Free Service, Paid Repairs (several allowed). Blank: all. |
| Is Active | Shown on the record | Not read. Inactive definitions still create entitlements and still appear in pickers. |
| Bill To Partner Account | Invoice covered work to the service order's partner account | Takes precedence over BillingAccount on invoices. Claims ignore it. |
Not on the seeded forms
Active Service Contract Required, Is Scope Restricted, Restrict Asset Contract Lines Generation and SKU work but are on no seeded layout; see Configuration. Item Lot Type is also on the record but nothing reads it.
The full field list is in the Item Service Contract reference.
Business rules
Validations on save. These run on every save, new or edit:
- Usage Hours cannot be less than 0 — Minimum Usage (Hours) is 0 or less. Because the field defaults to 0, a definition saved without a positive value here is refused.
- Maximum Hours should be greater than Minimum hours — Maximum Usage (Hours) is below the minimum.
- Maximum Usage should be greater than Minimum Usage. — Maximum Usage (Reading) is below Minimum Usage (Reading).
Usage band. When a service order or opportunity header names the definition in Service Contract, its Usage Reading (Hours) must be between Minimum Usage (Hours) and Maximum Usage (Hours), and its Usage Reading between the reading minimum and maximum. Both ends are inclusive, a bound of 0 is not enforced, and a blank reading is not checked. A check-in inspection is checked against the contract on its opportunity. The message names the limits, for example Usage Reading (Hours) must be between … and … as per the Service Contract tagged on the Service Order. (or cannot be less than / cannot be more than when only one bound is set). The check runs when the record is created and whenever a reading or the contract changes.
Entitlement checks. On the header and on each line that names the definition:
- A lapsed entitlement gives The validity of this contract has lapsed!, The Usage Hours for this contract has lapsed! or KM reading exceeds service contract usage limit. This applies whatever the switches say.
- Active Service Contract Required: with no eligible entitlement, No Active Asset Service Contract. This Service Contract requires an active Asset Service Contract! With one, its date, hours and reading limits are checked.
- Is Scope Restricted: with no eligible entitlement, No Active Asset Service Contract. A Restricted Scope Contract requires an active Asset Service Contract! On lines, the item must be on the entitlement's scope lines and the quantity within its pending quantity.
- Single Use Contract: an entitlement marked Is Utilized is refused with This is a Single Use contract and has already been utilised! On lines, a missing entitlement is also refused.
Posting type. When an opportunity, quote or service order line is saved, its Posting Type is set to the definition's Contract Posting Treatment if the line's item is on the definition's lines. Otherwise a blank Posting Type becomes Generate Invoices, and a value already there is kept.
Who is billed. A customer invoice raised from a service order for lines under the definition goes to the service order's partner account if Bill To Partner Account is on. Otherwise it goes to the BillingAccount if set, and otherwise to the service order's customer. A claim's supplier account is the asset service contract's billing account if set, then the definition's BillingAccount, then the service order's customer. Lines under different definitions are invoiced on separate documents.
Split lines. When the definition is the second or third contract on a split service order line, its share is billed as a separate line for its Weightage Invoice Charge Item: on an invoice when its treatment is Generate Invoices, or on a claim when it is a claims treatment. A split line that names a definition without a charge item is refused.
Pickers. The service order line's Item Service Contract picker shows a definition when its Application To Type is blank, when the order has no Service Type, or when the order's Service Type is one of the definition's values. The service order header Service Contract picker and the opportunity and quote line pickers list every definition.
Deleting. Delete is a soft delete with no check for documents that still name the definition.
Example
A dealer sells a two-year extended warranty on a utility vehicle, covering 40,000 km with 1,000 km grace and a first service due after 11 months. The service manager opens the contract item Extended Warranty 2Y and, on its Service tab, selects New:
- Name Extended Warranty 2 Years, Service Type Warranty Repairs, BillingAccount the manufacturer's account, Item Extended Warranty 2Y, Date Effective From 1 April.
- Contract Posting Treatment Auto Generate Claims.
- Minimum Usage (Hours) 1, Maximum Usage (Hours) 5000, Maximum Usage (Reading) 40000, Grace Usage (Reading) 1000, From Days 335, To Days 730, Grace Usage (Days) 15.
On Related, the manager adds lines for the gearbox assembly (quantity 1) and gearbox labour (quantity 4).
On 10 April the vehicle is sold with the warranty on the same invoice. Posting the invoice creates the asset's entitlement: activated 10 April, due 11 March next year, valid till 10 April two years later, valid till reading 40,000.
Fourteen months later the vehicle returns at 38,200 km with a gearbox fault. The advisor raises a service order with Service Contract Extended Warranty 2 Years and Usage Reading 38200. The entitlement is linked. The gearbox line takes Posting Type Auto Generate Claims and, at invoicing, goes onto a claim against the manufacturer. Brake pads are not on the definition's lines, so the advisor adds that line without an Item Service Contract; it is billed to the customer as Generate Invoices.
Training
Practice exercise
- In a sandbox, create a Service Contract item and open its Service tab.
- Create a definition and leave Minimum Usage (Hours) at 0. Save.
- Set Minimum Usage (Hours) to 1 and Maximum Usage (Hours) to 100, set To Days to 365, and save again.
- Add one part to the definition's lines.
- Sell the contract item on an invoice line with an asset and post the invoice's inventory.
Expected result: step 2 is refused with Usage Hours cannot be less than 0. Step 3 saves. After step 5 the asset has one asset service contract whose valid-till date is the invoice date plus 365 days, with one scope line for the part.
Quick reference
- One definition per contract product; it lives on the contract item's Service tab.
- Entitlements are created only by the invoice's inventory posting, from every matching definition.
- Minimum Usage (Hours) must be above 0; set To Days and Maximum Usage (Reading) to the real limits.
- Changes to the definition don't touch entitlements already created.
- Contract Posting Treatment applies only to items on the definition's lines.
- Bill To Partner Account beats BillingAccount on invoices.
- Is Active, Service Type and Item Lot Type change nothing; use Date Effective Till to retire a definition.
- Split lines need a Weightage Invoice Charge Item on the second and third contracts.
Permissions
Definitions use the standard entity permission for Item Service Contract. The seeded Sales, Sales Executive, Sales Manager, Service, Standard User and System Admin profiles grant full access: view, create, edit and delete. A user whose profile does not grant the entity cannot see or change definitions. Because a definition decides what work is covered and who pays, keep edit access to the people who own contract products. See Security profiles.
Configuration
- Where users reach definitions. No seeded app lists the entity. Users reach it from the contract item's Service tab. To give it a list entry, go to Setup → Design Studio → Apps, open an app and use Manage Items to add Item Service Contract (see the create-an-entity walkthrough).
- Hidden switches. Active Service Contract Required, Is Scope Restricted, Restrict Asset Contract Lines Generation and SKU are not on the seeded forms. To use them, add them to the Item Service Contract layouts in the layout designer.
- Validations. The three usage-limit validations are entity validations, which you can review in the data model tools (see Business rules).
- Pickers by order type. Use Application To Type to narrow which definitions service order lines offer for each service order Service Type.
- Reminders. Contract-schedule campaigns watch the due dates that From Days produces.
- Field app. The mobile service case form lists definitions by name in its service contract picker.
Common problems
"Usage Hours cannot be less than 0"
Minimum Usage (Hours) is 0, its default. Enter a positive value and make Maximum Usage (Hours) at least as large. The check runs on every save, so an older definition that still holds 0 can't be edited until you fix the value.
"Maximum Hours should be greater than Minimum hours" or "Maximum Usage should be greater than Minimum Usage."
A maximum is below its minimum. Raise the maximum or lower the minimum.
Selling the contract created no asset service contract
Check that the invoice line names an Asset (or sits in a package whose parent line does), that its item has Item Type Service Contract, and that the definition's Item or SKU matches it. Check that the invoice date falls inside Date Effective From and Date Effective Till, and that the invoice's inventory posting was run.
The asset got two entitlements from one sale
Two definitions match the item and the invoice date. Close one with Date Effective Till.
"The validity of this contract has lapsed!" the day after the sale
The definition's To Days was 0 when the contract was sold, so the entitlement's valid-till date is the sale date. Correct the valid-till date on the asset service contract and set To Days on the definition for future sales. The same applies to KM reading exceeds service contract usage limit when Maximum Usage (Reading) was 0.
"Usage Reading (Hours) must be between … as per the Service Contract tagged on the Service Order."
The order's hours reading is outside the definition's hours band. Check the reading. If the band is wrong, change the definition; the check reads the definition, not the entitlement.
Covered lines are billed to the customer instead of claimed
The line's item is not on the definition's lines, so the treatment did not apply. Add the item to the lines, or set the line's Posting Type yourself.
"Missing Contract. Please check if the Service Contract exists and try again."
The order, opportunity or quote names a definition that has been deleted. Pick another definition, or clear the contract.
Common questions
Does changing a definition update contracts already sold?
Partly. The usage band, enforcement switches, posting treatment and billing accounts are read from the definition each time a job is saved, so they change straight away. The dates, hours, readings, grace and scope lines were copied onto each asset service contract when it was created and stay as they were. To change an entitlement already sold, edit the asset service contract itself.
Why does Is Active not stop a definition being used?
No process reads it. An inactive definition still creates entitlements when its item is invoiced, and pickers still list it. To stop new sales creating entitlements, set Date Effective Till. To stop jobs naming it, delete it, but only after no open order, opportunity or quote names it, because those are then refused on their next save.
What is the difference between Service Type and Application To Type?
Service Type (Warranty Repairs or Paid Repairs) is a label for reporting and nothing filters on it. Application To Type is what the service order line picker reads: a definition is offered on a line only when its values include the order's Service Type, or when either is blank. The opportunity and quote line pickers and the service order header picker list every definition.
Can one item have several definitions?
Yes, and every definition that matches the item and the invoice date creates its own entitlement on the asset. That suits a package of separate covers, such as a free-service plan and a warranty sold together. For successive versions of the same plan, give each one non-overlapping Date Effective From and Date Effective Till dates so a sale creates only one.