Skip to main content

Work Orders from a Tech's Perspective

The work order edit page is the same Blade view for everyone — technician, supervisor, office. What's different is what's visible and editable. That difference is what this page explains: which sections appear, in what order, and what triggers them to unlock.

The pending-start gate​

A work order opens in pending status (or unassigned if no tech is set yet). When a tech opens a work order in unassigned or pending, the page shows a stripped-down view: customer, unit, due date, status widget. The Items card, the Files card (photos), the Internal Notes card, and the checklist response area are all hidden.

That's the pending-start gate. It enforces a workflow rule: log items and evidence while you're on site, not before. The gate is controlled by a pendingStart boolean in edit.blade.php:

$pendingStart = !auth()->user()->can('work_orders.supervise')
    && in_array($item->status, ['unassigned', 'pending']);

Two consequences:

  • The gate only applies to non-supervisors. A supervisor opening the same pending work order sees every section.
  • The gate releases when the tech starts the work order (status moves to ongoing) and pendingStart becomes false on the next page load.

The gate is friendly to the field flow: there's no scrolling past empty sections, no temptation to fill items in advance, and no risk of submitting evidence for the wrong job. The downside is that techs who want to "preview" a work order from the office see a thin page; that's intentional.

The status widget​

The right column shows a status widget that's the tech's primary control surface. From top to bottom:

  • Status badge — color-coded by current status. unassigned is grey, pending is light blue (Bootstrap info), ongoing is blue (primary), paused is near-black (dark), waiting_approval is yellow/amber (warning), cancelled is red (danger), completed and billed are green (success).
  • Action buttons — only the transitions the tech can take from here. From pending: Start Work Order. From ongoing: Pause Work Order and Complete Work Order (which moves to waiting_approval). From paused: Start Work Order (resume). Techs never see Approve & Complete, Mark as Billed, or Cancel.
  • Timestamps — Arrived, Job Done, Signed Off. These populate as the corresponding transitions fire.
  • History link — opens the Status History modal listing every status change with the user, the timestamp, and GPS coordinates if captured.
  • Compliance banner — if the work order has incomplete strict refrigerant checklist obligations, a yellow warning shows here with a count, and explains how to clear it.

The widget never collapses. Even on a phone, it's the first thing scrolled into view because it controls everything else.

The items card​

Items is the workhorse section. It only renders when pendingStart is false.

Each row shows the catalog item, quantity, optional notes, and (for refrigerant items) a small refrigerant icon plus a charge-event panel that expands inline. For regulated refrigerants, the row demands extra fields: event type, designation, technician certification, destination (for recoveries). See Record a Refrigerant Charge Event for the full panel.

Pricing columns are conditional on work_orders.pricing. Most techs don't have it, so they see item names and quantities but no dollar amounts. Items still save with prices behind the scenes; the office sees them on the supervisor view.

The Add Item button at the top-right of the card opens a search picker. The picker is keyboard-friendly (type to search, arrow keys to navigate) — important on a tablet.

The files card​

Photos. The card shows existing photos as thumbnails with a remove icon, plus an upload control. Limits are enforced server-side: 50 MB per file, MIME types restricted to image formats. Phone cameras dump multi-megapixel images by default, so the limit is realistic but not unlimited.

Photos are tied to the work order, not to a checklist or item. There's no per-row attachment; if you need to associate a photo with a specific failure, name it descriptively or attach a note that points to it.

Photos render full-size in a lightbox when tapped. Tap-and-hold on iOS triggers the system download menu.

The internal notes card​

Free-text notes, capped at 1,000 characters per note. The card label is Internal Notes and the card is collapsed by default — the badge next to the label shows the current note count, and tapping the header expands the card to reveal the existing notes and the entry form.

Multiple notes per work order are allowed and stack with the most recent at the top. Each note shows the author and timestamp. Saving a note posts the form straight to /notes — it's separate from the main work order's Update Work Order save.

Notes are visible to anyone who can see the work order. The customer doesn't see them on the public report, but supervisors and office staff do.

The checklists section​

If a checklist is attached to the work order's type, the checklist response area renders inside the form. Each item shows the prompt and the appropriate response control (yes/no, text, photo, signature). Required items hard-block submission until they're complete; pressing Complete Work Order with required items still open returns a Cannot complete work order: N required checklist items must be completed first error. See Use a Checklist on a Work Order for the full flow.

What's hidden vs. just disabled​

Two distinct mechanisms control visibility:

  • Hidden — the section isn't rendered at all. Items, files, notes, and checklists when pendingStart is true. Pricing columns when the user lacks work_orders.pricing. Status transition buttons the user can't take.
  • Disabled — the section renders but inputs are read-only. After waiting_approval, the items, files, and notes cards render but in a read-only state. A tech can see what they submitted but can't change it without a supervisor sending the work order back.

The hidden vs. disabled distinction matters for explaining behavior. "Where's the items card?" usually means hidden (start the work order). "Why can't I edit?" usually means disabled (work order is past ongoing).

What a supervisor sees that a tech doesn't​

Same page, more controls:

  • Approve & Complete (status moves to completed) and Start Work Order (sends back to ongoing, the supervisor's "reject" path) in the status widget when the work order is waiting_approval.
  • Mark as Billed when the work order is completed.
  • Cancel from pending, ongoing, waiting_approval, or paused.
  • Pricing columns on the items card.
  • View episode and similar deep links for compliance-linked work orders that work without 403'ing.
  • Reassign dropdown for the technician.

A tech viewing the same work order doesn't see those controls and doesn't get suggestive empty placeholders for them — they simply aren't rendered.