Linking Equipment to Contracts - edmozley/freeitsm GitHub Wiki

Equipment covered by a contract

A contract can list the equipment it covers: the mobile service agreement and the handsets and SIM cards on it, the internet agreement and the router, the maintenance contract and the machines it protects. The link is visible from both ends, so you can start at the paperwork or at the thing on somebody's desk.

The developer guide is Equipment covered by a contract — Developer Guide.

Requested by dschipfel in discussion #106.

1. Adding equipment, from either end

From the contract: open it and find the Equipment panel, then click Add.

From the equipment: open an asset, go to its Contracts tab and click Add to a contract. That picker searches by contract number, title or supplier name, because "the Vodafone one" is how most people refer to a contract they have not opened in a year, and it offers the contracts closest to ending first — a contract you are about to lose is the one you are most likely to be attaching equipment to.

Quicker still: right-click any asset in the equipment list and choose Add to a contract, without opening it at all. See Assets.

Whichever end you start from the result is the same link, and it can be removed from either end.

🔑 Somebody standing at a desk with a new handset should not have to go and find the agreement first. That is the whole reason for the second route.

Searching from the contract side

Search by name, model, serial number, asset tag or location. Location matters more than it looks: nobody knows the hostname of a meeting-room television, and nobody knows the serial number of a SIM card. They know what it is and where it lives.

Anything already on the contract is left out of the results — offering it again could only produce a no-op.

2. The reference on a link

Each link carries an optional reference, typed straight onto the row: a phone number, a line ID, a seat number.

🔑 It belongs to the link, not to the equipment, and that distinction is the useful part. Move a handset onto a different agreement and you keep the handset and lose the line — which is exactly what happens in real life.

Details of the thing itself — a SIM's IMSI, a laptop's purchase date — belong on the asset, where custom asset fields can hold them.

3. From the equipment's side

An asset gains a Contracts tab listing every agreement covering it, with the supplier, the end date and the notice date.

The notice date is picked out in the warning colour on purpose. An end date is easy to plan around; a notice period is what quietly turns a decision you meant to make into a renewal you did not. Having it on the equipment means the question can be asked while somebody is holding the thing, rather than only when the contract happens to be open in front of them.

If the reader cannot see the Contracts module, the tab says so rather than showing an empty list. "No contracts" and "you may not see contracts" are different answers, and reading one as the other is how somebody concludes a contract was never set up.

4. Removing equipment

Remove takes the equipment off the contract and nothing else. The asset stays exactly where it was in Asset Management; the contract is untouched.

The confirmation says so in as many words, because "Remove" next to a piece of equipment reads as "delete the equipment" to enough people to be worth a sentence.

5. The equipment report

Equipment report, at the top of a contract, produces a one-page list of everything it covers: the supplier, the dates and the notice date, then a row per item with its type, serial, asset tag, location and reference.

It goes out three ways, and all three show the same rows:

	What it is for
Print or save as PDF	Opens the report in a new tab and offers your print dialog. There is no PDF library in FreeITSM — "save as PDF" is your browser doing it, which every browser can.
Download as CSV	The same rows as a spreadsheet, for reconciling against a supplier’s own list. Quoted properly, so a model name with a comma in it does not shift every column after it, and written with a byte-order mark so Excel reads accented names correctly rather than guessing at a codepage.
Email	Sends the report as the body of a message, through the same sending mailbox the portal uses. It goes to the contract owner unless you type a different address.

⚠️ The report is filtered exactly as the panel above it is. It is never a way to see equipment you could not otherwise see, and the emailed copy contains what the sender can see — they are the one choosing to send it.

6. On an installation serving more than one company

The equipment list on a contract shows only equipment from the companies you can reach.

⚠️ It does not tell you how many were left out. A count of things you cannot see is itself a disclosure. If a contract covers ten assets and you may see three, you are shown three and told nothing about the other seven.

Note that contracts themselves are not company-scoped — every contract is visible to anybody with the Contracts module. Only the equipment side is filtered, because the equipment is the only half of the link that belongs to a company at all.

7. What this is not

🔑 Renewal reminders already exist, and this is not them. A workflow can fire when a contract approaches its end date, at windows you choose, with nothing linked to it at all. That is driven by cron/workflow_scheduled.php — see Scheduled tasks.

Linking equipment tells you what is affected when that reminder arrives. It is not what produces the reminder.

8. A worked example

The request that prompted this: managing mobile phones and SIM cards.

Create the contract — Mobile Service Agreement, with its end date and notice period.
In Asset Management, make sure the handsets and SIMs exist as assets. If you do not already have a type for them, add Mobile phone and SIM card under the asset type settings; they are ordinary types like any other.
On the contract, Equipment → Add, and search for each one. (Or the other way round: right-click each handset in the asset list and choose Add to a contract, which is usually quicker when you are working through a box of new phones.)
Put the line number in the reference on each SIM's row.
Set up a workflow on contract.expiring if you want to be told before the notice date arrives.

From then on: open any handset and its Contracts tab answers "what are we on, and by when do we have to say something?"