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

# Tags

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

Admins manage the site's tag folders and the tags in them: create, edit and delete folders, add, rename, copy, move and delete tags, merge folders, import tags from a CSV file, and choose the groups each folder is enabled in.

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

* **Where:** web `/account/:id/manage-tags` (Site Console, tab "Tags", after "Users" and "Areas & Rooms"). The apps manage tags per group, in [Group settings](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-settings.md).
* **Who:** the tab shows to role "Admin"; the route also admits group admins, who can open it by URL. Folder controls need the site permission "Edit Tag Folders" and tag controls need "Manage Tags", both read from the stored current site ([Users](https://docs.snapfix.com/how-the-apps-work/screens/console/users.md#site-permissions-web)). After a [Site details](https://docs.snapfix.com/how-the-apps-work/screens/console/site-details.md) save, or after a site is picked from a multi-site list, the stored site carries these permissions as off, so the controls hide until the site list reloads.
* **Feature:** [Site tags](https://docs.snapfix.com/product/features/console/site-tags.md)

The calls on this page are in the [Tags API](https://docs.snapfix.com/engineering-reference/api/tags.md).

## Layout

1. **Title bar.** "Tags", and, with "Edit Tag Folders", "Select Tag Folders", which starts multi-select.
2. **Left column (one third).** "Add Folder" (needs "Edit Tag Folders"; title "Create New Tag Folder") and "Merge Tags" (needs "Manage Tags"; it opens the tag editor), and a search field "Search Tag folders". The list: each folder's name with "(N tags)", and its description under the name when it has one. It loads 50 folders at a time as you scroll. An open folder shows "Add New Tag" at the top (needs "Manage Tags"), then its tags, each with the number of tasks that use it, as "(0)".
3. **Right column (two thirds).** The selected folder's name and description, with "Edit", "Delete tag folder" and "CSV upload" (with a help popover), all needing "Edit Tag Folders". Below, the "Groups" card: "Search Groups", the text "Switch on up to groups to grant them access to the selected tag folder.", the switch "Enable tag folder in all Groups", one switch per group, and "Cancel" and "Save", disabled until a switch changes. The card lists every live task group of the site, so it is often far longer than a user's own group list.
4. **Multi-select bar.** In multi-select: "N tag folder(s) selected", "Select Loaded Tag Folders", "Delete Selected" and a close button.

## Inputs

### Tag folder (create and edit)

| Field                               | Type | Required       | Default                           | Rules and messages                                                                                                                                                                                                                                 |
| ----------------------------------- | ---- | -------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Tag Folder Name \*"                | Text | On create only | Empty, or the current name        | Placeholder "Enter Tag Folder Name". Up to 20 characters. Empty on create: "Enter Tag Folder Name". Longer: "Your input exceeds the maximum allowed length of 20 characters". On edit the name can be cleared; the server then keeps the old name. |
| "Tag Folder Description (optional)" | Text | No             | Empty, or the current description | Placeholder "Enter Tag Folder Description". Up to 255 characters.                                                                                                                                                                                  |

"Save" is disabled while the form is invalid; on edit it also needs a change.

### Tag

* **Name:** up to 100 characters, unique in its folder. The inline "Add New Tag" field has no limit and no message, so a longer name can be typed. A blank name is not saved. A name that already exists in the folder is skipped with no message.
* **Search:** "Search Tag folders" asks the server 300 ms after typing stops.

### CSV upload

* **File:** one column, one tag per row. The help popover says: "Upload a list of tags all at once using a CSV file. The CSV file should only contain a single column with all the tags you'd like to add."
* **Review:** one field per tag, with a remove button. A blank tag shows "Please enter a tag name", a tag over 100 characters shows the length message, and a repeated row shows "Tag name already exists". "Create" is disabled while the list is empty or invalid.

## Actions

| Action            | Who                        | What happens                                                                                                                                                                                                                                                                | API                                                                    |
| ----------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Load the folders  | Role "Admin", group admins | Lists the folders, 50 at a time, with the search text.                                                                                                                                                                                                                      | [Tags API](https://docs.snapfix.com/engineering-reference/api/tags.md) |
| Open a folder     | Role "Admin", group admins | Lists its tags with their task counts, its details and its groups.                                                                                                                                                                                                          | [Tags API](https://docs.snapfix.com/engineering-reference/api/tags.md) |
| Add Folder        | "Edit Tag Folders"         | "Create New Tag Folder", then "Save". The list reloads.                                                                                                                                                                                                                     | [Tags API](https://docs.snapfix.com/engineering-reference/api/tags.md) |
| Edit              | "Edit Tag Folders"         | "Edit Tag Folder", then "Save" changes the name or the description.                                                                                                                                                                                                         | [Tags API](https://docs.snapfix.com/engineering-reference/api/tags.md) |
| Delete tag folder | "Edit Tag Folders"         | "Deleting tags": "Deleting this tag folder will permanently remove all its tags. Are you sure you want to continue?" with "Cancel" and "Delete". A failure shows the API's message, then an alert with the raw key "TAG.ERROR\_DELETING\_FOLDER", which has no translation. | [Tags API](https://docs.snapfix.com/engineering-reference/api/tags.md) |
| Delete Selected   | "Edit Tag Folders"         | First asks with counts: "You're about to delete N tag folder(s) (M empty). This will remove T tag(s) and affect K task(s). Do you want to proceed?", which can show raw HTML tags as text. Then deletes the folders and confirms with "You've deleted N tag folder(s)".     | [Tags API](https://docs.snapfix.com/engineering-reference/api/tags.md) |
| Add New Tag       | "Manage Tags"              | Type a name in the open folder and press Enter or "+".                                                                                                                                                                                                                      | [Tags API](https://docs.snapfix.com/engineering-reference/api/tags.md) |
| Merge Tags        | "Manage Tags"              | Opens "Edit Tags / Merge Tag Folders" ([Dialogs and sheets](#dialogs-and-sheets)).                                                                                                                                                                                          | None until "Save"                                                      |
| CSV upload        | "Edit Tag Folders"         | Opens the browser's file picker, then the review dialog "CSV upload". "Create" saves the tags into the folder; tags that already exist are skipped with no message.                                                                                                         | [Tags API](https://docs.snapfix.com/engineering-reference/api/tags.md) |
| Groups            | Role "Admin", group admins | Each group switch, or "Enable tag folder in all Groups", marks a change; "Save" sends only the changed groups, "Cancel" restores them.                                                                                                                                      | [Tags API](https://docs.snapfix.com/engineering-reference/api/tags.md) |

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

## States

* **Loading:** spinners in the folder list, in a folder's tag list while it loads, and in the groups card.
* **Empty:** "No tag folders found" when the site has no folders or the search matches none; "No tags found" in an empty folder; "No data available" in the groups card.
* **Error:** failed saves show the API's message; a failed folder delete adds the raw-key alert above.
* **No permission:** without "Edit Tag Folders", "Select Tag Folders", "Add Folder", "Edit", "Delete tag folder" and "CSV upload" are hidden. Without "Manage Tags", "Merge Tags" and "Add New Tag" are hidden. Members who are neither role "Admin" nor group admins never reach the route.

## Dialogs and sheets

* **Create New Tag Folder / Edit Tag Folder:** see [Inputs](#tag-folder-create-and-edit), with "Cancel" and "Save".
* **Edit Tags / Merge Tag Folders:** a dialog about 1,040 pixels wide and 90 percent of the screen high, with "Search tags", two folder panels, and "Cancel" and "Save" ("Save" is disabled until a change). The hint reads "Selete a second tag folder if you wish to drag-and-drop, copy, paste, and merge tags and tag folders". Each panel shows a folder's tags with Undo, Copy, Paste and Delete; tags can be dragged between the panels, and the two panels cannot show the same folder. Merging two folders asks first, saying "Tag folders store only unique tags. When folders are merged, any duplicate tags will be combined into one." and that the tags will be enabled in every group that had either folder; a failed merge shows "Failed to merge tag folders. Please try again." Deleting tags asks "These tags will be removed from all items where they're currently applied. Delete the selected tags permanently?", and "Undo" can bring them back until "Save". "Save" applies the pending deletes, then adds and renames, then moves.
* **Cancel Changes:** "Cancel" in the editor always asks "Cancel Changes" / "Changes were not saved. Any unsaved changes will be lost. Do you want to Continue?" with "Cancel" and "OK", even when nothing changed. Both buttons close the editor, so "Cancel" in this prompt also drops the pending changes.
* **Deleting tags:** the folder delete confirmation in [Actions](#actions).
* **CSV upload:** the file picker, then the review dialog ([Inputs](#csv-upload)).

## Platform differences

Web only. The apps manage the tags of each group in [Group settings](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-settings.md), with no site-wide folder list, merge or CSV import. The group settings import reports "Saved {saved} tags of {total}"; this page's import does not.


---

# 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/tags.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.
