> 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/groups/group-settings.md).

# Group settings

{% 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/groups/group-settings.md).
{% endhint %}

Change one group: its photo, name, description, purpose and instructions, the names of its red, amber and green statuses, its tag folders, what a task in it must have, its checklist and archive automations, its users and their roles, and archiving or deleting it.

![Group settings](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-3b1e60747ffd0373f976f832a287ad87d3d80299%2Fgroup-settings.png?alt=media)

* **Where:** web `/group/:id/settings`; iOS and Android: the settings button on a group row ([Groups](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-list.md)), the group's menus, and the settings icon in [Group purpose](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-purpose.md). Asset registers use the same page at `/asset-register/:id/settings` ([Register settings](https://docs.snapfix.com/how-the-apps-work/screens/assets/register-settings.md)).
* **Who:** web: admins and users with "Group Settings Access" (`perBusSettingsScreenAccess`); the page checks this once the group has loaded and sends everyone else to Fix. iOS: the same users, if they are not read-only. Android's group list opens it for admins only. The API lets every member who isn't read-only change or delete the group, whatever these screens show.
* **Feature:** [Groups](https://docs.snapfix.com/product/features/groups/groups.md); users are in [Group members](https://docs.snapfix.com/product/features/groups/group-members.md).

## Getting here

* **Web:** the three-dot button on a group card ([Groups](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-list.md)), or the settings button in a group's task list header ([Group tasks](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md)).
* **iOS and Android:** the row button on the groups list, the group's menus, or the settings icon on the purpose screen. iOS also opens the Users tab from the "New group created" banner.
* **Back:** web goes back to the page it came from; after a save it goes back by itself.

## Layout

### Web

A back button and "Group Settings" at the top. Below, a card titled "Group Details" with three buttons: "Group Settings" (opens the drawer), "Group QR" (opens [Group QR codes](https://docs.snapfix.com/how-the-apps-work/screens/groups/qr-codes.md); not on asset registers) and "Save".

1. **Left column:** the photo with an edit button ("Edit group photo"), "Group name" \*, "Description" \* (the group's address), "Purpose" and "Instructions"; then "Labels" with "Define the names of status color-code" and a field each for "Red", "Yellow" and "Green".
2. **Right column:** "Tags & Labels" with "These tag folders are available in this group. Click on any folder to see all the tags it contains." and the folders; then "Users" ([Users](#users)).
3. **The "Group Settings" drawer**, 393 px wide on the right: the switches under [Settings drawer](#settings-drawer-web).

### iOS and Android

An editor with the tabs "Details", "Users" and "Tags" ("Attributes" instead of "Tags" for an asset register). The Details tab holds the photo, name, description, purpose, instructions, status names, the task rules and automations (under advanced options), archiving and, for admins, the QR button and delete. Android's title is "Edit: {group}".

## Inputs

### Details

| Field                 | Type            | Required | Default           | Rules and messages                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------- | --------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Photo                 | Image           | No       | The group's image | Web: "Edit group photo", "Drag and drop an image here OR Choose an image", with "Cancel" and "Save". Saved with the page.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Group name            | Text            | Yes      | Current name      | Web: empty shows "Please enter the group name" once the field has been left. Typing stops at 100 characters, so "Your input exceeds the maximum allowed length of 100 characters" shows only for a value set by a script. The server refuses a name another group of the site uses, and its message shows in an alert. iOS and Android check the name with the server before saving; a taken name shows "Duplicate Group": "Group names must be unique. Your chosen group name already exists, in this account. Please choose another group name." |
| Description           | Text            | Yes      | Current address   | Web: empty shows "Please enter a description". Up to 120 characters. Shown as the second line of the group's card.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Purpose, Instructions | Multi-line text | No       | Current text      | Web: typing stops at 255 characters. Shown in [Group purpose](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-purpose.md).                                                                                                                                                                                                                                                                                                                                                                                                         |
| Red, Yellow, Green    | Text            | No       | Current names     | Web: typing stops at 255 characters each. A new group starts with "New tasks", "Tasks in progress" and "Completed tasks".                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Settings drawer (web)

Each switch only changes the form; the page's "Save" sends it. All are off for a new group.

| Section                              | Switch                                                | What it does                                                                                                       |
| ------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| "Tag(s) required for Tasks"          | "Tag(s) Required", one per tag folder                 | "Tasks without at least one tag from each mandatory category will not be accepted." The server doesn't check this. |
| "Asset & User Requirements"          | "Asset(s) required for Tasks"                         | A new task needs an asset.                                                                                         |
|                                      | "Assigned user(s) required for Tasks"                 | A new task needs an assignee.                                                                                      |
| "Checklist Automations"              | "Auto set Task to Yellow when Checklist started"      | Starting a checklist moves the task to yellow.                                                                     |
|                                      | "Auto set Task to Green when Checklist completed"     | Completing it moves the task to green.                                                                             |
|                                      | "Checklist must be 100% before set to Green"          | Blocks green until the checklist is complete.                                                                      |
|                                      | "Allow manual NFC checks"                             | Lets users tick an item without tapping its NFC tag.                                                               |
| "Task Completion & Archiving"        | "Auto Archive Green Tasks"                            | Opens "Auto-archive Tasks in Green" ([Dialogs and sheets](#dialogs-and-sheets)).                                   |
|                                      | "Task approval required"                              | "When enabled, all tasks for this group must be approved by a Group Admin when changed to Green by a user."        |
| "Communication & Media Restrictions" | "Send daily group email report to all group admins"   | A daily email summary to each admin.                                                                               |
|                                      | "Block Photos from Gallery"                           | Only camera photos can be added.                                                                                   |
| "Task Room / Area Requirements"      | "A Room must be associated with all tasks"            | Turning it on turns off "An Area OR a Room…".                                                                      |
|                                      | "An Area must be associated with all Tasks"           | Turning it on turns off "An Area OR a Room…".                                                                      |
|                                      | "An Area OR a Room must be associated with all tasks" | Turning it on turns off the two above.                                                                             |
| "Group Control"                      | "Archive this group"                                  | Hides the group from the list for everyone; the "Archived groups" filter shows it. No dialog.                      |
|                                      | "Delete This Group"                                   | A button; see [Actions](#actions).                                                                                 |

Asset registers show only "Allow manual NFC checks", "Block Photos from Gallery" and the group control.

### Users

The "Users" section, under "Users in this group", lists the members sorted by name, with "Search users". Each row shows the name, the contact data when the site shows it, the role ("Admin", "User", or read-only for an inactive membership) and, for users with "Add or Remove Users in Group" (`perBusSettingsEditUser`), a menu with "Edit" and "Delete". The menu is on every row, the user's own included. A member who never signed in has the warning "This user has already been added to the group but has never used the Snapfix mobile or web app. Please ask this user to login to Snapfix." Below come "Invited users", each with "Resend invitation" and "Delete", and the button "Add users to this group". With no members the section shows "No user found in your group" and "Invite a new user into your business site.".

## Actions

| Action                         | Who                                                                                                                                                                              | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | API                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Open the page                  | Users with access                                                                                                                                                                | Loads the group with its members, invitations and tag folders, then builds the form. A failed load, or a user without access, goes to Fix with no message.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | [`GET /v1/app/businesses/{uuid}`](https://docs.snapfix.com/engineering-reference/api/groups.md#get-v1appbusinessesuuid)                                                                                                                                                                                                                                                                    |
| "Save" (web)                   | Users with access                                                                                                                                                                | Enabled when the form is valid and has been changed; it stays enabled after a change is undone. Sends the details and the drawer switches, shows a success state for 1.5 seconds, then goes back to the previous page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [`PUT /v1/app/businesses/{uuid}`](https://docs.snapfix.com/engineering-reference/api/groups.md#put-v1appbusinessesuuid), sent as a form `POST` with `_method=PUT`                                                                                                                                                                                                                          |
| Archive or unarchive           | Users with access                                                                                                                                                                | "Archive this group" in the drawer, then "Save". The group leaves the active list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | [`PUT /v1/app/businesses/{uuid}`](https://docs.snapfix.com/engineering-reference/api/groups.md#put-v1appbusinessesuuid) with `inActive`                                                                                                                                                                                                                                                    |
| "Delete This Group"            | Web: users with access. iOS and Android: admins only \[[ASK-71](https://github.com/snapfix/docs/blob/main/ASK.md#ask-71-who-may-archive-or-delete-a-group-and-see-its-qr-codes)] | Web asks "Delete Group": "Are you sure you want to delete the "{name}" group?" with "Cancel" and "Delete"; the name is put into the dialog as markup. Then a success state, and after 1.5 seconds the page goes to Fix. The drawer says "Deleting a group permanently removes the group and all task data within it.", but the server only marks the group deleted \[[ASK-80](https://github.com/snapfix/docs/blob/main/ASK.md#ask-80-what-should-deleting-a-group-do-to-its-tasks-and-members)]. iOS: "Are you sure you want to delete this group and all it's task?" (refused for the user's only group: "You are only part of one group. You can't delete your last group."); Android: "Are you sure you want to delete this Group and all it’s Tasks?", each with "Yes" and "No". | Web: [`DELETE /v1/app/businesses/{uuid}`](https://docs.snapfix.com/engineering-reference/api/groups.md#delete-v1appbusinessesuuid). Apps: the group row is saved as deleted through [`?action=save_pri_business`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-actionsave_pri_business)                                                                               |
| "Auto Archive Green Tasks"     | Users with access                                                                                                                                                                | Turning it on opens the auto-archive dialog. Its first "Save" asks how many tasks would be archived; the second sets the weeks. "Cancel" turns the switch off again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [`GET /v1/app/businesses/{businessUuid}/job-count-to-archived`](https://docs.snapfix.com/engineering-reference/api/groups.md#get-v1appbusinessesbusinessuuidjob-count-to-archived)                                                                                                                                                                                                         |
| Tag folders                    | Admins, and users with "Edit Tag Heading"                                                                                                                                        | "Tag Folder Permissions" picks the folders this group uses; a folder opens its tags. The member dialog no longer offers "Edit Tag Heading", so on the web only admins edit tags \[[ASK-79](https://github.com/snapfix/docs/blob/main/ASK.md#ask-79-who-should-edit-a-groups-tags)].                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [Tags API](https://docs.snapfix.com/engineering-reference/api/tags.md)                                                                                                                                                                                                                                                                                                                     |
| "Add users to this group"      | Users with "Add or Remove Users in Group"                                                                                                                                        | Opens "Add users to: {group}" with the site's users who are not in the group ([Dialogs and sheets](#dialogs-and-sheets)). The server accepts users from any site.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md) (`POST /v1/app/user/add-relation/{group}`)                                                                                                                                                                                                                                                                        |
| "Edit" a member                | Same                                                                                                                                                                             | Opens "User role & permissions".                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md) (`PUT /v1/app/user/{user}/update-relation/{group}`)                                                                                                                                                                                                                                                               |
| "Delete" a member              | Same                                                                                                                                                                             | Asks "Delete User": "Are you sure you want to delete user {name} from the group?" with "Delete" and "Cancel"; it removes the person from the group, not from Snapfix. The name is put into the dialog as markup. The person stays assigned to their tasks \[[ASK-75](https://github.com/snapfix/docs/blob/main/ASK.md#ask-75-should-removing-a-member-take-them-off-their-tasks)].                                                                                                                                                                                                                                                                                                                                                                                                    | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md) (`DELETE /v1/app/user/{user}/remove-relation/{group}`)                                                                                                                                                                                                                                                            |
| Last admin                     | Anyone changing members                                                                                                                                                          | Web refuses to remove or demote the only admin: "Each group must at least one active admin user. You can choose to add an additional admin user to this group before deleting this admin user or delete the group altogether if it's no longer in use." iOS: "Each group must have one or more admin users. If this group is no longer required you can choose to delete the group."; Android: "Each group must have at least one active admin user. …". The server doesn't check this.                                                                                                                                                                                                                                                                                               | -                                                                                                                                                                                                                                                                                                                                                                                          |
| Resend or cancel an invitation | Same                                                                                                                                                                             | "Resend invitation" sends it again; "Delete" asks "Delete invitation": "Do you want to delete invitation for {contact}?". The web can't send a new invitation \[[ASK-76](https://github.com/snapfix/docs/blob/main/ASK.md#ask-76-should-the-web-send-invitations-or-should-its-unused-invitation-code-go)].                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                                                                                                                                                                                                                                   |
| "Group QR"                     | Web: users with access. iOS and Android: admins \[[ASK-71](https://github.com/snapfix/docs/blob/main/ASK.md#ask-71-who-may-archive-or-delete-a-group-and-see-its-qr-codes)]      | Opens [Group QR codes](https://docs.snapfix.com/how-the-apps-work/screens/groups/qr-codes.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                                                                                                                                                                                                          |
| Save (iOS, Android)            | Users with access                                                                                                                                                                | Saves on the device and starts the sync.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [`?action=save_pri_business`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-actionsave_pri_business), [`?action=save_pri_settings_business`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-actionsave_pri_settings_business), [`?action=save_pri_status`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-actionsave_pri_status) |
| Back (iOS, Android)            | Anyone                                                                                                                                                                           | With unsaved changes: "There are unsaved changes in this group. Do you want to save those changes?"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -                                                                                                                                                                                                                                                                                                                                                                                          |

## States

* **Loading:** web shows a skeleton until the group loads. The apps show the device's copy.
* **Empty:** a group with no tag folders shows "No data available"; no members shows "No user found in your group".
* **Error:** web shows the server's message in an alert and leaves the form as it was. Android closes the editor with "Something went wrong. Please try again." when it can't read the group.
* **No permission:** see **Who**.
* **Offline:** web needs a connection. The apps save on the device and sync later; Android's QR icon asks for a connection.

## Dialogs and sheets

* **Auto-archive Tasks in Green** (web): "Auto-archive Tasks in Green after:" with 1 to 52 weeks ("Week" or "Weeks"), the warning "Please note that, when you press Save, all Tasks that have been in Green longer than the number of weeks you choose, will be immediately archived. This action cannot be undone. This process will repeat weekly.", then "Pressing Save will archive {n} task(s) in this group, that have been in Green for over {weeks} weeks. The task(s) will be archived within a few minutes." and "Please confirm or cancel."
* **Tag Folder Permissions** (web): "All Tag Folders" with a switch, then each folder with its tag count and a switch, "Cancel" and "Save".
* **Add users to: {group}** (web): "Add users", "Users who are already part of your network are shown in this list and can be directly added to the group.", the list ("User not found in your network" when empty), "You can add new users to your group and network using their email or phone number.", "Back" and "Done". The info text also says "Other Snapfix users can be added through the "Add new user" option.", which this picker doesn't have.
* **User role & permissions** (web): "Role in this group" (Admin or User), "Read-only user", and for "User" the "Advanced Permissions": "Create New Task", "Change task to red", "Change task to yellow", "Change task to green", "View All Tasks", "Hide Task Notes", "Delete or Archive Tasks", "Access Attachments", "Assign Users", "Generate Reports", "Create Planned Tasks", "Group Settings Access" and "Add or Remove Users in Group". "Cancel" and "Save".
* **Delete Group**, **Delete User** and **Delete invitation** confirmations (web), and the apps' delete and unsaved-changes questions.
* **Edit group photo** (web) and **Group QR Codes** ([Group QR codes](https://docs.snapfix.com/how-the-apps-work/screens/groups/qr-codes.md)).

## Platform differences

* **Structure:** web has one page and a drawer; the apps have tabs.
* **Who opens it:** web and iOS: admins and "Group Settings Access" holders; Android's group list: admins only.
* **Archive, delete and QR:** web offers them to everyone with access; the apps offer delete and QR to admins only \[[ASK-71](https://github.com/snapfix/docs/blob/main/ASK.md#ask-71-who-may-archive-or-delete-a-group-and-see-its-qr-codes)].
* **Duplicate names:** web relies on the server's check on save; the apps check with the server before they save.
* **Save:** web saves on the server at once; the apps save on the device and sync.


---

# 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/groups/group-settings.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.
