> 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/areas-and-rooms.md).

# Areas & rooms

{% 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/rooms/areas-and-rooms.md).
{% endhint %}

Site admins create, edit and delete the site's areas and rooms, and see each room's or area's groups and tasks.

![Areas & rooms](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-5d80f0358657062ebeb45f99be096ed449a8d385%2Fareas-and-rooms.png?alt=media)

* **Where:** web `/account/:id/manage-areas-rooms`, the Site Console tab "Areas & Rooms" ([Site console](https://docs.snapfix.com/how-the-apps-work/screens/console.md))
* **Who:** the tab shows only for the site role "Admin". The route also admits group admins, who can open it by address, and its guard checks the site that is selected, not the one in the address. Without the "Admin" role the page shows only the list: no "Select" button, no "+" button and no detail panel. The API lets any site member create, rename and delete rooms and areas one at a time; who should be allowed is open \[[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)].
* **Feature:** [Rooms and areas](https://docs.snapfix.com/product/features/rooms/rooms-and-areas.md)

The apps have no such page; they rename rooms and areas and edit their texts in [Room info](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-info.md) and [Area info](https://docs.snapfix.com/how-the-apps-work/screens/rooms/area-info.md). Rooms and areas are listed for everyone on [Room tasks](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-tasks.md) and [Areas](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas.md).

## Layout

The page title "Areas & Rooms", then one panel in two columns.

**Left column**, top to bottom:

1. The tabs "Rooms" and "Areas"; only the active tab shows its count, as in "Rooms (122)".
2. The "Search Rooms" or "Search Areas" field and, for admins, a round "+" button. Its tooltip shows a translation key, "ONLY\_EN.ADD\_ROOM" or "AREA.ADD\_AREA", because neither key has English text.
3. The list, 50 items at a time as the user scrolls, one row per room or area with a round icon and the name (area names are translated when the site has translation on). For admins, the first row is selected when the list loads, and "Select Rooms" or "Select Areas" sits at the top right of the panel.

Without the "Admin" role, the list takes the full width.

**Right column** (admins only):

1. The selected room or area: the name, its description and, for a room, its instructions; "Delete Room" or "Delete Area", and "Edit".
2. "Groups", with a "Search Groups" field: the groups whose tasks use this room or area. The first group is chosen on load.
3. "Tasks": the chosen group's tasks that use this room or area, with the red, amber and green counts and a card per task. Above them, the hint "Select a group to see what tasks this room is tagged to." (or "…this area is tagged to.") shows whenever the chosen group has tasks, also on load; it hides only for a group with none.

In selection mode, the list's header shows the count "1 room(s) selected" (or areas), "Select Loaded Rooms" (or "Select Loaded Areas"), "Delete Selected" and a close button.

## Inputs

| Field                                              | Type                | Required              | Default                 | Rules and messages                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------------------------------------- | ------------------- | --------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Search                                             | Text                | No                    | Empty                   | Sent 1 second after the last key release; the server matches as on [Room tasks](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-tasks.md#inputs) and [Areas](https://docs.snapfix.com/how-the-apps-work/screens/rooms/areas.md#inputs). A new search leaves selection mode, clears the selection and reloads the list.                                                                                                                   |
| Tab                                                | Rooms or areas      | No                    | Rooms                   | Changing the tab leaves selection mode and clears the search.                                                                                                                                                                                                                                                                                                                                                                                          |
| Edit room: "Room Number"                           | Text                | Yes                   | The current name        | At most 10 characters; the field stops there. Empty: "Save" turns off, and once the field has been touched it shows "Please enter a room number". A name of only spaces passes the form; the server refuses it with the alert "The name field must be a string."                                                                                                                                                                                       |
| Edit room: "Room Description", "Room Instructions" | Text, several lines | No                    | The current text        | At most 255 characters each.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Edit area: "Area name"                             | Text                | Yes                   | The current name        | At most 255 characters. Empty: "Save" turns off, with "Enter area name". Only spaces: the same server alert as for rooms.                                                                                                                                                                                                                                                                                                                              |
| Edit area: "Area Description (optional)"           | Text                | No                    | The current description | At most 255 characters. The web has no area instructions \[[ASK-86](https://github.com/snapfix/docs/blob/main/ASK.md#ask-86-should-areas-have-instructions-on-the-web)].                                                                                                                                                                                                                                                                               |
| Create rooms: "From", "To"                         | Numbers             | "From": yes; "To": no | Empty                   | Whole numbers are expected, but with "To" empty a decimal such as 1.5 is added and saved as a room. "From" above "To": "The From count cannot be greater than the To count. Please adjust the values before proceeding." More than 500 numbers: "The requested room count exceeds the limit of 500. Please reduce the count before proceeding with generation." Rooms can only be named with numbers here; any other name is set later in "Edit room". |
| Create rooms: total                                | Count               | -                     | -                       | More than 1,000 rooms in the dialog's "Added Rooms": "The total room count cannot exceed the limit of 1000. Please remove some rooms before adding more." The check counts only the rooms staged in this dialog, not the site's rooms. Names that differ from an existing room only in case are created.                                                                                                                                               |
| Create areas: "Area name"                          | Text                | Yes, to add           | Empty                   | Placeholder "e.g Playground". Trimmed; an empty name adds nothing. A name already in the list, ignoring case: "Area already exists in the list." No length limit while adding.                                                                                                                                                                                                                                                                         |
| Create areas: templates                            | Checkboxes          | No                    | Unchecked               | Template names come from the server.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Create areas: upload                               | An .xlsx file       | Yes, to upload        | -                       | At most 10,000 areas: "Maximum of 10000 areas allowed per upload." A file without an "Area Name" column: "Uploaded file does not match the required template format. Please use the correct template."                                                                                                                                                                                                                                                 |
| Create areas: uploaded names                       | Text                | Yes                   | The name from the file  | At most 50 characters. Shorter than 2: "Minimum 2 characters required." A repeat: "Duplicate area name found." These checks don't turn off "Create Areas", and edits to the names are ignored: the names from the file are created.                                                                                                                                                                                                                    |

## Actions

| Action                           | Who                    | What happens                                                                                                                                                                                                                 | API                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open the page or switch tabs     | Anyone who can open it | Loads the first 50 rooms or areas and, for admins, selects the first. The room list also carries each room's statuses, counts and reservation.                                                                               | [`POST /v1/app/rooms/list`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomslist) or [`POST /v1/app/areas/list`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1appareaslist)                                                                                                           |
| Search, load more                | Anyone who can open it | Reloads the list, or loads the next 50 items.                                                                                                                                                                                | As above                                                                                                                                                                                                                                                                                                                               |
| Select a room or area            | Admins                 | Shows its details and loads its groups; the first group is chosen and its tasks load.                                                                                                                                        | [`GET /v1/app/rooms/{uuid}/businesses`](https://docs.snapfix.com/engineering-reference/api/rooms.md#get-v1approomsuuidbusinesses) or [`GET /v1/app/areas/{uuid}/businesses`](https://docs.snapfix.com/engineering-reference/api/rooms.md#get-v1appareasuuidbusinesses)                                                                 |
| Choose a group                   | Admins                 | Lists that group's tasks that use the room or area, with counts.                                                                                                                                                             | [`GET /v1/app/rooms/{uuid}/business/{businessUuid}/jobs`](https://docs.snapfix.com/engineering-reference/api/rooms.md#get-v1approomsuuidbusinessbusinessuuidjobs) or [`GET /v1/app/areas/{uuid}/business/{businessUuid}/jobs`](https://docs.snapfix.com/engineering-reference/api/rooms.md#get-v1appareasuuidbusinessbusinessuuidjobs) |
| "+" on Rooms                     | Admins                 | Opens [Create rooms](#create-rooms).                                                                                                                                                                                         | [`POST /v1/app/rooms`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approoms) on create                                                                                                                                                                                                                          |
| "+" on Areas                     | Admins                 | Opens [Create Areas](#create-areas).                                                                                                                                                                                         | [`GET /v1/app/areas/templates/list`](https://docs.snapfix.com/engineering-reference/api/rooms.md#get-v1appareastemplateslist), then [`POST /v1/app/areas`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1appareas) on create                                                                                      |
| "Edit"                           | Admins                 | Opens "Edit room" or "Edit Area Details".                                                                                                                                                                                    | [`PUT /v1/app/rooms/{uuid}`](https://docs.snapfix.com/engineering-reference/api/rooms.md#put-v1approomsuuid) or [`PUT /v1/app/areas/{uuid}`](https://docs.snapfix.com/engineering-reference/api/rooms.md#put-v1appareasuuid) on save                                                                                                   |
| "Delete Room" or "Delete Area"   | Admins                 | Asks for confirmation, deletes, and selects the next row (or the previous one). 1.5 seconds after the delete, the list drops the row that is selected at that moment, which is another row if the user picked one meanwhile. | [`DELETE /v1/app/rooms/{uuid}`](https://docs.snapfix.com/engineering-reference/api/rooms.md#delete-v1approomsuuid) or [`DELETE /v1/app/areas/{uuid}`](https://docs.snapfix.com/engineering-reference/api/rooms.md#delete-v1appareasuuid)                                                                                               |
| "Select Rooms" or "Select Areas" | Admins                 | Starts selection; clicking rows toggles them; "Select Loaded Rooms" selects the rows loaded so far.                                                                                                                          | None                                                                                                                                                                                                                                                                                                                                   |
| "Delete Selected"                | Admins                 | Asks for confirmation, deletes the selected rows, shows "You've deleted {n} room(s)" (or "area(s)"), leaves selection mode and reloads the list. The server deletes them one query at a time.                                | [`POST /v1/app/rooms/delete/multi`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1approomsdeletemulti) or [`POST /v1/app/areas/delete/multi`](https://docs.snapfix.com/engineering-reference/api/rooms.md#post-v1appareasdeletemulti)                                                                             |

## States

* **Loading:** a spinner in the list, the groups panel and the tasks panel until their data arrives; rows can't be picked while groups or tasks load.
* **Empty:** "No data available" in the list, the groups panel or the tasks panel when it has no rows.
* **Error:** a failed first page leaves "No data available" in the list. A failed save or delete shows the error alert and leaves the item as it was.
* **Saved:** a save or create shows its success state and closes the dialog 1.5 seconds later. An edited room or area shows its new name in the list; new ones appear when the list reloads.
* **No permission:** without the "Admin" role, only the list, with its tabs and search ([Who](#areas--rooms)).

## Dialogs and sheets

### Create rooms

Title "Create rooms", with "1. Use the "Room range" field to create multiple rooms at once.", "2. Generate and review up to 500 entries at a time." and "3. Note: Each Room number will be unique".

1. **Range:** "Room numbers ranging", the "From" and "To" fields (placeholders "E.g. 1" and "E.g. 10") and a round "+" button titled "Create", which is off until the range is valid. "+" fills the step with the numbers from "From" to "To" ("From" alone gives one number), shown as chips with the count "{n} new rooms". Chips can be picked; then "Remove Selected" removes them. "Clear All" (shown as "Cancel", turned off, while the step is empty) empties the step. "Add Room" moves the numbers to "Added Rooms".
2. **Review:** "Added Rooms" with the staged numbers, in pages. With chips picked: "Cancel" and "Remove Selected". Otherwise "Clear All" and "Create Rooms", which sends all of them in one request, shows its success state, closes 1.5 seconds later and reloads the list. Numbers that already exist are skipped by the server, and the dialog says nothing about them.

The dialog closes with its close button; nothing is saved until "Create Rooms".

### Create Areas

Title "Create Areas", with three tabs that build one list: "Pick From Templates", "Create Areas" and "Upload Areas". The footer button "Create Areas" stays off until the list has an area (its fallback alert "Please select, create, or upload at least one area." can't show then). It creates the list in one request, closes 1.5 seconds later and reloads the list. The server skips names that already exist in the site, ignoring case, and says nothing about them.

* **Pick From Templates:** template names with checkboxes; a click on the row or the box toggles it.
* **Create Areas:** the "Area name" field; the round "+" button (titled "Create") or Enter adds the name. Each listed name has a minus button.
* **Upload Areas:** a drop zone, "Drag or drop files here, or click to select files", with "Support file types: .xlsx" written in English in the code, and "Download Template". After a file is read, "Review Uploaded Areas" lists its names as editable fields, with "Clear All" and a remove button per row ([Inputs](#inputs)).

### Edit room

Title "Edit room". The room icon, then "Room Number \*", "Room Description" and "Room Instructions" ([Inputs](#inputs)). "Cancel" and "Save"; "Save" is off while the form is invalid. With no change, "Save" just closes. Otherwise it saves, shows its success state and closes 1.5 seconds later. The save also sends the room's number, description and instructions to analytics with the user's email.

### Edit Area Details

Title "Edit Area Details". The area icon, then "Area name \*" and "Area Description (optional)". Same buttons and rules as "Edit room"; the analytics event carries the area's name and description.

### Delete

* **One item:** title "Delete Room" or "Delete Area", "Delete this room from the site?" or "Delete this area from the site?", and "Cancel" and "Delete Room" or "Delete Area". The message shows stray markup after the question.
* **Several:** "You're about to delete {n} room(s). Do you want to proceed?" (or "area(s)"), with "Cancel" and "Delete Selected".


---

# 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/areas-and-rooms.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.
