> 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-assignment.md).

# Assigning housekeeping tasks

{% 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-assignment.md).
{% endhint %}

**Assigning** gives a housekeeping task, a [clean](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md) or an [inspection](https://docs.snapfix.com/product/features/housekeeping/inspections.md), a person and a start time today. Housekeeping managers share the day's tasks across the people on the [staff schedule](https://docs.snapfix.com/product/features/housekeeping/staff-schedule.md) on the web timeline: "Auto Assign Tasks" does it for them, or they drag a task onto a person's row, assign or unassign many tasks with "Bulk Actions", and clear the red assignments with "Reset All". In the iOS and Android apps, site admins see the same day as a timeline, and move or assign tasks there.

## Rules

### Who and what

* Assigning one task needs "assign user" in the task's group: its admin, or a member with "assign users" who isn't read-only ([`POST /v1/app/housekeeping/reassignment/{uuid}`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingreassignmentuuid)). The timeline screens are for site admins ([Task timeline](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md)).
* "Auto Assign Tasks" and the resets need a site admin ([`POST /v1/app/housekeeping/auto-assign-tasks-async`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingauto-assign-tasks-async)).
* Only red tasks, not yet started, can be moved or unassigned, on every platform ([Drag and drop](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md#drag-and-drop)).
* A task goes only to a person whose role today fits it; the server refuses other moves, with a message that shows as a translation key. The roles are in [Staff schedule](https://docs.snapfix.com/product/features/housekeeping/staff-schedule.md#roles).
* An assignee who is not in the task's group is added to it as a User ([Common side effects](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#common-side-effects)).
* Each assignment is recorded as made by hand or by "Auto Assign Tasks" ([assigned task object](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#assigned-task-object)).

### Times and working hours

* A move with a start time keeps that time; the server doesn't check it against the person's working hours, and refuses only a task that would run past midnight \[[ASK-95](https://github.com/snapfix/docs/blob/main/ASK.md#ask-95-should-tasks-be-placed-only-inside-the-persons-working-hours)]. A past time becomes now. Android refuses a drop outside the person's shifts on its own ([Platform differences](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md#platform-differences)).
* Without a start time, the server puts each task in the person's first free slot within their working hours, and refuses it when none fits ("Cannot assign job: no free slot after the current time fits this job duration."). Self-checkers are the exception ([`POST /v1/app/housekeeping/bulk-reassignment`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingbulk-reassignment)).
* A person's other tasks move out of the way, so tasks don't overlap. A clean's inspection follows it and starts after the clean ends, within the inspector's working hours, except for self-checkers ([Drag and drop](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md#drag-and-drop)).
* A self-checker's day is rebuilt when their tasks change, so their routine inspections follow their cleans.

### Auto Assign Tasks (web)

* It needs someone on today's schedule; otherwise "No Staff Available" offers "Add Staff" ([Auto assign and reset](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md#auto-assign-and-reset-web)).
* When some tasks were placed by hand, it asks "Do you want to auto-assign manually assigned tasks?": "No" keeps them, with their inspections, and "Yes" reassigns them too.
* It first unassigns today's red tasks of the people on the schedule, except those it keeps, then places the site's unassigned red housekeeping tasks that have a room, cleans before inspections. A task counts as today's when it changed after midnight UTC.
* The plan comes from the assignment provider set on the server, by default an AI provider that receives the tasks (room, floor, type, duration, priority) and the staff (role and shift times) \[[ASK-91](https://github.com/snapfix/docs/blob/main/ASK.md#ask-91-which-auto-assign-provider-runs-in-production-and-may-it-send-data-to-an-ai-service)]. Its rules prefer fitting roles but don'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)]; one rule set keeps a "Both" person from inspecting a clean they cleaned (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/AutoAssign/PromptAlignedJobAssignment/RoleEligibility.php:84`).
* The button reads "Reassign Tasks" when no task is unassigned and some are on the timeline. Tasks that don't fit stay unassigned. The result is "All tasks assigned to staff", "Some tasks are still unassigned. All staff are fully booked for today." with "Add More Staff", or "Failed to auto-assign tasks".
* Despite its name, the run finishes inside the request; the page checks its status every 5 seconds, and the result is kept for an hour. When at least one task was assigned, a silent update goes to the other members of the site's groups, not to the manager who ran it.

### Bulk Actions and resets (web)

* "Bulk Actions" selects red tasks, then "Assign Tasks" gives them to one person or "Unassign All" takes their people off. Replacing assignees asks "Reassign Tasks?" first. The server picks the start times ([Assigned Users](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md#assigned-users-web)).
* One bulk action takes up to 100 tasks, and linked inspections count toward the limit. It runs in the background, one per site at a time, and reports each task that failed with a reason ([`POST /v1/app/housekeeping/bulk-reassignment-async`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingbulk-reassignment-async)).
* "Reset All" takes everyone on today's schedule off their red tasks; a person's "Reset Tasks" does the same for one person. Amber and green tasks keep their people, although the question says all assigned tasks are reset. The reset calls are GET requests that change data. "Reset All" works only on the Timeline tab and isn't marked disabled elsewhere.

### Assigning in the apps

* iOS and Android move a red task by dragging it to a 15-minute slot ([Drag and drop](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md#drag-and-drop)). iOS doesn't check working hours on a drop \[[ASK-95](https://github.com/snapfix/docs/blob/main/ASK.md#ask-95-should-tasks-be-placed-only-inside-the-persons-working-hours)].
* Tapping an unassigned task opens "Assign Task", which lists the people with working hours that day whose role fits. iOS puts the task in the first free gap within the person's hours; Android in the first free time from the task's start, without checking working hours \[[ASK-95](https://github.com/snapfix/docs/blob/main/ASK.md#ask-95-should-tasks-be-placed-only-inside-the-persons-working-hours)] ([Assign Task](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md#assign-task-apps)).
* The apps have no auto-assign, bulk actions or resets \[[ASK-89](https://github.com/snapfix/docs/blob/main/ASK.md#ask-89-which-housekeeping-actions-should-the-mobile-apps-have)].

### Effects of an assignment

* Assigning and unassigning write a line in the task's chat and notify the people assigned or removed, and silent updates tell the other devices to refresh ([Common side effects](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#common-side-effects)).
* The unassigned list shows the site's red housekeeping tasks that nobody is assigned to, that weren't placed by hand, and that have a room ([`POST /v1/app/housekeeping/tasks`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingtasks)).
* Saving the schedule can unassign tasks, so the timeline can change while a manager works on it ([Staff schedule](https://docs.snapfix.com/product/features/housekeeping/staff-schedule.md#sessions)).

## Flow

```mermaid
flowchart TD
  pool["Unassigned: today's red housekeeping tasks"] --> how{"How"}
  how -->|"Auto Assign Tasks"| keep{"Reassign hand-placed tasks?"}
  keep -->|no| kept["Hand-placed tasks stay"]
  keep -->|yes| all["All red tasks of the day go back"]
  kept --> plan["Provider places tasks in staff hours"]
  all --> plan
  how -->|"Drag or tap"| one["One task: a person and a time"]
  how -->|"Bulk Actions"| bulk["Up to 100 tasks: one person, server picks times"]
  one --> check{"Role fits, ends before midnight?"}
  bulk --> check
  check -->|no| refused["Refused"]
  check -->|yes| placed["On the person's timeline"]
  plan --> placed
  plan --> left["Tasks that don't fit stay unassigned"]
  placed -->|"Reset All or Reset Tasks"| pool
```

## Platforms

| Capability                                  | Web                                                                                                          | iOS                  | Android                                  |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------- | ---------------------------------------- |
| See each person's timeline                  | Hour ruler, 5-minute drops                                                                                   | 15-minute slots      | 15-minute grid or list                   |
| Drag a red task to a person and time        | Yes; a past time or a wrong role is ignored with no message                                                  | Yes, with an alert   | Yes, refused outside the person's shifts |
| Assign an unassigned task                   | Drag onto a row, or "Bulk Actions"                                                                           | Tap: "Assign Task"   | Tap: "Assign Task"                       |
| "Auto Assign Tasks", "Bulk Actions", resets | Yes                                                                                                          | No                   | No                                       |
| Create tasks and assign them                | "Create Tasks" dialog                                                                                        | "Create Tasks" sheet | "Create Tasks" sheet                     |
| Print the day's schedule                    | Yes ([Housekeeping reports](https://docs.snapfix.com/product/features/housekeeping/housekeeping-reports.md)) | No                   | No                                       |

## Screens

* [Task timeline](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md): the web Timeline tab, and the apps' Assigned and Unassigned tabs, where assigning happens.
* [Staff schedule](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/schedule.md): who is on duty.

## API and data

* [Housekeeping API](https://docs.snapfix.com/engineering-reference/api/housekeeping.md):
  * [`POST /v1/app/housekeeping/reassignment/{uuid}`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingreassignmentuuid): assign, move or unassign one task; the web, both apps, and the apps' snooze.
  * [`POST /v1/app/housekeeping/bulk-reassignment-async`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingbulk-reassignment-async) and [`POST /v1/app/housekeeping/bulk-reset-async`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingbulk-reset-async), with [`GET /v1/app/housekeeping/bulk-actions/status/{taskId}`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#get-v1apphousekeepingbulk-actionsstatustaskid); the same assignment also runs at once at [`POST /v1/app/housekeeping/bulk-reassignment`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingbulk-reassignment).
  * [`POST /v1/app/housekeeping/auto-assign-tasks-async`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingauto-assign-tasks-async), with [`GET /v1/app/housekeeping/auto-assign-tasks/status/{taskId}`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#get-v1apphousekeepingauto-assign-tasksstatustaskid), which anyone signed in can read with the ID.
  * [`GET /v1/app/housekeeping/reset-tasks-async/{parentUuid}`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#get-v1apphousekeepingreset-tasks-asyncparentuuid) and [`GET /v1/app/housekeeping/reset-user-tasks-async/{userUuid}`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#get-v1apphousekeepingreset-user-tasks-asyncuseruuid).
  * [`POST /v1/app/housekeeping/assigned-tasks/list`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingassigned-taskslist) (each person's tasks) and [`POST /v1/app/housekeeping/tasks`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md#post-v1apphousekeepingtasks) (the unassigned list, with no page limit).
* Tables: [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) (time range, assignment type, pending flag), [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md) (who has each task), [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) (assignment lines), [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) (assignees added to the group), [`tPri_User_WorkingHours`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user_workinghours.md) (sessions).

## Depends on

* [Staff schedule](https://docs.snapfix.com/product/features/housekeeping/staff-schedule.md): who is on duty, in which role and hours.
* [Cleaning tasks](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md) and [Inspections](https://docs.snapfix.com/product/features/housekeeping/inspections.md): the tasks that are assigned.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): the "assign users" permission.
* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md) and [Task chat](https://docs.snapfix.com/product/features/chat/task-chat.md): the task's assignees and the assignment lines.
* [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md): the notices to assignees and the silent updates.
* [Housekeeping reports](https://docs.snapfix.com/product/features/housekeeping/housekeeping-reports.md): the printed schedule.

## Edge cases

* **Nobody on the schedule:** "Auto Assign Tasks" offers "Add Staff"; the apps' "Assign Task" sheet has nobody to offer ("No users with working hours were found." on Android).
* **Everyone fully booked:** the tasks that don't fit stay unassigned.
* **Partly failed bulk run:** "{n} tasks assigned, {m} failed. Review and retry failed tasks."; a run over 5 minutes shows "This is taking longer than expected. The timeline has been refreshed." While it runs, the header buttons are off and dragging is locked.
* **Over 100 tasks:** "You can assign up to 100 tasks at a time. Please select fewer tasks and try again."
* **Refused web move:** the task goes back and the shared alert shows the server's message.
* **Tasks outside working hours:** each person's row on the web shows a red count of them.
* **Time zones:** the unassigned list and auto-assign count the day from midnight UTC, not the site's midnight.
* **Offline:** the timelines need a connection. On Android, people assigned to a housekeeping task on the task screen are placed with the next sync, also after a time offline (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/data/repository/SyncRepository.kt:1240-1252`).
* **iOS planner:** the Housekeeping chip also shows inside a group's planned tasks for account admins.


---

# 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-assignment.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.
