Job Scheduler

The Job Scheduler manages automated job creation from compliance schedules, recurring templates, quotes, and purchase orders.

Overview

Flow: Trigger → Job Created → Assignment → Scheduling → Execution → Completion Key Files:

packages/workbooks-jobs/src/workflows/job-progress-tracker.ts
apps/workbooks-api/src/trpc/routers/workbooks-jobs.ts
apps/workbooks-api/src/trpc/routers/compliance-workflow.ts

Job Status States

type JobStatus =
  | "draft"        // Created but not ready
  | "scheduled"    // Assigned and dated
  | "in_progress"  // Work underway
  | "on_hold"      // Temporarily paused
  | "completed"    // Work finished
  | "cancelled"    // Job cancelled
  | "invoiced";    // Invoice generated (terminal)

Workflow Diagram

Trigger Sources

Compliance Schedule

Auto-generated from asset compliance requirements (lead time before due date)

Recurring Template

Weekly, monthly, or custom recurring job patterns

Quote Accepted

Automatic job creation when customer accepts quote

Purchase Order

Direct conversion from approved PO

Assignment Phase

Auto-Assignment
Manual Assignment

Automatic Technician Assignment

Jobs can be auto-assigned based on:

Criterion	Weight	Description
Skills Match	High	Technician has required certifications
Availability	High	Not already booked during window
Location	Medium	Proximity to job site
Workload	Medium	Balance across team
Preferences	Low	Technician preferences

// Auto-assignment algorithm
const assignTechnician = async (job: Job) => {
  const candidates = await getAvailableTechnicians({
    date: job.scheduledDate,
    skills: job.requiredSkills,
    location: job.location,
  });
  
  const ranked = candidates.map(tech => ({
    tech,
    score: calculateScore(tech, job),
  })).sort((a, b) => b.score - a.score);
  
  return ranked[0]?.tech;
};

Scheduling Phase

Date/Time Selection

Choose scheduled date and time window:

All day
Morning (8am-12pm)
Afternoon (12pm-5pm)
Specific time slot

Calendar Sync

Job added to:

Technician’s calendar
Team scheduling board
Customer portal (if enabled)

Notifications

Automatic notifications sent:

Technician: Job assignment
Customer: Appointment confirmation
Admin: Scheduling summary

Execution Tracking

Job Progress

interface JobProgress {
  status: JobStatus;
  startedAt?: Date;
  completedAt?: Date;
  technicianLocation?: GeoPoint;
  checkInTime?: Date;
  checkOutTime?: Date;
  timeEntries: TimeEntry[];
  photos: Photo[];
  notes: Note[];
  faults: Fault[];
}

Real-time Updates

Event	Tracking
Start work	GPS check-in, timer starts
Progress	Photos, notes, updates
Pause	On-hold reason captured
Complete	GPS check-out, time logged
Issue found	Fault created

Status Transitions

From	To	Trigger
draft	scheduled	Assign tech + set date
draft	cancelled	Cancel job
scheduled	in_progress	Start work
scheduled	cancelled	Cancel job
in_progress	completed	Finish work
in_progress	on_hold	Pause (waiting)
in_progress	cancelled	Cancel job
on_hold	in_progress	Resume work
completed	invoiced	Generate invoice

Compliance Integration

Jobs created from compliance schedules include:

interface ComplianceJobData {
  scheduleId: string;
  requirementId: string;
  assetId: string;
  dueDate: Date;
  complianceType: string;
  standardReference: string; // e.g., "NFPA 10 §7.2.1"
}

When job completes:

Compliance schedule marked complete
Next schedule calculated
Asset compliance status updated

API Endpoints

Endpoint	Method	Description
`workbooksJobs.create`	Mutation	Create new job
`workbooksJobs.assign`	Mutation	Assign technician
`workbooksJobs.schedule`	Mutation	Set date/time
`workbooksJobs.updateStatus`	Mutation	Change status
`workbooksJobs.getSchedule`	Query	Get scheduling board
`workbooksJobs.getByTechnician`	Query	Technician’s jobs

Customer Lifecycle

Job creation from quotes

Asset Compliance

Compliance-driven job scheduling

Developer - Overview

Core Workflows

Billing & Subscriptions

Integrations

Team Management

Onboarding Wizards

Reference

Overview

Job Status States

Workflow Diagram

Trigger Sources

Compliance Schedule

Recurring Template

Quote Accepted

Purchase Order

Assignment Phase

Automatic Technician Assignment

Dispatcher Assignment

Scheduling Phase

Execution Tracking

Job Progress

Real-time Updates

Status Transitions

Compliance Integration

API Endpoints

Customer Lifecycle

Asset Compliance

​Overview

​Job Status States

​Workflow Diagram

​Trigger Sources

Compliance Schedule

Recurring Template

Quote Accepted

Purchase Order

​Assignment Phase

​Automatic Technician Assignment

​Dispatcher Assignment

​Scheduling Phase

​Execution Tracking

​Job Progress

​Real-time Updates

​Status Transitions

​Compliance Integration

​API Endpoints

​Related Documentation

Customer Lifecycle

Asset Compliance

Overview

Job Status States

Workflow Diagram

Trigger Sources

Assignment Phase

Automatic Technician Assignment

Dispatcher Assignment

Scheduling Phase

Execution Tracking

Job Progress

Real-time Updates

Status Transitions

Compliance Integration

API Endpoints

Related Documentation