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

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

Tasks and planned tasks can be linked to **assets**, so each asset shows the work done on it. People link assets when they create or change a task or a planned task, start a task or a planned task from an asset, and see an asset's tasks and planned tasks on the asset itself. One link joins one task to one asset; a task can link several assets, and an asset can be linked to many tasks. The assets themselves are in [Asset registers](https://docs.snapfix.com/product/features/assets/asset-registers.md).

## Rules

### Linking assets to a task

* A task links assets from any register of the site: the user picks a register, then ticks its assets ([Select asset register](https://docs.snapfix.com/how-the-apps-work/screens/assets/select-asset.md)). On the web this is the task's "Assets" dialog ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#assets)).
* Linking needs a task the user can change. Android does not open the picker for an archived, locked or future task, a task outside its time range, or a user who is inactive in the group. iOS lets only group admins unlink, and refuses the picker when the site's plan has no assets ("Not included in this business account") ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#users-tags-rooms-assets-and-compliance)).
* The link and unlink routes check only that the caller is signed in: not that they may change the task or see the assets, and they accept assets of other sites. They do refuse a task that cannot be changed now, such as a locked or archived one ([`POST /v1/app/tasks/asset-link`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksasset-link)).
* A link is a task link row between the task and the asset ([`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md)). The apps save their links the same way and sync them later ([`?action=save_pri_jobjoblink`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_jobjoblink)).
* Linking adds an "added" line to the task's chat and a push to the task's people; unlinking adds a "removed" line and a push. iOS's picker writes "Added : {asset}" and "Removed : {asset}" lines ([`POST /v1/app/tasks/asset-unlink`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksasset-unlink), [Select asset register](https://docs.snapfix.com/how-the-apps-work/screens/assets/select-asset.md#actions)).
* A new task made for an asset links the asset and copies the asset's checklist, checklist name and signature setting. An asset of another site is ignored ([`POST /v1/app/tasks`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasks)).
* When a group requires an asset, the web's "Add a Task" saves the task first and adds the asset in a separate request, so a failure leaves the task without it. A register can require an asset on its tasks (`assetRequired`), but the web's register drawer does not show that setting ([Asset register settings](https://docs.snapfix.com/how-the-apps-work/screens/assets/register-settings.md#settings-drawer-web)).
* Copying or moving a task keeps its asset links, and so does copying or moving an asset ([Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md), [`POST /v1/app/assets/copy`](https://docs.snapfix.com/engineering-reference/api/assets.md#post-v1appassetscopy)).
* A deleted asset leaves the task's asset list, although its link row stays (api\_php\_live\_v2 @ ef3c4319f6, `app/Models/JobModel.php:419-428`).

### The asset's side

* The asset's Tasks tab lists the linked tasks, 20 at a time, with red, amber and green counts, total cost and total time, and a search ([Asset detail](https://docs.snapfix.com/how-the-apps-work/screens/assets/asset-detail.md#actions)). The counts and totals cover only the page that was loaded. The search text goes into the database query unescaped ([`GET /v1/app/assets/{uuid}/jobs`](https://docs.snapfix.com/engineering-reference/api/assets.md#get-v1appassetsuuidjobs)).
* The list needs a user who may view the asset, and it holds only the linked tasks they can see in each task's own group. A member of any multi-site sees every linked task.
* The Tasks tab's "+" starts a new task for the asset: the user names it, picks the group, and the new task is linked to the asset ([Asset detail](https://docs.snapfix.com/how-the-apps-work/screens/assets/asset-detail.md#actions)).

### Planned tasks

* A planned task can carry assets like a task. On the web, the asset's "+" on Planned Tasks, or "Create Planned Task For This Asset" in "Actions", opens the planned task editor with the asset filled in and the group still to choose. It needs a user who may change the asset and has "Create Planned Tasks" and "Create New Task" ([Planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md)). The server checks neither permission; the intended rule is open \[[ASK-51](https://github.com/snapfix/docs/blob/main/ASK.md#ask-51-which-permissions-should-planned-tasks-need)].
* In the apps, assets picked for a planned task are saved with the planned task ([Select asset register](https://docs.snapfix.com/how-the-apps-work/screens/assets/select-asset.md#actions)).
* Each task the scheduler creates from a planned task is linked to its assets, unless an asset was deleted (py\_scheduler @ c8b1344036, `models/feature_job_from_scheduler.py:663-697`). The scheduler does not apply the group's task requirements, such as a required asset \[[ASK-59](https://github.com/snapfix/docs/blob/main/ASK.md#ask-59-should-a-groups-task-requirements-apply-to-planned-tasks)].
* The asset's Planned Tasks tab lists the asset's planned tasks by date, 20 at a time \[[ASK-107](https://github.com/snapfix/docs/blob/main/ASK.md#ask-107-does-the-asset-planned-tasks-tab-load-its-list)]. The apps' list also shows created planned tasks of other assets ([`POST /v4/jobs`](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v4jobs), [`POST /v3/jobs`](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3jobs)).
* A planned task list can be filtered by an asset attribute value, which goes into the database query unescaped.

## Flow

```mermaid
flowchart LR
    task["Task or planned task"] --> pick["Pick a register, then tick assets"]
    pick --> link["Link saved: 'added' line and push"]
    link --> asset["Asset: Tasks and Planned Tasks tabs"]
    asset --> newtask["'+' on Tasks: new task, linked"]
    asset --> newplan["Create Planned Task For This Asset"]
    newplan --> scheduler["Scheduler creates tasks linked to the asset"]
    scheduler --> asset
    newtask --> asset
```

## Platforms

| Capability                               | Web                                 | iOS                                                                            | Android                       |
| ---------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------ | ----------------------------- |
| Link assets to a task                    | The task's "Assets" dialog          | "Add Assets" in the task's "+" menu, the tagging sheet and the new-task picker | The tagging sheet             |
| Unlink                                   | Users who can change the task       | Group admins                                                                   | Users who can change the task |
| Link assets to a planned task            | The editor's assets section         | The planned-task picker                                                        | The planned-task picker       |
| An asset's tasks, with counts and totals | Tasks tab                           | TASKS tab                                                                      | Tasks tab                     |
| An asset's planned tasks                 | Planned Tasks tab, occurrences only | TASKS tab segment; also other assets' created planned tasks                    | Tasks tab; the same problem   |
| New task from an asset                   | "+" on the Tasks tab                | "+" on the TASKS tab, or a scan                                                | A scan                        |
| Offline linking                          | No                                  | Yes, synced later                                                              | Yes, synced later             |

## Screens

* [Asset detail](https://docs.snapfix.com/how-the-apps-work/screens/assets/asset-detail.md): the Tasks and Planned Tasks tabs, and the actions that start new ones.
* [Select asset register](https://docs.snapfix.com/how-the-apps-work/screens/assets/select-asset.md): the pickers on iOS and Android.
* [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#assets): the task's "Assets" dialog on the web.
* [Planned task](https://docs.snapfix.com/how-the-apps-work/screens/planner/planned-task.md): the editor that the asset's actions open.

## API and data

* [`POST /v1/app/tasks/asset-link`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksasset-link) and [`POST /v1/app/tasks/asset-unlink`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksasset-unlink): the web's links.
* [`?action=save_pri_jobjoblink`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_jobjoblink): the apps' links.
* [`GET /v1/app/assets/{uuid}/jobs`](https://docs.snapfix.com/engineering-reference/api/assets.md#get-v1appassetsuuidjobs): an asset's tasks with counts and totals.
* [`POST /v4/jobs`](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v4jobs) (web) and [`POST /v3/jobs`](https://docs.snapfix.com/engineering-reference/api/planner.md#post-v3jobs) (apps), with `uuid_assets`: an asset's planned tasks.
* [`POST /v1/app/tasks`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasks) with `assetUuid`: a new task for an asset.
* Tables: [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md) (the links) and [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) (tasks and assets). [`tPri_JobAsset`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobasset.md) is an older link table that no live flow writes ([`?action=save_pri_job_asset`](https://docs.snapfix.com/engineering-reference/api/tasks.md#any-actionsave_pri_job_asset)).

## Depends on

* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md) and [Task chat](https://docs.snapfix.com/product/features/chat/task-chat.md): the task, its "added" and "removed" lines, and its pushes.
* [Task creation](https://docs.snapfix.com/product/features/tasks/task-creation.md): a new task for an asset, and a group's required asset.
* [Planned tasks](https://docs.snapfix.com/product/features/planner/planned-tasks.md) and [Plan calendar](https://docs.snapfix.com/product/features/planner/plan-calendar.md): planned tasks that carry assets.
* [Checklists](https://docs.snapfix.com/product/features/checklists/checklists.md): the asset's checklist, which a new task copies.
* [Time and cost](https://docs.snapfix.com/product/features/tasks/time-and-cost.md): the totals on the asset.
* [Asset registers](https://docs.snapfix.com/product/features/assets/asset-registers.md) and [Asset codes](https://docs.snapfix.com/product/features/assets/asset-codes.md): the assets, and the scan that starts a task.
* [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md): the pushes for links.

## Edge cases

* **Offline (apps):** links are kept on the phone and synced later; the web needs a connection.
* **Locked, archived or out-of-range task:** the link routes refuse it with "The task can not be updated" ([`POST /v1/app/tasks/asset-link`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksasset-link)).
* **Several sites:** the link routes accept assets of other sites; a new task ignores an asset of another site.
* **Deleted asset:** tasks stop listing it, and new planned tasks are no longer linked to it.
* **Old iOS picker:** its save does nothing, and its two actions read any site's old asset registers and assets with no membership check, but no button opens it ([Select asset register](https://docs.snapfix.com/how-the-apps-work/screens/assets/select-asset.md#old-ios-picker)).
* **Time zones:** planned-task times depend on the servers' clocks \[[ASK-55](https://github.com/snapfix/docs/blob/main/ASK.md#ask-55-do-the-scheduler-and-api-servers-run-on-utc)].


---

# 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/assets/asset-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.
