> 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/how-the-apps-work/screens/reports/ops-dashboard.md).

# Ops dashboard

{% 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)). Platforms: web. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/reports/ops-dashboard.md).
{% endhint %}

The "Ops Dashboard" tab shows the analytics frame: a separate web app (ops\_dashboard\_fe), served from its own host, that charts tasks, tags, rooms and areas, users, sites and housekeeping, with its own filters, drill-downs, exports and saved views.

![Ops dashboard](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-0bb791506a59f9a6087ab2701fb82d6e7b1d783e%2Fops-dashboard.png?alt=media)

* **Where:** web `/dashboard-reports/ops-dashboard`, the "Ops Dashboard" tab of "Dashboard & Reports". The web page has no title or filter banner of its own on this tab; the frame shows its title "Operational Dashboard" and its filter bar.
* **Who:** the tab shows for role "Admin", unless the site's `taskDashboardEnabled` is 0. The page has no role check, so the route opens for any user who knows it. The analytics API answers only for sites where the user is an admin and the dashboard is on ([Analytics request](https://docs.snapfix.com/engineering-reference/api/reports.md#analytics-request)). How the dashboard is turned on for a site is open \[[ASK-118](https://github.com/snapfix/docs/blob/main/ASK.md#ask-118-how-is-the-ops-dashboard-switched-on-for-a-site)].
* **Feature:** [Ops dashboard](https://docs.snapfix.com/product/features/reports/ops-dashboard.md)

## Layout

The web page is one frame that fills the area below the tabs. It shows the frame when the site's `taskDashboardEnabled` is 1 and the build is a production build; otherwise it shows "Ops Dashboard is not enabled".

**The frame's address.** The web app builds it from its environment: the frame's host, then three query parameters, the site's ID (`parent_uuid`), the user's access token (`jwt`) and the analytics API host (`api_base_url`). The token is in the address. A site change builds the address again.

**What the frame checks.**

* `main.js` reads the three values from the address, or else from window settings that `index.html` can declare. Without a site ID and a token, it replaces the page with "Dashboard Configuration Required".
* It reads the token's payload, without checking its signature or expiry, to name the user in Datadog and in its event log. The API checks the token.
* On a 401 or 403 answer the frame shows its error banner and also sends a `DASHBOARD_AUTH_401` message to the page around it. The web app does not listen for it.
* The frame's event log sends the page address without the query string, so the token does not reach that analytics service. The Datadog set-up keeps the full address, so the token can reach Datadog's page views.
* `embed_test.html` on the same host takes a pasted token and opens the frame with it. The web app does not use it.
* The frame loads D3 and the Datadog scripts from public CDNs without integrity hashes.

**Inside the frame**, top to bottom:

1. The title "Operational Dashboard", the "Saved Views" menu with the number of views used out of the limit (for example "0/5"), and "+ Save View".
2. The filter bar: "Filters", one chip per filter ("Site", "Date", "Fixed range", "Timeframe", more through "Add filter"), "Apply" (off until something changes) and "Clear filters".
3. The tabs "Overview", "Tasks", "Tags", "Rooms and Areas", "Users", "Sites" and "Housekeeping".
4. "Overview": six counters ("Tasks Created", "Tasks Completed", "Overdue Tasks", "New checklist", "Incomplete Checklist", "Completed Checklists"), then the charts "Task Summary" (a donut with a "MANUAL" / "PLANNED" / "TOTAL" table), "Tasks by Group", "Manual vs Planned Tasks" and "Tasks by assigned User". Each chart has an expand button and a menu.
5. "Tasks": a summary table. "Tags", "Rooms and Areas" and "Users": their analytics charts. "Sites": charts per site, with "View data". "Housekeeping": a menu of eight reports: "At a Glance", "Cleaning History", "Cleans by Room Type", "Housekeeper Benchmark", "Inspector Benchmark", "Training Needs", "Activity Log" and "Back to Back Reservations".

## Inputs

The web app passes the three values above. The frame's own filters:

| Field                                                                                                          | Type                                                                                  | Required | Default          | Rules and messages                                                                                                    |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| "Fixed range"                                                                                                  | One of "Last month", "Last 7 days", "Last 90 days", "Last 6 months", "Last 12 months" | No       | "Last month"     | Applies when no dates are entered. Entering dates sets the chip to "Not applied"; choosing a preset clears the dates. |
| "Date"                                                                                                         | From and to dates                                                                     | No       | None ("Any")     | An explicit range; "Any" means no dates are entered, so "Fixed range" applies.                                        |
| "Timeframe"                                                                                                    | "Day", "Week" or "Month"                                                              | No       | "Day"            | How the time series is grouped (`group_by`).                                                                          |
| "Site"                                                                                                         | Sites                                                                                 | No       | The current site | The chip starts on the site the web app passed.                                                                       |
| "Group", "Assigned to", "Created by", "Status", "Overdue", "Priority", "Manual / Planned", "Tag folder", "Tag" | Values of each filter, added through "Add filter"                                     | No       | None             | Nothing selected means all.                                                                                           |

"Apply" sends the changes and "Clear filters" resets them. The requests carry the [Analytics request](https://docs.snapfix.com/engineering-reference/api/reports.md#analytics-request) fields.

## Actions

| Action                                          | Who                         | What happens                                                                                                                                                                                         | API                                                                                                                                                                                                                                                                    |
| ----------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open the Overview, Tasks or Sites tab           | Admins, through the web tab | Loads the main time series for the filters; these tabs draw from it.                                                                                                                                 | [`timeseries`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-apianalyticstimeseries)                                                                                                                                                              |
| Open the Tags tab                               | As above                    | Loads the tags for the chosen tag folder.                                                                                                                                                            | [`tag-analytics`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-apianalyticstag-analytics)                                                                                                                                                        |
| Open the Rooms and Areas tab                    | As above                    | Loads rooms and areas.                                                                                                                                                                               | [`room-area-analytics`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-apianalyticsroom-area-analytics)                                                                                                                                            |
| Open the Users tab                              | As above                    | Loads users.                                                                                                                                                                                         | [`user-analytics`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-apianalyticsuser-analytics)                                                                                                                                                      |
| Click a counter or a chart point                | As above                    | Opens the drill-down with the tasks behind the number.                                                                                                                                               | [`drill-down`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-apianalyticsdrill-down), [`drill-down/export`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-apianalyticsdrill-downexport)                                      |
| Chart menu                                      | As above                    | "Download as JPEG", "Download chart series (CSV)" or "Download task-level data (CSV)".                                                                                                               | None (made in the browser), or the drill-down export for task-level data                                                                                                                                                                                               |
| Expand a chart, or "View data" on a Sites chart | As above                    | Opens the chart, or its data table with export, in a dialog.                                                                                                                                         | None                                                                                                                                                                                                                                                                   |
| Pick a Housekeeping report                      | As above                    | Loads that report.                                                                                                                                                                                   | The `/api/reports/…` endpoints in the [Housekeeping API](https://docs.snapfix.com/engineering-reference/api/housekeeping.md)                                                                                                                                           |
| "+ Save View"                                   | As above                    | Saves the filters, tab states and preferences under a name. Five views per user by default (the server sets the limit); at the limit the button is off and its tooltip says "Maximum views reached". | [`saved-views`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-apianalyticssaved-views)                                                                                                                                                            |
| Open a saved view                               | As above                    | Applies its filters and tab, and records the open (failures are ignored).                                                                                                                            | [`/access`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-apianalyticssaved-viewsview_idaccess)                                                                                                                                                   |
| Star a saved view                               | As above                    | Makes it the default ("Default view").                                                                                                                                                               | [`/default`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-apianalyticssaved-viewsview_iddefault)                                                                                                                                                 |
| Edit or delete a saved view                     | As above                    | Changes or removes it.                                                                                                                                                                               | [`PUT saved-views/{view_id}`](https://docs.snapfix.com/engineering-reference/api/reports.md#put-apianalyticssaved-viewsview_id), [`DELETE saved-views/{view_id}`](https://docs.snapfix.com/engineering-reference/api/reports.md#delete-apianalyticssaved-viewsview_id) |

Saved views belong to the user, not the site ([Saved view object](https://docs.snapfix.com/engineering-reference/api/reports.md#saved-view-object)). On load the frame applies the default view with the tab it saved; without a default it applies the starting filters and opens "Overview".

## States

* **Loading:** the frame shows its own loading state while data loads. The web tab shows nothing of its own: its loading flag is set but never shown.
* **Empty:** charts show their own empty text, such as "No tags available".
* **Error:** the frame shows a banner at the top with the message and a dismiss button, and "Retry" for errors other than sign-in and permission. The messages: "Your session has expired. Please refresh the page to continue." (401), "You do not have permission to access this data." (403), "Data is being prepared. Please wait..." (the frame retries after the server's delay), "Server is busy. Please try again in a moment.", "Too many requests. Please wait before trying again.", "Invalid request. Please check your inputs.", "The requested resource was not found." and "An unexpected error occurred. Please try again.".
* **Missing settings:** without a site ID or token, or without the frame's hosts in the build, the web tab shows an empty area: it sets "Parent UUID is required", "JWT token is required", "Parent UUID and JWT token are required", "Dashboard configuration is missing" or, when the frame fails to load, "Failed to load the dashboard. Please try again.", but never shows them.
* **Not enabled:** "Ops Dashboard is not enabled" on test and local builds, or for a site whose `taskDashboardEnabled` is not 1.
* **No permission:** the API answers 403 "Forbidden." for a site the user does not administer, and "No accessible accounts found" when the user administers no site with the dashboard on; the frame shows its 403 message.
* **Offline (mobile):** not applicable, web only.

## Dialogs and sheets

* **Save view:** titled "Save Current View" for a new view or "Update View" for an existing one. A name ("Enter view name", up to 100 characters; "View name is required" when empty), an optional description ("Optional description", up to 500 characters) and "Set as default view". Buttons "Cancel" and "Save View" (or "Update View").
* **Delete View:** "Are you sure you want to delete ""?" and "This action cannot be undone.", with "Cancel" and "Delete".
* **Drill-down:** the tasks behind a number, with the columns "Job Reference", "Task Title", "Group", "Status", "Priority", "Created By", "Assignee", "Created", "Completed", "Due Date", "Room" and "Area"; a search box, sorting, pages, and CSV and Excel export.
* **View data:** the data table behind a Sites chart, with export.
* **Expanded chart:** a chart in a large dialog.
* **Filter editor:** the popover where each filter is set, and the date pickers for "Date".

## Platform differences

Web only. The apps have no Ops Dashboard. The housekeeping board has its own dashboard ([Housekeeping dashboard](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/dashboard.md)).


---

# 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/how-the-apps-work/screens/reports/ops-dashboard.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.
