From 045ad00fae225c9af89036d65398c3e6ae0908c5 Mon Sep 17 00:00:00 2001 From: martin-ai Date: Wed, 10 Jun 2026 06:54:36 +0000 Subject: [PATCH] for-users: document background tasks (#79757) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Charlotte (#79757) asked for a comprehensive user-facing article on fylr's background tasks under additional-features. New page covers: - What background tasks are and why a user would reach for them - Where the Task Manager lives (tray icon in the header) - How to create a task — pick a Module, give it a Title, fill the per-module parameters, save, walk away - The three end-user-relevant modules and their parameters: * Metadata — re-apply a mapping, optionally limited by a search, with merge-vs-override and tag-set/unset options * Delete Objects — bulk delete from a search, with the delete-policy choice between "also delete linked" and "unlink" * Set / Unset Tags — bulk tag operation from a search - The Task Manager list (Module / Title / Status / Started / Finished / Next Run) and how to read it, including where the task log lives when something fails - Deleting old task receipts vs cancelling a running task - The system.task system right and the rule that module-level operations still require their own underlying permissions (no rights bypass) Two hint blocks: - a warning to spot-check the search filter before bulk-delete, since a task with the wrong filter can affect far more records than intended - a note that tasks are user-scoped, with system.root being the exception that sees everyone's tasks The page is added to SUMMARY.md under FOR USERS > Additional Features, next to Change History, matching the location requested in the ticket. The page style follows the existing user-facing articles (change-history.md, lists.md): short intro, parameter bullets, hint callouts for caveats, a Required Permissions block at the end. --- SUMMARY.md | 1 + .../additional-features/background-tasks.md | 103 ++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 for-users/additional-features/background-tasks.md diff --git a/SUMMARY.md b/SUMMARY.md index 4a76fd6..76cae16 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -147,6 +147,7 @@ * [Lists](for-users/lists.md) * [Additional Features](for-users/additional-features/README.md) * [Change History](for-users/additional-features/change-history.md) + * [Background Tasks](for-users/additional-features/background-tasks.md) * [Mobile App](for-users/mobile-app.md) ## FOR ADMINISTRATORS diff --git a/for-users/additional-features/background-tasks.md b/for-users/additional-features/background-tasks.md new file mode 100644 index 0000000..6ccf874 --- /dev/null +++ b/for-users/additional-features/background-tasks.md @@ -0,0 +1,103 @@ +--- +description: >- + Run long-running operations on many records — bulk metadata updates, deletes, + and tagging — in the background while you continue working. +--- + +# Background Tasks + +Some operations in fylr touch many records at once. Re-applying a metadata mapping to thousands of files, deleting a search result with all its links, or setting a tag on every record in a pool can each take several minutes. Background tasks let you start such an operation, walk away, and come back to a finished result instead of holding a browser tab open. + +A task runs on the server. You can close the browser, log out, or work on something else while it runs. The Task Manager shows the progress of every task you started and keeps each finished task as a receipt with its log. + +## Where to find the Task Manager + +The Task Manager opens from the icon in the tray area of the fylr header bar (top right, next to your user menu). The button is only visible to users who have permission to run tasks. The window that opens lists every task you have created, newest first, with five columns: Module, Title, Status, Started, Finished, and Next Run. + +To dismiss the window, click outside of it or close it with the X. The task itself keeps running on the server. + +## Creating a task + +Click the plus button at the bottom of the Task Manager. A dialog opens with two fields you always fill in: + +* **Module** — which kind of operation the task will perform. The available modules are described below. +* **Title** — a short description so you can recognise the task later. The title only helps you keep your tasks apart; it has no effect on what the task does. + +Below those two fields the dialog rebuilds itself depending on the module you picked. Each module has its own parameters — for example, the *Delete Objects* module asks for a search and a delete policy, the *Metadata* module asks for a mapping. Fill in the parameters, then click **Save**. + +A new entry appears in the Task Manager list. The task is queued and will start as soon as the server has capacity. You can close the dialog and the Task Manager — the task keeps running. + +## Available modules + +### Metadata + +Re-applies a configured metadata mapping to a set of records. Use this after a mapping has changed, after a configuration import, or after a basetype change, to bring records back in line with the new mapping. + +The module asks for: + +* **Mapping** — the configured metadata mapping to apply. +* **Search** — limits the task to a subset of records. Leave empty to run over everything the mapping applies to. +* **Set/Unset Tags** — optionally adds or removes tags as part of the mapping pass. +* **Merge Values** / **Override Values** — controls whether values from the mapping are merged into existing values or replace them outright. + +### Delete Objects + +Bulk-deletes records that match a search. This is the same delete that the right-click menu offers for a single record — except a task can apply it to hundreds of thousands at once and walks the link graph safely. + +The module asks for: + +* **Search** — defines which records to delete. +* **Delete Policy** — controls what happens to records that link to the records you are deleting: + * **Delete** also deletes subordinate or reverse-linked records. + * **Unlink** removes the links and leaves the linking records intact. + +{% hint style="warning" %} +A bulk-delete with the wrong search filter can affect many more records than you intended. Run the same search in the normal Search view first to confirm the result set before starting the task. +{% endhint %} + +### Set / Unset Tags + +Adds or removes tags on every record matching a search. Useful for adopting a new tagging convention, or cleaning up tags from an old workflow without opening each record individually. + +The module asks for: + +* **Search** — which records to act on. +* **Tags to set** and **Tags to unset** — the tags to add to or remove from each matching record. + +## Reading the task list + +| Column | What it shows | +| --- | --- | +| Module | Which module the task uses. | +| Title | The description you entered when you created the task. | +| Status | Where the task is in its life cycle — *queued*, *running*, *finished*, or *failed*. | +| Started | When the task actually began executing on the server. Empty if the task is still queued. | +| Finished | When the task ended. Empty if the task is still running. | +| Next Run | For tasks that are scheduled to repeat, when they will run next. *Now* means the task is queued and waiting for capacity. | + +Click a row to open the task's details: the parameters you supplied, the records it touched, and the log of what happened. The log is the place to look if a task ended with status *failed* — fylr writes the error message into the log so you can decide whether to fix the input and run the task again. + +## Deleting old tasks + +Tasks accumulate over time. Select a finished task and click the minus button at the bottom of the Task Manager to delete it. The task receipt is removed; the records the task already acted on are not affected. + +Tasks that are still queued or running cannot be deleted from the list directly. Open the task's details and use **Cancel** there instead. + +## Required Permissions + +The following permissions control who can see and run background tasks. + +Available under a user's or group's **System Rights**. + +Permission **Access Tasks** (`system.task`): + +* Allows users to open the Task Manager and see their own tasks. +* Without this permission the Task Manager icon is hidden from the header bar entirely. + +Each module additionally requires whatever permission the underlying operation would require if performed manually. For example, the *Delete Objects* module is only useful to users who would be allowed to delete the matched records one by one — the task does not bypass record-level permissions. + +{% hint style="info" %} +Tasks are user-specific. You only see tasks you created. Administrators (`system.root`) can see and manage every user's tasks. +{% endhint %} + +