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

# Group users

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

Staff see the members of one group with their permissions, add members, change their permissions and passwords, upload members from a file, and export the list.

* **Where:** admin app `/group-users`; menu "Group Users". The "Group Users" button of the [Groups](https://docs.snapfix.com/how-the-apps-work/screens/staff/groups.md) page opens it with the site's name, the group and the type 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 member list, the member check and the writes check no staff flag and no membership of the group.
* **Feature:** [Customer administration](https://docs.snapfix.com/product/features/staff/customer-admin.md)

## Layout

1. **Title row.** "Group Users", and "Actions" with a round menu button on the right.
2. **Filter row.** "Select an Account" (the [account picker](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#account-picker): the site named in the address, or else the first site), "Select a Type" ("Task" at first, or "Asset"), "Select a Group" (the site's groups of that type, by name; deleted groups are marked) and "Add/Remove columns" with its "Show Columns" list. The group named in the address, or else the first group, is picked when the groups load. Changing the type clears the group.
3. **Table.** The members of the group, 10 rows per page by default (10, 20, 50 or 100). Columns, shown at first unless noted: "UUID" (hidden), "Username" (pinned left, with a sort), "Staff username", "Mobile Number" (hidden), "First Name" (hidden), "Last Name" (hidden), "Name", "Address" (hidden), fifteen read-only permission ticks of which "View All Tasks", "Create New Tasks" and "Delete/Archive Tasks" show at first, and "Action", pinned right, with "Edit", "Edit User Details" (opens [Users](https://docs.snapfix.com/how-the-apps-work/screens/staff/users.md) for the person) and "Reset password". Deleted and inactive members stay listed, marked.

The "Actions" menu has "Add a new User" and "Upload Multiple Users" (both need a picked group, and are disabled while the groups load), "Upload Users To Multiple Groups" (disabled while the groups load), "Users Permissions" (needs members) and "Export" (needs members, and is disabled while the table loads).

## Inputs

| Field             | Type                             | Required             | Default  | Rules and messages                             |
| ----------------- | -------------------------------- | -------------------- | -------- | ---------------------------------------------- |
| Select an Account | Single select with search        | Yes, for the groups  | As above | Picking a site loads its groups.               |
| Select a Type     | Select, "Task" or "Asset"        | No                   | "Task"   | Shows that type's groups and clears the group. |
| Select a Group    | Select                           | Yes, for the members | As above | Picking a group loads its members.             |
| Columns           | Checkboxes, under "Show Columns" | No                   | As above | Applies at once.                               |

## Actions

| Action                     | Who              | What happens                                                                           | API                                                                                                                                                      |
| -------------------------- | ---------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Load the groups            | Anyone signed in | Loads the site's groups, sorted by name, and lists 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)                 |
| Load the members           | Anyone signed in | Loads the group's members with their contact details and permissions.                  | [`POST ?action=admin_read_pri_user_business_v2`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_read_pri_user_business_v2) |
| Menu items and row buttons | Anyone signed in | Open the dialogs below. "Edit User Details" opens the Users page with the person's ID. | See [Dialogs and sheets](#dialogs-and-sheets)                                                                                                            |

## States

* **Loading:** the table shows its spinner while the members load, and the group list while the groups load.
* **Empty:** a group with no members shows no rows, and "Users Permissions" and "Export" are disabled.
* **Error:** the group and member lists show no message. An answer that is not a success empties the list; 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.

### Add User and Edit User Group Permission

Opened by "Add a new User" ("Add User") or by a row's "Edit" ("Edit User Group Permission").

**Add User** starts with the hint "Fill in the mobile number or email or both and click on Check User".

| Field                       | Type    | Required         | Default | Rules and messages               |
| --------------------------- | ------- | ---------------- | ------- | -------------------------------- |
| Email                       | Text    | One of the four  | Empty   | "Please enter valid Email."      |
| Staff Username              | Text    | One of the four  | Empty   | No check.                        |
| Country Code, Mobile Number | Numbers | Both, or neither | Empty   | "Wrong format." without a digit. |

"Check User" is enabled while the form is valid, at least one field has a value, and the country code and mobile number are both filled or both empty. It looks the person up with the group ([`POST ?action=admin_check_user`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_check_user)), and fills the four fields from the record found. Then:

* **No such person.** The filled fields become read-only and the form adds "Password" (read-only, a generated 10-character password of upper and lower case letters and digits, shown on screen), "First Name" and "Last Name" (both required) and "Address" (optional). An answer that is not a success is taken as "no such person" too, with no message.
* **In Snapfix but not in this group.** The person's email, name, mobile and IDs, and "This User is already part of snapfix but is not part of the group. Fill in the details below and click on Submit to add them to this group.", although the button says "Save".
* **Already in this group.** A note says so, and "Reset" clears the form to check again.

In the first two cases the type and permissions follow: "Admin" (the default) or "User" \[[ASK-219](https://github.com/snapfix/docs/blob/main/ASK.md#ask-219-should-a-member-added-in-the-admin-app-start-as-admin)], and fifteen "Advanced Permissions": "View All Tasks", "Create New Tasks", "Access Document" and "Assign User" ticked; "Delete/Archive Tasks", "Create Planned Tasks", "Create New Checklist Item", "Edit Checklist Item", "Delete Checklist Item", "Generate Reports", "Create New Group", "Group Setting Access", "Add/Remove Users in/from Group", "Add/Edit/Delete Tag" and "Edit Tag Heading" not. "Save" creates the person when needed and adds them to the group with that type and those permissions, then closes and reloads the table ([`POST ?action=admin_save_user`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_save_user)).

**Edit User Group Permission** shows the person's email, name, mobile and IDs, the group and site, and the created and modified times and users, each time both as stored and as `MM/dd/YYYY HH:mm:ss`. The type and the permissions start from the membership. A "Delete" checkbox in the footer asks "Deleting a user Group Permission is usually carried out by the customer." and "Are you sure it's safe to delete this user Group Permission?" with "Delete". "Save" writes the membership's type, permissions and deleted flag ([`POST ?action=save_pri_user_business_v2`](https://docs.snapfix.com/engineering-reference/api/users.md)). Here "Delete/Archive Tasks" sets both flags behind it; the table and the matrix below show and change only the delete flag.

"Cancel" is always there; "Check User" and "Save" spin while they run.

### Reset Password

Opened by a row's "Reset password". It is the same dialog as on the Users page: see [Reset Password](https://docs.snapfix.com/how-the-apps-work/screens/staff/users.md#reset-password).

### Upload New User(s)

Opened by "Upload Multiple Users". The text asks for a .csv file with at least one record and the columns `username`, `password`, `firstname`, `lastname`, `address`, `countrycode`, `mobile` and `usertype`, in that order, and says that a type of "admin" or "administrator" makes an admin and anything else a normal user. "Download Sample File" gives a sample.

* Only a file the browser reports as `text/csv`: "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." Headings that differ: "Missing or incorrect CSV headers. Please ensure you have provided correct CSV headers."
* A row with no username, country code or mobile is skipped. A row repeats when its username, or its country code (without "+") and mobile (without spaces, dashes or underscores), came before; repeats are marked and counted as "Duplicate Entries: N".
* The review table has one editable row per person, the password in clear, a "Type" select ("Admin" or "User") and a remove button; "Reupload" starts again. "Upload", disabled while a repeat remains, sends all rows in one request and closes ([`POST ?action=admin_save_users`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_save_users)).

### Upload User(s) To Multiple Groups

Opened by "Upload Users To Multiple Groups", for the site's groups of the chosen type that are not deleted. The text asks for an .xlsx file with at least one record and the columns `username`, `password`, `firstname`, `lastname`, `address`, `countrycode`, `mobile`, `usertype` and `groups`, in that order; a type of "admin" or "administrator" makes an admin, else a "Normal User". The help icon on `groups` says "Leave the groups field blank in order to select all available groups".

* Only Excel files the browser reports as such: "You can only upload XLSX file!". The first sheet is read; an empty one gives "No data found", and wrong columns "… Column are excepted in users sheet but found …".
* `groups` holds group names separated by commas. A blank cell means every group listed, and so does a cell whose names match no group. The repeat rules are those of Upload New User(s).
* Each review row has a "Groups (n/m)" button that opens a "Groups" list with "All Groups" and one checkbox per group; its "Save" needs a group.
* "Upload", disabled while a repeat remains, sends every row with its groups in one request and closes ([`POST /v1/admin/user-relations/multiple`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminuser-relationsmultiple)). Country codes and mobile numbers go through `Number()`, so a blank one is sent as 0. The passwords are sent and logged as typed.

### Users Permissions

Opened by "Users Permissions". Its width is set to "95wh", which is not a CSS length, so it keeps the default width.

* "Admin" or "User" (the default) chooses which members the table lists.
* Each row starts ticked and shows the email, or the country code and mobile, then the fifteen permission checkboxes; only ticked rows can be changed and are saved. A permission's heading checkbox sets it for every member of the type shown.
* A row's "Apply to All Users" asks "Are you sure you want to apply the permissions to all users?" with "Confirm", and copies that row's permissions to every member of the type, but only the ticked rows are saved.
* "Save", enabled once a row is ticked and something changed, sends the ticked members of the type on screen and closes ([`PUT /v1/admin/user-relations/multiple`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminuser-relationsmultiple)). Changes made on the other type are dropped, with no warning.

### Export Group Users

Opened by "Export". "Check All", then "UUID", "Username", "Name", "Address", "Country Code" and "Mobile Number" (ticked), "Staff Username", "First Name", "Last Name" and the fifteen permissions (not ticked), and "Include Deleted" (off; deleted members are left out without it). "Export", disabled until an option is ticked, writes `group-users.xlsx` with one sheet, "Group Users", from the group's members. The "Address" column holds the names. No request.


---

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