> 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/planner/plan-calendar.md).

# Plan calendar

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

The **Plan calendar** shows the **planned tasks** coming up, day by day, for the whole site or for one group. On the web it is a month calendar beside the planners, with the dates to come listed beside it. On the apps it shows a week or a month at a time, with the planned tasks listed under it. People pick a day to jump to it, filter the list and open any planned task from it. Planners are set up and changed in [Planned tasks](https://docs.snapfix.com/product/features/planner/planned-tasks.md).

## Rules

### What is listed

* The calendar lists the dates to come of each planner that is not paused and whose group is active ([POST /v4/jobs](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v4jobs), apipy @ 0e83c85e5a, `model/v4/schedule.py:603-615`).
* On the web, a date that has already become a task is not listed. The apps list created tasks too, with their colour, and open them ([POST /v3/jobs](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3jobs)).
* A group's planner shows only that group's dates ([Group planner](https://docs.snapfix.com/how-the-apps-work/screens/planner/group-planner.md)).
* The list calls take the user from the request body, and the server does not check that the caller may see the groups asked for.
* The scheduler reads planner times in the site's time zone \[[ASK-55](https://github.com/snapfix/docs/blob/main/ASK.md#ask-55-do-the-scheduler-and-api-servers-run-on-utc)]. The web shows the list in the browser's time zone, so a start typed in site time can show at another hour ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md#layout)).

### Views and navigation

* The web shows one month at a time; the calendar can be hidden ("Hide calendar") and shown again, with the selected date under it. The apps show a week or a month, switched with the week and month controls ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md#actions)).
* Days with planned tasks are marked: on the web from the server's list of days, on iOS with a dot ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md#layout)).
* On the web, picking a day loads the planned tasks from that day on. On the apps, tapping a day scrolls the list to it, when it has planned tasks ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md#inputs)).
* The web lists rows under date dividers and loads 50 planned tasks at a time, later ones at the bottom and earlier ones at the top, and 10 planners at a time ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md#actions)).
* On iOS and Android, tapping "Planned Tasks" while already on it switches to the planners page ("Scheduler" on iOS) ([Plan](https://docs.snapfix.com/how-the-apps-work/screens/planner/plan.md#layout)).

### Filters and search

* The web filters the dates by priority, "Assigned to me", "Created by", "Assigned to" and, on a site's page, "Groups". "Rooms", "Areas", "Date" and "Tags" are offered but never sent, so they change nothing (web\_app\_v2 @ 0989b8e685, `planner-helper.service.ts:38-45`, `:99-131`).
* The apps filter by status colour, priority, scheduled only, "My tasks", groups, "Created by" and "Assigned to", in a bottom sheet. Applying a filter reloads the list ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md#inputs)).
* On the web, choosing a planner card narrows the list to that planner. Choosing it again clears the choice. A paused planner can't be chosen ([Manage planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/manage-planned-tasks.md#actions)).
* On the web, the search box ("Search Planned Tasks") finds planner cards on the server, on Enter; the dates are not filtered. The apps search only the items already loaded.

### Opening a planned task

* On the web, a planned task opens the planned task for that date, for users with "Create Planned Tasks" or group admin. Others get "You don't have the right permissions to create or edit planned tasks in this group. Reach out to the group admin to review your permissions." ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md#actions)).
* On the apps, a created task opens its chat. A date still to come opens the planned task editor, for users who may plan. Others get an alert ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md#actions)).
* The web and the apps open different things for the same item \[[ASK-53](https://github.com/snapfix/docs/blob/main/ASK.md#ask-53-should-a-planned-task-open-the-planner-editor-or-the-created-task)].

### Permissions and empty states

* Any signed-in user can open the Plan page. The "Add Task" button, the "⋯" menu and the floating "+" show only to users who may create planned tasks in a group. On Android the top "+" stays visible in a group.
* An empty list shows "Manage your Planned Tasks in a Snap!" with a hint to create one on the apps; the web's planned-tasks list shows "No data available" ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md#states)).
* A failed load shows the empty state, with no message, on the web and on iOS.

## Flow

```mermaid
flowchart LR
  open["Open Plan or a group's planner"] --> view["Pick a month on the web, or a week or month in the apps"]
  view --> load["Load the dates to come"]
  load --> pick{"Pick a day, a planner or a filter?"}
  pick -- "day" --> jump["List starts at that day"]
  pick -- "planner (web)" --> one["Only that planner's dates"]
  pick -- "filter" --> reload["List reloads with the filter"]
  pick -- "a planned task" --> pickTask{"Created or still to come?"}
  pickTask -- "created (apps)" --> task["Task chat"]
  pickTask -- "still to come" --> editor["Planned task editor, if allowed"]
```

## Platforms

| Capability                     | Web                                                                     | iOS                                                                                  | Android                                  |
| ------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------- |
| Views                          | month only, collapsible                                                 | week and month                                                                       | week and month                           |
| Days with planned tasks marked | yes, from the server                                                    | yes, with a dot                                                                      | not in the screen docs                   |
| Jump to a day                  | the list starts at the picked date                                      | the list scrolls to the tapped day                                                   | not in the screen docs                   |
| Filters                        | priority, assigned to me, created by, assigned to, groups (site's page) | status colour, priority, scheduled only, "My tasks", groups, created by, assigned to | the same kinds as iOS, in a filter sheet |
| Search                         | planner cards only                                                      | loaded items only                                                                    | loaded items only                        |
| Created tasks in the list      | no                                                                      | yes                                                                                  | yes                                      |
| Offline                        | needs a connection                                                      | shows the device's copy                                                              | needs a connection                       |

## Screens

* [Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md): the calendar and the list, on the web and in the apps.
* [Plan](https://docs.snapfix.com/how-the-apps-work/screens/planner/plan.md): the Plan tab on iOS and Android.
* [Group planner](https://docs.snapfix.com/how-the-apps-work/screens/planner/group-planner.md): the calendar for one group.
* [Manage planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/manage-planned-tasks.md): the planner list beside the calendar.

## API and data

* Web: [POST /v4/jobs](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v4jobs) lists the dates to come, and the days that have them. [POST /schedules-v2](https://docs.snapfix.com/engineering-reference/api/planner.md#post-schedules-v2) lists the planner cards, and [POST /schedules-v2/uuids](https://docs.snapfix.com/engineering-reference/api/planner.md#post-schedules-v2uuids) returns every planner that matches, for "select all".
* Apps: [POST /v3/jobs](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3jobs) lists the created tasks and the dates to come. [POST /schedules](https://docs.snapfix.com/engineering-reference/api/planner.md#post-schedules) lists the planners.
* Tables: [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md) holds the planners behind each date. [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) holds the created tasks.

## Depends on

* [Planned tasks](https://docs.snapfix.com/product/features/planner/planned-tasks.md): the planners behind every date, and the planner's rules.
* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md): the created tasks that the apps show and open.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): which groups a user sees, and the permissions for creating and editing.
* [Asset tasks](https://docs.snapfix.com/product/features/assets/asset-tasks.md): the asset's planned tasks tab lists the same dates.
* [Switching sites](https://docs.snapfix.com/product/features/groups/site-switching.md): the site picker, and the sites a multi-site user can open.

## Edge cases

* **Offline:** the web and Android need a connection. iOS shows the device's copy of the list ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md#states)).
* **Failed load:** the list shows empty, with no message.
* **Long lists:** the API has no maximum page size. The web loads 50 planned tasks at a time.
* **Paused or inactive:** a paused planner's dates and the dates of a planner in an inactive group are not listed ([POST /v4/jobs](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v4jobs)).
* **Parked planners:** a planner that the scheduler has stopped can still show its dates here while its group is active.
* **Several sites:** a multi-site user switches site to see another site's planners ([Switching sites](https://docs.snapfix.com/product/features/groups/site-switching.md)).
* **Time zones:** see [What is listed](#what-is-listed).


---

# 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/planner/plan-calendar.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.
