Run the full work order lifecycle

This guide shows you how to run a work order from triage to completion in ATOM, and how to keep status, priority, lifecycle cards, and edits on the right record.

Use this guide when an admin has more than the first job to track. The first job tutorial only walks one happy path. This guide covers list/detail navigation, statuses, priority, service type, category tags, request and context sections, lifecycle cards for quote, booking, and invoice, files, activity, and which edits belong on which record.

#Find the right work order

Work Orders is the central job record after intake. Use it instead of Quotes, Invoices, or Schedule when you need the full job context.

Open the list at /work-orders from the sidebar. The list shows every work order with the title, the linked job title, the request description, and the status badge.

Use the list filter when the queue is long:

• /work-orders?view=open shows only open work orders. Use this view when you are doing daily triage and do not want completed or rejected rows.
• /work-orders shows every work order, including completed and rejected. Use this view when you are checking past work, for example Hot water valve replacement (docs-wo-completed) or Decorative shelf installation request (docs-wo-rejected).

The list also opens automatically. When you visit /work-orders and at least one row exists, ATOM redirects you to the first work order detail page so you do not stare at an empty page. The list panel stays visible on the left, so you can switch rows without going back. If the workspace has no rows yet, ATOM shows No work orders yet with the matching empty state. The Open view empty state offers View all work orders to switch back to the unfiltered list.

If a list link points at /work-orders/:id/edit, follow it. ATOM redirects edit URLs to the detail page because work orders are edited inline from the detail surface, not on a separate edit screen.

#Read the work order detail page

Open a work order from the list or from a related record (an inbox thread, a quote, a booking, or an invoice). The detail page is the handoff surface for the office team.

The page shows these sections in order, top to bottom:

• The breadcrumb header with the agency, property, and current work-order title.
• The status badge in the header. It uses lifecycle state (Open, Completed, Cancelled, or Superseded) when set, and falls back to the coordination status (Triage, Need Info, Ready, Active, Completed, or Rejected).
• Open in Inbox button when a Gmail inbox thread is linked to the work order. Use this to jump back to the source conversation. The action stays hidden on work orders without a linked thread.
• Request — the source document and editable description.
• Context — property and agency.
• Service Lifecycle — the quote, booking, and invoice cards.
• Activity — comments, notes, and the audit trail.

Use Kitchen sink leak assessment (docs-wo-triage) when you want to see every section populated with a draft quote, a proposed booking, a draft invoice, and a linked inbox thread.

#Use the Request section for source-of-truth edits

Request is the source document for the work order. Edit it here, not on the quote, booking, or invoice.

In Request, you can edit:

• The description. Click the description text to edit it inline; ATOM saves when you click away.
• The category tags. Use Add category... to apply categories such as Plumbing, Electrical, Building, or Safety & Access. Manual category tags can be removed; auto-applied tags stay locked until the source rule changes.
• The service type. Pick one of General, Repair, Maintenance, Installation, or Inspection.
• The priority. Pick one of Low, Normal, High, or Emergency.

Set the right combination for each example:

• Kitchen sink leak assessment keeps Plumbing, Repair, and Emergency because water is pooling under the sink.
• Carport sensor light replacement (docs-wo-ready) keeps Electrical, Installation, and Normal.
• Smoke alarm chirping in retail corridor (docs-wo-in-route) keeps Safety & Access, Maintenance, and High.

The Request card also shows the source sender, the received timestamp, and any file attachments. Click the attachment summary, for example 2 attachments, to open the file viewer. Files attached on the work order stay with the work order — they are not the same as line-item attachments on the quote or invoice.

Do not retype tenant contact details or property addresses in the description. Those belong on the property record.

#Confirm property and agency in the Context section

Context shows the property and the agency. Use this section to confirm the work happens at the right place and bills the right contact.

Treat the breadcrumb in the header as a navigation shortcut, not an edit surface:

• Select the agency breadcrumb to open /agencies/:id when you need agency contact details or related properties.
• Select the property breadcrumb to open /properties/:id when you need the tenant, address, or unit notes.

