Calendar and Dispatch

Work the compact calendar

Calendar opens in Day with a time axis and crew and individual resource rows. Jobs and a crew member's appointments share the crew row, and overlapping visits remain visible. Each populated row identifies its time zone. Locations use their own local clocks, while conflict warnings continue to come from the server's capacity checks. Week, Month, and Agenda remain available.

The Unscheduled strip summarizes work without a service date; open it to work through the full queue in a sheet. Summary and Filters are collapsed disclosures for secondary totals and search, event scope, office, crew, member, and conflicts. Active filters remain visible and can be removed individually or cleared. Deposit received and Waive appear only when the member has both invoice-management and refund permissions. Other members still see the deposit status and job link. Select a job for its details and permitted actions.

Approved member time off appears as dated, all-day context for team managers within their authorized locations. It describes an individual absence and does not block an entire crew or create a new capacity rule. Multi-day jobs and visits without usable clock times remain listed rather than receiving invented slots. On narrow screens, scroll the Day grid horizontally or choose Agenda; the queue, filters, and job details open in sheets.

Open Calendar at /calendar in the web app's left navigation. The shared calendar combines sales appointments and service jobs while keeping the complete All jobs catalog as a separate view on the same page. Booked lead appointments appear on their scheduled date in Day, Week, Month, and Agenda; the Sales appointments total counts those same visits.

Calendar on a phone-sized web screen

The date and Day timeline appear before the Unscheduled strip. Week shows seven dates with event counts; select a date to see that day's service jobs and sales appointments. Month and Agenda remain available. Filters shows the active-filter count and opens the search and filter controls. Open Summary to see the secondary totals. The Unscheduled strip opens the full queue in a sheet, where the existing schedule and payment actions remain available. On desktop, the Day timeline uses crew and individual resource rows; the queue is available from the same strip and sheet.

Choose the work and calendar view

Use Combined to see sales and operations together. Operations limits the view to service jobs and the unscheduled queue. Sales appointments limits the view to booked lead appointments. Combined is the default because a technician may run a sales visit and service work on the same day.

Choose a time layout:

• Day shows one service date by crew.
• Week shows Monday through Sunday by crew.
• Month shows the complete calendar grid. Select +N more to reveal work hidden by the compact day view.
• Agenda merges the visible appointments and service jobs into one

chronological list. Combined mode does not place all service work ahead of all sales work.

An empty Day or Week retains its calendar grid, and an empty Operations Month retains the month layout. Agenda shows a clear empty state instead of a blank panel. The Home accepted work to schedule link opens All jobs filtered to unscheduled work.

Use the arrows to move one period, Today to return to the current local date, or the date field to jump directly to a date. Clearing the date field leaves the current period in place.

Read and filter the calendar

The summary shows Service jobs, Sales appointments, To schedule, Conflicts, and the filtered Scheduled value for the currently displayed filters. Turning on Conflicts only also makes the service-job, appointment, and conflict totals match the conflicting cards that remain on screen. Conflicts cover exact-time overlaps for one appointment assignee, one crew, or a technician's appointment against that technician's crew job.

Search matches the visible job number, real customer name, saved service address, service-job title, sales appointment type, and appointment assignee name or email. Appointment cards and Agenda rows show the appointment type label when one is saved. Saved assignees use a teammate name or email when available; if the assignee is not in the current member directory, CE Pro shows Assigned team member. Unassigned means the appointment has no saved assignee. Combine search with Location, Crew, or Team member. Use Conflicts only to isolate overlaps. Crew filtering includes Unassigned work. Capacity is calculated from the complete secured period before display filters are applied, so filtering the screen cannot hide a real capacity determinant. Use Clear filters to restore Combined and the full visible period.

A team member's service jobs come from that teammate's crew. Selecting a teammate who has no crew does not relabel every unassigned job as theirs; the view keeps only that teammate's sales appointments.

Assign a sales appointment on the web

On lead creation or the lead detail page, keep Assigned rep as the person who owns the opportunity. Use the separate Appointment assignee picker for the teammate who will run the visit. Owners, admins, office staff, and sales reps are eligible by default. A technician appears only when an admin grants that teammate Run sales appointments. The teammate must also have access to the lead's service location.

