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

# Groups

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

Staff list a site's groups, add, edit, delete, copy and export them, and upload groups, schedules, tasks, assets, tags and checklists in bulk.

* **Where:** admin app `/groups`; menu "Groups". The "Business Groups" button of the [Account](https://docs.snapfix.com/how-the-apps-work/screens/staff/accounts.md) page and the group links of other staff pages open it with a site's name in the address.
* **Who:** anyone signed in to the admin app ([Access](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#access)). The calls behind it check no staff flag and no membership; the group change checks no access at all.
* **Feature:** [Customer administration](https://docs.snapfix.com/product/features/staff/customer-admin.md)

## Layout

1. **Title row.** "Groups", and "Actions" with a round menu button on the right.
2. **Intro.** "Each account can have one or more groups. Tasks are contained within these groups."
3. **Filters.** "Select an Account", the [account picker](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#account-picker): the first site whose name matches the name in the address, or else the first site of the list, is picked when the page opens. "Select a Type": "Task" (the default) or "Asset"; cleared, it shows no groups.
4. **Table.** The site's groups of the chosen type, 10 rows per page by default (10, 20, 50 or 100), with a quick jump box. Columns: "Name" (sort and search box), "Address" (search box) and "Action", pinned to the right, with a round "⋯" button for the [row menu](#row-menu), a "Group Users" button that opens [Group users](https://docs.snapfix.com/how-the-apps-work/screens/staff/group-users.md) and a "Group QRs" button that opens [QR management](https://docs.snapfix.com/how-the-apps-work/screens/staff/qr-management.md) for the group. Deleted and inactive groups stay in the table, marked.

The "Actions" menu has "Create a new Group", "Upload Multiple Groups", "Upload Multiple Schedules", "Copy Group Details" and "Export". The first four are disabled until a site is picked; "Export" is disabled while the table loads.

## Inputs

| Field                       | Type                                             | Required           | Default  | Rules and messages                                                           |
| --------------------------- | ------------------------------------------------ | ------------------ | -------- | ---------------------------------------------------------------------------- |
| Select an Account           | Single select with search                        | Yes, for the table | As above | Picking a site loads its groups.                                             |
| Select a Type               | Select, "Task" or "Asset"                        | No                 | "Task"   | Shows the loaded groups of that type, with no request.                       |
| Name search, Address search | Text, in the column's search box ("Search name") | No                 | Empty    | Keep the loaded rows whose name or address contains the text, ignoring case. |

## Actions

| Action                     | Who              | What happens                                                                | API                                                                                                                                      |
| -------------------------- | ---------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Load the groups            | Anyone signed in | Loads every group of the site, then shows those of the chosen type.         | [`POST ?action=admin_read_pri_business`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_read_pri_business) |
| Actions menu items         | Anyone signed in | Open the dialogs below.                                                     | See [Dialogs and sheets](#dialogs-and-sheets)                                                                                            |
| "Group Users", "Group QRs" | Anyone signed in | Open that page with the site's name, the group and the type in the address. | None                                                                                                                                     |

## States

* **Loading:** the table shows its spinner while the groups load.
* **Empty:** a site with no groups of the chosen type shows no rows.
* **Error:** the group list shows no message. An answer that is not a success empties the table; a failed request keeps the old rows.
* **No permission:** none in the app.

## Dialogs and sheets

Each save below shows "Success" when it works and the server's message when it does not. "Cancel" is disabled while a save runs; in Upload Schedules it shows a spinner instead.

### Row menu

The "⋯" button's menu: "Edit"; "Upload Tasks With Checklist" (task groups) or "Upload Assets With Checklist" (asset groups), the same dialog, which creates tasks in both cases \[[ASK-214](https://github.com/snapfix/docs/blob/main/ASK.md#ask-214-what-should-upload-assets-with-checklist-create-in-an-asset-register)]; "Create Random Tasks" and "Upload Tags" for task groups; "Upload Assets With Attributes" for asset groups; and "Upload Checklist". A "Group Summary" item is in the code but switched off, so it never shows \[[ASK-217](https://github.com/snapfix/docs/blob/main/ASK.md#ask-217-should-the-group-summary-item-be-finished-or-removed)].

### Add Group and Edit Group

Opened by "Create a new Group" or by "Edit". When editing, "Business UUID" and "Parent UUID", each copyable, sit at the top, and the audit fields "CreatedBy", "fCreatedTs", "Created", "ModifiedBy", "fModifiedTs" and "Modified" sit below the form, under their internal names, with dates as `MM/dd/YYYY HH:mm:ss`.

| Field   | Type                    | Required | Default                             | Rules and messages                                                                                                                                                                                                                                                                                                                                                  |
| ------- | ----------------------- | -------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name    | Text                    | Yes      | The group's name                    | "Please input Account name."                                                                                                                                                                                                                                                                                                                                        |
| Address | Text                    | Yes      | The group's address                 | "Please input Account Address."                                                                                                                                                                                                                                                                                                                                     |
| Active  | Checkbox                | No       | Ticked unless the group is inactive | Edit only.                                                                                                                                                                                                                                                                                                                                                          |
| Delete  | Checkbox, in the footer | No       | Ticked for a deleted group          | Edit only. Ticking it asks "Deleting a group is usually carried out by the customer." and "Are you sure it's safe to delete this group?" with "Delete". A deleted group stays listed, and its tasks and members are left as they are \[[ASK-80](https://github.com/snapfix/docs/blob/main/ASK.md#ask-80-what-should-deleting-a-group-do-to-its-tasks-and-members)]. |

"Add" creates the group in the site with its default settings, statuses and tags; the server records the text "admin" as its creator \[[ASK-77](https://github.com/snapfix/docs/blob/main/ASK.md#ask-77-who-should-be-recorded-as-the-creator-of-groups-users-and-sites-made-through-the-staff-admin-routes)] ([`POST /group`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-group)). "Save" sends the group's row with the new name, address, active and deleted flags ([`POST ?action=modify_pri_business`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-actionmodify_pri_business)). Either closes the dialog and reloads the table; both are disabled while the form is invalid.

### Upload New Group(s)

Opened by "Upload Multiple Groups". The text asks for a .csv "file of users" with at least one record and the columns `name` and `address`, with "Download Sample File".

* Only a file the browser reports as `text/csv` is taken; anything else gives "You can only upload CSV file!".
* More than 100 rows after the heading: "The CSV file can have a maximum of 100 entries. Please reduce the number of records in the CSV file and try again". The first two headings must be `name` and `address`: "name and address columns are required".
* Rows with a blank name are skipped. The review table has Name and Address inputs (both with the placeholder "Name") and a remove button per row; "Duplicate Entries: N" counts repeated names, compared without surrounding spaces, and a name blanked in the table counts as an error. "Upload" is disabled while any error remains; "Reupload" starts again.
* "Upload" creates the groups, closes and reloads the table ([`POST ?action=admin_create_businesses_v2`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_businesses_v2)).

### Upload Schedules

Opened by "Upload Multiple Schedules". The text asks for an .xlsx file with at least one record ("Maximum record count is 150"), with "Download Sample File": a workbook with a `Task_details` sheet, start dates set to tomorrow, and linked sheets.

* Only Excel files the browser reports as such: "You can only upload XLSX file!". Without a `Task_details` sheet: "No data found". More than 150 rows: "The maximum record count is 150, but the uploaded file contains N items."
* The server checks and creates the schedules in the groups the file names, whatever site is picked ([`POST /schedule-upload`](https://docs.snapfix.com/engineering-reference/api/planner.md#post-schedule-upload)). When it reports a failed check with messages, the first message shows and the dialog stays; otherwise "Success" shows and the dialog closes, also when rows failed.

### Copy Group Details to Other

Opened by "Copy Group Details". The groups come from the site's group list with members ([`GET /v4/groups/{parentUUID}`](https://docs.snapfix.com/engineering-reference/api/groups.md#get-v4groupsparentuuid)), whose member lists are cut at 1,024 bytes per group and leave out members with an empty field.

| Field                                               | Type                                         | Required                   | Default         | Rules and messages                                                                                                                                                                                               |
| --------------------------------------------------- | -------------------------------------------- | -------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Select an Account                                   | Account picker, from the page's loaded sites | Yes                        | The page's site | Picking a site loads its groups.                                                                                                                                                                                 |
| Select a Source Group                               | Select with search                           | Yes                        | Empty           | The site's groups.                                                                                                                                                                                               |
| Destination Group 1, 2, …                           | Select with search, one per row              | Yes                        | Empty           | The site's groups except the source and those picked in other rows. "Add Destination Group" adds a row; with two rows or more each has a remove button. Rows left empty are still sent, and the copy then fails. |
| User 1, 2, …                                        | Select                                       | No, though marked required | Empty           | Shown when the destination group has members: its members with a name, as "Name - username". The chosen member becomes the admin of the copy there; with none, the source group's admin is used.                 |
| Copy Users, Copy Schedules, Copy All Group Settings | Checkboxes                                   | No                         | All ticked      | Copy Users copies the members with their roles \[[ASK-73](https://github.com/snapfix/docs/blob/main/ASK.md#ask-73-should-copying-a-group-copy-its-members)].                                                     |

"Save" is disabled until a source and a destination are picked. It copies the source group into each destination with the chosen options and closes ([`POST /copy-group-data`](https://docs.snapfix.com/engineering-reference/api/groups.md#post-copy-group-data)).

### Export Groups

Opened by "Export". "Check All", then "ID" (off), "UUID" (on), "Name" (on) and "Address" (off), and "Include Deleted" (off). "Export" is disabled until an option is ticked, and writes `groups.xlsx`, with one sheet "Groups", from the groups in the table at that moment, so the type and the searches apply. No request.

### Upload Tasks With Checklist and Upload Assets With Checklist

Opened from the row menu. The file is an .xlsx or .xls workbook, with "Download Sample File".

* The sheet whose name does not contain "ck" is the task sheet; there must be only one ("Only one task sheet should be there, but found …"). Its columns must be `Title`, `Status` and `ck_name`, in that order (`ck_name` may be missing). Every sheet whose name contains "ck" is a checklist sheet with the columns `Title`, `sortorder`, `Yes/No`, `Pass/Flag/Fail`, `starEnabled`, `satisfactionEnabled`, `Add Notes / Photo`, `Notes`, `Mandatory` and `Section`, and becomes a tab unless it is empty. A column mismatch reads "… Column are excepted in … sheet but found …". An empty task sheet: "No data found".
* The task tab lists Title (up to 50 characters), Status (red, amber or green; "yellow" reads as amber) and ck\_name (a checklist tab), with a remove button per row. A repeated or blank title marks the tab and blocks "Upload". A task with no status shows none and uploads as red.
* The checklist tabs are never checked: their code to mark repeated titles, or rows with more than one of "Yes/No", "Pass/Flag/Fail", "Start Enabled" and "Satisfaction Enabled" on, never runs.
* A task's `ck_name` picks its checklist by the sheet's position among all checklist sheets, empty ones included, so after an empty checklist sheet the later tasks get the next sheet's checklist, and the last one's get none.

| Field      | Type                          | Required | Default | Rules and messages                                                                                                                                                                     |
| ---------- | ----------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Owner User | Select, "Select a Owner User" | Yes      | Empty   | The group's members who are not deleted ([`admin_read_pri_user_business_v2`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_read_pri_user_business_v2)). |

"Upload" is disabled while a tab is marked or no owner is picked. It creates the tasks, each with its checklist, as the chosen owner, not as the signed-in staff user, and closes ([`POST ?action=admin_create_jobs`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_jobs)).

### Create Random Tasks

Task groups only.

| Field                             | Type                                   | Required | Default | Rules and messages                                             |
| --------------------------------- | -------------------------------------- | -------- | ------- | -------------------------------------------------------------- |
| Owner User                        | Select, "Select a Owner User for Task" | Yes      | Empty   | The group's members who are not deleted, as "Name - username". |
| Number of Task to create in Group | Slider, 1 to 10                        | Yes      | 5       | The server takes any count.                                    |

"Save", disabled until an owner is picked, creates that many tasks in the group with random titles and images and a fixed description, as the chosen member, and closes ([`POST /v4/random-jobs`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v4random-jobs)). These are real tasks in a live group, made with no confirmation \[[ASK-221](https://github.com/snapfix/docs/blob/main/ASK.md#ask-221-should-create-random-tasks-be-offered-for-live-customer-groups)].

### Upload Tags

Task groups only. The text asks for an .xlsx "file of tasks". One tab per tag folder of the group ([`admin_read_group_tag_settings`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_read_group_tag_settings)), each with the folder's tags, an "Uploaded tags" part, a "Delete" checkbox and "Upload" (or "Reupload"). With no folders: "No data available"; an empty folder: "No tags available".

* "Upload" reads the first sheet's `TagName` column and skips names the folder already has; with no new name left: "No data found". New tags show in random colours, which are not saved.
* "Delete" soft-deletes every tag of that folder when saved, and queues the change for the apps; the folder stays, and tags uploaded for it in the same save are then added.
* "Save", enabled once a folder has new tags or is marked "Delete", sends each changed folder and closes ([`admin_update_group_tag_settings`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_update_group_tag_settings)).

### Upload Assets With Attributes

Asset registers only. The workbook needs a sheet `assets` with the columns `Title` and `Status`, in that order ("Assets sheet not found" without it; "No data found" when empty). An optional sheet `attributes` holds one row per asset, matched by position, with one column per attribute. Repeated attribute headings come in as `name_1`, `name_2`; the dialog drops those, so only the first column of a repeated heading counts, though a third repeat is kept.

* Tabs "Assets" and, with attribute rows, "Attributes". The assets table has Title (up to 50 characters), Status (red, amber or green; "yellow" reads as amber; none uploads as green) and a remove button; a repeated or blank title blocks "Upload". Removing a row from either table leaves the other as it was, so the later assets get the previous row's attributes.
* "Upload" creates the assets with their attributes in the register and closes ([`POST ?action=admin_create_assets`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_assets)).

### Upload Checklist

Step one takes an .xlsx file; its first sheet must have the ten checklist columns listed above, in that order ("… Column are excepted in checklist sheet but found …"; "No data found" when empty). Step two shows the rows, with a switch per option, a remove button per row and "Reupload"; rows with a blank title are not sent.

| Field        | Type               | Required | Default | Rules and messages                                                                                                                                              |
| ------------ | ------------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Select a Job | Select with search | Yes      | Empty   | Every task of the group, by title, with no limit ([`admin_read_jobs`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_read_jobs)). |

"Upload", disabled until a task is picked, replaces that task's checklist with the rows and closes ([`POST ?action=admin_create_checklist`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_checklist)).


---

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