> 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/console/checklists.md).

# Checklists

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

Admins keep checklist folders and templates for the site, or for the whole multi-site: create, edit, copy, move and delete them, enable each template in groups (and, on a multi-site, in sites), assign or replace it on tasks, remove it from tasks, see its audit trail, and fetch templates from the library or the multi-site.

![Checklists](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-41fef0c925c6406d7bb3008dc36844d77344e1a5%2Fchecklists.png?alt=media)

* **Where:** web `/account/:id/manage-checklist` (Site Console, tab "Checklists") and `/multi-site/checklists` (Multi-Site Console, tab "Checklists"). The template editor is [Edit checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/edit-checklist.md); a checklist on a task is [Checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md).
* **Who:** Site Console: the tab shows to role "Admin" and gets every action. The route also admits group admins; they get the list full width, with no buttons and no right-hand panel, but each template still has its "⋯" menu. Access goes by the site role, not by the site permission "Create | Edit | Delete Checklists" \[[ASK-131](https://github.com/snapfix/docs/blob/main/ASK.md#ask-131-should-the-create--edit--delete-checklists-permission-let-users-manage-checklist-templates)]. Multi-Site Console: every multi-site user gets the whole page \[[ASK-123](https://github.com/snapfix/docs/blob/main/ASK.md#ask-123-who-may-manage-a-multi-site-and-change-its-members-site-roles)].
* **Feature:** [Checklist templates](https://docs.snapfix.com/product/features/checklists/checklist-templates.md)

## Layout

1. **Title.** "Checklist".
2. **Left column (one third).** In the Multi-Site Console, a dropdown first chooses the scope: the multi-site, or one of its sites. Then, for role "Admin" and in the Multi-Site Console, "Add Folder" (title "Create Folder"), "Library" (title "Checklist Library") and "Assign" (title "Assign Checklist"); in the narrow column the three labels are cut off. A search field "Search Checklists Folders". The folder list: each folder's name with "(N Checklists)" and its description. An open folder shows "Add New Checklist" (role "Admin" and the Multi-Site Console), then its templates, each with its description and a "⋯" menu.
3. **Right column (two thirds; role "Admin" and the Multi-Site Console).** The folder's name and description with "Edit" and "Delete Folder". A card with the tabs "Preview" (the template's items), "Sites" (Multi-Site Console only: the sites the template is enabled in) and "Groups" (the groups it is enabled in). The Groups tab lists the caller's own groups of the site, one switch each \[[ASK-134](https://github.com/snapfix/docs/blob/main/ASK.md#ask-134-should-a-templates-groups-tab-list-every-group-of-the-site)]. Under the card, a "Tasks" card lists the tasks that use the template in the group or site picked.

The template menu has "View Checklist", "Assign to Tasks", "Remove from Tasks", "Edit", "Move from folder", "Replace Checklist", "Make a Copy", "Delete" and "Audit Trail"; "Set as Multisite" is added in the Multi-Site Console when a site is picked. Several items have info popovers, such as "Assign a Checklist Template to multiple tasks at once." and "Template checklists are replaceable - changes will apply ONLY to the tasks where the checklist hasn’t been started yet."

## Inputs

### Checklist (new, copy, move, set as multi-site)

| Field                              | Type   | Required | Default                                         | Rules and messages                                                                                                                                                                                                                                                           |
| ---------------------------------- | ------ | -------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Checklist Name \*"                | Text   | Yes      | Empty, or the template's name for copy and move | Placeholder "e.g. Closing SOPs". Up to 255 characters; typing stops at 255. Empty: "Enter checklist name" once the field is touched, and the button stays disabled. Longer: "Your input exceeds the maximum allowed length of 255 characters". A name of spaces only passes. |
| "Checklist Description (optional)" | Text   | No       | Empty                                           | Placeholder "e.g. Maintenance". Up to 255 characters.                                                                                                                                                                                                                        |
| "Folder"                           | Select | Yes      | The open folder                                 | The folders of the chosen site.                                                                                                                                                                                                                                              |
| "Site"                             | Select | Yes      | The current site                                | Copy and move in the Multi-Site Console only.                                                                                                                                                                                                                                |

### Checklist folder

| Field                                     | Type | Required       | Default                           | Rules and messages                                                                                                                                                                                              |
| ----------------------------------------- | ---- | -------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Checklist Folder Name \*"                | Text | On create only | Empty, or the current name        | Placeholder "e.g. Locations". Up to 255 characters. Empty on create: "Enter checklist name", the checklist's text rather than a folder's, and "Save" stays disabled. On edit the name can be cleared and saved. |
| "Checklist Folder Description (optional)" | Text | No             | Empty, or the current description | Placeholder "e.g. Maintenance". Up to 255 characters.                                                                                                                                                           |

The save-time alert these dialogs have for an empty name says "Please enter a username"; the disabled button never lets it show.

## Actions

Folder and template lists come from [`GET /v1/app/checklists/{scope}/folders`](https://docs.snapfix.com/engineering-reference/api/checklists.md#get-v1appchecklistsscopefolders) and [`GET /v1/app/checklists/{scope}/templates/list-by-folder/{folderUuid}`](https://docs.snapfix.com/engineering-reference/api/checklists.md#get-v1appchecklistsscopetemplateslist-by-folderfolderuuid); `scope` is `site`, or `multiSite` in the Multi-Site Console with no site picked.

| Action                  | Who                                  | What happens                                                                                                                                                                                                                                                                                                                    | API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Add Folder              | Role "Admin"; multi-site users       | "New Checklist Folder", then "Save".                                                                                                                                                                                                                                                                                            | [`POST /v1/app/checklists/{scope}/folders`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistsscopefolders)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Edit (folder)           | Role "Admin"; multi-site users       | "Edit Checklist Folder", then "Save".                                                                                                                                                                                                                                                                                           | [`PUT /v1/app/checklists/{scope}/folders/{uuid}`](https://docs.snapfix.com/engineering-reference/api/checklists.md#put-v1appchecklistsscopefoldersuuid)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Delete Folder           | Role "Admin"; multi-site users       | "Delete Checklist Folder": "Deleting this Checklist folder will permanently remove all its Checklists from its Tasks. Do you want to continue?" with "Cancel" and "Delete".                                                                                                                                                     | [`DELETE /v1/app/checklists/{scope}/folders/{uuid}`](https://docs.snapfix.com/engineering-reference/api/checklists.md#delete-v1appchecklistsscopefoldersuuid)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Add New Checklist       | Role "Admin"; multi-site users       | "New Checklist": name, description and folder, then "Next" opens the editor "Create your Checklist" ("Require Signature", sections and items), where "Save" creates the template. The first dialog stays behind the editor, with a spinner on "Next", until the editor closes.                                                  | [`POST /v1/app/checklists/{scope}/templates`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistsscopetemplates)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| View Checklist          | Anyone with the menu                 | Shows the template's items in a dialog.                                                                                                                                                                                                                                                                                         | [`GET /v1/app/checklists/{scope}/templates/{uuid}`](https://docs.snapfix.com/engineering-reference/api/checklists.md#get-v1appchecklistsscopetemplatesuuid)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Edit                    | Anyone with the menu                 | Opens [Edit checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/edit-checklist.md).                                                                                                                                                                                                                        | See [Edit checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/edit-checklist.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Make a Copy             | Anyone with the menu                 | "Copy Checklist": a name and a folder, and in the Multi-Site Console a site ("Select the Site, Checklist Name and Folder for the checklist copy.").                                                                                                                                                                             | [`POST /v1/app/checklists/{scope}/templates/copy`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistsscopetemplatescopy)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Move from folder        | Anyone with the menu                 | "Move Checklist": a name and another folder, and in the Multi-Site Console a site ("Select the Site, Checklist name, and Folder where the checklist will be moved to.").                                                                                                                                                        | [`POST /v1/app/checklists/{scope}/templates/move`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistsscopetemplatesmove)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Set as Multisite        | Multi-site users, with a site picked | Opens the create dialog with the template's name and items; "Save" creates it as a multi-site template.                                                                                                                                                                                                                         | [`POST /v1/app/checklists/{scope}/templates`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistsscopetemplates)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Delete                  | Anyone with the menu                 | Confirms, then deletes the template.                                                                                                                                                                                                                                                                                            | [`DELETE /v1/app/checklists/{scope}/templates/{templateUuid}`](https://docs.snapfix.com/engineering-reference/api/checklists.md#delete-v1appchecklistsscopetemplatestemplateuuid)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Assign, Assign to Tasks | Anyone with the button or menu       | "Assign Checklist to Tasks": step 1 "Select Checklist" (the open folder's templates, with dates), step 2 "Select Tasks" (the tasks of a group or the site), then assign. The task picker lists only tasks with no checklist items of their own (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/AssetJobService.php:1544-1547`). | Picker: [`POST /v1/app/tasks/list-for-checklist`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptaskslist-for-checklist). Assign: [`POST /v1/app/checklists/{scope}/jobs`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistsscopejobs) or [`.../jobs/all`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistsscopejobsall)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Replace Checklist       | Anyone with the menu                 | The same task picker, then "Replace Checklist": "This will replace the original checklist in all selected tasks with the new one. Do you want to proceed?" with "Replace". Because the picker offers only tasks whose checklist has not been started, the info popover's promise holds.                                         | [`POST /v1/app/checklists/{scope}/jobs`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistsscopejobs)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Remove from Tasks       | Anyone with the menu                 | "Remove from templates": pick the tasks, then "Removing this checklist from the selected task(s) will erase any progress made within it. Do you want to continue?" with "Remove".                                                                                                                                               | [`POST /v1/app/checklists/{scope}/jobs/delete`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistsscopejobsdelete)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Audit Trail             | Anyone with the menu                 | "Audit Trail" with the template's name and description and its changes per day (actor, text, time); "No activity logs found" when empty.                                                                                                                                                                                        | [`GET /v1/app/checklists/{entityUuid}/activities`](https://docs.snapfix.com/engineering-reference/api/checklists.md#get-v1appchecklistsentityuuidactivities)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Library                 | Role "Admin"; multi-site users       | In the Multi-Site Console with no site picked, and on a site outside any multi-site: "Checklist Library", to search the library and download templates. On a site that belongs to a multi-site: "Pick from templates", with the multi-site's folders.                                                                           | Library: [`POST /v1/app/checklists/library`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistslibrary), then [`POST /v1/app/checklists/{scope}/templates/download`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistsscopetemplatesdownload). Pick: [`GET /v1/app/checklists/site/folders/{parentUuid}/multiSite`](https://docs.snapfix.com/engineering-reference/api/checklists.md#get-v1appchecklistssitefoldersparentuuidmultisite), [`GET .../list-by-folder/{folderUuid}/multiSite`](https://docs.snapfix.com/engineering-reference/api/checklists.md#get-v1appchecklistssitetemplatesparentuuidlist-by-folderfolderuuidmultisite), then [`POST /v1/app/checklists/site/templates/download/multiSite`](https://docs.snapfix.com/engineering-reference/api/checklists.md#post-v1appchecklistssitetemplatesdownloadmultisite) |
| Groups tab              | Role "Admin"; multi-site users       | Each group switch, or the all-groups switch, saves at once.                                                                                                                                                                                                                                                                     | Site: [`PUT /v1/app/checklists/site/permissions/group`](https://docs.snapfix.com/engineering-reference/api/checklists.md#put-v1appchecklistssitepermissionsgroup), [`.../group/all`](https://docs.snapfix.com/engineering-reference/api/checklists.md#put-v1appchecklistssitepermissionsgroupall); list: [`GET /v1/app/checklists/site/{templateUuid}/permissions/{parentUuid}/groups`](https://docs.snapfix.com/engineering-reference/api/checklists.md#get-v1appchecklistssitetemplateuuidpermissionsparentuuidgroups). Multi-site: [`PUT /v1/app/checklists/multiSite/permissions/group`](https://docs.snapfix.com/engineering-reference/api/checklists.md#put-v1appchecklistsmultisitepermissionsgroup), [`.../group/all`](https://docs.snapfix.com/engineering-reference/api/checklists.md#put-v1appchecklistsmultisitepermissionsgroupall)                                                         |
| Sites tab               | Multi-site users                     | Each site switch, or all of them, saves at once.                                                                                                                                                                                                                                                                                | [`PUT /v1/app/checklists/multiSite/permissions/parent`](https://docs.snapfix.com/engineering-reference/api/checklists.md#put-v1appchecklistsmultisitepermissionsparent), [`.../parent/all`](https://docs.snapfix.com/engineering-reference/api/checklists.md#put-v1appchecklistsmultisitepermissionsparentall)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Tasks card              | Role "Admin"; multi-site users       | Lists the tasks that use the template in the group or site picked.                                                                                                                                                                                                                                                              | [`GET /v1/app/checklists/{scope}/jobs/{templateUuid}/group/{businessUuid}`](https://docs.snapfix.com/engineering-reference/api/checklists.md#get-v1appchecklistsscopejobstemplateuuidgroupbusinessuuid), [`GET /v1/app/checklists/multiSite/jobs/{templateUuid}/parent/{parentUuid}`](https://docs.snapfix.com/engineering-reference/api/checklists.md#get-v1appchecklistsmultisitejobstemplateuuidparentparentuuid)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

Failed actions show the API's message in an alert.

## States

* **Loading:** spinners in the folder list, the groups card and the tasks card.
* **Empty:** "No data available" in the folder list. "Select the groups where this Checklist is enabled." with no template picked; "No site is enabled for the selected checklist." on the Sites tab with no site on; In the Tasks card, "Select a group to see what tasks this Checklist is assigned to." heads the list when the chosen group or site has tasks, and "No data available" shows when it has none; on the QA site the card read "No data available" before any group was clicked.
* **Error:** failed actions show the API's message. When a switch save fails, the switches are enabled again.
* **No permission:** group admins see the folder list and the template menus only (see **Who**).

## Dialogs and sheets

* **New Checklist, Copy Checklist, Move Checklist, set as multi-site:** see [Inputs](#checklist-new-copy-move-set-as-multi-site).
* **New Checklist Folder / Edit Checklist Folder:** see [Inputs](#checklist-folder).
* **Delete Checklist Folder, delete template:** confirmations.
* **Assign Checklist to Tasks:** "Assign a Checklist Template to multiple tasks at once.", the steps "Select Checklist" and "Select Tasks", "Cancel" and "Next".
* **Replace Checklist, Remove from templates:** the messages in [Actions](#actions).
* **Audit Trail:** see [Actions](#actions).
* **Checklist Library:** "Choose checklist template(s) to download.", a search field and "Back".
* **Pick from templates:** "Choose a Checklist from the template list. Template checklists are updatable - changes will apply to all tasks where the checklist hasn't been started yet.", the multi-site's folders with their counts, and "Save", disabled until a template is chosen.

## Platform differences

Web only. The apps fill and edit a template's checklist on a task ([Checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md)) and have no template list. The Sites tab, "Set as Multisite" and the site field of copy and move exist only in the Multi-Site Console.


---

# 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/console/checklists.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.
