Staff — Reference
The Staff surface is the operational-team plane for every SGEN site. It owns the records of internal team members who run the business day-to-day — not the platform operators who hold admin credentials, but the people on the schedule: support agents, fulfillment hands, retail-floor staff, account managers, technicians. Anything that maps a real human to an operational role, a shift, or a customer-facing handle traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a workforce-management workflow. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Staff records live under the Staff module in SG-Admin. The module renders four primary views — the staff list, the staff create / edit form, the shift schedule grid, and the role-mapping editor — and exposes a small set of write operations for create, update, schedule assignment, role mapping, and lifecycle transitions (active / on-leave / inactive).
The module is paired by convention: one half renders the views and prepares the data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
Staff and Users are distinct surfaces and should not be confused. Users carries platform-operator identity — the people who log in to /sg-admin and hold capabilities against the platform. Staff carries operational-role identity — the people whose names appear on a shift, an assignment, or a customer-facing ticket. The two records can be linked (a User record can point to a Staff record when the operator is also on the schedule), but the link is optional and most Staff records do not carry a paired User.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Staff
- URL prefix:
/sg-admin/staff/ - View templates:
application/views/Admin/Staff/
┌────────────────────────────────────────────────────────────────────────────┐│ SG-Admin → Staff [+ Add staff] │├────────────────────────────────────────────────────────────────────────────┤│ Name Operational role Status Next shift ││ ──────────────── ──────────────────── ────────── ───────────────────── ││ Sandra Lim Support — Tier 2 active Mon 09:00 - 17:00 ││ Marcus Tan Fulfillment Lead active Today 14:00 - 22:00 ││ Elena Rivera Account Manager active Tue 10:00 - 18:00 ││ Diego Santos Technician on-leave (returns 2026-06-12) ││ Priya Nair Retail Floor active Today 12:00 - 20:00 ││ ││ [⋯ Edit] [⋯ View schedule] [⋯ Set status] [⋯ Map role] │└────────────────────────────────────────────────────────────────────────────┘Actions
The Staff surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List and filter
Returns the staff records visible to the current operator, paginated, with name, operational role, status, next-shift, and contact columns. Supports column sort, free-text filter across name and role, status filter (active / on-leave / inactive), and per-page count. The next-shift column resolves from the shift schedule surface — staff with no upcoming shift show a blank value rather than a falsy placeholder.
Create staff record
Opens an empty staff form. Required fields at minimum: full name, operational role, status. Optional fields cover contact details (email, phone), preferred working hours, default location, employment type (full-time / part-time / contract), start date, and an optional link to a User record for staff who also log in to /sg-admin. On submit, the surface validates the role against the configured role catalog and persists the record.
Edit staff record
Loads an existing record into the same form shape used for create, pre-populated. Submit replaces the stored record with the posted values; fields left blank do not clear server-side values (the form is partial-update by default). Role changes are validated against the role catalog; an invalid slug is rejected with a structured message naming the missing role.
Set status
Transitions a staff member between active, on-leave, and inactive. Status changes are write-protected behind a confirmation step in the UI but are a single field write at the data layer. On-leave records remain in the default list view (with a leave-end date if supplied); inactive records disappear from the default list and require the inactive filter to surface.
Assign to shift
Adds a staff member to a slot in the shift schedule grid. The schedule surface is rendered as a week view with rows per staff member and columns per day; an assignment is a (staff_id, date, start, end, location) tuple. Conflicts (overlapping shifts, exceeded weekly-hour cap if configured) are flagged at submit time and the assignment is rejected with the conflicting slot named.
Bulk shift import
Accepts a CSV or pasted block of shift assignments and applies them in a single transaction. Each row is validated independently; the surface returns a per-row pass / fail report and applies only the passing rows. Useful for rolling forward a recurring schedule from one week to the next.
Map role
Edits the role catalog itself — adds a new operational role slug, edits a role's display name, or retires a role. Retiring a role that is still assigned to active staff is rejected with a structured message listing the affected records; the operator must reassign first.
Soft delete
Marks the record inactive and detaches it from any future shifts (past shifts remain attributed for audit). Soft-deleted records remain queryable via the inactive filter; their authored content (customer tickets handled, orders fulfilled) remains attributed to the staff record.
Restore
Reverses a soft delete. The record returns to the active list with its prior role and contact details intact. Past shifts remain attributed; future shifts must be reassigned manually.
Data model
A staff record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Stable across edits. |
name | string | Display name. Not unique. |
operational_role | string | Slug from the configured role catalog. See Map role above. |
status | enum | active, on-leave, inactive. |
email | string | Optional. Used for shift notifications when present. |
phone | string | Optional. Used for SMS shift reminders when configured. |
employment_type | enum | full-time, part-time, contract. Optional. |
default_location | string | Optional. Used as the default location on new shift assignments. |
preferred_hours | json | Optional. Per-weekday availability window for schedule-assist hints. |
start_date | date | Optional. First active day. |
leave_end | date | Optional. Set when status transitions to on-leave. |
user_id | integer | Optional. Links to a User record when the staff member also logs in to SG-Admin. Null when no link. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
Shift attribution. Past shifts retain their staff attribution even after the staff record is soft-deleted, on-leave, or has its role remapped. Historical attribution is append-only.
User link. The user_id field is the bridge to the Users surface. When set, the staff member can log in to /sg-admin with that User's credentials and the User's capabilities determine what they see. When null, the staff record exists purely as an operational reference — appearing on schedules and assignments but never as a login identity.
STAFF RECORD├── id integer primary key├── name string display├── operational_role string role catalog slug├── status enum active | on-leave | inactive├── contact email, phone (optional)├── employment_type enum full-time | part-time | contract├── default_location string seed for new shift assignments├── preferred_hours json weekday availability windows├── start_date date first active day├── leave_end date set on on-leave transition├── user_id integer optional link to Users surface└── timestamps created_at, updated_at↓ optional linkUSER RECORD (Users surface)(only when staff also operates SG-Admin)↓ referenced bySHIFT ASSIGNMENT(staff_id, date, start, end, location)Permissions
Access to the Staff surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Staff surface.
Layer 2 — per-action capability. Within SG-Admin, each Staff action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List staff | ✔ | ✔ | ✔ |
| Create staff | ✔ | ✔ | — |
| Edit staff | ✔ | ✔ | — |
| Set status | ✔ | ✔ | — |
| Assign to shift | ✔ | ✔ | — |
| Bulk shift import | ✔ | — | — |
| Edit role catalog | ✔ | — | — |
| Retire role | ✔ | — | — |
| Soft delete | ✔ | — | — |
| Restore | ✔ | — | — |
| Link to User record | ✔ | — | — |
Cross-surface rules. Linking a staff record to a User record (user_id set) is privileged because it grants the staff member a login surface. The action is restricted to Administrators by default and emits an Activity Log entry tagged staff.user_link for downstream review.
Self-edit allowance. A staff member who is also a User (via user_id link) can edit their own contact details and preferred hours without holding the broader edit capability. Status, role, and shift assignments remain gated by capability.
Audit. Every write — create, edit, status change, shift assignment, role-catalog edit, user link, delete, restore — emits an Activity Log entry. The log records the acting operator, the target staff record, and the change shape (field-level diff for edits). Activity Log retention is governed by the site's general settings.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-edit allowance │ staff editing own contact /│ │ preferred hours → permitted└─────────────┬─────────────┘│ resolved▼┌───────────────────────────┐│ Cross-surface guard │ user_id link → admin-only +│ │ staff.user_link audit tag└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entryRelated references
- Users — Reference. Owns operator identity. The
user_idfield on a staff record points here. A Staff record without a linked User has no login surface. - Settings — Reference. Owns the operational-role catalog, the default weekly-hour cap, the SMS shift-reminder provider configuration, and Activity Log retention.
- Shift Schedule — Reference. The week-view grid where shift assignments are authored. Shift rows attribute to staff
id. - Locations — Reference. The
default_locationfield resolves against the configured Locations catalog. - Activity Log — Reference. Source of the staff audit trail. Every write emits an entry; the
staff.user_linktag is the bridge for downstream notification routing. - Notifications — Reference. Shift-reminder notifications resolve through the notification template surface. The default template cites the shift date, start, and location.
- Tickets — Reference. Customer-support tickets carry the handling staff
idfor attribution. Re-attribution applies on staff soft delete.
/docs/staff.