What the module does

Field service management (FSM) is the work of servicing the installed base at customer sites: the pumps, drives and other equipment you delivered and still look after. The module holds the installed assets and their warranties, the service contracts and their service level agreements (SLAs: the promised time to respond and to resolve), the work orders that come from cases or preventive plans, the scheduling and dispatch of technicians by skill, territory and travel, an offline technician app, van stock, and the claims that recover the cost of failed parts from suppliers.

This is the family of tools sold as Salesforce Field Service, Microsoft Dynamics 365 Field Service, ServiceTitan, PTC ServiceMax, IFS FSM, Jobber, Housecall Pro and FieldEdge. Vendor training sites such as Salesforce's Trailhead explain their words for the same ideas: service territories, work orders, appointments and mobile workers ^[3].

The standards behind it

You do not need to buy the standards for this course; the pages cited are the official catalogue entries.

Ten capabilities, three tiers

Each capability carries a tier. MVP must exist for a small or mid-size business to cancel its field service subscription with confidence. STD is parity with mainstream tools, what a buyer expects in a demo. BIC marks a best-in-class difference. MVP and STD are required for the course; BIC is advanced work.

The installed base starts at the shipment

An installed asset is a customer-owned product in service. Each one keeps its serial number as text, a link to the serial unit that shipped (serial_unit_id), a soft link to the sales order (sales_order_ref), the service site, and optionally a parent asset: a drive module hangs under the pump it belongs to. Warranty start and end sit on the asset. Both empty means no warranty.

Contracts and the entitlement check

A service contract is one of five types (warranty, maintenance, full service, time and materials, subscription) with a start and end date, response and resolution hours, and an entitlements block saying which line types it covers and when its clock runs. Contract rows list the assets they cover. A contract in draft never covers anything; neither does one that has expired or been cancelled.

The lab seed used through the module (made-up customers, serials and dates, loaded in Session 2) gives a table to check any version of the rule against:

A job booked for an asset that is out of warranty and out of contract is flagged billable at booking. That is the first thing the module is checked against at the end of the course.

Thirteen tables on the shared spine

Every table starts with the standard columns every platform table has: id, tenant_id, created_at, created_by, updated_at, updated_by, row_version, archived_at and ext (a JSON column for extra values). The module has no customer list, parts list, people table or stock location of its own: it points at core_party, core_address, core_item, core_serial_unit, core_person, core_storage_location, core_calendar and core_attachment.

The table below is the full definition: every column the module adds to the standard ones, with its type and whether it is required (req). Types are as in the specification: text, int, num (a decimal number), bool, date, ts (a timestamp with time zone), money, qty (a quantity), uuid and json; an arrow means a foreign key to that table. A soft link is a uuid with no foreign key, because the other module may not be installed yet. Vendors may use other names for the same records; Salesforce's Field Service basics module, for one, speaks of work orders and service appointments ^[1], and ^[2] is an overview of that product. It is what your agent builds from in Session 2.

Money and quantities are numeric, never text or floating point, and every timestamp stores one exact instant, shown in the reader's time zone. In the lab seed, money figures are lab values, not rates.

Rules the database itself holds

