Contract definition lines are the list of components (parts, labour and other items) a service contract definition covers, with the quantity each one allows. They are the definition's scope. A definition (the Item Service Contract record) is set up once against the contract item you sell. Its lines then decide which part and labour lines a service order may charge to the contract, and which lines take the contract's posting treatment. When the contract is sold and invoiced against an asset, the lines also become that asset's entitlement scope. For the definition as a whole and the per-asset entitlement, see Asset service contracts.
Overview
Each line holds a Component Item and a Quantity. A definition can have any number of lines: a short list of labour items for a free-service contract, or a long parts list for a warranty. The lines are maintained by hand on the definition's Related tab and read by the platform in four places:
- Service order line check. A Part or Work Item line on a service order that names this definition in its Item Service Contract is refused unless its item is on the lines.
- Posting type. An opportunity, quote or service order line takes the definition's Contract Posting Treatment only when its item is on the lines.
- Contract change on a service order. When you change the Service Contract on a saved service order, the new definition's lines become order lines.
- Entitlement creation. When the contract item is invoiced and the invoice is posted, each line is copied onto the asset's entitlement as a scope line.
When to use it
Add lines whenever a contract should cover only certain work: the parts a warranty replaces, the labour items a service plan includes, the consumables a free service provides. Keep them current when the covered parts list changes.
Leave a definition without lines only when it is not meant to limit which items a service order can charge to it. A definition with no component lines has no scope for the service order check to enforce.
How xMatix handles it
- The lines are read when a document is saved. The service order check, the posting type and the contract change all read the definition's lines at the moment the document is saved. An edit to the lines applies to the next save of any document that names the definition.
- Entitlements are copies. Scope lines on an existing asset entitlement were copied when the contract was invoiced. Editing or deleting a definition line afterwards does not change them, so correct existing entitlements on their own Lines tab.
- Is In Scope is not stored. The line forms show an Is In Scope checkbox, but the platform keeps no value for it. Every line that has a component item counts as covered, whether the box is ticked or not. To exclude an item, leave it off the lines.
- Only the item is checked on a service order. The line check asks only whether the item is on the definition's lines; it does not compare quantities. Quantity limits are enforced by the restricted-scope check, which reads the asset entitlement's scope lines and their pending quantity (see How contracts shape service work).
Prerequisites
- The contract item exists with Item Type set to Service Contract, and the definition has been created for it. See Items.
- Every component you want to list exists as an item, usually of type Part or Work Item.
- Your security profile allows you to create and edit Item Service Contract Line records (see Permissions).
Procedure
Step 1 — Open the service contract definition
Open the contract item (its Item Type is Service Contract) and go to the Service tab. The item's service contract definitions are listed there. Open the definition you want to change, or select New in that list to create one. On a new definition, check that Item names the contract item and fill in its validity, usage and posting settings (these are described in Asset service contracts).
The saved definition opens with its name, Service Type and Is Active in the header, and two tabs: Related and Details.
Step 2 — Add a covered component
On the Related tab, select Quick Add above the lines list. A short form asks for:
- Component Item — the part, labour or other item the contract covers.
- Quantity — how many units the contract allows (whole numbers from 1).
- Is In Scope — this box has no effect (see How xMatix handles it); you can leave it as it is.
Save. The line appears in the list with a generated name. Repeat for every component the contract covers.
Step 3 — Correct or remove a line
In the lines list, use the row's Edit to change the component or quantity, or Delete to remove the line. You can also open a line: its record shows the Scope panel (Component Item, Quantity, Is In Scope) and System Information, with Edit and Delete in the header.
Removing a line takes the item out of the definition's scope for documents saved from then on. It does not remove scope lines already copied onto asset entitlements.
Step 4 — Check the effect on a service order
On a service order, add a Part or Work Item line and set its Item Service Contract to the definition:
- If the item is on the definition's lines, the line saves, and its Posting Type takes the definition's Contract Posting Treatment if one is set.
- If it is not, the save is refused with Item '…' is not covered by Item Service Contract '…'. Only Items listed on that contract's lines can be added.
Step 5 — Change the contract on a saved service order (optional)
If you change the Service Contract on the header of a saved service order, every order line whose Item Service Contract is the previous contract is deleted, and one new line is added for each line of the newly chosen definition that has a component item. Each new line carries the definition line's component item and quantity, with the new contract as its Item Service Contract. Lines with no contract or a different one stay as they are, so lines that came from an estimate, quote or campaign are normally untouched; a line you added by hand with the previous contract on it is deleted too. Clearing the contract deletes the old contract's lines and adds nothing. Choosing the same contract again changes nothing.
Fields
| Field | What it means | Notes |
|---|---|---|
| Component Item | The part, labour or other item the contract covers | Not marked required, but a line without it is ignored by the service order check and adds no order line on a contract change. The lookup lists every item. |
| Quantity | How many units of the component the contract allows | Whole numbers from 1 on the add form. Copied unchanged onto entitlement scope lines and onto order lines on a contract change. |
| Is In Scope | A checkbox on the line forms | Not stored and not used. Every line with a component item counts as covered. |
| Item Service Contract | The definition the line belongs to | Filled in when you add the line from the definition's Related tab. |
| Name | The line's reference | Generated on save from the line's name setting (default series ISS). Not on the add form. |
The full field list is in the Item Service Contract Line reference.
Business rules
- Service order line check. It applies to service order lines only, and only to items of type Part or Work Item. It is skipped when the line has no Item Service Contract (a paid repair line), when the line has no item, or when the definition has no lines with a component item. Charge items and service contract items are never checked. Opportunity and quote lines are not checked.
- Posting type. When an opportunity, quote or service order line is saved, its Posting Type is overwritten with the definition's Contract Posting Treatment if the line's item is on the definition's lines and the treatment is set. Otherwise the line falls back to Generate Invoices, but only if its posting type is still blank.
- Entitlement creation. When an invoice with a Service Contract item is posted, each definition line is copied onto the new asset entitlement with its component item and quantity, unless Restrict Asset Contract Lines Generation is switched on for the definition. Every line is copied, including one with no component item. The copied scope lines start with a pending quantity of zero (see Asset service contracts).
- Contract change on a service order. One order line per definition line with a component item, as described in Step 5.
- Duplicates. Nothing stops the same component appearing on two lines. The service order check treats it once, but a contract change and entitlement creation add one line per definition line, so avoid duplicates.
- Numbering. The line's Name comes from the Item Service Contract Line Name Setting: default series ISS, a date part and a six-digit running number.
Example
A dealer sells a 12-month "Pump Care Plan" contract item for its water pumps. The definition lists four lines:
| Component Item | Quantity |
|---|---|
| Impeller kit | 1 |
| Shaft seal | 2 |
| Pump overhaul labour (Work Item) | 1 |
| Site inspection labour (Work Item) | 2 |
The plan is invoiced against a customer's pump, and posting the invoice creates the pump's entitlement with the same four scope lines.
Three months later the pump comes in with a leak. The service advisor raises a service order, adds a Shaft seal line and a Pump overhaul labour line, and sets Item Service Contract on both to the Pump Care Plan. Both lines save, and their Posting Type follows the plan's Contract Posting Treatment. The advisor then adds a Bearing set line against the same contract. It is refused, because the bearing set is not on the definition's lines. The advisor clears the line's Item Service Contract so the bearing set is billed to the customer as paid work.
Training
Practice exercise
In a sandbox:
- Open a Service Contract item and create a definition on its Service tab.
- On the definition's Related tab, use Quick Add to add one Part and one Work Item, each with quantity 1.
- On a service order, add a line for the part with Item Service Contract set to your definition, then a line for a different part with the same contract.
Expected result: the first line saves. The second is refused with Item '…' is not covered by Item Service Contract '…'. Only Items listed on that contract's lines can be added. Clearing the second line's Item Service Contract lets it save.
Quick reference
- Lines live on the definition's Related tab; add them with Quick Add.
- A line is a component item plus a quantity. Every line with an item counts as covered.
- Is In Scope is not stored. To exclude an item, leave it off the lines.
- Service order Part and Work Item lines that name the contract must use a listed item.
- A definition with no lines does not limit which items a service order can charge to it.
- The line quantity is not checked on a service order. Entitlement scope lines carry the quantity limit.
- Editing lines does not change entitlements that already exist.
- Changing a saved service order's contract replaces the old contract's lines with the new definition's lines.
Permissions
Line records use the standard entity permission for Item Service Contract Line. The seeded Sales, Sales Executive, Sales Manager, Service, Standard User and System Admin profiles grant full access: view, create, edit and delete. Clone and bulk Delete are granted separately as server actions (Clone to Sales Executive, Standard User and System Admin). A user whose profile does not grant the entity cannot see or change the lines. Because the lines decide what a service order can charge to a contract, keep edit access to the people who maintain contracts. See Security profiles.
Configuration
- Where definitions are reached. Neither the definition nor its lines has its own entry in a seeded app. Users reach them through the contract item's Service tab. To give them a list of their own, go to Setup → Design Studio → Apps, open an app and use Manage Items to add Item Service Contract (see the create-an-entity walkthrough).
- Definition settings that work with the lines. Is Scope Restricted (the restricted-scope check against the entitlement's scope lines), Restrict Asset Contract Lines Generation (stops lines being copied onto new entitlements) and Active Service Contract Required are not on the seeded definition forms. To set them, add the fields to the Item Service Contract layouts in the layout designer.
- Component Item lookup. The seeded Component Item lookup filter (Part items only) is inactive, so the lookup lists every item. An administrator can activate or change it in the entity's lookup filters.
- Is In Scope. Because the field is not stored, consider removing it from the New Service Contract Line quick-add form and the line view layout so users are not misled.
- Line names. The line name format is the Item Service Contract Line Name Setting under Setup → Feature Hub → Platform → Document Settings (see Templates and document settings).
Common problems
"Item '…' is not covered by Item Service Contract '…'"
The service order line names a definition whose lines do not include the line's item. Add the item to the definition's lines if the contract really covers it. If it is paid work, clear the line's Item Service Contract.
A part I removed from the contract is still accepted on a customer's asset
The service order line check reads the definition's current lines, but the restricted-scope check reads the asset entitlement's scope lines, which were copied at invoicing. Remove or correct the scope line on the entitlement's Lines tab as well.
I unticked Is In Scope but the item is still covered
Is In Scope is not stored, so it has no effect. Delete the line to take the item out of the contract.
Any part can be added to the contract
The definition has no lines with a component item, so there is no scope to enforce. Add the covered components.
New entitlements have no scope lines
Either the definition had no lines when the invoice was posted, or Restrict Asset Contract Lines Generation is switched on for it. Add scope lines to the entitlement by hand on its Lines tab.
Common questions
Does the line quantity limit what a service order can use?
Not through the definition. The service order line check only asks whether the item is listed. The quantity is copied onto each entitlement's scope line when the contract is invoiced, and the restricted-scope check compares a service line's quantity with the pending quantity on that scope line. That check runs only for definitions with Is Scope Restricted switched on, and generated scope lines start with a pending quantity of zero until someone fills it in.
Can I list exclusions on a contract?
No. Every line with a component item counts as covered, and the Is In Scope box that looks like an exclusion switch is not stored. Record only what the contract covers. Anything not listed is outside the scope of a definition that has lines.
Do I need to list labour items?
Yes, if service orders should charge labour to the contract. Work Item lines are checked the same way as Part lines. Labour that is not on the lines must be entered without an Item Service Contract, which makes it paid work.
What happens to existing customers when I change the lines?
New service order lines, posting types and contract changes use the new lines from the next save. Existing asset entitlements keep the scope lines they were given at invoicing until you edit them.