Entities & What They Require
This is the technical companion to How Everything Connects. Use it when you need to know exactly what fields are required and what prerequisite records must exist.
Site
The root container for everything. A physical building.
| Field | Required? | Notes |
|---|---|---|
| Name | ✅ Yes | Unique within your org |
| Timezone | ✅ Yes | Defaults to America/Chicago if not set |
| Address, City, State, Country | Optional | For display and reporting |
Depends on: Nothing. This is your starting point.
System
A logical grouping of equipment within a site. Examples: HVAC, Refrigeration, Electrical.
| Field | Required? | Notes |
|---|---|---|
| Site | ✅ Yes | Which site this system belongs to |
| Name | ✅ Yes | Unique within the site |
| System type | Optional | Used to match specialized service providers |
Depends on: Site
Space
A named physical area inside a site. Examples: Walk-in Cooler #1, Sales Floor.
| Field | Required? | Notes |
|---|---|---|
| Site | ✅ Yes | Which site this space is in |
| Name | ✅ Yes | Unique within the site |
| Space type | Optional | E.g. cooler, freezer, sales area |
Depends on: Site
Asset (Equipment)
An individual piece of equipment.
| Field | Required? | Notes |
|---|---|---|
| Site | ✅ Yes | Which site |
| System | ✅ Yes | Which system group it belongs to |
| Name | ✅ Yes | Unique within site + system |
| Class | ✅ Yes | Equipment category (from dropdown) |
| Space | Optional | Places the asset in a physical area |
| Asset tag | Optional | QR/barcode identifier for mobile scanning — strongly recommended |
PM Schedule
A recurring maintenance task on a specific asset.
| Field | Required? | Notes |
|---|---|---|
| Asset | ✅ Yes | The specific equipment to maintain |
| Work Order Type | ✅ Yes | Usually Preventive Maintenance or Inspection |
| Frequency | ✅ Yes | Days between occurrences (7, 14, 30, 90, 180, 365, or custom) |
| Next due date | ✅ Yes | When the first task should generate |
| Title | Optional | Auto-generated if blank |
| Service subtype | Optional | E.g. Filter Replacement, Oil Change |
| Assigned service provider | Optional | Pre-fills on WO creation |
Depends on: Asset
Service Provider
A contractor company you hire to do work. Org-level — not tied to a specific site until you grant site access.
| Field | Required? | Notes |
|---|---|---|
| Company name | ✅ Yes | |
| Optional | Company contact | |
| Phone | Optional | |
| System types | Optional | Specialties; used for filtering when assigning |
Depends on: Nothing. Org-level.
Technician
An individual employee of a service provider.
| Field | Required? | Notes |
|---|---|---|
| Service Provider | ✅ Yes | Which company they belong to |
| Name | ✅ Yes | |
| Optional | Must match their Vigil invite email | |
| Phone | Optional |
Depends on: Service Provider
Service Provider Site Access
Grants a service provider permission to work at a specific site. Required before a technician can check in to a job at that site.
| Field | Required? |
|---|---|
| Service Provider | ✅ Yes |
| Site | ✅ Yes |
Depends on: Service Provider + Site
Issue (Event)
A recorded problem.
| Field | Required? | Notes |
|---|---|---|
| Site | ✅ Yes | Auto-derived from asset/space if provided |
| Issue type / title | ✅ Yes | Short description of the problem |
| Severity | ✅ Yes | Low, Medium, High, Critical |
| Start time | ✅ Yes | Auto-set to now |
| Evidence | ✅ Yes | At least one photo, note, or document |
| Asset | Optional (recommended) | The specific piece of equipment |
| Space | Optional | The area of the building |
| Description | Optional | Full detail of the problem |
| Due date | Optional |
At least one of asset, space, or explicit site required as location anchor.
Depends on: Site — asset and space are optional but recommended.
Work Order
An actionable task to resolve something.
| Field | Required? | Notes |
|---|---|---|
| Work Order Type | ✅ Yes | Repair, Replacement, Preventive, Inspection, Diagnostic |
| Origin (exactly one of): | ✅ Yes | See below |
| — Issue | An open Issue | |
| — PM Schedule | An active PM Schedule | |
| — Project | A site Project | |
| — Detection signal | An active Early Warning signal | |
| Service Provider | Optional | Assign on creation or later |
| Due date | Optional | |
| Priority | Optional | Routine, Normal, Urgent, Emergency |
| Notes | Optional | Instructions for the technician |
Site, asset, and space are auto-filled from the origin — you don't set them manually.
Depends on: Site (via origin) + one of Issue / PM Schedule / Project / Detection signal.
Work Order Session
A time-tracked block when a technician works on a job.
| Field | Required? | Notes |
|---|---|---|
| Work Order | ✅ Yes | |
| Check-in time | ✅ Yes | Auto-set when technician checks in |
| Check-out time | Optional | Set when they check out |
| Service Provider | Optional | Auto-filled from WO assignment |
| Session notes | Optional | What the technician did |
| Evidence photos | Optional (may be required by checkout rules) |
Depends on: Work Order
Evidence
A photo, document, or note attached to a record.
| Field | Required? | Notes |
|---|---|---|
| Evidence type | ✅ Yes | photo, pdf, invoice, vendor_record, note, telemetry |
| File / content | ✅ Yes | The actual file or text |
| Captured at | ✅ Yes | Auto-set |
| Link target | ✅ Yes | Must be linked to an issue, asset, or work order session |
Evidence is immutable — it cannot be edited or deleted after creation. This preserves the audit trail.
Depends on: Issue or Asset or Work Order Session
User / Invite
| Field | Required? | Notes |
|---|---|---|
| ✅ Yes | The person's work email | |
| Role | ✅ Yes | See Roles & Permissions |
| Service Provider | Required if SP role | Which contractor company |
| Site access | Optional for org users | Restrict to specific sites; blank = all sites |
Depends on: Service Provider (for SP roles only)