Jobs¶

Available to: Owner, Project Manager, Supervisor, Badge Worker (limited), Accounting (read-only)

A job represents active, in-progress work. Jobs are created automatically when a bid is approved — they are never created manually. The job inherits all project details from its source bid and tracks execution through to completion and invoicing.

How a Job is Created¶

Jobs are system-generated. When an Owner approves a bid:

The bid status changes to Bid Approved.
The system creates a corresponding Job linked via bid_id.
The Job's initial status is Ready to Start.
The PM and Supervisor assigned to the bid carry over to the job.

You cannot create a job directly. All jobs originate from an approved bid.

Job Fields¶

Field	Description
`bid_id`	Reference to the originating bid. The bid is the source of truth for client, location, scope, and financial details.
`staff_assignments`	Multi-select list of Project Managers and Supervisors assigned to this job (via `JobStaffAssignment`). Each entry has a user and a role (`project_manager` or `supervisor`).
`badge_worker`	Badge worker (site escort) assigned for site access. Manage profiles under Settings → Team or Escorts in the nav.
`permits_list`	Free-text list of permits required.
`po_number`	Client Purchase Order number.
`materials_status`	Status of materials procurement. One of: `None Needed`, `Needed`, `Ordered`, `Shipped`, `Delivered`.
`inspections_status`	Status of required inspections. One of: `None Needed`, `Needed`, `Requested`, `Pass`, `Failed`.
`completion_date`	Expected or actual job completion date.
`start_date`	The date work officially began.
`status`	Current workflow state of the job. See status machine below.
`blocked`	Boolean — whether the job is currently blocked from progressing.
`blocked_reason`	Required when `blocked` is true. Free-text explanation of the block.
`priority`	Boolean — marks the job as high priority. Triggers SMS to PM and Supervisor.

Fields Inherited from Bid at Job Creation¶

When a bid is approved, the following fields are copied to the new Job:

Bid Field	Job Field
`project_manager`	Initial staff assignment (role: `project_manager`)
`supervisor`	Initial staff assignment (role: `supervisor`)
`escort`	`escort`
`escort_name`	`escort_name`
`po_number`	`po_number`
`permits_list`	`permits_list`
`priority`	`priority`
`materials_status`	`materials_status`
`inspections_status`	`inspections_status`
`expected_completion_date`	`completion_date`

All inherited fields can be updated on the Job after creation.

Status Machine¶

Status	Description	Who Can Set
`Ready to Start`	Job created, awaiting field work to begin.	System (on job creation)
`In Progress`	Work has started.	PM, Supervisor
`Completed / Needs Invoice`	Work is done; invoice has not yet been created.	PM, Owner
`Job Cancelled`	Job was cancelled before or during work. No invoice will be created.	Owner

Ready to Start → In Progress → Completed / Needs Invoice
                             ↘ Job Cancelled (Owner only, any pre-completed state)

Once a job reaches Completed / Needs Invoice, it cannot be moved backward. Transition carefully.

Worker Assignments¶

Jobs support many-to-many worker assignments via the JobWorkerAssignment model.

Workers assigned to a job are Badge Worker role users.
Assignments are managed by the PM or Supervisor.
A worker must have an active account in the same tenant to be assigned.
Workers can see jobs they are assigned to (limited view: status, location, start date).
Assignment history is tracked in the ActivityLog under action type assignment.

Subcontractor Assignments¶

Jobs support multi-select subcontractor assignments via the JobSubcontractor model.

Subcontractors are external parties, tracked by name and contact information.
Use the Subcontractors multi-select in the Job Operations edit panel to assign or remove subcontractors.
Adding or removing a subcontractor is logged in the ActivityLog under action type subcontractor_added.
Subcontractors do not have system accounts — they are informational records only.
The PM manages subcontractor assignments.

The Blocked Flag¶

Setting blocked = true on a job halts progress tracking and triggers notifications.

An SMS is sent to the PM and Owner when a job is blocked.
When the block is cleared, an SMS is sent to the PM.
blocked_reason is required when setting the flag.
Blocked jobs are surfaced as alerts in the dashboard feed.

A blocked job still exists in its current status. Blocking does not change status — it is a separate signal.

The Priority Flag¶

Setting priority = true marks a job as urgent.

Triggers an immediate SMS to the assigned PM and Supervisor.
Priority jobs appear in the dashboard alert panel for the Owner and PM.
Can be toggled by the PM or Owner at any time.

Visibility Rules by Role¶

Role	What They Can See
Owner	All jobs across the tenant.
Project Manager	Jobs where they are the assigned PM.
Accounting	All jobs (read-only).
Supervisor	Jobs where they are the assigned Supervisor.
Badge Worker	Jobs they are explicitly assigned to (limited fields only).

Badge Workers see job status, location, and start date only. They cannot see financial details or bid information.