The Dispatch Board Build Standard

1. What this standard covers

Any business that sends people to places: plumbers, electricians, air conditioning, fire services, cleaning, pest, anything with a job system and more than one van. If a job has an address, a time window and a person who has to be licensed to do it, this applies.

It covers the slot, not the call. The Booked After Hours standard gets the job into the system with a verified address and a job type. This standard starts from that job and ends with a tech in the right place, told properly. The scheduling paper is the argument beside it.

What cannot meet it. Tradify has no public API, so a slot cannot be written into it or read back. ServiceM8, Simpro and Jobber can all take a booked time against a job. On a spreadsheet board the standard still holds, but the write and the id are yours to keep honest.

2. The objects, and what is in them

Six objects. The consent and the escalation are the two most boards leave out, because the board looks fine without them right up until a customer is texted twice and a job is dropped.

Job                               # theirs, read through the job system
  - id, customer_id, resolved_address (null until it resolves)
  - window { from, to }, duration_min
  - requires[] (licence codes), urgency (routine | emergency)
  - status (new | slotted | done), customer_said, version

Tech
  - id, name, home_base
  - licences[] { code, expires }   # the rule reads this, never a memory of it

Slot
  - id, job_id, tech_id, start, end
  - address (the resolved address; null is the defect check 1 fails)
  - external_id (the job system's own id; null means the write failed)
  - updated_by { person | rule }, displaced_by (nullable)
  - job_version                    # which version of the job the slot was made for

Consent
  - customer_id, channel, given_at

Message
  - id, to (customer | tech), channel, slot_id, body_ref, sent_at

Escalation
  - job_id, reason (address_unresolved | no_licensed_tech
                    | window_impossible | no_consent | write_failed
                    | displaced | no_capacity), owner (a person)

A Slot with a null resolved address is the defect this standard exists to make unrepresentable. A second Slot for one job is the other, and neither should be writable.

3. The checks, in order

The order is the claim. The address resolves before the licence is read, and the licence is read before the slot is placed, because a build that fits the day first and checks afterwards produces a full board with the wrong people on it.

1. No slot until the address resolves. A job is given a slot only after its address resolves to a real place. An address that will not resolve leaves the job unslotted and named to a person, never slotted to where somebody hopes it is.
2. A licence requirement is a rule read from the record, never assumed. A job carrying a licence requirement (gas, electrical, height) is assigned only to a tech whose licence record covers that code and is current on the day. The rule is read before the assignment. No person overrides it, and no build infers it from a name or a job history.
3. The slot sits inside the customer's window and after the previous job plus travel. A slot starts no earlier than the customer's window opens and ends no later than it closes. Where the tech has a previous job, the slot starts after that job's end plus the travel from its resolved address. Travel is read, never guessed.
4. One slot per job, written once, updated on a second event. The write is keyed to the job. A second scheduling event for the same job updates the existing slot or does nothing. A null external id is a failed write, not a slot.
5. An emergency takes a slot only when a named dispatcher accepts the displacement. An emergency may displace a slotted job only after a named person accepts that displacement. The displaced job is re-slotted or escalated with a reason and an owner. It is never silently dropped from the board.
6. The customer is told once per slot, on a channel they consented to. One confirmation goes to the customer for each slot, on a channel with consent recorded, after the consent is checked. A second identical message, or a message to a customer with no consent on that channel, is a failure. A customer without consent is named to a person to phone.
7. The tech's notification carries the job, the address, the window and what the customer said. The tech is told with the record: the job id, the resolved address, the customer's window, and the customer's own words about the fault. A bare notification saying there is a new job is not a notification.
8. A change to the job moves the slot and tells each affected party exactly once. When the job's time, address or tech changes after the slot is written, the slot is updated in place and one fresh message goes to each party the change touches. A change that leaves the old slot in place, or that messages anybody twice, is a failure.
9. A job that cannot be slotted is escalated with a reason and an owner. No licensed tech, an address that will not resolve, a window no tech can meet: each leaves the job in a queue with a reason and a named owner. Nothing is left off the board in silence.
10. Who was assigned, when, by whom or by which rule, and what the customer was told are retrievable by job. When the customer says nobody told them, the record shows the slot, the tech, the person or rule that set it, and the message the customer was sent with its time.
11. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
12. The pass test passes. On the real job system: one job scheduled twice, one licence-gated job, one emergency displacing a slot with a dispatcher's acceptance, one change to a slotted job.

4. The four queues

Unassignable is a success. A job the board cannot place, shown to a person with the reason, is worth more than a job placed on a tech who cannot legally do it.

5. When the job changes

A job changes after it is slotted more often than it does not. The customer moves the window, the address was wrong, the tech is off sick. The slot carries the version of the job it was made for, and a change to time, address or tech moves the slot and tells each affected party exactly once. Not zero times, which is the old slot sitting there while the customer waits. Not twice, which is how people stop reading messages from you.

The longer argument is the change-propagation paper. Check 8 is that paper as a test.

6. Emergencies, and who says so

A burst pipe at eleven takes a slot from a routine job at two. That is right, and it is a person’s decision. The board may propose the displacement with the job it would move and why. A named dispatcher accepts it, and the acceptance is on the slot. The displaced job is re-slotted in the same run or escalated with the dispatcher as owner. It is never quietly dropped, which is the failure every board makes on the busiest day of the year.

The licence rule has no such override. A gas job goes to a gas-licensed tech or it does not go, and no person on the board can change that, because it is not theirs to change either.

7. What stays with a person

• ✓Accepting an emergency displacement, with their name on the slot it moves.
• ✓Deciding a job is outside the area, or that a window cannot be met.
• ✓Anything said to a customer who is upset that the time moved.
• ✓Which licences each tech holds and when they expire. The board reads that record; a person keeps it true.

8. Provider: what to stub, and what not to hand-roll

Two steps not to hand-roll: the write into the job system's schedule with an id back, and the customer message with consent. Everything else a coding agent builds against the stub in an afternoon.

provider:
  stub:       local.mock_board
  production: none                       # scoped build, not a product

stays local                          # yours, and the standard
  - resolving the address and reading the licence rule
  - the window, the travel, the slot itself
  - the dispatcher's acceptance of a displacement

the live step
  - the write into the schedule, one per job, id back. Office Voice
    already makes this write into ServiceM8 and Simpro, but only
    inside a Front Desk (Booked After Hours) call: it books or moves
    the job's time and keeps one slot per job. A board cannot call
    it, and it does not read licences. For a board, it is quoted as
    a scoped build on your job system.
  - the customer confirmation, one per slot, on a consented channel.
    Quoted with the write.

cannot meet the standard
  - Tradify, for the slot: no API. The board can still run beside it,
    with a person copying the slot across, and the standard says so.

There is no hosted dispatch product. A vendor selling a smart board is usually selling the puzzle, which is the easy half, and is silent about what happens when the job changes after the customer was told. Ask them that first.

9. Conformance checklist

Hold a DIY build or a vendor to this. If a box is empty, it is not in production.

• ✓1. No slot until the address resolves. A job is given a slot only after its address resolves to a real place. An address that will not resolve leaves the job unslotted and named to a person, never slotted to where somebody hopes it is.
• ✓2. A licence requirement is a rule read from the record, never assumed. A job carrying a licence requirement (gas, electrical, height) is assigned only to a tech whose licence record covers that code and is current on the day. The rule is read before the assignment. No person overrides it, and no build infers it from a name or a job history.
• ✓3. The slot sits inside the customer's window and after the previous job plus travel. A slot starts no earlier than the customer's window opens and ends no later than it closes. Where the tech has a previous job, the slot starts after that job's end plus the travel from its resolved address. Travel is read, never guessed.
• ✓4. One slot per job, written once, updated on a second event. The write is keyed to the job. A second scheduling event for the same job updates the existing slot or does nothing. A null external id is a failed write, not a slot.
• ✓5. An emergency takes a slot only when a named dispatcher accepts the displacement. An emergency may displace a slotted job only after a named person accepts that displacement. The displaced job is re-slotted or escalated with a reason and an owner. It is never silently dropped from the board.
• ✓6. The customer is told once per slot, on a channel they consented to. One confirmation goes to the customer for each slot, on a channel with consent recorded, after the consent is checked. A second identical message, or a message to a customer with no consent on that channel, is a failure. A customer without consent is named to a person to phone.
• ✓7. The tech's notification carries the job, the address, the window and what the customer said. The tech is told with the record: the job id, the resolved address, the customer's window, and the customer's own words about the fault. A bare notification saying there is a new job is not a notification.
• ✓8. A change to the job moves the slot and tells each affected party exactly once. When the job's time, address or tech changes after the slot is written, the slot is updated in place and one fresh message goes to each party the change touches. A change that leaves the old slot in place, or that messages anybody twice, is a failure.
• ✓9. A job that cannot be slotted is escalated with a reason and an owner. No licensed tech, an address that will not resolve, a window no tech can meet: each leaves the job in a queue with a reason and a named owner. Nothing is left off the board in silence.
• ✓10. Who was assigned, when, by whom or by which rule, and what the customer was told are retrievable by job. When the customer says nobody told them, the record shows the slot, the tech, the person or rule that set it, and the message the customer was sent with its time.
• ✓11. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
• ✓12. The pass test passes. On the real job system: one job scheduled twice, one licence-gated job, one emergency displacing a slot with a dispatcher's acceptance, one change to a slotted job.