Contract lines

A contract line is one commercial position in your contract register: the item sold under an agreement, how many, at what price, for how many years and hours, and how many of the customer's assets it covers. Lines sit beside the contract header in the Contracts app, and planned preventive-maintenance visits (PM tasks) can point at a line. Like the rest of the Contracts app, a line is a record you keep. It does not bill, renew or schedule anything.

Overview

The contract line holds the commercial detail a contract header does not: the item, quantity, unit price and discount, the contract years and contract hours, and the asset count. Each line also names a customer Account.

Two facts shape how you work with lines:

• A line has no link to its contract. The contract line has no Contract field, so xMatix cannot tell which agreement a line belongs to. The Scope tab on a contract lists every contract line in your organization, not just that contract's lines. The Account is the only thing a line and its contract have in common.
• The shipped forms show only part of the line. The New/Edit form has ten fields. Cost price, billing, visit, warranty and bill-to/ship-to fields exist on the line but are on no shipped form. Your administrator can add them (see Configuration).

When to use it

• You keep a register of signed service or maintenance agreements and want each priced position on record.
• You want contract value, contracted hours and assets under contract to add up per customer in reports and dashboards.
• You plan preventive-maintenance visits and want each PM task tied to the line that pays for it.

Do not use contract lines to give a customer service cover that xMatix enforces on service orders. Enforced cover comes from the service contract definition and its lines, which become the customer's asset service contract when the contract item is invoiced. Nothing on a service order, quote or invoice reads a contract line.

How xMatix handles it

• Numbering. Each line gets an automatic number from the SCL series when it is first saved. As shipped, the number is the series, the day's date and a six-digit counter with no separator, for example SCL26102026000001, and the counter restarts every day. Whatever you typed in Name is replaced. See Document numbering.
• Defaults. When you save a line with Quantity, Unit Price, Cost Price, Asset count, Contract Hours, Contract Years, Year Number or Billed Amount empty, the field is saved as 0.
• No calculations. Nothing is calculated from the line. There is no line total, the discount is not applied to the price, and Billed Amount is never filled from invoices.
• No checks. Apart from the name, no field is required, and there are no validations or business rules on contract lines.
• PM tasks. A PM task has a Contract Line field. Setting it ties the visit to the line, so reports can show what each line owes.

Prerequisites

• Access to the Contracts app and a security profile that allows contract lines (see Permissions).
• The customer set up as an account, and the items you sell under agreements set up as items.

Procedure

Step 1 — Open the contract lines

Open the Contracts app and select Contract Lines. The All Contract Line view lists every line with Name, Line item description, Quantity, Contract Hours and Contract Years. Use search, filters and column controls to narrow the list.

You can also work from a contract: open the contract and select the Scope tab. That tab shows the same list, with every line in your organization, and a New button.

Step 2 — Add a line

1. Select New on the Contract Lines list or on a contract's Scope tab. The Create Contract Line form opens.
2. Enter a Name. The form requires one, but it is replaced by the SCL number when you save, so any short text will do.
3. Choose the Item the line is for, and type a Description that says which agreement the line belongs to (for example the contract number and contract year). Because a line has no Contract field, this description is the most reliable way to find the agreement's lines later.
4. Enter the Quantity, Unit Price and Discount (a percentage).
5. Enter the Contract Years, Contract Hours and Asset count the agreement promises.
6. Choose the customer Account. Use the same account as the contract header so the line adds up under the right customer.
7. Save. The line appears in the list with its SCL number as the name.

The line does not appear only on its own contract: every contract's Scope tab shows it.

Step 3 — Find the lines of one agreement