When property or tenant details are wrong, fix them on the property record. The work order picks up the corrected details on its next load. Do not edit the address inside the work order description.

#Read the Service Lifecycle cards

Service Lifecycle is the row of three cards under the request and context. The cards show the active Quote, Booking, and Invoice for the work order in left-to-right order.

Each card has three visible states:

• empty — no record exists yet. ATOM shows an Add Quote, Add Booking, or Add Invoice button so you can start the next step from the work order.
• active — a record exists but is not finished. The card shows the version or status, plus a quick subtext such as v1 • Draft for a draft quote, Feb 4 • 9:00 AM for a proposed booking, or INV-DOC-001 • Draft for a draft invoice.
• completed — the record reached its terminal state. ATOM marks quotes accepted, bookings done, and invoices paid as completed.

Click a populated card to open the related drawer without leaving the work order. The drawer shows the quote, booking, or invoice in place so you keep the work-order context. Use the create buttons on empty cards when the next record does not exist yet.

When a coordination summary is available (waiting on customer, waiting on technician, or waiting on supplier), ATOM shows it above the cards. Use it to see why the next step has not progressed before you decide whether to create a new record or send a reminder.

Use the demo examples to check each state:

• docs-wo-triage — Kitchen sink leak assessment shows an active quote (Draft), an active booking proposed for Emma Wilson, and an active invoice (Draft).
• docs-wo-ready — Carport sensor light replacement shows a Ready work order with a quote ready for booking.
• docs-wo-active — Balcony door rollers jammed shows an Active work order with the technician already scheduled.
• docs-wo-completed — Hot water valve replacement shows lifecycle state Completed. Use it to verify a paid invoice and a done booking.
• docs-wo-rejected — Decorative shelf installation request shows lifecycle state Cancelled and no further lifecycle work.

#Open the right record from the work order

Use the lifecycle cards instead of jumping into Quotes, Schedule, or Invoices first. The cards keep the work-order, property, agency, and inbox context attached.

For each lifecycle action:

• Quote work — open the Quote card. The drawer is the quote panel. For the build, approval, and send flow, follow Build, approve, and send a quote.
• Booking work — open the Booking card. The drawer is the booking panel. For technician selection, schedule check, and editing, follow Book and manage technician visits.
• Invoice work — open the Invoice card. The drawer is the invoice panel. For invoice status, payment, and Xero handling, follow Track invoices, payments, and Xero status.
• Inbox thread — select Open in Inbox. Use this when the next conversation belongs on the linked Gmail thread, for example following up on docs-wo-need-info for missing access notes. For inbox-side review, follow Turn an inbox email into a clean work order.

Each drawer adds a quick return path. Close the drawer with the dialog close button to stay on the same work order. Use View Full Details from a drawer only when you need the full quote, booking, or invoice page — return to /work-orders/:id from the breadcrumb when you do.

#Map each status to the right next action

Use the work-order status as the operational state and the lifecycle state as the terminal state.

• New — a work order that has not been triaged yet. Confirm the request before changing it.
• Triage — newly intaken work that still needs review. Example: Kitchen sink leak assessment (docs-wo-triage). Confirm property, agency, priority, service type, and category before booking. Use the inbox guide when the triage comes from an email thread.
• Need Info — the request is paused while the office or technician collects more information. Examples: Bathroom ceiling mould investigation (docs-wo-need-info) needs access notes; Intercom handset replacement access missed (docs-wo-no-show) needs a new access window. Add an Office Only comment in Activity that starts with Needs review: and names the missing item.
• Ready — the work order is approved and ready for the next step, usually a booking. Example: Carport sensor light replacement (docs-wo-ready). Use the booking card to schedule the technician visit.
• Active — work is in progress or scheduled. Examples: Balcony door rollers jammed (docs-wo-active) is on the schedule; Smoke alarm chirping in retail corridor (docs-wo-in-route) is en route. Use the booking and invoice cards as work progresses.
• Completed — work is finished, photos are uploaded, and the invoice is closed. Example: Hot water valve replacement (docs-wo-completed). Lifecycle state moves to Completed. Do not edit closed work orders for new scope; create a new work order instead.
• Rejected — the request is declined and will not progress. Example: Decorative shelf installation request (docs-wo-rejected). Lifecycle state moves to Cancelled. Record the reason in an Office Only comment for the audit trail.

