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

# QR management

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

Staff build the QR forms that people scan to report a problem or send a request, with their pages and fields, for each task group; they also copy a form's link, show its QR code, download its JSON and delete it.

* **Where:** admin app `/qr-management`; menu "QR Management". The [Groups](https://docs.snapfix.com/how-the-apps-work/screens/staff/groups.md) page's "Group QRs" button opens it for a group, with the site's name and the group's ID in the address (webadmin\_angular @ db972390b8, `src/app/pages/groups/groups.component.html:98-100`).
* **Who:** any signed-in staff user. The route checks only that a session exists; the QR form routes take only staff tokens on the server ([Staff API](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminqr-form)).
* **Feature:** [QR forms](https://docs.snapfix.com/product/features/qr/qr-forms.md)

## Layout

1. The title "QR Management", then a round "+" button with the text "Create a new QR form".
2. Two pickers above the table:
   * "Select an Account": the site picker ("Type to search account"). The first site found is chosen when the page opens. From the Groups page it searches for the site's name and takes the first result, which can be another site whose name contains that name.
   * "Select a Group", with the same placeholder: the site's task groups only, sorted by name, deleted ones in red. It can be cleared. The group from the Groups page link is chosen, or else the first group.
3. The forms table, 10 rows per page by default (10, 20, 50 or 100) with a page jump. Columns:
   * "Form Type", "In App Title" and "Poster Title", each with a search, and sortable.
   * "Poster Description": the first 100 characters, then "..." when longer, with the full text on hover.
   * "QR": "Preview" (a QR code of the form's web link in a popover; the link ends in the form's ID), "Copy QR Url" and "Download QR JSON".
   * "Action", fixed at the right: edit and delete.

Edit is disabled, with the tooltip "Legacy forms cannot be edited", for the types `basic_v1`, `basic_v2`, `radiobuttons_v1` and `dropdown_v1`; legacy forms can still be deleted. Stored radio-button forms are `radiobutton_v1`, so they still open in the editor.

## Inputs

| Field                                                       | Type                                | Required | Default              | Rules and messages                                                                                                                                                                                                        |
| ----------------------------------------------------------- | ----------------------------------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Select an Account                                           | Search select                       | No       | The first site found | Searches site names on the server 1 second after typing. Choosing a site loads its task groups.                                                                                                                           |
| Select a Group                                              | Select, searchable and clearable    | No       | See Layout           | Choosing a group loads its forms. Clearing it sends the list request with the text `undefined` as the group, which the server answers `404`, so the table keeps the previous group's rows.                                |
| Column search ("Form Type", "In App Title", "Poster Title") | Text, from the column's search icon | No       | Empty                | "Search" and "Reset" as on [SMS/E-mail delivery](https://docs.snapfix.com/how-the-apps-work/screens/staff/sms-email-delivery.md#inputs); the box says "Search name". A contains-match ignoring case, on the loaded forms. |

## Actions

| Action                       | Who   | What happens                                                                                                                                                                       | API                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Choose a site                | Staff | Lists the sites, then loads the chosen site's groups and the forms of the group it selects.                                                                                        | [`GET /v4/parents`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v4parents), [`POST ?action=admin_read_pri_business`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_read_pri_business), [`GET /v1/admin/qr-form`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminqr-form) |
| Choose a group               | Staff | Loads the group's forms.                                                                                                                                                           | [`GET /v1/admin/qr-form`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminqr-form)                                                                                                                                                                                                                                           |
| "+" ("Create a new QR form") | Staff | Opens [Create QR Form](#create-qr-form-and-edit-qr-form) for the selected group. It is disabled only while a delete runs, so it also opens with no group, and the save then fails. | None                                                                                                                                                                                                                                                                                                                                                |
| Edit                         | Staff | Opens [Edit QR Form](#create-qr-form-and-edit-qr-form) with the form's content. Disabled for legacy types and while a delete runs.                                                 | None                                                                                                                                                                                                                                                                                                                                                |
| "Copy QR Url"                | Staff | Copies the form's web link and shows "QR url copied to clipboard.".                                                                                                                | None                                                                                                                                                                                                                                                                                                                                                |
| "Download QR JSON"           | Staff | Downloads the form's content as `<form type>-<creation time in ms>.json`. The file is cut short at the first "#".                                                                  | None                                                                                                                                                                                                                                                                                                                                                |
| Delete                       | Staff | Asks "Are you sure you want to delete the item?" with a danger "Delete". On success "Success" shows and the row goes; a refusal shows the server's message.                        | [`DELETE /v1/admin/qr-form/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#delete-v1adminqr-formuuid)                                                                                                                                                                                                                          |

## States

* **Loading:** the two pickers and the table show their loading state.
* **Empty:** a group with no forms shows an empty table.
* **Error:** the group and form lists show no error message. When the group list fails, the group picker stays empty and the table keeps loading. When the form list fails, the table keeps the previous group's forms, and edit and delete act on them.
* **No permission:** none in the app.

## Dialogs and sheets

### Create QR Form and Edit QR Form

"Create QR Form" or "Edit QR Form", 1100 px wide, in five steps that can be opened in any order: "QR Info" ("Web/Mobile App"), then "Page Form", "Components", "Page Success" and "Page Fail" (each "QR App"). Each step shows an error mark until it is valid. Footer: "Import" at the left, "Cancel" and "Save".

**QR Info.** A new form gets the type `dynamic_v1`, which has no field; an edited form keeps its type.

| Field                             | Type      | Required                   | Default                                                              | Rules and messages                                                     |
| --------------------------------- | --------- | -------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| In App Title                      | Text      | Yes                        | Empty                                                                | Up to 25 characters. "In App Title is required."                       |
| Poster Title                      | Text      | Yes                        | Empty                                                                | Up to 25 characters. "Poster Title is required."                       |
| Poster Description                | Text area | Yes                        | "This QR will ask the user for some basic details and create a task" | Up to 200 characters. "Poster Description is required."                |
| Poster Hacker Warning             | Checkbox  | No                         | Off                                                                  | Ticking it makes the next field required.                              |
| Poster Hacker Warning Description | Text area | When the warning is ticked | "You will never be asked for a username or password"                 | Up to 200 characters. "Poster Hacker Warning Description is required." |

**Page Form.**

| Field                              | Type                            | Required | Default       | Rules and messages                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------- | ------------------------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Title                              | Text                            | Yes      | Empty         | Up to 40 characters; placeholder "Report issues, requests and feedback". "Title is required."                                                                                                                                                                                                                                                                                                              |
| Submit Button Text                 | Text                            | Yes      | "Submit"      | Up to 10 characters. "Submit Button Text is required."                                                                                                                                                                                                                                                                                                                                                     |
| Header Image Url, Footer Image Url | Web address, with an eye button | Yes      | A stock image | "Header Image Url is required." (or "Footer"), "... is not valid." for a bad address or an image that does not load, and "The image should be square, with a maximum dimension of 500x500 pixels.". The eye button shows the image full size and is disabled while the field has an error. Each change loads the image again to check it, and a slow earlier check can mark or clear the field afterwards. |

**Components.** A type select ("Image", "Singleline", "Multiline", "Radiobuttons" or "Dropdown", "Image" first) and a "+" button with "Add Component" add a component at the end. Components are dragged by their handle to reorder and deleted with their own button. "Image" can be added once; its option is then disabled. "Job Title" and "Job Description" can each be the target of one component only: a target in use is disabled in the other components.

| Field                                                 | Type                                                     | Required                                       | Default                                                                    | Rules and messages                                                                          |
| ----------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| ID                                                    | Text, read-only                                          |                                                | The component type                                                         |                                                                                             |
| Label ("Component Label")                             | Text                                                     | Yes                                            | Empty                                                                      | Up to 35 characters. "Label is required."                                                   |
| Hint ("Component Hint")                               | Text                                                     | No                                             | Empty                                                                      | Up to 35 characters on "Image", 50 on the others.                                           |
| Mandatory                                             | Checkbox                                                 | No                                             | Off                                                                        | Every type.                                                                                 |
| Target                                                | Multi-select: "Job Title", "Job Description", "Job Chat" | Yes, except on "Image"                         | The first free target; "Multiline" takes "Job Description" when it is free | "Target is required."                                                                       |
| Input Type                                            | Select: "Text" or "Email"                                | Yes, on "Singleline"                           | "Text"                                                                     | "Input Type is required."                                                                   |
| Content items                                         | List                                                     | At least one, on "Radiobuttons" and "Dropdown" | One empty item                                                             | Items are dragged to reorder; an item's delete button is disabled while it is the only one. |
| Item Text ("Component Item Text")                     | Text                                                     | Yes                                            | Empty                                                                      | Up to 100 characters. "Text is required."                                                   |
| Item Hint ("Component Item Hint")                     | Text                                                     | No                                             | Empty                                                                      | Up to 50 characters.                                                                        |
| Item Job Chat Message ("Component Item Chat Message") | Text                                                     | No                                             | Empty                                                                      | Up to 100 characters.                                                                       |
| Item Default                                          | Checkbox                                                 | No                                             | Off                                                                        | One item at a time.                                                                         |

On save, and on import, the app checks the set as a whole and stops with "Image component must be unique.", "Input type must be either text and email." or "tPri\_Job.fTitle or tPri\_Job.fDescription must be unique.", the last naming internal fields.

**Page Success and Page Fail.** The same fields, with different defaults.

| Field                                     | Type                            | Required | Default                                                | Rules and messages                                                                                                 |
| ----------------------------------------- | ------------------------------- | -------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| Title                                     | Text                            | Yes      | "Thank you!" (success), "Something went wrong!" (fail) | Up to 40 characters. "Title is required."                                                                          |
| Repeat Button Text                        | Text                            | Yes      | "Report another issue" (success), "Try again" (fail)   | Up to 25 characters. "Repeat Button Text is required."                                                             |
| Text                                      | Text                            | No       | "Issue submitted successfully" (success), empty (fail) | Up to 50 characters.                                                                                               |
| Header Image Url, Footer Image Url        | Web address, with an eye button | Yes      | A stock image                                          | As on Page Form.                                                                                                   |
| Enable Shareable Link                     | Switch                          | No       | On                                                     | Success page only.                                                                                                 |
| Promotion: Text ("Promotion Text")        | Text                            | Yes      | "The simplest maintenance platform in the world."      | Up to 50 characters. "Text is required."                                                                           |
| Promotion: Button Text                    | Text                            | Yes      | "Learn More"                                           | Up to 25 characters. "Button Text is required."                                                                    |
| Promotion: Button Link                    | Web address                     | Yes      | A stock link                                           | "Button Link is required." or "Button Link is not valid."                                                          |
| Promotion: Main Image Url, Logo Image Url | Web address, with an eye button | Yes      | Stock images                                           | "Main Image Url is required." or "Logo Image Url is required.", "... is not valid.", and the square-image message. |

| Action   | Who   | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | API                                                                                                                                                                                                                                            |
| -------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Save"   | Staff | Disabled until all five steps are valid and there is at least one valid component. Sends the type, the three titles, the hacker warning and its text, and the form's pages; a new form goes to the selected group. On success "Success" shows, the dialog closes, and the row is added at the end or updated. A refusal shows the server's message and the dialog stays open, for example "The selected group does not have an admin assigned. Please add an admin to the group before creating the QR code." While saving, "Save" shows a spinner and "Import", "Cancel", the close button and a click outside do nothing. | [`POST /v1/admin/qr-form`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminqr-form) (new), [`PUT /v1/admin/qr-form/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#put-v1adminqr-formuuid) (edit) |
| "Import" | Staff | Opens [Import QR JSON schema](#import-qr-json-schema).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | None                                                                                                                                                                                                                                           |
| "Cancel" | Staff | Closes without saving.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | None                                                                                                                                                                                                                                           |

### Import QR JSON schema

"Import QR JSON schema", 700 px wide, with the tabs "JSON File" and "JSON Editor".

* **JSON File:** a drop area, "Upload JSON file", for a `.json` file. A file whose type is not JSON gets "Please upload correct json file!", and an empty one "Unable to read imported file data.". A file that is read opens in the editor tab; a file that is not valid JSON gives no message.
* **JSON Editor:** a code editor that checks the text against the QR form schema, which requires `page_form`, `page_success` and `page_fail`.

| Action   | Who   | What happens                                                                                                                                                                                                     | API  |
| -------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| "Import" | Staff | Enabled when the JSON passes the schema; pressing it runs the component checks above. Fills the Page Form, Components, Page Success and Page Fail steps and opens "Page Form"; the QR Info step does not change. | None |
| "Cancel" | Staff | Closes.                                                                                                                                                                                                          | None |


---

# 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/qr-management.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.
