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

# Create planned task

{% 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, iOS and Android. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/planner/planned-task.md).
{% endhint %}

Create or change a schedule: its group, the task it will create (title, picture or large text, users, tags, assets, compliance systems, rooms and areas, time range, checklist, note, attachment, reminder, priority, due date) and when that task repeats. Saving does not create a task; the scheduler creates each task later ([`POST /v3/scheduler/job`](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3schedulerjob)). The words for the rule and for the tasks it creates differ between screens and platforms.

![Create planned task](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-1c7c1f00982d1f6edf0de5f55f8762d0b1ad5f62%2Fplanned-task.png?alt=media)

The picture shows the web "Create Planned Task" page with a group chosen: the details on the left and the users and tags on the right.

* **Where:**
  * Web: `/plan/planned-task/create`; `/plan/planned-task/create/group/:id` from a group's planner; `/plan/planned-task/create/task/:id` from a task's actions, and from an asset's planned tasks with `;groupType=assets`; `/plan/planned-task/edit/:id/settings` for a whole schedule; `/plan/planned-task/edit/:id/:date` for one planned task. The header shows a back button and "Create Planned Task" or "Edit Planned Task".
  * iOS: the "+" on the Plan tab, the schedules' "Create Planned Tasks", a schedule's settings button, a future planned task, a task's menu and an asset's planned tasks.
  * Android: the "+" of the Plan tab and of the group planner, the empty states' create buttons, a schedule's settings button, a future planned task, and the task menu's "Create Planned Tasks" ("Create Planned Task For This Asset" on an asset).
