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

# Planned tasks

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

**Planned tasks** are tasks that Snapfix creates on a schedule, for work that repeats. A person sets up a **planner** in one group, with its title, users, tags, rooms, areas, assets, checklist, note, picture, priority, due date, time range, start date, start time and repeat, and can add a reminder. A scheduler on Snapfix's servers creates each **planned task** in the group when its date comes, and from then on the created task is an ordinary task. A planner can start from scratch, from a group, or from an existing task or asset. People pause and resume planners, change one date or all of them, and delete planners or single dates. The dates still to come are on the [Plan calendar](https://docs.snapfix.com/product/features/planner/plan-calendar.md). The apps and the web use "planned task", "schedule" and "planner" for the same things in different ways.

## Rules

### Where a planner starts

* From the site's Plan page ("Add Task", "+" in the apps), from a group's planner with the group preset, from an existing task (`/create/task/:id` on the web), or from an asset ([Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md#inputs)).
* Starting from a task copies its title, picture, checklist, users and tags into the planner and leaves the task as it is ([Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md#inputs)).
* Staff can also create planners from a spreadsheet in the admin app, one per row ([POST /schedule-upload](https://docs.snapfix.com/engineering-reference/api/planner.md#post-schedule-upload)).

### Planners

* A planner belongs to one group, and the group can't be changed once the planner is saved. Groups where the user is inactive are not offered ([Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md#inputs)).
* The title is required and can hold up to 255 characters ([Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md#inputs)).
* Every created task gets the planner's title, picture or large text, note, priority, users, followers, tags, rooms, areas, assets, checklist, due date and time range ([POST /v3/schedule](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3schedule)). The large text is drawn as HTML.
* The start date and time are required. On the web they start at tomorrow, 9:00 AM; the apps start at today ([Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md#inputs)).
* A planner has one start time. The scheduler reads it in the site's time zone; a site with no time zone is read as Europe/Dublin (py\_scheduler @ c8b1344036, `models/feature_schedule.py:158-175`). For the times to be right, the server clock must be UTC \[[ASK-55](https://github.com/snapfix/docs/blob/main/ASK.md#ask-55-do-the-scheduler-and-api-servers-run-on-utc)].
* A time range (start, end and duration) is copied to each created task. A due date counts from the moment the task is created ([Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md#inputs)).

### Repeats and dates

* A planner either does not repeat ("Does not repeat"), or repeats by "Day", "Week", "Month" or "Year" ([Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md#inputs)).
* "Day" creates tasks on the weekdays chosen, Monday to Friday by default.
* "Week" creates tasks every N weeks on the weekdays chosen. At least one weekday is required ("One day is required").
* "Month" creates tasks every N months, on the day of the month of the start date. On the web and on iOS, a planner that starts on the 29th, 30th or 31st creates no task in the months that do not have that day. The API also accepts other monthly patterns (first or last day, a weekday near the start date); Android alone offers one of them, "the end of each month" (apipy @ 0e83c85e5a, `model/schv3/feature_schedule.py:1795-1872`).
* "Year" creates tasks every N years, on the start date.
* A planner that does not repeat creates one task, on its start date. The API does not refuse a one-time planner dated in the past (`feature_schedule.py:2039-2057`).
* A planner ends on its end date ("Ends on") or never ("Never ends"). The "Ends at" time on the web does nothing; the server reads only the end date.

### Reminder

* With "Add 24 hour reminder" on, a reminder push ("… is scheduled for tomorrow") goes to the assigned users before each planned task, but it is always sent as a silent push, so it never shows ([Reminders](https://docs.snapfix.com/product/features/notifications/reminders.md)). Followers are not notified, and a planner with no assigned users sends no reminder.
* The first reminder is set 12 hours before the first task, when the planner is saved. Later reminders are set 24 hours before their task. The screen says 24 hours for every reminder (`feature_schedule.py:483-488`; py\_scheduler `models/cron_schedule_v3.py:693-699`).
* If the reminder time has already passed when the planner is saved, the reminder goes out 15 minutes later. That can be the same day as the task, while the text still says "tomorrow".
* A paused planner sends no reminders. A planner paused across a reminder time sends no more reminders until it is changed.

### What a created task gets

* The scheduler creates the tasks itself, not the request that saves the planner, so a saved planner makes nothing until the scheduler next runs. It prepares each task up to 12 hours ahead, kept hidden until it is due, and the task shows in the group from about 5 minutes before its time (py\_scheduler `config/constant.py:139-150`).
* The task is created in the planner's group. It is red and has the sub-status "New". A group with no red status or no "New" sub-status can't take the task ([POST /v3/scheduler/job](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3schedulerjob)).
* The planner's creator is the task's creator. When that person is no longer in the group, the group's first admin is used.
* The task's description is the planner's note. Without a note it reads "Planned daily", "Planned weekly", "Planned monthly" or "Planned yearly", or "Planned date" for a one-time planner. The chat gets a line from the creator with the same planner type and the date, and a "Created Task" line ([Task chat](https://docs.snapfix.com/product/features/chat/task-chat.md)) (py\_scheduler `models/feature_job_from_scheduler.py:186-200`).
* Creating a task sends no push notification ([POST /v3/scheduler/job](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3schedulerjob)).
* Changing or deleting a planner does not change tasks already created ([DELETE /v3/schedule](https://docs.snapfix.com/engineering-reference/api/planner.md#delete-v3schedule)).

### Pausing and resuming

* Pausing stops new tasks from the planner and removes its dates from the calendar. Tasks already created stay as they are ([PUT /schedule/{uuid}/pause](https://docs.snapfix.com/engineering-reference/api/planner.md#put-scheduleuuidpause)).
* Resuming works out the next date from today, so missed dates are not created ([PUT /schedule/{uuid}/play](https://docs.snapfix.com/engineering-reference/api/planner.md#put-scheduleuuidplay)).
* Pausing asks for confirmation ("Deactivate Schedule": "Do you want to deactivate this schedule of Planned Tasks? Note: you can reactivate it any time."). Resuming does not ask ([Manage planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/manage-planned-tasks.md#dialogs-and-sheets)).
* On the web, several planners can be paused at once from "Select Planners". The request returns at once, and the planners pause in the background; planners already paused are skipped, and failures are not reported ([POST /schedules/pause](https://docs.snapfix.com/engineering-reference/api/planner.md#post-schedulespause)).
* On the web a paused planner can't be selected in the list ([Manage planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/manage-planned-tasks.md#actions)).

### Changing and deleting

* When one planned task is changed, the user picks how far the change reaches. The web offers "This task only." or "Tasks from \[date] will be updated.". iOS and Android add "Tasks in this planned, from today onwards, will be updated.", which sends the whole planner \[[ASK-57](https://github.com/snapfix/docs/blob/main/ASK.md#ask-57-should-the-apps-from-today-onwards-option-replace-the-whole-series)]. On iOS, picking "This task only." sets no choice, so "Update" then cancels the save (ios @ aa31967ac8, `SnapFix/ScheduleUpdatePopup.swift:117-143`).
* Changing the repeat, dates or times saves the whole planner without asking. Settings edits also apply to all ([Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md#actions)).
* The API takes the same choice: the whole planner, one date, or the dates from a date on. A date today or earlier can't be changed with "one date" or "from this date" ([PUT /v3/schedule](https://docs.snapfix.com/engineering-reference/api/planner.md#put-v3schedule)).
* Deleting a planner on the web asks "Delete planned task" / "Are you sure you want to delete the planned task?" with "Note: Deleted planned task cannot be recovered". Deleting one date of a repeating planner asks whether to delete only that date or that date and the later ones ([DELETE /v3/schedule](https://docs.snapfix.com/engineering-reference/api/planner.md#delete-v3schedule)).
* Deleting removes the dates not created yet and keeps the tasks already made ([DELETE /v3/schedule](https://docs.snapfix.com/engineering-reference/api/planner.md#delete-v3schedule)).

### Who may do what

* Creating needs both "Create New Task" and "Create Planned Tasks" in the group, or group admin. On the web, changing and pausing need only "Create Planned Tasks", so a person can change a planner they could not have created. The apps ask for both for changing and pausing too \[[ASK-51](https://github.com/snapfix/docs/blob/main/ASK.md#ask-51-which-permissions-should-planned-tasks-need)] ([Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md#inputs), [Manage planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/manage-planned-tasks.md#inputs)).
* With no group the user may plan in, the web shows "You are not an admin of any group, so you cannot create planned tasks." ([Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md)).
* The web's permission check before a save never runs.
* The server does not check group membership on any planner route; pausing, resuming and bulk pausing check only that the caller is signed in, and several routes take the acting user from the request body.
* On the site's page, the web shows the pause switch and the "⋯" button to every user who is not inactive in the site; a user without the rights sees an alert after tapping them.
* Any signed-in user can see the Plan page of the site. Members see the planners of the groups they belong to ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md)).

### Limits

* The plan's task limit is not checked when a planner is saved or when a task is created from it \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)]. The iOS planner editor shows "No new tasks left in this account.", and its "Learn More" link opens a missing page.
* An attachment can be up to 20 MB on iOS and 40 MB on Android ([Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md#dialogs-and-sheets)).

### Repeating one task (Android, older screen)

* Android still has an older way to repeat one existing task, from the task chat's menu (the task schedule screen). It writes the older schedule (`POST /schedule` in the [Planner API](https://docs.snapfix.com/engineering-reference/api/planner.md)), which is copied into the current one \[[ASK-58](https://github.com/snapfix/docs/blob/main/ASK.md#ask-58-can-the-unreachable-old-android-schedule-screen-and-its-v1-route-go)].

## Flow

```mermaid
flowchart TD
  start["Plan, Add Task or + in a group"] --> form["Set group, title, start date, start time and repeat"]
  form --> allowed{"Group allows planned tasks?"}
  allowed -- "no" --> refused["Permission message"]
  allowed -- "yes" --> save["Save: planner stored, no task yet"]
  save --> cal["Dates listed on the calendar"]
  save -. "reminder on" .-> remind["Assignees reminded 12 or 24 hours before"]
  cal --> paused{"Paused?"}
  paused -- "yes" --> hold["No tasks until resumed"]
  paused -- "no" --> prep["Task prepared, hidden, up to 12 hours ahead"]
  prep --> show["Task shown in the group about 5 minutes before its time"]
  show --> own["Ordinary task: status, chat, due date"]
  prep -. "creation fails" .-> parked["Planner stops for good"]
```

## Platforms

| Capability                         | Web                                                                                                                                       | iOS                                      | Android                                                                                                                                      |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Create a planner                   | yes                                                                                                                                       | yes                                      | yes                                                                                                                                          |
| Start defaults                     | tomorrow, 9:00 AM                                                                                                                         | today                                    | today                                                                                                                                        |
| Repeat by day, week, month or year | yes                                                                                                                                       | yes                                      | yes                                                                                                                                          |
| Monthly on the end of the month    | no                                                                                                                                        | no                                       | yes                                                                                                                                          |
| Change one date                    | "This task only" or "from this date"                                                                                                      | three choices; "This task only" cancels  | three choices                                                                                                                                |
| Pause and resume one planner       | yes                                                                                                                                       | yes                                      | yes                                                                                                                                          |
| Pause several planners at once     | yes                                                                                                                                       | no                                       | no                                                                                                                                           |
| Reminder                           | yes                                                                                                                                       | yes                                      | yes                                                                                                                                          |
| Attachment size limit              | not in the screen docs                                                                                                                    | 20 MB                                    | 40 MB                                                                                                                                        |
| Plan's task limit                  | not checked \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)] | message in the editor                    | not in the screen docs                                                                                                                       |
| Older one-task repeat              | no                                                                                                                                        | no                                       | yes \[[ASK-58](https://github.com/snapfix/docs/blob/main/ASK.md#ask-58-can-the-unreachable-old-android-schedule-screen-and-its-v1-route-go)] |
| Works offline                      | no                                                                                                                                        | the planner list shows the device's copy | no                                                                                                                                           |

## Screens

* [Plan](https://docs.snapfix.com/how-the-apps-work/screens/planner/plan.md): the Plan tab on iOS and Android, with the planned tasks page.
* [Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md): the calendar and the list of dates to come, beside the planners.
* [Manage planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/manage-planned-tasks.md): the planners, with pause and resume.
* [Group planner](https://docs.snapfix.com/how-the-apps-work/screens/planner/group-planner.md): the same planner inside one group.
* [Create planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md): creating and changing a planner or one of its dates.

## API and data

* Web: [POST /v3/schedule](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3schedule) creates a planner, [PUT /v3/schedule](https://docs.snapfix.com/engineering-reference/api/planner.md#put-v3schedule) changes it and [DELETE /v3/schedule](https://docs.snapfix.com/engineering-reference/api/planner.md#delete-v3schedule) deletes it or part of it. [GET /v3/schedule/{uuid}](https://docs.snapfix.com/engineering-reference/api/planner.md#get-v3scheduleuuid) loads it for editing. [PUT /schedule/{uuid}/pause](https://docs.snapfix.com/engineering-reference/api/planner.md#put-scheduleuuidpause) and [PUT /schedule/{uuid}/play](https://docs.snapfix.com/engineering-reference/api/planner.md#put-scheduleuuidplay) pause and resume it, and [POST /schedules/pause](https://docs.snapfix.com/engineering-reference/api/planner.md#post-schedulespause) pauses several. [POST /schedules-v2](https://docs.snapfix.com/engineering-reference/api/planner.md#post-schedules-v2) lists planners, and [POST /v4/jobs](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v4jobs) lists the dates to come.
* Apps: [POST /schedules](https://docs.snapfix.com/engineering-reference/api/planner.md#post-schedules) lists planners, and [POST /v3/jobs](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3jobs) lists created tasks and the dates to come.
* Admin app: [POST /schedule-upload](https://docs.snapfix.com/engineering-reference/api/planner.md#post-schedule-upload) creates planners from a spreadsheet.
* Scheduler: py\_scheduler creates the tasks itself. It calls [POST /v3/scheduler/job](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3schedulerjob) when its own creation fails, and for every task if it runs in API mode. Which mode production uses is not in any repo \[[ASK-50](https://github.com/snapfix/docs/blob/main/ASK.md#ask-50-which-job_create_mode-does-production-py_scheduler-use)]. Its calls send a login written in its source.
* Tables: [`schedule_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_v3.md) holds the planners, one row per version. [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) holds the created tasks. Their chat lines are in [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md). Each creation is logged in [`schedule_log_v3`](https://docs.snapfix.com/engineering-reference/db/tables/schedule_log_v3.md).

## Depends on

* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md): everything that happens to a created task after it is created, including its due date.
* [Creating tasks](https://docs.snapfix.com/product/features/tasks/task-creation.md): planned tasks are one of the other ways tasks start.
* [Plan calendar](https://docs.snapfix.com/product/features/planner/plan-calendar.md): lists the dates to come.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): the group, its roles and the permissions that decide who may plan.
* [Rooms and areas](https://docs.snapfix.com/product/features/rooms/rooms-and-areas.md) and [Asset tasks](https://docs.snapfix.com/product/features/assets/asset-tasks.md): rooms, areas and assets copied to each task, and the asset's planned tasks tab.
* [Checklist templates](https://docs.snapfix.com/product/features/checklists/checklist-templates.md) and [Checklists](https://docs.snapfix.com/product/features/checklists/checklists.md): a checklist added to a planner is copied to each task.
* [Reminders](https://docs.snapfix.com/product/features/notifications/reminders.md) and [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md): the planner reminder is a push to the assigned users.
* [Task chat](https://docs.snapfix.com/product/features/chat/task-chat.md): the "Created Task" line and the planner line in each task's chat.
* [Subscriptions](https://docs.snapfix.com/product/features/billing/subscriptions.md): the plan's task limit, which is not checked here \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)].
* [Switching sites](https://docs.snapfix.com/product/features/groups/site-switching.md): planners belong to one site. A multi-site user switches site first.

## Edge cases

* **Offline:** the web and Android need a connection to save or list planners. iOS keeps a copy of the planned tasks list on the device ([Planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-tasks.md#states)). Creation runs on Snapfix's servers, so a phone that is offline does not stop a planner from making tasks.
* **Failed loads:** a failed planner request shows the empty state with no message on the web and on iOS.
* **Paused across a reminder time:** the reminders stop until the planner is changed.
* **Creation fails or the group is inactive:** the scheduler stops the planner for good and leaves its dates on the calendar while the group is active. A planner with a reminder is deleted on the day its reminder falls due, if its group is inactive or deleted \[[ASK-54](https://github.com/snapfix/docs/blob/main/ASK.md#ask-54-should-a-planner-restart-when-its-group-is-reactivated)].
* **Scheduler outage:** missed tasks are created late, with their original dates, when someone runs the scheduler's catch-up (`py_scheduler:schedulev3_catchup.py`).
* **Several sites:** the web lists the planners of the current site. A multi-site user switches site first.
* **Time zones:** planner times are the site's local time, and the server must run on UTC for them to be right \[[ASK-55](https://github.com/snapfix/docs/blob/main/ASK.md#ask-55-do-the-scheduler-and-api-servers-run-on-utc)].
* **Monthly on the 29th to 31st:** months without that day get no task.
* **Assets:** the asset's planned tasks tab can list other assets' created tasks.
* **Bulk upload:** the admin app shows success when some rows fail to save. The server has no limit on the rows.


---

# 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/planned-tasks.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.
