Dispatch

dispatch is the field service desk. A dispatcher creates a work order at an asset location or an address, puts it in a technician's slot on the schedule board, and plans the order the technician drives to their jobs. The technician opens their day plan, marks each job en route, on site and done, and records the parts they used.

better-supabase add dispatch

import { createDispatch } from "better-supabase/blocks/dispatch";

The module requires tenant and access. With assets a work order and a part can name an asset location and an asset, with bookings a work order can take its slot from a booking, and with catalog and inventory a part can name the product variant and the stock location it came from. With outbox every change records an event, and with audit the writes are audited. Technicians are the organization's members who hold dispatch.work; members hold it by default.

TablesCopy Anchor Link

Every table is read through the functions only. Readers with dispatch.read see every work order, and a technician with dispatch.work sees and works their own. blocks.dispatch.entities renames the tables and functions.

Create and schedule work ordersCopy Anchor Link

const dispatch = createDispatch({ transport, tenant: organizationId });

const order = await dispatch
  .create({
    title: "Service the boiler",
    priority: "high",
    locationId,
    assetId,
  })
  .orThrow();

await dispatch
  .schedule(order.id, {
    technicianId,
    startsAt: Temporal.Instant.from("2030-01-07T09:00:00Z"),
  })
  .orThrow();

A work order without a slot waits in the backlog (unscheduled). Pass technicianId and startsAt to create, or a bookingId to take the slot from a booking, to schedule it at once. A slot without endsAt lasts defaultDuration (one hour). The database refuses a slot that overlaps another scheduled, en route or on site work order of the same technician, under an advisory lock per technician, so two dispatchers can't book the same hour. Creating, changing and scheduling need dispatch.manage.

The dispatch section lists a record's work orders on its page, with create and cancel writes.

The status lifecycleCopy Anchor Link

Each step stamps its time (enRouteAt, arrivedAt, completedAt, cancelledAt) and records work_order.status_changed with from and to. Setting the status a work order already has changes nothing.

The board and the day planCopy Anchor Link

const board = await dispatch
  .board({
    from: Temporal.PlainDate.from("2030-01-07"),
    to: Temporal.PlainDate.from("2030-01-11"),
  })
  .orThrow();

const day = await dispatch
  .technicianDay(Temporal.PlainDate.from("2030-01-07"))
  .orThrow();

The board reads 1 to 31 days in the block's timeZone (UTC by default). It returns the scheduled work orders with their day, the technicians (the ones you pass, else the ones with work), and the backlog, most urgent first.

planRoute sets the order a technician drives to their work orders on a day; each must be a live work order of theirs. technicianDay returns the route's stops in that order, then the day's other work orders by start. technicianId defaults to the caller, so a technician opens their own plan. A dispatcher plans any route; a technician plans their own.

blocks: {
  dispatch: { options: { timeZone: "Europe/Amsterdam", defaultDuration: "90 minutes" } },
},

PartsCopy Anchor Link

await dispatch
  .recordPart(order.id, {
    name: "Gasket",
    quantity: 2,
    unit: "pc",
    variantId,
    locationId,
  })
  .orThrow();

A part is free text, an asset, or a catalog variant taken from an inventory location. Recording a part moves no stock: book the movement in the inventory block when the job is done. The technician on the work order and dispatchers record parts, and the one who recorded a part can remove it.

UI recipesCopy Anchor Link

The dispatch-board UI recipe renders the board as a kanban with the backlog as the first column and a column per technician, and technician-day renders a technician's route as a list with the status buttons. Both are in the Next.js example.

ErrorsCopy Anchor Link

EventsCopy Anchor Link

work_order.created, work_order.updated, work_order.scheduled, work_order.unscheduled, work_order.status_changed, work_order.part_used and dispatch_route.planned. The events page lists their payloads.