Existing appointments keep showing an inactive historical assignee, but that person cannot be selected for a new or changed appointment. Concurrent web appointment edits are revision-safe: if another browser changes the appointment first, refresh the lead instead of overwriting the newer schedule.

Work the unscheduled queue

Open the Unscheduled strip to see accepted, repeat, and standalone work without a service date in the queue sheet. Each card shows its saved customer, title, target month when available, and value. Confirm the required service location, then select Schedule and enter the date, optional time, optional active crew from that location, and estimated hours. Existing work appears once; scheduling changes that job instead of creating a duplicate.

Create standalone work

With Manage calendar, select New job from either Calendar view. Search for an existing active customer or work-owning service site, choose one of its active saved properties, and enter the service or job title. Notes and total are optional. Choose Unscheduled to place it in To schedule, or Schedule now and provide a date, start time, duration, and optional active crew from the property's service location. Duration must be a positive whole number of minutes, with an absolute cap of 1,440, but it must fit wholly before midnight. The actual maximum is therefore lower and depends on the selected start time. If the visit would cross midnight, the schedule dialog explains that you can choose an earlier start or a shorter duration.

CE Pro assigns a visible job number atomically and opens the new job after the save. A lost-response retry with the same browser command resolves to that same job. A crew overlap blocks the first attempt; scheduling anyway requires a reason and records the normal conflict-override audit. Company portfolio parents, inactive customers, archived properties, cross-location crews, and out-of-scope records cannot be used.

When Schedule or Move opens, the save action waits until permitted crew choices load. A failed request keeps the entered values and offers Retry crew choices. A deactivated crew remains visible on existing work but cannot be selected for a new assignment.

Capacity and intentional overlaps

Exact intervals use a back-to-back-safe boundary: an event ending at 10:00 does not conflict with one beginning at 10:00. If a job has no start/duration or an appointment has no complete start/end time, its capacity is Capacity unknown. Clean Estimate does not guess a duration.

The current job record has one service date, so a start plus duration cannot reach or cross midnight. Existing overnight records remain protected by conflict checks on both sides of midnight. The calendar checks two local dates on either side of the requested period. That covers the full 26-hour difference between the UTC+14 and UTC-12 timezone extremes without adding off-period events to the visible cards or summary totals.

When one teammate can work across offices, Clean Estimate converts each appointment and job from its own service-location timezone before comparing the intervals. A job's duration is added after its start is converted to an absolute instant, so daylight-saving changes do not silently alter the planned duration. If your access is limited to one office, a visible event still shows a conflict badge when it overlaps capacity at another office; the other office's customer and event details remain hidden.

Saving a known overlap is blocked first. If the overlap is intentional, enter a Conflict override reason and select Schedule anyway. The reason and conflicting record identifiers are retained in an audit event. Changing the proposed date, time, crew, assignee, or duration clears the earlier approval and checks the new slot again.

Changing a scheduled job's date or start time also requires a customer-facing reschedule reason. Cancellation requires its own reason.

Changing only a job resource, such as its truck, crew, or linked estimate, keeps the existing schedule reminder and does not send a customer time-change notice. A real date or time change uses the normal reschedule notification path; saving the same appointment slot again does not create another reschedule event.

The web board accepts at most a 46-date inclusive period (a start-to-end difference of 45 days). Day, week, month, and Agenda requests stay within that boundary. Conflict badges are produced in one bounded, set-based database pass for the secured period instead of comparing every card with every other card in the browser. Ordered indexes narrow appointment and job candidates by organization, date, teammate, and crew before interval comparisons run.

Only active crews can receive newly scheduled work or a new teammate assignment. An inactive crew remains visible on historical work and as a disabled current teammate assignment, but it is not offered as a new choice. Scheduling, teammate reassignment, and crew activation changes recheck the crew under the same ordered lock, so a concurrent deactivation either commits first and rejects the new assignment or waits until the valid assignment commits. If a crew becomes inactive while a scheduling dialog is open, the dialog keeps its entered fields and asks the dispatcher to choose another crew or Unassigned. Unsupported direct crew-state writes fail closed when a Calendar writer owns that crew gate. A crew's service location is immutable after creation; moving a crew requires a future workflow that can safely reconcile its members and work.

Permissions

