> 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/tasks/pick-group.md).

# Add task to a group

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

Choose the group a new task goes into. The app then asks for anything the group requires, saves the task on the phone, opens it, and uploads it in the background.

* **Where:** iOS and Android: after [Photo edit and name](https://docs.snapfix.com/how-the-apps-work/screens/tasks/photo-edit.md), [Text or sketch task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/text-task.md) or [Voice task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/voice-task.md), when the task was started from Home ("Snap", the "+" menu, the iOS quick action); iOS also as a sheet for tasks started from a room or an area
* **Who:** members of at least one task group on the current site; see [Who can add a task to which group](#who-can-add-a-task-to-which-group)
* **Feature:** [Creating tasks](https://docs.snapfix.com/product/features/tasks/task-creation.md)

Tasks started inside a group skip this screen; the group screen saves them ([Group tasks](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md)). The first task right after setup uses [First task group](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/first-task.md) instead.

| Flow                                   | iOS                                      | Android                                                                                                        |
| -------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Photo, video, sketch or text from Home | `GuideAddUserSelectGroupVC`, full screen | `SelectGroupActivity` with `GroupSelectFragment`, full screen                                                  |
| Voice task from Home                   | `GuideAddUserSelectGroupVC`, full screen | `RoomGroupSelectionBottomSheet`, a sheet                                                                       |
| Task from a room or an area            | `SelectGroupVC`, a sheet                 | the room or area screen ([Room tasks](https://docs.snapfix.com/how-the-apps-work/screens/rooms/room-tasks.md)) |

## Who can add a task to which group

* The list holds only the task groups of the current site where the user is a member ([`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md)). Asset registers have their own flow and are left out. Being a site admin (role "Admin") adds no groups and no rights here.
* Multi-site users see the current site's groups only; to add a task elsewhere they switch site first ([Site switcher](https://docs.snapfix.com/how-the-apps-work/screens/groups/site-switcher.md)).
* Inactive groups: the iOS full screen leaves them out; the iOS sheet and Android list them, dimmed, and they cannot be picked.
* Creating needs the group role "Admin" (group admin) or the group permission `perJobCreateNew`. Members whose status in the group is inactive are refused.
* When the group requires an assignee, the user also needs the group permission `perAssignUser`, or must be a group admin.
* When the site's plan has no new tasks left, the task cannot be added (see [Task limit banner](#task-limit-banner)).

## Layout

**Full screen (`GuideAddUserSelectGroupVC`, `SelectGroupActivity`)**

* **Top bar:** back, and the title "Add task to a group" (asset registers: "Add asset to an asset register"). A close button exists on both but is hidden.
* **Search field:** "Search Group" (Android "Search group").
* **Heading:** "Select a group" (asset registers: "Select an asset register").
* **Group list:** each row shows the group's image, name and address, and a check mark or radio button. Groups that Snapfix AI suggests carry an AI badge and move to the top.
* **Task limit banner:** hidden until needed (see [Task limit banner](#task-limit-banner)).
* **Bottom bar:** "Cancel" and "Save". "Save" stays disabled until a group is picked. A "Create a New Group" button exists on both but is hidden.

**Sheets (iOS `SelectGroupVC`, Android `RoomGroupSelectionBottomSheet`)**

* The title "Add task to a group"; Android adds a close button.
* A search field ("Search" on iOS, "Search group" on Android), the group list, "Cancel" and "Save". The iOS sheet can be dragged down or closed by tapping outside it; the Android sheet opens fully expanded.

## Inputs

| Field  | Type          | Required | Default                                                                             | Rules and messages                                                                                                                      |
| ------ | ------------- | -------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Search | text          | no       | empty                                                                               | Filters as the user types. iOS matches name and address, Android the name only. The iOS field has a clear button                        |
| Group  | single choice | yes      | the first AI-suggested group, if any; on the sheets a group passed in by the caller | Tapping a picked row on iOS unpicks it. On the iOS full screen "Save" then answers "Select a group"; elsewhere "Save" is disabled again |

## Actions

| Action              | Who                                           | What happens                                                                                                                                                                                                                                                                                                                                       | API                                                                                                                                                                                           |
| ------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pick a group        | anyone here                                   | Marks the row and enables "Save"                                                                                                                                                                                                                                                                                                                   | none                                                                                                                                                                                          |
| "Save"              | see [Who](#who-can-add-a-task-to-which-group) | Runs the checks below, then saves the task                                                                                                                                                                                                                                                                                                         | see [Saving the task](#saving-the-task)                                                                                                                                                       |
| Back, "Cancel"      | anyone here                                   | iOS: back to the [Camera](https://docs.snapfix.com/how-the-apps-work/screens/tasks/camera.md), or to Home for a voice task; the photo or recording is dropped. Android full screen: closes and opens a fresh [Camera](https://docs.snapfix.com/how-the-apps-work/screens/tasks/camera.md). Android sheet and iOS sheet: close; the task is dropped | none                                                                                                                                                                                          |
| AI group suggestion | automatic                                     | See [AI group suggestion](#ai-group-suggestion)                                                                                                                                                                                                                                                                                                    | Android [`POST /v1/app/tasks/suggestions/group`](https://docs.snapfix.com/engineering-reference/api/ai.md); iOS the endpoint named `tasks-group-suggestion` in the endpoint list it downloads |

**Checks on "Save", in order**

1. Task limit: when the site has no new tasks left, the [Task limit banner](#task-limit-banner) appears and nothing else happens. The iOS sheet and the Android sheet skip this check.
2. Membership: an inactive member gets "You are inactive in this group. Reach out to the group admin to review your status." (Android ends with "your position."); the iOS sheet shows the permission message below instead.
3. Permission: without the group role "Admin" or `perJobCreateNew`: iOS full screen "You don’t have the right permissions to create task in this group. Reach out to the group admin to review your permissions."; iOS sheet and Android "You don’t have the permission to create task in this group. Reach out to the group admin to review your permission."
4. Required details: when the group requires tags, an assignee, an asset, a room or an area, [Tag your task](#tag-your-task) opens. Android first checks the assignee rule: a user who may not assign gets "To create a task, you need to assign a user to it. However, you do not have permission to assign users. Please contact your administrator for assistance." and stays on the list. iOS shows the same text only when the user submits the dialog. On the iOS sheet the check reads the group's old per-slot tag flags instead of its mandatory tag folders, so a group whose only requirement is a mandatory tag folder gets no dialog.
5. Asset registers: [Asset attributes](https://docs.snapfix.com/how-the-apps-work/screens/assets/asset-attributes.md) opens when the register has attributes to fill in.
6. Location: when the group asks to confirm the task location (`fJobLocationConfirm`), [Set the task location](#set-the-task-location) opens.
7. The task is saved, and the app opens it ([Saving the task](#saving-the-task)).

### AI group suggestion

When the site has AI suggestions on (`fAiSuggestionEnabled` in the site settings) and the task has an image, the app sends the image and the name to Snapfix AI as soon as the list loads. The groups that come back get the AI badge and move to the top; the first is picked unless the user already picked one. The task records whether the chosen group was suggested (`business_aiSuggested`), and the app logs suggestion and choice ([`?action=save_ai_job_log`](https://docs.snapfix.com/engineering-reference/api/ai.md)). Failures are silent. Both apps ask only for photo tasks, not for videos, sketches, text or voice tasks. On Android a suggestion that arrives while the search field holds text can crash the screen or garble the list.

## Saving the task

The apps save everything on the phone first and upload it later; nothing waits for the network. Shared upload and sync behavior belongs in [Shared behavior](https://docs.snapfix.com/how-the-apps-work/shared.md).

### What the app stores

The task ([`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md)):

| Field                                           | Value                                                                                                                                                                                                                                                                                           |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                          | made on the phone                                                                                                                                                                                                                                                                               |
| `uuid_tBusiness`                                | the chosen group                                                                                                                                                                                                                                                                                |
| `uuid_tUserBusiness`                            | the creator's membership in that group                                                                                                                                                                                                                                                          |
| `uuid_tStatus`, `uuid_tStatusSub`, `color`      | the group's status `Red` and sub-status `New`, and `color` `red` (asset registers: `Green`)                                                                                                                                                                                                     |
| `fTitle`                                        | the name, see [Photo edit and name](https://docs.snapfix.com/how-the-apps-work/screens/tasks/photo-edit.md), [Text or sketch task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/text-task.md), [Voice task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/voice-task.md) |
| `fLargeTextTitle`                               | the large text of text, sketch and voice tasks                                                                                                                                                                                                                                                  |
| `fImage`                                        | the image's file name on the phone, replaced by its web address once uploaded                                                                                                                                                                                                                   |
| `fVideoHeader`                                  | 1 for video tasks                                                                                                                                                                                                                                                                               |
| `fLat`, `fLng`                                  | iOS: the position read before the camera opened; Android: the last known position when saving; or the position chosen in [Set the task location](#set-the-task-location); 0,0 when none                                                                                                         |
| `fJobReference`                                 | the last six digits of the creation time                                                                                                                                                                                                                                                        |
| `fCreatedTs`, `fModifiedTs`, `fJobTs`, `fRedTs` | the phone's clock at creation                                                                                                                                                                                                                                                                   |
| `fPriorityNumber`                               | 1000                                                                                                                                                                                                                                                                                            |
| `enum_JobType`                                  | 201 to 206 by how the task started, 41 for voice ([`enum_JobType`](https://docs.snapfix.com/engineering-reference/db/tables/enum_jobtype.md))                                                                                                                                                   |
| `title_aiSuggested`, `business_aiSuggested`     | 1 when the name or the group came from Snapfix AI                                                                                                                                                                                                                                               |
| `enum_Origin`                                   | added at upload while the task is unchanged since creation: 1 Android, 2 iOS                                                                                                                                                                                                                    |

Linked records: the creator as a task user ([`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md)); the "Created task" chat item; a video message for video tasks, a voice message for voice tasks; and whatever [Tag your task](#tag-your-task) collected: tags, assignees, linked assets, rooms and areas, each with its own chat item ("added: …", "assigned …"). iOS also links the room or area the task was started from.

### Upload

A background sync sends the queue when there is a connection. iOS starts it right after saving, when the app becomes active, when the network comes back, and as a background task that the system may run from a minute after the app goes to the background. Android queues a background job that waits for a connection.

1. **Media first.** The task image goes to [`?action=save_image`](https://docs.snapfix.com/engineering-reference/api/files.md) (multipart field `uploaded_file`; the answer carries `image_url`). Videos go to [`?action=save_video`](https://docs.snapfix.com/engineering-reference/api/files.md) (the answer carries `data.video_url`), plus their thumbnail through `save_image`. Voice recordings not already uploaded by the voice flow go to [`?action=save_document`](https://docs.snapfix.com/engineering-reference/api/files.md) (`doc_url`). Each web address then replaces the local file name in the task or chat item, which is queued again. A task with an image, saved through this screen, waits until the image has a web address, so the server never sees the local file name.
2. **Records**, as JSON `{"insert_data": [ … ]}` in batches of up to 500 rows per table, with the user's bearer token. The task goes first, through [`POST ?action=save_pri_job`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job). Its linked records follow: the task user through [`POST ?action=save_pri_job_user`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job_user), tags through [`?action=save_pri_job_tag`](https://docs.snapfix.com/engineering-reference/api/tags.md), chat items through [`?action=save_pri_job_chat`](https://docs.snapfix.com/engineering-reference/api/chat.md), assignees through [`POST ?action=save_pri_job_userassigned`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job_userassigned), linked assets through [`POST ?action=save_pri_jobjoblink`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_jobjoblink), rooms through [`POST ?action=save_pri_job_room`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job_room), areas through [`POST ?action=save_pri_job_area`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job_area), and the AI log through [`?action=save_ai_job_log`](https://docs.snapfix.com/engineering-reference/api/ai.md). iOS also logs that the creator viewed the group and the task ([`POST ?action=save_pri_log_businessvieweduser`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_log_businessvieweduser), [`POST ?action=save_pri_log_jobvieweduser`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_log_jobvieweduser)). The server answers with counts of processed and failed rows.

Both apps also post change messages to the Firebase database so other members' apps refresh ([Shared behavior](https://docs.snapfix.com/how-the-apps-work/shared.md)).

### Offline

Everything above works without a connection: the task shows in the app at once and uploads when a connection returns. AI suggestions are skipped. Exception: an iOS voice task started from Home loses its recording ([Voice task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/voice-task.md)).

### On failure

There is no message to the user. iOS tries each step three times and then moves on to the next table, leaving the rows queued for the next sync; a media upload that fails three times is marked failed and tried again on later syncs. Android retries with growing pauses, refreshes an expired session once, and keeps failed rows and media queued. When an iOS video upload fails, the video message's web address is overwritten with an empty value.

### Where the app goes next

* **iOS:** back to Home with the new task open on top ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md)).
* **Android:** the chosen group's task list ([Group tasks](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md)) opens, and the new task opens on top of it. In asset registers it opens the register's asset list.

## States

* **Loading:** the list comes from the phone's own data and shows at once; the AI suggestion arrives later.
* **Empty:** a user with no task groups on the site sees an empty list with no message; "Save" stays disabled.
* **Error:** none of its own; the checks above show alerts, and upload errors are silent.
* **No permission:** see the checks on "Save".
* **Offline (mobile):** works; see [Offline](#offline).

## Dialogs and sheets

### Tag your task

iOS `TagRequiredVC` (a pushed screen), Android `TagRequiredDialog` (a full-screen dialog). Opens when the chosen group requires details before a task can be saved.

* **Title:** "Tag your task". **Text:** "Add one or more %@ from each required category below.", filled with the required kinds, on iOS for example "tags, users and rooms".
* **Sections**, one per requirement:
  * each tag folder the group marks mandatory ([`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md) `fMandatory`): pick one or more tags;
  * an assignee section ("Assign User" on iOS) when the group requires an assignee ([`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md) `fAssigneeRequired`): pick group members;
  * an asset section when the group requires an asset (`fAssetRequired`): opens [Pick asset for task](https://docs.snapfix.com/how-the-apps-work/screens/assets/select-asset.md);
  * room and area sections when the group requires a room (`fRoomRequired`), an area (`fAreaAssociatedTask`), or either one (`fAreaOrRoomAssociatedTask`), and the site has rooms or areas. A task started from a room or area already has one, so that section is left out.
* Each section expands, with a search field ("Find" plus the section name on iOS). With AI suggestions on, iOS marks suggested tags, users, rooms and areas and lists them first, and can offer new tags Snapfix AI made up ("New Tags Created by AI"); text and sketch tasks get no suggestions.
* **"Submit"** checks every required section. Messages: iOS "Please select required tags!", "Please select required User!", "Please select required asset!", "Please select required room!", "Please select required area!", "Please select required room / area!"; Android "Please select required tags!", "Please select required users!", "Please select required assets!", "Please select required rooms!", "Please select required areas!", "Please select at least one room or area.". On iOS a mandatory tag folder with no tags does not block, and an assignee section blocks a user who may not assign (the alert under "Save", step 4). The selections are stored with the task, and the flow goes on.
* **Back:** returns to the previous screen without saving.

### Set the task location

iOS `SetLocationVC`, Android `LocationBottomSheet`; both are sheets. Opens when the group asks to confirm the location.

* **Title:** "Set the task location". A map with the user's position, a pin in the centre, zoom buttons and a button to recentre on the user.
* **"Your GPS location":** uses the phone's position. iOS shows "Accurate to N meters" under it; Android writes "Your GPS location Accurate to N meters" on the button. It is disabled until a position is known, and when location is off or not allowed.
* **"Map location":** uses the position under the centre pin.
* **Close:** goes on without changing the position. The Android sheet cannot be dismissed any other way. On iOS a tap outside the sheet closes it without going on; the task is saved only when the user tries again.

### Task limit banner

Shown in the list when the site's plan allows no more tasks: "No new tasks left in this account." followed by the link "Learn more" (on iOS in English only). The link opens a help center page that no longer exists. The banner has a close button.

## Platform differences

* The voice task picker is a full screen on iOS and a sheet on Android; tasks from rooms and areas use a sheet on iOS and the room or area screen on Android.
* The iOS full screen leaves inactive groups out; the iOS sheet and Android list them disabled. iOS searches names and addresses, Android names only.
* Android checks the assignee rule before opening [Tag your task](#tag-your-task); iOS only on "Submit".
* The task limit applies on the iOS and Android full screens only.
* After saving, iOS opens the task over Home; Android opens the group's task list and then the task.


---

# 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/tasks/pick-group.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.