* **Who:** creating needs both "Create New Task" and "Create Planned Tasks" in the group, or group admin; the group list holds only those groups. On the web, opening, pausing and deleting an existing schedule need less ([Actions](#actions)) \[[ASK-51](https://github.com/snapfix/docs/blob/main/ASK.md#ask-51-which-permissions-should-planned-tasks-need)].
* **Feature:** [Planned tasks](https://docs.snapfix.com/product/features/planner/planned-tasks.md)

## Layout

**Web:** a bar with the quick-action icons and "Create Plan" ("Save" when editing), then two columns.

* **Left:** "Select a group" (required, read-only when editing); the title; the picture or large text, 164 px tall, with a change button; "Schedule status" with the switch (only on `/edit/:id/settings`); "Scheduled" with the date and time; "Repeats". When it repeats: "Frequency" (Day, Week, Month, Year), "For", and "Ends on" with "Ends at".
* **Right**, once a group is chosen: the users (assigned, followed, created by) and the tags, then a section for each item added from the icons: assets, compliance system, rooms and areas, time range, checklist, note, attachment, reminder and priority. A due date has no section, so once set it shows only as the icon's tick.
* **Icons:** "Add Priority", "Add Note", "Add Attachment", "Add An Asset", "Compliance System", "Room And/Or Area", "Add Checklist", "Add Due Date", "Add 24 Hour Reminder", "Add Time Range", and "Delete" when editing. A tick marks an icon whose section has content. User and tag icons exist in the template but are switched off, because both sections always show.

**iOS:** a pushed screen titled "Create Planned Tasks" ("Edit Planned Tasks"), with "Save". Top to bottom: "Select a group"; the title, with "Task title is required"; the picture or large text, with "Upload or Take Task Image" and "Task image is required"; "Scheduled" with the date and "9:00 AM"; "Repeats" ("Does not repeat" or "Repeats every"), "Frequency", "For" (seven day chips, or a count such as "weeks on Monday"), and "Ends" with "Never" or "On Date"; then sections for "Assigned to", "Followed by", "Tags", "Assets", "Comply", "Room", "Area", "Checklist", "Attachment", "Notes", "Reminder", "Due Date" and "Time Range". A bottom bar holds shortcuts ("User", "Tag", "Asset", "Checklist", "More"). Editing from the schedules list adds "Schedule status" with a switch.

**Android:** a screen titled "Create Planned Tasks" ("Edit Planned Tasks"), with "Save". Top to bottom: "Select a Group"; "Add title" with "Task title is required."; "Upload or Take Task Image" with "Task image is required."; "Scheduled" with "9:00 AM"; "Repeats" with "Does not repeat"; then "Users", "Tags", "Room", "Area" and "More". Editing adds "Schedule status".

Neither app ever shows "Task image is required": the check that would show it is switched off, so a picture is optional.

## Inputs

| Field                  | Type                                 | Required       | Default                                                                 | Rules and messages                                                                                                                                                                                                                                                                                                                |
| ---------------------- | ------------------------------------ | -------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Group                  | single choice                        | yes            | none; `/create/group/:id` and the mobile group planner preset the group | "Please choose a group" (web). The list holds the site's groups that are not inactive, where the user is admin or has both create permissions and is not an inactive member, sorted by name. Android also leaves out asset registers. Changing the group loads its details, so the users, tags and rooms match it.                |
| Title                  | text, one line                       | yes            | empty; from a task, its title                                           | Spaces alone count as empty. Web: placeholder "Write a title for this task...", "Please enter a title", and over 255 characters "Your input exceeds the maximum allowed length of 255 characters" (the field also stops at 255). Apps: "Task title is required".                                                                  |
| Picture or large text  | image or text                        | no             | none; from a task, its picture                                          | Web: the picture through "Upload image" with a cropper, or the large text dialog; setting one clears the other. The change button is hidden in groups that block gallery photos. With neither, the web saves the whole title as the large text and iOS its first 50 characters. Large text is shown as HTML.                      |
| Start date             | date                                 | yes            | tomorrow (web, iOS)                                                     | Web: the picker starts at tomorrow, except on `/edit/:id/settings`, which allows any date; "Cancel" and "Set". iOS: "Please select start date" when empty. Android: "Select start date". Android allows today onward (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/ScheduleTaskActivity.java:1890`).    |
| Start time             | time                                 | yes            | "9:00 AM"                                                               | One time a day. On the web changing it also sets the end time.                                                                                                                                                                                                                                                                    |
| Repeats                | "Does not repeat" or "Repeats every" | yes            | "Does not repeat"                                                       | "Does not repeat" saves a `single` schedule, which creates one task.                                                                                                                                                                                                                                                              |
| Frequency              | Day, Week, Month, Year               | when repeating | Day                                                                     |                                                                                                                                                                                                                                                                                                                                   |
| For (Day)              | weekdays, Monday first               | at least one   | Monday to Friday                                                        | Clearing the last day shows "One day is required" with "A section of at least one day in the week is required to planned task that repeats weekly." (web) or "A selection of at least one day in the week is required to schedule a task that repeats weekly." (apps). The check is on the daily days while the text says weekly. |
| For (Week)             | count                                | yes            | 1                                                                       | 1 to 52, "week on a {weekday}." The weekday is the start date's.                                                                                                                                                                                                                                                                  |
| For (Month)            | count                                | yes            | 1                                                                       | 1 to 12, "month on the {13th} day."                                                                                                                                                                                                                                                                                               |
| For (Year)             | count                                | yes            | 1                                                                       | 1 to 5, "year on {Nov 13}."                                                                                                                                                                                                                                                                                                       |
| Ends on                | "Never" or a date                    | when repeating | "Never"                                                                 | Web: "Set Date" opens the picker, with "Never", "Cancel" and "Set". The earliest end is a week after the start. Choosing a frequency moves the end to the start plus one period, unless an end date was set.                                                                                                                      |
| Ends at                | time                                 | no             | the start time                                                          | Web: shown greyed out; it always equals the start time. The server does not use it.                                                                                                                                                                                                                                               |
| Users                  | assigned and followers               | no             | none; the creator is listed as "Created by" and "Followed by"           | The [Assigned to, Followed by](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md) dialog.                                                                                                                                                                                                                   |
| Tags                   | tags                                 | no             | none; from a task, its tags                                             | The task's [Tags](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md) dialog.                                                                                                                                                                                                                                |
| Assets                 | assets                               | no             | none; from an asset, that asset                                         | The task's assets dialog.                                                                                                                                                                                                                                                                                                         |
| Compliance system      | systems                              | no             | none                                                                    | The task's compliance system dialog.                                                                                                                                                                                                                                                                                              |
| Rooms and areas        | rooms, areas                         | no             | none; from a task, its room and area                                    | The task's rooms and areas dialog.                                                                                                                                                                                                                                                                                                |
| Time range             | start and duration                   | no             | none                                                                    | The shared "Set Time Range" dialog ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md)).                                                                                                                                                                                                      |
| Checklist              | items or a template                  | no             | none; from a task, its checklist with answers, notes and media cleared  | Picking a template sends the template link; editing the items afterwards sends the items instead.                                                                                                                                                                                                                                 |
| Note                   | text                                 | no             | none; from a task, its note                                             | The task's notes editor.                                                                                                                                                                                                                                                                                                          |
| Attachment             | one file                             | no             | none                                                                    | "Upload file"; uploaded at save. iOS refuses files over 20 MB, Android over 40 MB.                                                                                                                                                                                                                                                |
| Reminder               | on or off                            | no             | off                                                                     | Web: "Assigned users receive a notification on 24 hours before the planned task(s)." Android: "Assigned users receive a notification on the day before the scheduled task(s)." The server reminds 12 hours before.                                                                                                                |
| Priority               | on or off                            | no             | off                                                                     | "Set as Priority", "Add priority star to task", and a bin to clear it.                                                                                                                                                                                                                                                            |
| Due date               | period and count                     | no             | none; from a task, cleared                                              | Counted from each task's creation: hours 1 to 24, days 1 to 31, weeks 1 to 52, months 1 to 12 ([Set due date](#dialogs-and-sheets)). Android shows "Due date is set at" with the date.                                                                                                                                            |
| Schedule status (edit) | switch                               | no             | on                                                                      | "Schedule active", "Schedule inactive since" with the time, or "Schedule finished" once it has ended (then no switch). Turning it off asks "Deactivate Schedule" first.                                                                                                                                                           |

## Actions

| Action                         | Who                                                                                                | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                            | API                                                                                                                                                                                                                                    |
| ------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open the form (web)            | anyone with the address                                                                            | Loads the group list, and the schedule or the source task, behind a spinner. A group list slower than 20 seconds, or failing, adds to a retry count kept in the browser; on the third such load the page goes back. A schedule that fails to load goes back at once.                                                                                                                                                                                                    | [`GET /v1/app/businesses`](https://docs.snapfix.com/engineering-reference/api/groups.md), [`GET /v3/schedule/{uuid}`](https://docs.snapfix.com/engineering-reference/api/planner.md#get-v3scheduleuuid)                                |
| "Create Plan"                  | web: enabled for any valid form                                                                    | Uploads a new attachment and picture, then creates the schedule. The button shows progress, then success, and 1.5 seconds later the page goes back to the planner it came from. A failure leaves the button idle and keeps the form. iOS and Android: "Save", then "Schedule created.".                                                                                                                                                                                 | [`POST /v3/schedule`](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3schedule)                                                                                                                                   |
| "Save" on `/edit/:id/settings` | same                                                                                               | Saves the whole series.                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PUT /v3/schedule`](https://docs.snapfix.com/engineering-reference/api/planner.md#put-v3schedule)                                                                                                                                     |
| "Save" on one planned task     | same                                                                                               | If the repeat, dates, start time or repeat settings changed, it saves the whole series without asking \[[ASK-56](https://github.com/snapfix/docs/blob/main/ASK.md#ask-56-should-changing-a-planned-tasks-date-or-repeat-skip-this-task-or-later)]. Otherwise it asks the [update question](#dialogs-and-sheets) first. The apps ask the same, but a single schedule and an edit from the schedules list save the series. iOS and Android then show "Schedule updated.". | [`PUT /v3/schedule`](https://docs.snapfix.com/engineering-reference/api/planner.md#put-v3schedule)                                                                                                                                     |
| "Delete"                       | editing, with either create permission (web)                                                       | A single schedule, or one opened from settings, asks "Delete planned task"; settings deletes the whole series, a single schedule its one date. A planned task of a repeating schedule asks the update question in delete mode. On success the page goes back after 1.5 seconds. Android calls it "Cancel schedule".                                                                                                                                                     | [`DELETE /v3/schedule`](https://docs.snapfix.com/engineering-reference/api/planner.md#delete-v3schedule)                                                                                                                               |
| Schedule status switch         | web: on settings, either create permission; the switch then checks "Create Planned Tasks" or admin | Pauses (after "Deactivate Schedule") or resumes the whole schedule, as on [Manage planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/manage-planned-tasks.md#actions).                                                                                                                                                                                                                                                                           | [`PUT /schedule/{uuid}/pause`](https://docs.snapfix.com/engineering-reference/api/planner.md#put-scheduleuuidpause), [`PUT /schedule/{uuid}/play`](https://docs.snapfix.com/engineering-reference/api/planner.md#put-scheduleuuidplay) |
| Quick-action icon (web)        | per icon, below                                                                                    | Opens that item's dialog, or adds or clears its section. Nothing is saved until "Create Plan" or "Save".                                                                                                                                                                                                                                                                                                                                                                | -                                                                                                                                                                                                                                      |
| Back                           | anyone                                                                                             | Leaves without saving. Switching site on the web also drops the form and opens `/plan/planner`.                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                                                                                                                      |

**Web icon permissions.** Priority, due date, reminder, assets, tags, room and compliance need an active membership of the group (admins always pass). The note needs notes not hidden; the attachment needs document access; time range and checklist need "manageChecklist"; delete needs editing and either create permission.

**Permission gaps.** Opening a schedule and pausing it need only "Create Planned Tasks" on the web, and deleting needs either create permission, while creating needs both. "Create Plan" and "Save" apply no permission check of their own: the check sits after an early `return`. The save routes do not check the group or the acting user.

**What is sent.** `user_uuid`, `type` (`single`, `daily`, `weekly`, `monthly`, `yearly`), `start_date`, `start_time` as a list of one time, `end_date` and `end_time` when set, `reminder`, `preview` 0, `update_type`, the repeat settings, and `job_json` with the task. Field meanings are in [`POST /v3/schedule`](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3schedule).

## States

* **Loading:** a spinner over the page until the groups and, when editing, the schedule have arrived. While saving, the button shows progress and the sections stop taking changes. iOS: a progress overlay. Android: "Refreshing…".
* **Empty:** with no group the user may plan in, the web replaces the form with "You are not an admin of any group, so you cannot create planned tasks." The sentence says "admin" although the check is the two create permissions. The right column stays empty until a group is chosen.
* **Error:** web: the API's message through the shared alert; the form keeps its values. iOS: the API's message, or "Something went wrong". Android: the message, "Something went wrong. Please try again.", or "Failed to create the future Task. Please try again in a few minutes.".
* **No permission:** the group list is the gate; a user with no permitted group sees the empty state.
* **Offline (mobile):** iOS refuses to save offline and keeps the form. Android: "You must be connected to the Internet to carry out this task. Please connect and try again." The web needs a connection.

## Dialogs and sheets

* **Update question** (web): title "Planned task update" or "Planned task delete"; "You are updating a Planned Task." or "You are deleting a Planned Task." then "Do you want this change to be applied to all future Tasks, or only to this Task?"; "Apply changes to:" with "This task only." (chosen by default, `single_date`) and "Tasks from \[Nov 13 2026] will be updated." or "…will be deleted." (`future_dates`); "Cancel" and "Update" or "Delete". There is no whole-series option.
* **Update question** (iOS, Android): the same, with a third option "Tasks in this planned, from today onwards, will be updated." (or "deleted"), which sends `all` \[[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, tapping "This task only." sets no choice, so "Update" then quietly cancels.
* **Delete planned task** (web): "Delete planned task", "Are you sure you want to delete the planned task?" and "Note: Deleted planned task cannot be recovered"; "Cancel" and "Delete". The text can show stray markup. After a delete the page goes back to the planner.
* **Cancel schedule** (Android): "Cancel schedule" and "No new tasks will be generated going forward. Are you sure you want to cancel this task schedule?"; then "Schedule cancelled." (iOS shows the same message after a delete).
* **Deactivate Schedule:** the question in [Manage planned tasks](https://docs.snapfix.com/how-the-apps-work/screens/planner/manage-planned-tasks.md#dialogs-and-sheets).
* **Set due date** (web): "The first Planned Task will be created on:" with the start, "Set the Due Date+Time for this Planned Task:", "This Task is due" with a count of hours ("Hours after the Planned Task creation"), days, weeks or months, "As an example, the Due Date+Time for the first Planned Task will be" with a preview, and "\*This will be repeated for each Planned Task"; "Cancel" or "Cancel due date", and "Save".
* **Picture and large text** (web): the task's picture dialog (upload with cropper, sketch, delete) and large text dialog, working on the form only.
* **End of month** (Android): when the start date is the last day of its month and the repeat is monthly, "Save" asks "Do you want to choose this specific date or do you want to use the end of each month as your start or repeat date?" ("Selected date", "End of each month"), also when nothing about the date changed.
* **Plan limit** (iOS): "No new tasks left in this account." with "Learn More", whose help page is missing.

## Platform differences

| Topic                  | Web                            | iOS                          | Android              |
| ---------------------- | ------------------------------ | ---------------------------- | -------------------- |
| Shape                  | two columns, sections as cards | one scrolling form           | one scrolling form   |
| Save button            | "Create Plan" / "Save"         | "Save"                       | "Save"               |
| Delete label           | "Delete"                       | delete                       | "Cancel schedule"    |
| Update question        | two options                    | three options                | three options        |
| Due date after setting | only the icon's tick           | its section                  | "Due date is set at" |
| Monthly end of month   | no                             | no                           | asks                 |
| Status switch          | settings only                  | from the schedules list only | when editing         |

Android still contains an older per-task "Schedule Task" screen (`ScheduleTaskOldActivity`) for the old `/schedule` routes, but nothing in the app opens it: the task menu's entry opens this form \[[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)].


---

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