• No second asset for a serial. A partial unique index on tenant, item and serial_no (where the serial is not empty) refuses a serial installed twice. A check refuses an asset that is its own parent.
• Numbers are unique per business. swo_no and claim_no come from a number sequence, never from the phone; contract_no is typed by the service manager and the database refuses a duplicate.
• Dates make sense. A contract's end_at is not before its start_at; an appointment's scheduled_end is after its scheduled_start.
• One open job per preventive plan. A partial unique index on the plan id in the job's ext applies only while the job is new, scheduled, dispatched, en_route, on_site or incomplete. A second open job for one plan is refused by the database, so a repeated run of the plan engine makes nothing new.
• Parts move through the inventory ledger, which is append-only. A used part is a ledger row from the van (module M12 holds the ledger), and a mistake is a reversing row, never an edit. A security-definer trigger on the ledger (it runs with its owner's rights) keeps each location's balance, so no route writes a balance itself.
• A sign-off cannot be changed. A trigger refuses any update or delete of fsm_customer_signoff, and the service report is stored as an attachment with its hash.

The JSON the rules read

JSON is a plain text format for lists and named values, so one column can hold a whole weekly timetable. Two shapes matter most. The contract's entitlements say what is covered and when the clock runs; a contract with no business_hours counts every hour. The technician's ext says what they can do and what their van should hold.

fsm_service_contract.entitlements
{ "covers": ["labor", "travel"],
  "business_hours": {
    "timezone": "Region/City",
    "schedule": { "mon": [["08:00","17:00"]], "tue": [["08:00","17:00"]],
                  "wed": [["08:00","17:00"]], "thu": [["08:00","17:00"]],
                  "fri": [["08:00","17:00"]], "sat": [], "sun": [] },
    "holidays": ["2026-06-19"] } }

fsm_technician.ext
{ "skills": ["pump", "controls"],
  "van_min": { "PUMP-SEAL": 2, "FILTER": 2 },
  "replenish_from": "WH-1" }

Ten statuses for a work order

An incomplete job is still open: the visit ended without the fix and another is needed. A visit has its own status too (scheduled, dispatched, en_route, on_site, completed, cancelled, no_access), because one job can take more than one visit.

Who uses it, and on which screen

Machine accounts do the rest, each with its own login and no person behind it: one creates installed assets from shipments, one generates preventive jobs and watches SLA clocks, one posts parts to the ledger, and one, used only while the old tool's data is moved in (Sessions 5 and 6), imports it. Giving each job its own login is what lets the access matrix stay small and checkable.

Events, and personal data

Book the job

Booking is where cover is decided. When a dispatcher books a job for an installed asset, the server runs the entitlement check at the booking date and then sets the party and site from the asset; billable, the covering contract and covered_by (warranty, contract or none) from the check; the skills needed from the item; and the job number from the number sequence. A job asked for by a customer case keeps the case's id as case_ref, a soft link, so booking works where the help desk module is not installed.

Only repair and warranty jobs under a contract carry an SLA due time, taken from the contract's clock. Preventive, inspection, install, upgrade and decommission jobs are planned work and have none. A preventive job is made by an engine: each active plan whose next-due date has arrived, and that has no open job carrying that plan's id, books one and moves its next-due date forward from the previous due date, so a late visit does not shift the plan.

The service clock counts business hours

ITIL 4's service level management is about measuring a target the way it was agreed. A contract that promises a four-hour response during business hours does not mean four hours on the wall clock. The clock counts only hours that fall inside an opening period on a day that is not a holiday. If the job is booked outside opening hours, counting starts at the next opening. A contract with no business hours counts every hour.

Dispatch by skills, territory and travel

The dispatch board suggests a technician only if they are active, in the job's territory, and hold every skill the job needs. It then orders them by the earliest arrival: ETA = the later of (a) the window start and (b) the previous appointment's end, or the shift start, plus the travel time from the previous place. The drive is added to (b) only, never to the window start, so a technician whose drive from home ends before the window opens can arrive when it opens. On a desktop the dispatcher drags a job onto a technician; on a phone the same move is two taps, because dragging with a thumb is unreliable.

Travel time here is the straight-line distance between the previous place (the previous job's site, or the technician's home) and the job's site, from the coordinates in core_address, at 111.2 km per degree of latitude and an average of 60 km/h, rounded to whole minutes. These are lab values: replace the speed with one measured from your own drives, and remember that roads are longer than straight lines. The 111.2 km per degree is right only along the lab's single meridian; for real sites use a great-circle (haversine) distance, the shortest path between two latitude and longitude points over the earth's curve. A paid routing service gives real road times and costs whatever its provider's price page says; nothing in this course needs one, so the free way comes first. For how one vendor presents its dispatch app, see ^[1]. Left out: the specification marks schedule optimisation (planning many jobs at once) as best-in-class; this course suggests technicians one job at a time, and optimisation is extension work.

The technician's phone, offline

A technician is often where there is no signal. When they sign in, the phone saves the next days' jobs, sites, assets, history and the van's parts list to IndexedDB, the browser's own database on the phone, which survives closing the app ^[3]. Each job's moves (on my way, arrived, time, parts, photos, resolution, signature, complete) go into a queue, and every new row gets an id made on the phone with crypto.randomUUID(), so the same entry can be sent twice and a repeat adds nothing: the server calls this being idempotent.

The server, never the phone, sets each line's price from the item's list price, and decides billable and warranty_covered from the job. On completion it builds the service report, a printable page listing the work, parts and times. An HTML file that any browser prints to PDF is the free way. The customer's signature is captured on the phone, uploaded with the entry, and stored in a sign-off row that cannot be changed. A job with one visit is marked first-time fix.

Van stock follows the ledger

A technician's van is a storage location. When a part line is accepted, a second route posts one ledger row from the van, tagged with the line, and writes the ledger id back onto the line, so a repeat posts nothing. A used part is a fact, so the route never refuses it for lack of stock; replenishment shows the shortfall instead. For each technician and part, if the van's balance is below its minimum and no request is open, one parts request is made for the difference.

Billing hand-off and warranty recovery

The service manager's release to billing moves a completed job to ready_to_bill only when it has at least one billable line, a sign-off, and a ledger id on every part line. A CSV file of the billable lines, which the accounting package imports, is the free way to hand them on, and it moves those jobs to billed so a second export returns nothing. For one vendor's list of the features buyers look for in field service software, see ^[2]. A paid accounting connection would cost what its provider charges. A job's own billable flag only records that the work was not covered when it was booked; the lines decide the bill, so a job covered by a contract can still carry one billable part the contract does not cover.

Warranty recovery is a BIC capability. When a part failed under warranty, the service manager can claim its cost from the supplier: one claim per job and failed item, the amount claimed is the sum of the job's warranty-covered part lines, and the amount recovered stays empty until the claim is paid. Whether a supplier also pays labour depends on its written warranty terms: read them, do not guess.

Four measures

The specification names first-time fix, SLA attainment, mean time to repair, technician utilisation and repeat visits as the module's analytics; for how vendors describe their features, see ^[1] and ^[2]. A name says little without its definition, so this module writes each one down. A job billed since it was completed still counts: test the status for completed, ready_to_bill or billed, not completed alone, or the measures drop every job that has been handed to accounting. Left out: mean time to repair is not one of this course's four measures; it is extension work, and if you add it, write its definition beside it the same way.

Move in, in order

The specification's advice is to export customers, sites, assets, contracts and open jobs, and to import closed jobs as history for first-time-fix baselines. This module moves them in six imports: sites with their customers, assets, contracts, preventive plans, open jobs and closed jobs. The order matters, because each kind depends on the one before it.

• Every imported row keeps where it came from (the old tool's name and the old id in ext), and the script finds rows by them, so a re-run or a resumed import adds nothing twice. A dry run prints the counts first.
• Assets are matched to shipped serials with three outcomes: matched (the unit and order are taken from the shipment), near match (a person decides), and no match (imported with the serial as text, and listed). Write the matched share. This is pitfall 1, handled on real data.
• Every contract needs an end date. A contract the old tool rolls over with no end gets its next renewal date and is listed for the service manager. One whose end is past is imported as expired. A contract that counts calendar hours gets no business hours.
• Open jobs keep the old number (as OLD- followed by it, so it can never clash with the sequence) and the old tool's due times. Then run the entitlement check as of each job's booking date and list the jobs where the new answer differs from the old billable flag; decide each one and record the reason.
• Closed jobs arrive in their final state as history: lines marked as history with the old prices, first-time fix true for one visit and false for more, and left empty where the export has no visit data. Nothing fires, nothing is posted to the ledger, and nothing is billed a second time. Import enough earlier history, at least 30 days before the period you measure, for repeat visits.
• Counts reconcile. For each kind, rows in the export equal rows imported plus matched plus skipped, and every skipped row is listed and explained.

Before cut-over, a read-only check file returns zero for: installed assets with no service site; active contracts whose end date is already past; assets of serial-controlled items with no serial unit (each needs a written decision); open jobs with no site; scheduled or dispatched jobs with no appointment; and two assets with one item and serial. Fix the data, not the check.

Cut over and retire

1. Run side by side for at least a week. The dispatcher books every job of one pilot territory in both tools, and the technicians complete it in both. Put the old tool's figures and the platform's side by side and explain every difference.
2. Check what the module must keep: every job for an asset with no cover is billable (or has a manager's reason); every completed part line has a ledger id and each van's balance equals its ledger; three SLA due times worked out by hand match the stored ones; every completed job has a sign-off or a written reason, and a sign-off cannot be changed; every asset has a site.
3. Test a phone in airplane mode against the seed and the synthetic batch, and force a second send: every count must stay the same.
4. Cut over on a date you wrote down, with a rollback plan, the final delta import, and the old tool read-only. When the delta counts reconcile, remove the import login and its rows from the matrix. Customers should be told in plain words that any texts or emails the old tool sent will stop, because this module sends none.
5. Take a final full export first, then cancel or write the date the plan ends. Read the vendor's terms (notice period, renewal date, how long you can still export) on your own account page. The saving is the old cost, plus the helper tools you drop, less what the module costs on services you already pay for, worked out from real invoices and never from estimates.