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

# Task reports

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

Create spreadsheet and PDF reports from the tasks picked in the filters, then download them from the list of the user's reports of the last 30 days. Task, asset and site reports share this layout and list: [Asset reports](https://docs.snapfix.com/how-the-apps-work/screens/reports/asset-reports.md) and [Site reports](https://docs.snapfix.com/how-the-apps-work/screens/reports/site-reports.md) describe only what differs.

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

* **Where:** web `/dashboard-reports/task-reports`, the "Task Reports" tab of "Dashboard & Reports"
* **Who:** any signed-in user can open the page. Creating a report needs the group permission `perJobReportGenerate` in every group of the filters. Only the browser checks it; the report actions do not. The report types are not limited by the plan \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)].
* **Feature:** [Task reports](https://docs.snapfix.com/product/features/reports/task-reports.md)

## Layout

The page has the header, the tabs, the title "Task Reports" with the filter button, and the filter banner, as on the [Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/reports/dashboard.md#layout). Below them, two columns:

1. **Left: "Select a report to create".** The text "Please set your filters to see the required information", the "Create" button, and the six report types ([Inputs](#inputs)) as cards, one under the other. "Create" is off until a card is picked. "Create" is not drawn, and the cards cannot be picked, while the site has no group loaded.
2. **Right: "Your reports".** One card per report, ten a page with a choice of 5, 10, 25 or 100 ("Items per page"). Each card shows the report's name, its status (a progress ring and the status text), the file type ("XLSX" or "PDF"), the date it was made, a delete button and "Download".

The name is the stored report type in words with its first letter capital, cut at 25 characters and followed by "..." when longer. For a single-task report it is the task's title. So PDF multi-task reports are named "Multi tasks report" in the list, while the picker calls the type "Multi-Task Report (PDF)". The status is the last part of the server's status in words with its first letter capital, such as "In progress", "Completed" or "No tasks found" ([`reportStatus`](https://docs.snapfix.com/engineering-reference/api/reports.md#report-object)); the page shows it in capitals ("COMPLETED", "NO TASKS FOUND").

## Inputs

| Field       | Type                                                                                                                      | Required | Default                                                                                        | Rules and messages                                                                                                                                                                                                                                                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Report type | One of the six cards below                                                                                                | Yes      | None                                                                                           | A click picks the card; a second click clears it. "Create" stays off until a card is picked, so the alert "Please select a report type" is not reached from the page.                                                                                                                                                                                    |
| Filters     | The shared filters, as on the [Dashboard](https://docs.snapfix.com/how-the-apps-work/screens/reports/dashboard.md#inputs) | No       | Active tasks; all three statuses; created in the last month; the user's own groups of the site | They go with the report as the [report filter fields](https://docs.snapfix.com/engineering-reference/api/reports.md#report-filter-fields). An empty group selection is applied as every group again. Archived tasks go as `archived_tasks` here. Priority goes as `priorityLevel`, which the report actions do not read, so it does not change the file. |

The six report types, in the order the page shows them:

| Report                           | File | Description on the card                                                                                                                                                           | API                                                                                                                                     |
| -------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| "Multi-Task Report (export)"     | XLSX | "Spreadsheet report of multiple tasks."                                                                                                                                           | [`report_task_detail_excel`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actionreport_task_detail_excel)         |
| "Multi-Task Report (PDF)"        | PDF  | "PDF report of multiple tasks, including photos."                                                                                                                                 | [`multi_tasks_report_pdf`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actionmulti_tasks_report_pdf)             |
| "Completed tasks by user report" | XLSX | "Daily and weekly sum of completed tasks by users. Great for getting insights into workload."                                                                                     | [`completed_tasks_report_excel`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actioncompleted_tasks_report_excel) |
| "Time report"                    | XLSX | "Shows key timestamps for tasks to get insights into how long it takes to complete tasks."                                                                                        | [`report_time_excel`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actionreport_time_excel)                       |
| "Checklist report"               | XLSX | "Contains task level summary and individual checklist item details and audit lines. Ideal for deepdiving into exceptions." and the note "(Works only for tasks with checklists.)" | [`checklist_report_excel`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actionchecklist_report_excel)             |
| "Inspection report"              | PDF  | "Shows a visual representation of a checklist. Ideal for compliance documentation." and the note "(Works only for tasks with checklists.)"                                        | [`inspection_report`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actioninspection_report)                       |

Each type carries the name of a plan switch, such as `taskdetailreport_enabled`. The web never reads these switches, so no card is locked by the plan. The iOS and Android task lists read four of them to dim their own report items \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)].

## Actions

| Action             | Who                                                                          | What happens                                                                                                                                                                                                                                                                                                                                                                    | API                                                                                                                 |
| ------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Pick a report type | Any signed-in user                                                           | Selects the card, or clears it on a second click. No request.                                                                                                                                                                                                                                                                                                                   | None                                                                                                                |
| Create             | Any signed-in user with `perJobReportGenerate` in every group of the filters | Checks each selected group; on the first group without the permission, shows the permission alert and stops. Otherwise sends the filters to the type's action. The button shows a loading state, then a success state for 1.5 seconds; then the card is cleared and the new report goes to the top of "Your reports". A refused request shows the server's message in an alert. | The type's action (table above)                                                                                     |
| Load the list      | Any signed-in user                                                           | Loads the user's reports on open and again after every filter change. The filters do not change what the list holds.                                                                                                                                                                                                                                                            | [`user_reports`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actionuser_reports)             |
| Download           | Anyone who sees the report                                                   | Only at 100%: downloads the file from its link, or opens the link when the download fails, then shows a success state for 1.5 seconds. The file is public to anyone with the link. The button stays enabled for pending and failed reports and does nothing for them.                                                                                                           | None (the link comes with the report)                                                                               |
| Delete             | The report's owner                                                           | Opens "Delete report"; on "Delete", removes the report, shows a success state for 1.5 seconds and drops the card. The file stays on the server \[[ASK-120](https://github.com/snapfix/docs/blob/main/ASK.md#ask-120-should-the-report-pages-say-how-long-reports-stay)].                                                                                                        | [`delete_user_report`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actiondelete_user_report) |
| Change page        | Any signed-in user                                                           | Pages through the list in the browser.                                                                                                                                                                                                                                                                                                                                          | None                                                                                                                |

The list holds the user's reports from the last 30 days, also the single-task reports made from a task's share dialog ([Share task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#share-task)). Nothing on the page says that older reports drop off the list \[[ASK-120](https://github.com/snapfix/docs/blob/main/ASK.md#ask-120-should-the-report-pages-say-how-long-reports-stay)].

When the page opens, it asks the survey tool (Survicate) to show the survey for `WebReportsTasksScreen`, with the site's ID, name and customer type and the user's role \[[ASK-116](https://github.com/snapfix/docs/blob/main/ASK.md#ask-116-may-the-survey-tool-receive-users-contact-details-and-site-names)].

## States

* **Loading:** the list shows the loading animation until the answer arrives; a filter change empties the list first. Download and delete show a loading state on their card.
* **Empty:** "No data available", with "0 of 0" in the pager. The API answers "no reports found!" as an error, and the page shows the empty text.
* **Error:** the list request skips the app's error dialog, so a failed list looks empty. A failed create or delete shows the server's message in an alert and keeps the list as it was.
* **Pending:** a report below 100% shows a partly filled progress ring. While any report made in the last 24 hours is below 100%, the page asks for the list again every 8 seconds. A failed report stays below 100% (`completionPercent` -1), so it keeps the polling going until it is a day old.
* **Failed:** a failed report shows the failure as its status, for example "NO TASKS FOUND", and its "Download" does nothing.
* **No permission:** the permission alert, under [Dialogs and sheets](#dialogs-and-sheets).
* **Offline (mobile):** not applicable, web only.

## Dialogs and sheets

* **Permission alert:** "The group does not have the permissions needed to generate this report. Please uncheck that group from the Groups filter and try again." The group's name is in bold, and it goes into the message as HTML.
* **Delete report:** titled "Delete report", asking "Are you sure you want to delete this ""?" with the name in bold, and the buttons "Cancel" and "Delete".
* **Report type alert:** "Please select a report type". Not reachable, as under [Inputs](#inputs).
* **Filters:** the shared filter drawer ([Filters](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md#filters)).

## Platform differences

Web only for the report list and the spreadsheet reports. The apps have no report list. Their group, room and area task lists have "Share Multi Task Report (PDF)", which builds the PDF at once through [`business_job_report`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actionbusiness_job_report), [`room_job_report`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actionroom_job_report) or [`area_job_report`](https://docs.snapfix.com/engineering-reference/api/reports.md#post-actionarea_job_report), and a task makes its own report from its share action ([Share task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#share-task)).


---

# 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/reports/task-reports.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.
