> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/housekeeping/staff-schedule.md).

# Staff schedule

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/staff-schedule.md).
{% endhint %}

The **staff schedule** says who works in housekeeping today. Each day, housekeeping managers put the people on duty on "Today's Schedule", each with a **role** such as "Housekeeper", "Inspector", "Both (Inspector & Housekeeper)" or "Self Checker", and their working hours as **sessions**. Managers set it up on the web; the timeline, the assign sheets in the apps and "Auto Assign Tasks" read it. Only people on today's schedule, in a role that fits the task, can be given housekeeping tasks or set reminders on them.

## Rules

### Who and where

* Only site admins (role "Admin") change the schedule, on a site with housekeeping on and no multi-site selected. Everyone else is sent to Fix, and the API answers "Access denied" ([Staff schedule](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md), [`POST /v1/app/housekeeping/working-hours`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingworking-hours)).
* Until someone is on today's schedule, the page shows "Start Your Day" with "Add Staff" ([Staff schedule](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md#layout)).
* The person picker lists the site's users who are not deleted, without the people already on the schedule ([Inputs](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md#inputs)).

### Sessions

* A session is one block of working time for one person, on one weekday or, with no weekday, every day. The web saves new sessions for today's weekday, so they come back on that weekday each week (web\_app\_v2 @ 0989b8e685, `src/app/pages/housekeeping/timeline-board/timeline-board.component.ts:1514-1526`).
* On the board, ranges snap to 15 minutes, last at least 15 minutes and keep 15 minutes apart; each person keeps at least one range ([Inputs](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md#inputs)).
* A session's end must be after its start, and one person's sessions can't overlap on the same day ([`POST /v1/app/housekeeping/working-hours`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingworking-hours)).
* Session times are the site's local clock times. The web asks for the day by the date of the manager's browser, not the site's date (web\_app\_v2 @ 0989b8e685, `src/app/pages/housekeeping/housekeeping.component.ts:98`).
* Saving replaces all the sessions of each person in the request. Their red tasks today that fitted the old hours but not the new ones lose their assignee, with no warning \[[ASK-93](https://github.com/snapfix/docs/blob/main/ASK.md#ask-93-should-changing-someones-hours-warn-that-tasks-will-be-unassigned)], also on the other sites they work on. Amber and green tasks stay ([`POST /v1/app/housekeeping/working-hours`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingworking-hours)).
* The trash icon ("Delete from On Duty") removes a row at once, with no question; a saved person's sessions are removed on Save, and their red tasks are unassigned in the same way ([Actions](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md#actions)).
* A row for someone outside the site is left out of the save without an error.

### Roles

* Each person has one role, which applies to all their ranges. The API knows six roles; the web names them and what each may take:
  * "Housekeeper": cleans.
  * "Inspector": inspections.
  * "Both (Inspector & Housekeeper)": cleans and inspections.
  * "Self Checker": cleans, and the inspections of their own cleans up to their limit.
  * "House Person": only "Trash and towel" cleans, which a Housekeeper takes when no House Person is on duty.
  * "HK Maintenance": only "Pre Arrival Maintenance Blitz" cleans, which a Housekeeper takes when no HK Maintenance person is on duty (api\_php\_live\_v2 @ ef3c4319f6, `app/Support/Housekeeping/HousePersonAssignment.php`, `app/Support/Housekeeping/MaintenanceAssignment.php`).
* The web offers "Both", "Self Checker", "Housekeeper" and "Inspector"; "House Person" and "HK Maintenance" appear only when the site's clean types use them ([Inputs](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md#inputs)). The sessions table's list of roles lacks those two, so a session with them can be saved with an empty role.
* Each clean type names the roles that may take it ([`GET /v1/app/housekeeping/manual-clean-types`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#get-v1apphousekeepingmanual-clean-types)). A move to a person whose role doesn't fit is refused, with a message that shows as a translation key. "Auto Assign Tasks" prefers fitting roles but doesn't refuse others \[[ASK-92](https://github.com/snapfix/docs/blob/main/ASK.md#ask-92-should-auto-assign-refuse-a-role-that-does-not-fit-as-a-manual-move-does)] ([Assigning housekeeping tasks](https://docs.snapfix.com/product/features/housekeeping/housekeeping-assignment.md)).

### Staff work settings

* Each person has default working hours, which become their first range when they are picked for the schedule; existing ranges don't change ([Staff work settings](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md#staff-work-settings)).
* A self-checker has "Maximum Self-Checked Tasks": the number of their own cleans in a row that they inspect themselves, after which the next clean's inspection goes to another inspector. It must be at least 1. Empty means 3, although the label is marked required. The count starts again each day (api\_php\_live\_v2 @ ef3c4319f6, `app/Support/Housekeeping/HousekeepingSelfCheckerCadence.php:7-30`, `app/Services/Housekeeping/HousekeepingSelfCheckerDayRebuildService.php:439-440`).
* These settings are saved on the person's membership of the site ([`POST /v1/app/housekeeping/staff-work-settings`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingstaff-work-settings)). A person outside the site makes the whole request fail with "Access denied".

### Saving

* "Save" stays off until something changed and every row has a person, a role and a range with a start and an end; nothing says which row is incomplete. After a save, the board switches to the timeline ([States](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md#states)).
* "Cancel", and leaving the Schedule tab, drop unsaved changes without asking ([Actions](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md#actions)).

## Flow

```mermaid
flowchart TD
  open["Site admin: Housekeeping, Schedule tab"] --> empty{"Anyone on today's schedule?"}
  empty -->|no| start["Start Your Day: Add Staff"]
  empty -->|yes| rows["A row per person"]
  start --> rows
  rows --> pick["Pick the person and the role"]
  pick --> ranges["Set working ranges"]
  ranges --> settings["Optional: default hours and self-check limit"]
  ranges --> save{"Every row complete?"}
  save -->|no| ranges
  save -->|yes| saved["Saved: tasks outside the new hours unassigned, timeline opens"]
  saved --> assign["Staff can take tasks"]
```

## Platforms

| Capability                                                | Web                      | iOS                                  | Android                              |
| --------------------------------------------------------- | ------------------------ | ------------------------------------ | ------------------------------------ |
| Build today's schedule                                    | Yes, on the Schedule tab | No                                   | No                                   |
| Set roles, ranges, default hours and the self-check limit | Yes                      | No                                   | No                                   |
| Read who is on duty, their roles and hours                | Timeline and dashboard   | Timeline and the "Assign Task" sheet | Timeline and the "Assign Task" sheet |

## Screens

* [Staff schedule](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md): the Schedule tab, its rows and the staff work settings dialog.
* [Task timeline](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md): the staff rows that read the schedule.
* [Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/dashboard.md): a row per person on the schedule.

## API and data

* [`POST /v1/app/housekeeping/working-hours/list`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingworking-hourslist): the day's staff, sessions and default settings; the web, both apps and Snapfix AI read it. Any signed-in user can read any site's list.
* [`POST /v1/app/housekeeping/working-hours`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingworking-hours): replaces the sessions of the staff in the request.
* [`POST /v1/app/housekeeping/staff-work-settings`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingstaff-work-settings): default hours and the self-check limit.
* [`POST /v1/app/housekeeping/assigned-tasks/list`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingassigned-taskslist): the day's tasks per person, for the red count of tasks outside working hours.
* Tables: [`tPri_User_WorkingHours`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user_workinghours.md) (sessions; replaced ones stay as deleted rows), [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) (`default_start_time`, `default_end_time`, `fSelfCheckerInspectionInterval`), [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md) (assignments removed when hours change).

## Depends on

* [Site users](https://docs.snapfix.com/product/features/console/site-users.md): the people who can be put on the schedule.
* [Assigning housekeeping tasks](https://docs.snapfix.com/product/features/housekeeping/housekeeping-assignment.md): only scheduled people, in a fitting role and within their hours, are offered for tasks.
* [Cleaning tasks](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md) and [Inspections](https://docs.snapfix.com/product/features/housekeeping/inspections.md): the roles that may take each clean type, and the self-checker rule.
* [Housekeeping reports](https://docs.snapfix.com/product/features/housekeeping/housekeeping-reports.md): the dashboard and the printed schedule.
* [Reminders](https://docs.snapfix.com/product/features/notifications/reminders.md): housekeeping reminders are only for people on today's schedule.

## Edge cases

* **Failed load:** the page shows "Start Your Day", as if nobody were scheduled, with the shared error alert and no retry.
* **"Add Staff" on the empty page:** it opens the tab last used, which is the dashboard for a site with no saved tab, so the manager has to pick the Schedule tab.
* **Invalid self-check limit:** 0 or less keeps "Save" off and shows "Start time must be before end time." under the time fields.
* **Overlapping or reversed times:** refused with "The end time must be after the start time." or "New working hour sessions must not overlap for the same day."
* **Near midnight:** a manager in another time zone than the site can see another day's schedule.
* **Settings pages:** pages for roles, staff work, room types and task types exist in the web code, but their routes are commented out and can't be reached ([Staff work settings](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md#staff-work-settings)).
* **Several sites:** each site keeps its own schedule; saving a person's hours on one site can unassign their tasks on another.
* **Offline:** the web needs a connection.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/housekeeping/staff-schedule.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
