> 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/rooms/room-status.md).

# Room status

{% 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, iOS and Android. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/rooms/room-status.md).
{% endhint %}

The status and priority of every room, with reservation details; people change one room or several at once, and filter rooms by status and priority.

![Room status](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-6266c16f56a7992a980db4b4edfe519628bf6105%2Froom-status.png?alt=media)

* **Where:** web `/fix/rooms`, the Fix page's "Rooms" tab on its "ROOM STATUS" option (shown as "Room Status (122)"); iOS: Fix > "Room Status"; Android: the Fix tab's "Room Tasks" chip tapped again, which turns [Room tasks](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-tasks.md) into "Room Status (N)"
* **Who:** any signed-in member of the selected site. No screen checks a role for status or priority changes, and the API checks only site membership for them \[[ASK-81](https://github.com/snapfix/docs/blob/main/ASK.md#ask-81-who-may-create-rename-and-delete-rooms-and-areas-and-change-their-priority-and-status)]. No setting stops changes by hand: the building's "manual room status" flag is stored but nothing reads it \[[ASK-84](https://github.com/snapfix/docs/blob/main/ASK.md#ask-84-what-should-the-building-setting-manual-room-status-do)].
* **Feature:** [Room status](https://docs.snapfix.com/product/features/rooms/room-status.md); statuses can also come from a property management system ([PMS integrations](https://docs.snapfix.com/product/features/integrations/pms-integrations.md))

The "Room tasks" card in a room's dialog or sheet opens [Room](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room.md).

## Layout

**Web.** While nothing is selected, a row holds the filter button (marked while a filter applies), the "Search Rooms" field and an actions menu ("⋯") with one item, "Select Rooms". Below is a grid of room cards, loaded as the user scrolls, with the same page size as [Room tasks](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-tasks.md#layout). Each card:

* is tinted by its main status's colour, or by the secondary status's when the main one has none; only red, amber and green statuses tint a card;
* shows a priority star with its number ("1" high, "2" medium) when the room has a priority;
* shows the room name, cut at 10 characters, and the main and secondary status names in capitals with their icons, separated by a bar.

After "Select Rooms", the row becomes a selection bar: a "Select All Room" menu ("Select Loaded Rooms" or "Select All Rooms"), the count "1 Room(s) Selected", "Changes Priority", "Changes Status" (both off while nothing is selected) and a close button. Clicking a card toggles it; after "Select All Rooms", cards can't be toggled.

**iOS:** a filter button, a search button and a grid of two cards per row with the same content. A long press of half a second on a card starts selection: the top bar and the tab bar hide, and a toolbar shows select all, priority, status and close controls. Tapping a card then toggles it.

**Android:** the "Room Status (N)" chip, a filter icon and a search icon. The cards show a priority badge, the room name, the time the room last changed, and the main and secondary statuses. A long press starts selection: a bar shows select all, "1 Room selected" or "N Rooms selected", a priority button, a status button and a cancel button.

The tab, button or chip shows the room count, or "(shown / total)" while a filter or search narrows the list, for example "Room Status (101 / 122)" on the web and "(3/12)" on iOS.

## Inputs

| Field                       | Type                                               | Required | Default                            | Rules and messages                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------------------------- | -------------------------------------------------- | -------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search                      | Text                                               | No       | Web: the last search for this site | Web: the server search of [Room tasks](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-tasks.md#inputs), sent 1 second after the last key release. iOS and Android: the rooms on the device, by room name or status name.                                                                                                                                                                                    |
| Filter: priority            | "1" (high) and "2" (medium)                        | No       | None                               | Any of the two.                                                                                                                                                                                                                                                                                                                                                                                                            |
| Filter: status              | The site's main and secondary statuses, by section | No       | None                               | Web: the "Room Status" part of the drawer, one group per section of the site's catalogue.                                                                                                                                                                                                                                                                                                                                  |
| Priority (one room)         | Two stars, 1 and 2                                 | No       | The room's priority                | Choosing the set star again clears the priority. Only high and medium are offered on every platform; the API knows more levels ([Rooms API](https://docs.snapfix.com/engineering-reference/api/rooms.md#rooms-api)).                                                                                                                                                                                                       |
| Main status (one room)      | One status from the site's sections                | No       | The room's main status             | A read-only status is shown but can't be chosen. Choosing the selected status again does nothing.                                                                                                                                                                                                                                                                                                                          |
| Secondary status (one room) | One status from the secondary sections             | No       | The room's secondary status        | Web: only once a main status is chosen; otherwise the alert "Please select a main status first before selecting a secondary status". The apps allow it alone. Once set, a secondary status can be replaced but not cleared: no picker deselects it, and the server keeps it when none is sent \[[ASK-87](https://github.com/snapfix/docs/blob/main/ASK.md#ask-87-should-staff-be-able-to-clear-a-rooms-secondary-status)]. |
| Priority (several rooms)    | High or medium                                     | No       | None                               | Web: "Ok" with nothing chosen closes the dialog with no change. Android applies priority 0 instead.                                                                                                                                                                                                                                                                                                                        |
| Status (several rooms)      | Statuses by section                                | No       | None                               | Web: a main status, a secondary status, or both. iOS and Android: one status.                                                                                                                                                                                                                                                                                                                                              |

## Actions

| Action                 | Who    | What happens                                                                                                                                                                                                                                                                   | API                                                                                                                                                                                                                                                                                                                         |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open the list (web)    | Anyone | Loads the first page of rooms with their statuses, task counts and reservations, with the search and filters, then checks for new tasks.                                                                                                                                       | [`POST /v1/app/rooms/list`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomslist), [`POST /v1/app/rooms/get-updates`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomsget-updates)                                                                                    |
| Filter (web)           | Anyone | The drawer loads the site's status sections. The drawer and the room status dialog's status picker share one copy per site until the page reloads, so only the first of them sends the request. "Apply" filters on the server; the filters are kept per site in the browser.   | [`GET /v1/app/parents/{uuid}/room-statuses`](https://docs.snapfix.com/engineering-reference/api/rooms.md#get-v1appparentsuuidroom-statuses); [`POST /v1/app/rooms/list`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomslist) with `priorityLevel`, `status` and `statusSecondary`              |
| Filter (apps)          | Anyone | Filters the device copy. iOS keeps the choice per site on the device.                                                                                                                                                                                                          | None                                                                                                                                                                                                                                                                                                                        |
| Open one room          | Anyone | Web: opens the room status dialog, which loads the room. iOS and Android: open the room status sheet from the device copy.                                                                                                                                                     | Web: [`GET /v1/app/rooms/{uuid}`](https://docs.snapfix.com/engineering-reference/api/rooms.md#get-v1approomsuuid), and the status sections as above                                                                                                                                                                         |
| Save one room (web)    | Anyone | "Save" with no change closes the dialog with no request. Otherwise it sends the changed priority and the changed status at the same time, shows a message for each change the server accepted, and closes 1.5 seconds later. A refused change also closes the dialog as saved. | [`PUT /v1/app/rooms/{uuid}`](https://docs.snapfix.com/engineering-reference/api/rooms.md#put-v1approomsuuid) with `priority`; [`PUT /v1/app/rooms/{uuid}/status`](https://docs.snapfix.com/engineering-reference/api/rooms.md#put-v1approomsuuidstatus)                                                                     |
| Change one room (apps) | Anyone | A tap on a status saves it on the device and closes the sheet; the room's other status is kept. iOS saves a priority when the sheet closes; Android saves it on the tap.                                                                                                       | Device, then the sync: [`?action=save_pri_room`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-actionsave_pri_room) and [`?action=save_pri_log_roomstatuschange`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-actionsave_pri_log_roomstatuschange)                                  |
| Select rooms           | Anyone | Web: "Select Rooms". iOS and Android: a long press on a card.                                                                                                                                                                                                                  | None                                                                                                                                                                                                                                                                                                                        |
| Select all             | Anyone | Web: "Select Loaded Rooms" selects the loaded cards; "Select All Rooms" makes the change apply to every room that matches the search and filters, loaded or not. iOS and Android: every card on the screen.                                                                    | None                                                                                                                                                                                                                                                                                                                        |
| "Changes Priority"     | Anyone | Opens the priority dialog or sheet ([Dialogs and sheets](#dialogs-and-sheets)).                                                                                                                                                                                                | Web: [`POST /v1/app/rooms/priority/multi`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomsprioritymulti), or [`POST /v1/app/rooms/priority/all`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomspriorityall) after "Select All Rooms". Apps: device, then the sync. |
| "Changes Status"       | Anyone | Opens the status dialog or sheet.                                                                                                                                                                                                                                              | Web: [`POST /v1/app/rooms/status/multi`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomsstatusmulti), or [`POST /v1/app/rooms/status/all`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomsstatusall) after "Select All Rooms". Apps: device, then the sync.         |

What else a status change does depends on where it is made: web changes may create an inspection and reach every PMS the building uses; app changes reach the PMS the room is mapped to and create no inspection; neither creates cleaning tasks \[[ASK-83](https://github.com/snapfix/docs/blob/main/ASK.md#ask-83-which-room-status-changes-should-create-inspections-and-cleaning-tasks-and-reach-the-pms)]. [Status change side effects](https://docs.snapfix.com/engineering-reference/api/rooms.md#status-change-side-effects) has the details.

## States

* **Loading:** web: skeleton cards until the first page arrives; the room dialog shows a spinner until its room arrives. iOS and Android show the device copy at once.
* **Empty:** web: the placeholder of [Room tasks](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-tasks.md#layout), which talks about tasks, not statuses; a search or filter that matches nothing shows it too. The apps show their empty rooms view.
* **Error:** web: the list request shows no error; a failed first page leaves the placeholder and the tab reads "Room Status (Undefined)". If the dialog can't load its room, it closes. A refused single-room save closes the dialog as saved, and the card shows the new values until the next load. A refused bulk change shows the error alert and keeps its dialog open.
* **Read-only status:** shown on the cards, dialogs and sheets, but it can't be chosen on the web, on Android or in the iOS single-room sheet. The iOS multi-select sheet doesn't check it.
* **No permission:** none in the screen ([Who](#room-status)).
* **Offline (mobile):** changes are saved on the device and the sync sends them when the device is online ([shared behavior](https://docs.snapfix.com/how-the-apps-work/shared.md)).

## Dialogs and sheets

### Room status (web)

Opened by a click on a card. Title "Room status", with the text "Update Room Priority / Status".

* **Priority:** two stars, 1 and 2, under "Priority".
* **Room card:** the room name, "Room tasks" and the red, amber and green counts in full (the list shows "99+" above 99). A click opens [Room](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room.md) and closes the dialog.
* **Reservation:** when the room has a reservation, the reservation card of [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#layout), collapsed at first, with the room number, floor, occupancy and capacity ([reservation object](https://docs.snapfix.com/engineering-reference/api/rooms.md#reservation-object)).
* **Statuses:** the site's sections (on the QA site "Cleaning Status" and "Operation Status") with their main and secondary statuses.
* **Buttons:** "Cancel" and "Save". Messages: "You've updated {room} to {status}", "You've updated {room} to {main} and {secondary}" when both changed, "You've set high priority for {room}", "You've set medium priority for {room}" and "You've removed priority for {room}".

### Room status (iOS)

Opened by a tap on a card. A sheet with the room name and counts, the high and medium stars with an info button, the room card (opens [Room](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room.md)), the reservation card, which expands and collapses, and the statuses by section. A tap on a status saves it and closes the sheet; a read-only status does nothing. A tap on a star toggles it, and closing the sheet saves it. The messages are written in English in the code: "You’ve removed priority for {room}", "You’ve set high priority for {room}", "You’ve set medium priority for {room}", and, after a status change, "You’ve updated {room} to {status}", with a double space. After a main-status change that message names the room's secondary status, or shows nothing when the room has none.

In selection mode the same sheet has the header "Changes Status" with the count, holds one status at a time (a main status or a secondary status, so picking one clears the other), and has "Cancel" and "OK"; "OK" turns on once a status is chosen.

### Room status (Android)

Opened by a tap on a card. A sheet titled "Room Status", with "Update Room Priority / Status", the room name and counts, the high and medium priority cards with an info button, the reservation card (open when the room has a reservation), the statuses by category and the "ROOM TASKS" card, which opens [Room](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room.md). A tap on a priority card sets it, and a tap on the set card removes it. A tap on a status saves it and closes the sheet. Messages: "You've set high priority for %s", "You've set medium priority for %s", "You’ve removed priority for %s" and "You've updated %s to %s". That message names the new status, except when the new status takes the room out of the current filter: it then names the old one.

### Priority of several rooms

* **Web:** the dialog "Priority" with "Set priority for {n} room(s)", the stars "1 High Priority" and "2 Medium Priority", and "Remove priority" and "Ok". Messages: "You've set {n} room(s) as High Priority", "You've set {n} room(s) as Medium Priority", and after a removal the single-room text with the count, "You've removed priority for {n}".
* **iOS:** the sheet "Priority" with "Set Priority :" and the count, the two stars, "Apply" (on once a star is chosen) and "Remove Priority".
* **Android:** the sheet "Priority" with "set Priority" and the count, two star cards, "Remove Priority" and "Apply". "Apply" is always on; with no star chosen it writes priority 0 to every selected room, with no message.

### Status of several rooms

* **Web:** the dialog "Room status" with "Update status for {n} room(s)", the statuses by section, and "Cancel" and "Ok". A secondary status needs a main status first, and both are sent together. Rooms that already have the chosen main status are skipped, also for the secondary status, and the count leaves them out. Messages: "You've updated {n} room(s) to {status} status", or "You've updated {n} room(s) to {main} and {secondary}".
* **iOS:** the selection-mode sheet above, with one status. Message: "You've updated %@ to %@", with the selected-room count and the status.
* **Android:** the sheet "Room Status" with "Change Status" and the count, the statuses by category, and "Cancel" and "Apply". One status is set. Message: "You’ve updated {n} rooms to {status}".

### Filter

* **Web:** the "Filters" drawer with "Priority" and "Room Status" (one group per status section). "Apply" turns on once something is chosen, applies it and closes the drawer. "Clear Filters" clears the filters at once and closes the drawer.
* **iOS:** the room filter sheet with the two stars and the status sections; the choice is saved per site on the device.
* **Android:** the "Filters" sheet with "Priority", the status list, "Clear Filters" and "Apply"; the filter icon changes while a filter applies. The layout also holds a side filter drawer that nothing opens.

## Platform differences

| Topic                           | Web                               | iOS                                             | Android                                  |
| ------------------------------- | --------------------------------- | ----------------------------------------------- | ---------------------------------------- |
| Where                           | Another option of the "Rooms" tab | Another view, same Fix button                   | The same screen as Room tasks, same chip |
| One room                        | Pick, then "Save"                 | A tap saves the status; the star saves on close | A tap saves                              |
| Secondary without a main status | Refused                           | Allowed                                         | Allowed                                  |
| Several rooms, status           | Main and secondary together       | One of them                                     | One of them                              |
| Where a change goes             | The room routes                   | The device, then the sync                       | The device, then the sync                |
| Search                          | On the server                     | On the device, also status names                | On the device, also status names         |
| Single-room messages            | From the language file            | Written in the code                             | From the string file                     |

Android also has a separate room status screen (`RoomStatusFragment`) on the Track tab, which is hidden in both bottom bars; it opens only when the app restores Track as the last tab \[[ASK-10](https://github.com/snapfix/docs/blob/main/ASK.md#ask-10-which-differences-between-the-ios-and-android-apps-are-intended)].


---

# 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/rooms/room-status.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.