1. Open Contracts → Contract Lines (or a contract's Scope tab).
2. Search for the text you used in Description, such as the contract number.
3. To see all lines for a customer instead, filter on Account. You may need to add the Account column to your view first.

Step 4 — Review a line

Open a line from the list. The record page has three sections:

• Key Information — Name, Item, Quantity, Unit Price and Description.
• Asset & Contract — Contract Years, Contract Hours, Discount and Asset count.
• System Information — who created and last changed the line, and when.

Account is not shown on the record page as shipped. Select Edit to see it.

Step 5 — Change or delete a line

• To change a line, select Edit on the record page or Edit on its row in a list. The same ten fields as the New form open in a dialog. Save to apply your changes. The SCL number does not change.
• To delete a line, select Delete on the record page or on its row. If a PM task still points to the line, clear the task's Contract Line first: a line cannot be removed while a task references it.

Lines have no status, so nothing stops you editing an old line. Agree in your team who may change lines once an agreement is signed, and restrict it with security profiles.

Step 6 — Plan PM tasks against a line

Create the PM task from the contract's PM Tasks tab or from Contracts → PM Tasks, and choose the line in the task's Contract Line field. The task then counts against that line in views and reports. Creating a task does not dispatch a technician or create a service order.

Fields

The first ten fields are on the shipped New/Edit form, in form order. The rest exist on the line but are on no shipped form. They can be filled by import, through the API, or after an administrator adds them to the form.

The full field list is in the Contract Line entity reference.

Business rules

• Numbering: a new line's Name is set from the Contract Line Document Name Setting (series SCL, date format day-month-year, six-digit counter, no separator). Lines are not renumbered later.
• Required: only Name. No other field is checked, so a line with no item, no account and a zero quantity saves.
• Defaults: empty numeric fields are saved as 0 when the line is created. Is under warranty and Is parts supply start off.
• No status, no lock: a line has no status and stays editable for as long as your permissions allow.
• No downstream effect: quotes, orders, service orders and invoices do not read contract lines. Changing or deleting a line changes nothing outside the Contracts app, apart from PM tasks that point at it.
• Dashboards: the shipped Renewal Exposure and Contracts & SLA dashboards add up all contract lines, with no filter by agreement, date or status: Value up for Renewal and Billed on Contract sum Billed Amount, Assets under Contract sums Asset count, Contracted Hours sums Contract Hours, and the account tables group lines by Account. Because Billed Amount is on no shipped form, those amounts stay at zero until you fill it by import or an extended form.

Example

A facilities firm signs a three-year maintenance agreement with a hospital customer for its chillers. The contract header is saved as contract CT-0412.

1. The coordinator opens Contracts → Contract Lines and selects New.
2. They type x in Name, choose the item Chiller Annual Maintenance, and enter the description CT-0412 year 1 — chiller maintenance.
3. They enter Quantity 1, Unit Price 240000, Discount 5, Contract Years 3, Contract Hours 96 and Asset count 4, and choose the hospital as Account.
4. On save the line is named SCL26102026000001.
5. They add a second line in the same way for the spare-parts kit, with Quantity 4, Contract Hours 0 and the description CT-0412 — parts kit.
6. On the contract's PM Tasks tab they create four quarterly visits, each with Contract Line set to the first line.
7. Next month, searching the Contract Lines list for CT-0412 shows both lines. In the Contract Value by Account table on the Contracts & SLA dashboard, the hospital shows Quantity 5 and Hours 96.

Training

Practice exercise

In a sandbox, open any contract and create two lines for it from the Scope tab, with descriptions that start with the contract's number. Then:

1. Open a different contract and look at its Scope tab.
2. Search the Contract Lines list for the first contract's number.

Expected result: both lines appear on every contract's Scope tab, named with SCL numbers, not the text you typed in Name. The search returns exactly your two lines. Opening a line shows Key Information, Asset & Contract and System Information, but not the Account. Edit shows the Account.

Quick reference

• Contracts → Contract Lines lists every line; a contract's Scope tab shows the same list.
• A line has no Contract field: put the contract number in Description.
• Name is replaced by an SCL number on save.
• Use the contract's account as the line's Account.
• Discount is a percentage and is never applied.
• Billed Amount, Cost Price, billing and warranty fields are not on the shipped form.
• Link visits by setting Contract Line on the PM task.
• Contract lines never create invoices, service orders or entitlements.

Permissions

Contract lines follow ordinary entity permissions. As shipped, the System Admin, Standard User, Sales, Sales Executive, Sales Manager and Service security profiles have full access to contract lines (view, create, edit and delete, across all records). A user also needs the Contracts app to reach the list. Change this per profile in security profiles, and narrow which records people see with record security.

Configuration

Administrators can tailor contract lines in these places:

• Add the hidden fields to the form. Cost Price, Billed Amount, BillingTreatment, Visit Frequency, Year Number, Series, Vendor name, Is under warranty, Is parts supply, Bill To Account, Ship To Account and Remarks are on no shipped layout. Add the ones you use to the Contract Line Create layout (used by New and Edit) and, if you want them visible on the record page, to the Contract Line View layout, in Setup → Design Studio → Entities → Contract Line. See Design a form layout. The Account field is also missing from the View layout.
• Picklist values. BillingTreatment and Visit Frequency ship with no values. Add the values your agreements use before you put these fields on a form.
• Link lines to their contract. To make the Scope tab show only the open contract's lines, add a lookup from Contract Line to Contract in the data model, add it to the line's Create layout, and set the relation on the contract layout's Scope list in the layout designer.
• Numbering. The Contract Line Document Name Setting sets the SCL format. Change the default series, date format, number length or separator in Setup → Feature Hub → Platform → Document settings. With the shipped daily date part, numbers restart each day. See Document numbering.
• Views and list columns. Add Account, Item or Unit Price columns to the All Contract Line view, or create views per customer or per year.
• Rules. There are no shipped business rules. Use business rules if, for example, you want Item and Account to be required.
• Dashboards. The Renewal Exposure and Contracts & SLA dashboards read Billed Amount, Asset count, Quantity and Contract Hours from lines.
• Mobile. The Contracts app is not part of a shipped mobile app, so contract lines are a web task.

Common problems

My new line shows up on every contract

Expected as shipped. A contract line has no Contract field, and the Scope tab lists every line. Put the contract number in Description and search for it, or ask your administrator to add a contract lookup and bind the Scope list to it (see Configuration).

The name I typed was replaced by a number

The Contract Line Document Name Setting writes an SCL number into Name on the first save. Use Description for meaningful text.

I can't find where to enter cost price, billed amount or warranty

Those fields are not on the shipped New/Edit form. Ask your administrator to add them to the Contract Line layouts, or fill them by import.

The Account isn't on the line's record page

The shipped View layout has no Account field. Select Edit to see or change it.

The renewal dashboard shows zero value

The value tiles add up Billed Amount, which no shipped form fills and no invoice updates. Fill it by import or an extended form.

The discount isn't taken off the price

Nothing calculates from the line. Discount records the agreed percentage only.

Common questions

Does a contract line bill the customer?

No. Nothing creates an invoice or sales order from a contract line, and Billed Amount is not updated when you do invoice. Bill the agreement through service orders and invoices or sales documents, and keep the line as the record of what was sold. If you want the register to show what has been billed, add Billed Amount to the form and update it yourself, or import it.

Does a contract line give the customer cover on service orders?

No. Service orders check cover against the customer's asset service contract, which comes from the service contract definition when the contract item is invoiced. A contract line is never read by that check. Record the agreement in the Contracts app for reference and reporting, and set up the definition separately when you want xMatix to enforce the cover.

How do I record a multi-year agreement?

Either one line with Contract Years set to the full term, or one line per year. For a line per year, add Year Number to the form (your administrator can do this) and put the year in the description too, so each year's price and hours can be reported separately. Nothing creates the later years for you; add each line yourself or clone the record. Clone is not on the shipped record page, so most teams use New.

Can I see a customer's lines across all their contracts?

Yes. Filter the Contract Lines list on Account, or use the Contract Value by Account table on the Contracts & SLA dashboard, which groups lines by account with their billed amount, quantity and hours.

Related topics

• Contract records in xMatix
• Creating and maintaining contract records
• Asset service contracts
• Service contract definitions
• Document numbering
• Contract Line entity reference
• Contract — entity reference