Lifecycle state is the durable answer for reports and reopens:

• Open — any work order that is still active in the operational queue.
• Completed — the work finished. ATOM keeps the badge Completed until you explicitly reopen the work order.
• Cancelled — the work order was rejected or otherwise stopped. Use this when no further work is expected.
• Superseded — an older work order was replaced by a newer one for the same job. Use the newer work order for ongoing work.

#Use Activity for notes, comments, and the audit trail

Activity is the footer of the work order detail page. Use it for notes that belong on the request, not on the quote, booking, or invoice.

• Use Comment for a public note that the agency or tenant can see when the thread is shared.
• Use Office Only for an internal note. ATOM marks these comments with an Office Only badge. Start with Needs review: when the work order is in Need Info and the next admin needs an action.
• Use reactions on a comment when a short acknowledgement is enough.

Activity also records audit events: status changes, lifecycle transitions, category edits, quote sends, booking changes, and invoice updates. Read the audit trail before you contact the customer; the answer is often already in the timeline.

Do not paste long log dumps in the description. Keep the description short and put context in Activity comments.

#Pick the right record for each edit

When the same field exists on multiple records, edit it on the source record.

• Description, priority, service type, category — edit on the work order Request section. The quote, booking, and invoice inherit context but do not own these fields.
• Quote line items, customer notes, valid-until date, send path — edit on the quote. Follow the quote guide.
• Technician, start time, end time, booking priority, booking service type — edit on the booking. Follow the booking guide. The booking can carry its own service type and priority that override the work-order value for that visit, for example an Emergency booking against a High work order.
• Invoice amount, due date, send action, payment, Xero sync — edit on the invoice. Follow the invoice guide.
• Property address, tenant contact, map location — edit on the property from Context. Follow Find and maintain records.
• Agency name, billing email, agents — edit on the agency from Context or Directory > Agencies. Follow Find and maintain records.
• Inbox triage and tenant identification — edit on the inbox thread. Follow Turn an inbox email into a clean work order.

When you arrive on the work order from one of these records, use the breadcrumb or Open in Inbox to return to the originating record. The detail surface preserves the list panel context, so the originating list (Work Orders, Quotes, Schedule, or Invoices) stays visible on the left.

#Return without losing context

You rarely need to navigate by URL. Use the visible chrome instead.

• Use the back link ← Work Orders at the top of the detail page to return to the list with the previous filter (/work-orders or /work-orders?view=open).
• Use the breadcrumb agency or property entry to open the related record without breaking the work-order context — the list panel keeps Work Orders selected.
• Use the lifecycle drawers (Quote, Booking, Invoice) when you need the related record without leaving the work order. Close the drawer to come back.
• Use Open in Inbox to jump to the Gmail thread, then Open work order on the thread to come back.
• Use the command palette (⌘K / Ctrl+K) when you only know the work-order title or WO-DOC-NNNN-style code.

If a link still drops you on an empty page, recheck the URL. /work-orders/:id/edit always redirects to the detail page, and /work-orders redirects to the first row when the list has one. Both behaviours are intentional.

#Final check

Before you hand off the work order:

• The status and lifecycle state match reality (Open for in-flight, Completed for finished, Cancelled for rejected, Superseded for replaced).
• Priority, service type, and category tags match the request, not the technician's notes.
• Service Lifecycle shows the right quote, booking, and invoice cards, and any waiting-on summary above the cards is current.
• Activity has an Office Only Needs review: comment for any unresolved gap.
• Files attached to the work order belong on the work order; line-item attachments stay on the quote or invoice.
• Edits on property, agency, or inbox thread were made on the originating record, not in the work order description.