> 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/product/features/compliance/comply.md).

# Comply

{% 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)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/comply.md).
{% endhint %}

**Comply** is the compliance module of the web app, for site admins. Admins keep the site's **compliance systems**, filed under **system types**, the **contractors** who work on them, and their **compliance documents**. The **Comply dashboard** shows what is out of compliance, what expires soon, which **compliance tasks** (tasks linked to a system) are overdue or due, and which documents have expired or expire soon, with a PDF report to download. The **timeline** shows the same items as bars over time. The mobile apps have no Comply pages: they show a notice that Comply is on the web, and they can still link a compliance system to a task or a planned task.

## Rules

### Who uses it

* Only site admins (role "Admin" on the current site) use Comply. The side menu hides "Comply" from everyone else, and the pages send anyone else, group admins included, to Fix ([Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/compliance/dashboard.md#getting-here)).
* The API is wider than the pages. Writes, the overviews and two of the timelines need the site's admin role, but the system type, system, contractor and document lists, and the system type and contractor timelines, answer any member of the site; the two sort endpoints check membership only. Which reads members should get is open \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)] ([Compliance API](https://docs.snapfix.com/engineering-reference/api/compliance.md)).
* No plan, package or site setting turns Comply on or off; every site admin has it ([Subscriptions](https://docs.snapfix.com/product/features/billing/subscriptions.md)).
* Comply works on one site at a time. With a multi-site selected, a site dropdown on the tab bar picks the site ([Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/compliance/dashboard.md#layout)).
* The page opens the tab last used on that site, and the timeline its last filter ([Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/compliance/dashboard.md), [Timeline](https://docs.snapfix.com/how-the-apps-work/screens/compliance/timeline.md)).

### Setup

* A site with no system types gets two default types, "Company Certificates" and "Fire Safety", with their systems, the first time the Dashboard or the Systems tab opens. Two first loads at once can create two sets. The default systems get a frequency but no expiry alert, so they never turn amber until someone sets one \[[ASK-140](https://github.com/snapfix/docs/blob/main/ASK.md#ask-140-should-the-default-compliance-systems-get-the-30-day-expiry-alert)] ([`POST /v1/app/parents/comply-defaults`](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appparentscomply-defaults)).
* When that call creates nothing, the Dashboard and the Systems tab ask again after each empty answer, for as long as they are open.

### The dashboard

* A system is out of compliance once its expiry date has passed, expiring within its alert days before that, and in compliance otherwise, also when it has no expiry date. The details are in [Compliance systems](https://docs.snapfix.com/product/features/compliance/compliance-systems.md#status).
* "Compliance Tasks" counts the tasks of the site's live groups that have a live link to a compliance system. "Overdue": the due date has passed and the task is not green, or turned green after its due date. "Due Today": due today in the user's time zone and not green. "Due Soon": due from tomorrow to 30 days ahead and not green ([task overview](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appcomplyoverviewjobparentuuid)).
* "High Priority" and "Medium Priority" also count finished tasks.
* The task boxes do not check the linked system: a system of another site counts, and so do deleted systems and systems under a deleted type.
* The document boxes follow [Compliance documents](https://docs.snapfix.com/product/features/compliance/compliance-documents.md#rules): "Expiring" uses a fixed 30-day window \[[ASK-110](https://github.com/snapfix/docs/blob/main/ASK.md#ask-110-should-expiring-documents-use-a-fixed-30-day-window)].
* The dashboard loads its four overviews as one batch. On the QA site the task overview took from about a minute to over 90 seconds, and when it failed every card stayed empty, and the error alert offers no retry ([Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/compliance/dashboard.md#states)).
* "Download" builds the compliance report as a PDF and downloads it. Each click stores a new file, and old ones are never removed. Whether the file's plain link opens without a sign-in is open ([`GET /v1/app/report/comply`](https://docs.snapfix.com/engineering-reference/api/reports.md#get-v1appreportcomply)).
* A box with a count opens the list behind it: tasks open their task, documents their system or contractor ([Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/compliance/dashboard.md#dialogs-and-sheets)).

### The timeline

* The timeline shows system types, the systems of one type, contractors, or the tasks linked to one type's systems, on a month or week chart. Each item is green from the day it was created, amber from the start of its alert window and red from its expiry ([Timeline](https://docs.snapfix.com/how-the-apps-work/screens/compliance/timeline.md), [timeline item](https://docs.snapfix.com/engineering-reference/api/compliance.md#timeline-item-object)).
* Expiry days are worked out in the site's time zone ([Compliance API](https://docs.snapfix.com/engineering-reference/api/compliance.md#timeline-item-object)).
* The "Tasks" view fails when any of the type's linked tasks is a planned task, and then looks empty. A failed timeline request always looks like a site with no data.

### The apps

* iOS and Android show a notice that Comply is live on the web, "available to your Account Admins", to every user, with no role check \[[ASK-114](https://github.com/snapfix/docs/blob/main/ASK.md#ask-114-who-should-see-comply-in-the-mobile-apps)] ([Comply notice](https://docs.snapfix.com/how-the-apps-work/screens/compliance/mobile-notice.md)). The iOS text has a typo.
* The apps download the sites' system types, systems and task links, and upload the task links made on the phone, so tasks can be linked to a system ([`?action=read_parent_comply_data`](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-actionread_parent_comply_data), [`?action=save_job_comply_system`](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-actionsave_job_comply_system)). Neither action checks the caller's sites or tasks.

## Flow

```mermaid
flowchart TD
    menu["Side menu: Comply"] --> admin{"Site admin?"}
    admin -- no --> fix["Sent to Fix"]
    admin -- yes --> tabs["Dashboard, Timeline, Systems, Contractors, Folders"]
    tabs --> dash["Dashboard: load four overviews"]
    dash --> none{"No system types?"}
    none -- yes --> defaults["Create the default types and systems, then load again"]
    dash --> boxes["Counts; a count opens its list"]
    dash --> report["Download the PDF report"]
    tabs --> timeline["Timeline: types, systems, contractors or tasks"]
    tabs --> records["Systems, Contractors and Folders"]
    task["A task, on the web or in the apps"] --> link["Link it to a system"]
    link --> dash
```

## Platforms

| Capability                                            | Web                                 | iOS                                | Android                                      |
| ----------------------------------------------------- | ----------------------------------- | ---------------------------------- | -------------------------------------------- |
| Dashboard, Timeline, Systems, Contractors and Folders | Site admins                         | No                                 | No                                           |
| Comply notice                                         | No                                  | Plan > "Comply", and the side menu | The "Comply" chip on Plan, and the side menu |
| Download the compliance report                        | Site admins                         | No                                 | No                                           |
| Link a task to a system                               | The task's compliance system dialog | The tagging sheet                  | The tagging sheet                            |
| Pick a system for a planned task                      | The editor's compliance section     | Yes                                | Yes                                          |

## Screens

* [Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/compliance/dashboard.md) and [Timeline](https://docs.snapfix.com/how-the-apps-work/screens/compliance/timeline.md)
* [Systems](https://docs.snapfix.com/how-the-apps-work/screens/compliance/systems.md) and [System detail](https://docs.snapfix.com/how-the-apps-work/screens/compliance/system-detail.md)
* [Contractors](https://docs.snapfix.com/how-the-apps-work/screens/compliance/contractors.md) and [Contractor detail](https://docs.snapfix.com/how-the-apps-work/screens/compliance/contractor-detail.md)
* [Folders](https://docs.snapfix.com/how-the-apps-work/screens/compliance/folders.md)
* [Comply](https://docs.snapfix.com/how-the-apps-work/screens/compliance/mobile-notice.md): the notice in the apps
* [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#compliance-system): a task's compliance system

## API and data

* [Compliance API](https://docs.snapfix.com/engineering-reference/api/compliance.md): the four overviews, from [`GET /v1/app/comply/overview/system-type/{parentUuid}`](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appcomplyoverviewsystem-typeparentuuid) on; the four timelines, from [`GET /v1/app/comply/timeline/system-type/{parentUuid}`](https://docs.snapfix.com/engineering-reference/api/compliance.md#get-v1appcomplytimelinesystem-typeparentuuid) on; the defaults, [`POST /v1/app/parents/comply-defaults`](https://docs.snapfix.com/engineering-reference/api/compliance.md#post-v1appparentscomply-defaults); and the apps' two php-apis actions.
* [`GET /v1/app/report/comply`](https://docs.snapfix.com/engineering-reference/api/reports.md#get-v1appreportcomply): the PDF behind "Download".
* Tables: [`comply_SystemType`](https://docs.snapfix.com/engineering-reference/db/tables/comply_systemtype.md), [`comply_System`](https://docs.snapfix.com/engineering-reference/db/tables/comply_system.md), [`comply_Contractor`](https://docs.snapfix.com/engineering-reference/db/tables/comply_contractor.md), [`comply_Document`](https://docs.snapfix.com/engineering-reference/db/tables/comply_document.md), [`comply_DocumentType`](https://docs.snapfix.com/engineering-reference/db/tables/comply_documenttype.md), [`tPri_JobComplySystem`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobcomplysystem.md) (task links) and [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) (tasks).

## Depends on

* [Compliance systems](https://docs.snapfix.com/product/features/compliance/compliance-systems.md), [Contractors](https://docs.snapfix.com/product/features/compliance/contractors.md) and [Compliance documents](https://docs.snapfix.com/product/features/compliance/compliance-documents.md): the records Comply keeps, and their status rules.
* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md) and [Planned tasks](https://docs.snapfix.com/product/features/planner/planned-tasks.md): compliance tasks are ordinary tasks linked to a system, by hand or by a planner.
* [Task reports](https://docs.snapfix.com/product/features/reports/task-reports.md): the reports backend that builds the PDF.
* [Asset registers](https://docs.snapfix.com/product/features/assets/asset-registers.md): the assets that systems and contractors link to.
* [Site users](https://docs.snapfix.com/product/features/console/site-users.md): the site admin role, and the users assigned to systems and contractors.
* [Site switching](https://docs.snapfix.com/product/features/groups/site-switching.md): Comply follows the current site.
* [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md): linking a task to a system pushes to the task's people.

## Edge cases

* **Not a site admin:** the menu item is hidden, and a Comply address sends the user to Fix. The API still answers some reads \[[ASK-112](https://github.com/snapfix/docs/blob/main/ASK.md#ask-112-which-comply-reads-should-members-who-are-not-admins-get)].
* **Unknown address:** a `/comply/...` address that is not a page goes to a page that does not exist.
* **Slow or failed dashboard:** every card stays empty, with no retry.
* **Failed lists:** a failed system or contractor list leaves the Comply tabs disabled until the page reloads.
* **Deleted items:** a deleted system type leaves its systems unreachable; tasks of deleted systems still count on the dashboard; documents of deleted systems and contractors leave Folders and the dashboard.
* **Large sites:** no Comply list is paged.
* **Time zones:** "Due Today" and "Due Soon" follow the user's time zone offset; expiry checks compare with the server's clock, and the timeline's expiry days use the site's time zone.
* **Offline:** the web needs a connection. The apps' notice works offline, and their task links sync later.
* **Several sites:** each page shows one site.


---

# 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/product/features/compliance/comply.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.
