> 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/housekeeping-reports.md).

# Housekeeping reports

{% 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/housekeeping-reports.md).
{% endhint %}

Housekeeping managers follow the day in three places, all on the web. The housekeeping board's **Dashboard** tab shows each person's progress today: completion, total time, and tasks by status and by clean type. The board's print icon makes a PDF of the day's **schedule report**. The [Ops dashboard](https://docs.snapfix.com/product/features/reports/ops-dashboard.md) in "Dashboard & Reports" has a "Housekeeping" tab with eight reports across one or more sites, from "At a Glance" and "Cleaning History" to "Back to Back Reservations". The mobile apps have no housekeeping reports; their timeline shows the day's tasks.

## Rules

### Board dashboard

* The Dashboard tab and the print are for site admins on a site with housekeeping on and no multi-site selected ([Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/dashboard.md)).
* It has a row for each person on today's schedule, also people with no tasks, grouped by the role of their first range today in the order "Both (Inspector & Housekeeper)", "Self Checker", "Inspector", "Housekeeper", "House Person" and "HK Maintenance". An empty group is not shown. With nobody on the schedule, the board shows "Start Your Day" instead ([Layout](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/dashboard.md#layout)).
* Each task counts once. Red tasks are "To do", amber "In Progress" and green "Done"; "Completion" is the done share of the person's tasks, as a whole percentage with "{done} of {total}". Each clean type of the site has its own column ([Layout](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/dashboard.md#layout)).
* "Total Time" is how long the person's started tasks have run, from amber to green or to now, as the server counts it ([staff schedule object](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#staff-schedule-object)).
* The tab only reads today's data. It has no actions, and it ignores the board's filters. The search box above it takes text but doesn't change the rows.
* It refreshes every 60 seconds while visible, reloading the tasks but not the staff list ([Actions](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/dashboard.md#actions)).

### Schedule print

* The print icon in the board's header asks the server for the day's schedule report, which answers at once with the file's address. The page checks the report every 5 seconds, up to 6 times, opens it in a new tab when it is ready, and otherwise shows "Failed to generate report, please try again later." ([Header and bulk actions](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md#header-and-bulk-actions-web), [`?action=user_tasks_schedule_report`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actionuser_tasks_schedule_report)).
* "Today" for the print is the day in the time zone the browser sends, or UTC without one (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/report.functions.php:153-154`).
* It fails with "no user work schedules found for today" or "no tasks assigned to users for today" when there is nothing to print (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/report.functions.php:188`, `:211`).
* The print checks only that the caller is signed in, not that they are an admin of the site, and the PDF is publicly readable.
* It lists every weekday's sessions, one row per person, and picks tasks by their creation date. A "Self Checker", "House Person" or "HK Maintenance" is labelled "NA".

### Ops dashboard reports

* A user sees a site in these reports only when they are its admin and the site has the task dashboard on ([Report scope](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#report-scope)).
* The "Housekeeping" tab lists eight reports: "At a Glance", "Cleaning History", "Cleans by Room Type", "Housekeeper Benchmark", "Inspector Benchmark", "Training Needs", "Activity Log" and "Back to Back Reservations" ([Ops dashboard](https://docs.snapfix.com/how-the-apps-work/screens/reports/ops-dashboard.md#layout)). Inside the last two, the titles read "Room status log" and "B2B guests".
* The reports cover one site, several, or all the user may open. The periods are "Today", "This week", "This month" and "Custom", with presets such as "Yesterday", "Last 7 days", "Last 30 days", "Last month" and "Last quarter"; each site's days are its own time zone's (ops\_dashboard\_fe @ bbb2959b3b, `dashboards/HousekeepingDashboard.js:16-21`, `:421-440`; [Report scope](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#report-scope)).
* "At a Glance" shows eight tiles: total cleans, average clean and inspection time, inspection pass rate, guest and inspector turnaround, cleans finished on a phone, and variance by clean type ([`POST /api/reports/at-a-glance/summary`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportsat-a-glancesummary)).
* "Cleaning History" lists the period's completed cleans with rooms, housekeepers, times and inspection results, with a summary per housekeeper ([`POST /api/reports/cleaning-history/tasks`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportscleaning-historytasks)).
* The benchmarks compare housekeepers and inspectors with their teams. "Training Needs" names the checklist items inspections mark down most once the period has 100 completed cleans. "Activity Log" always covers the last seven days, and "Back to Back Reservations" one day ([Housekeeping API](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportstraining-needs)).
* Six of the eight reports export to CSV; "At a Glance" and "Training Needs" don't (ops\_dashboard\_fe @ bbb2959b3b, `dashboards/HousekeepingDashboard.js:629-637`).

## Flow

```mermaid
flowchart LR
  day["Today's staff and tasks"] --> dash["Board Dashboard tab: a row per person"]
  day --> print["Print icon: schedule report"]
  print --> pdf["PDF opens in a new tab when ready"]
  ops["Ops dashboard, Housekeeping tab"] --> pick["Pick a report, sites and period"]
  pick --> report["Report for the chosen sites"]
```

## Platforms

| Capability                           | Web                             | iOS | Android |
| ------------------------------------ | ------------------------------- | --- | ------- |
| Board dashboard: progress per person | Yes                             | No  | No      |
| Schedule print                       | Yes                             | No  | No      |
| Ops dashboard housekeeping reports   | Yes, in the Ops Dashboard frame | No  | No      |

## Screens

* [Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/dashboard.md): the board's Dashboard tab.
* [Task timeline](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md): the print icon in the board's header, on every tab.
* [Ops dashboard](https://docs.snapfix.com/how-the-apps-work/screens/reports/ops-dashboard.md): the "Housekeeping" tab.

## API and data

* [`POST /v1/app/housekeeping/assigned-tasks/list`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingassigned-taskslist): the rows of the board's dashboard, with the people from [`POST /v1/app/housekeeping/working-hours/list`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingworking-hourslist).
* [`?action=user_tasks_schedule_report`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actionuser_tasks_schedule_report) builds the print, and [`?action=user_reports`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actionuser_reports) reports when it is ready.
* The Ops dashboard reports: [accessible properties](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportsaccessible-properties), [at a glance](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportsat-a-glancesummary), [cleaning history](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportscleaning-historytasks) and its [housekeeper summary](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportscleaning-historyhousekeeper-summary), [cleans by room type](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportscleans-by-room-type), the [housekeeper](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportshousekeeper-benchmark) and [inspector](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportsinspector-benchmark) benchmarks, [training needs](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportstraining-needs), the [room status log](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportsroom-status-log) and [back-to-back guests](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-apireportsb2b-guests). Their shared parameters and errors are in [Report scope](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#report-scope).
* Tables: [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md), [`tPri_User_WorkingHours`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user_workinghours.md), [`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md), [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md), [`tPri_RoomGuestStatus`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_roomgueststatus.md) and [`tPri_RoomGuests`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_roomguests.md).

## Depends on

* [Staff schedule](https://docs.snapfix.com/product/features/housekeeping/staff-schedule.md): the people, their roles and their sessions.
* [Assigning housekeeping tasks](https://docs.snapfix.com/product/features/housekeeping/housekeeping-assignment.md): who has each task.
* [Cleaning tasks](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md) and [Inspections](https://docs.snapfix.com/product/features/housekeeping/inspections.md): what the reports count.
* [Room status](https://docs.snapfix.com/product/features/rooms/room-status.md): the changes in the room status log.
* [Ops dashboard](https://docs.snapfix.com/product/features/reports/ops-dashboard.md): the analytics frame that holds the "Housekeeping" tab. The web app's own [Dashboard](https://docs.snapfix.com/product/features/reports/dashboard.md) is a different feature.

## Edge cases

* **Nobody on duty:** the board shows "Start Your Day" instead of the dashboard; "No data available" shows when the table has no row ([Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/dashboard.md#states)).
* **Failed staff load:** the board shows "Start Your Day" with the shared error alert.
* **Slow loads:** on the QA site the lists behind the board took 1.5 to 2.8 seconds.
* **Training Needs below 100 cleans:** it shows only how far the period is from the threshold. With `dummy` in the dashboard's address it shows made-up results \[[ASK-94](https://github.com/snapfix/docs/blob/main/ASK.md#ask-94-should-dummy1-show-invented-training-needs-data-in-production)].
* **Bad period:** some report routes answer "500" with the error text instead of "400", and errors carry the exception's text.
* **Sites without the task dashboard:** they are not offered, and the server refuses their reports ([Report scope](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#report-scope)).
* **Offline:** every report 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/housekeeping-reports.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.