Manage calendar controls office-wide appointment assignment and conflict overrides as well as scheduling, moving, assigning, releasing, or overriding service work. The Manage crews control and crew create, activate, or deactivate actions are shown only to a teammate with this permission. A web-capable teammate who has Run sales appointments but not Manage calendar can create or change only an appointment on a lead they own, must keep the appointment assigned to themselves, and cannot override a conflict. Run sales appointments also controls who appears in a calendar manager's appointment-assignee picker, including explicitly qualified technicians. Location access still applies to both the scheduler and selected teammate. The current rep app role remains mobile-only; granting its default appointment permission does not unlock the full web administration surface.

For a sales runner without Manage calendar, the server authorizes a schedule edit against the lead owner saved on the locked current record. Changing the proposed owner in that same request cannot grant access, and combining lead reassignment with scheduling requires Manage calendar.

Mobile appointment saves

The approved V1 mobile layout, navigation, controls, labels, and styling stay unchanged. When a connected road teammate changes an existing lead appointment, Save schedule now keeps the existing editor open until the shared calendar accepts the revision. A successful save closes the editor. A stale revision, unavailable time, ineligible assignee, changed permission, an office-archived lead, or a connection failure keeps the editor open and shows a short actionable error so the user can refresh, correct, or retry the change. Ownership and the current appointment executor are checked while the lead is locked, so an office reassignment that wins first also prevents the former assignee from saving a stale appointment edit. Move others' cards is not office calendar authority.

The acknowledged mobile save never grants conflict-override authority. A road teammate must choose an available slot; only an authorized web calendar manager can record the required reason and schedule through a capacity conflict. New lead creation remains offline-capable because the new lead and its initial appointment are still one queued record.

Released app versions that try to change an existing appointment through an unrevisioned PowerSync PATCH receive the stable legacy-appointment-update-online-required per-operation rejection. The queue continues, and sync-down restores the server schedule. This preserves offline new-lead capture without letting an older queued edit overwrite a newer office revision or bypass capacity and executor checks.

Role, permission, active-state, location, and crew changes share the calendar's per-member lock before eligibility is read or written. Identity-provider deactivation takes organization gates in order, then each affected member gate and row in order before Canvassing territory cleanup. There is no global calendar batch gate. If an arbitrary determinant update already owns a member row while scheduling owns that member's calendar gate, the database fails the update closed immediately instead of waiting in the opposite order. The provider retries safely, and appointment scheduling revalidates the executor after a concurrent team change commits.

Reliability and release checks

The release suite applies the migration chain to a dedicated PostgreSQL 16 database named cleanestimate_calendar_test on a separate loopback service. The Calendar race suite exercises both commit orders for scheduling, direct member changes, provider deactivation, crew reassignment, and Canvassing assignment cleanup. It also verifies sibling-office privacy, the UTC+14/UTC-12 boundary, and index-backed plans with 50,000 irrelevant jobs and appointments.

The destructive test harness accepts only that exact literal, unencoded database name, proves it is not the application's DATABASE_URL, and remains loopback-only by default. A separately named explicit acknowledgement is required for a remote disposable test database. These tests validate concurrency and query plans on real PostgreSQL; source-text migration checks are supplemental.

Payment-pending work

If proposal acceptance is waiting on a deposit outcome, an authorized office user must either select Mark paid after verifying receipt or explicitly select Waive before scheduling. The calendar does not claim that payment succeeded when the provider has not confirmed it, and a waiver remains a distinct resolution rather than a received payment.

Current V1 parity boundaries

The shared sales-and-operations calendar is available on the web. These V1 capabilities remain later parity work:

Customer reschedule and cancellation requests stay in the V1-aligned Tasks follow-up queue until an authorized teammate approves them. They do not create a separate Calendar tab or change the confirmed booking before the guarded decision succeeds.

• trucks, truck-day crews, ordered route stops, drive times, route maps, and route optimization
• multi-day bars, explicit job end times, and capacity/pay totals
• estimate appointments and sales follow-up events; current Calendar events are

lead appointments and service jobs, so these V1 event types are immediate later parity work rather than removed features

• saved calendar views
• drag-and-drop dispatch and multi-property bulk scheduling
• appointment confirmation and the En route, On site, Invoiced, On hold, and Skipped states

Related guides

• Use Managing Jobs for the catalog and job status model.
• Use Managing Leads for appointment creation and assignment.
• Use Locations for service-location access.