From 4546b5d93bb2fb213298275725be61884bda5492 Mon Sep 17 00:00:00 2001 From: Josh Date: Tue, 10 Nov 2026 11:30:56 -0500 Subject: [PATCH] docs: clarify automated file tagging behavior and usage Explain rule matching, evaluation triggers, tag permissions, and behavior for existing files and assigned tags. Expand the folder-tagging example and document request-context and storage-root limitations. Clarify that other apps perform downstream actions, with examples and documentation links for retention, access control, and PDF conversion. Signed-off-by: Josh --- .../file_workflows/automated_tagging.rst | 132 +++++++++++++----- 1 file changed, 100 insertions(+), 32 deletions(-) diff --git a/admin_manual/file_workflows/automated_tagging.rst b/admin_manual/file_workflows/automated_tagging.rst index dbdc95257d6..2e277d50a93 100644 --- a/admin_manual/file_workflows/automated_tagging.rst +++ b/admin_manual/file_workflows/automated_tagging.rst @@ -1,55 +1,123 @@ -========================== -Automated tagging of files -========================== +====================== +Automated file tagging +====================== -Nextcloud's Files Automated Tagging app allows to assign collaborative tags -to files and folders based on rules, similar to :doc:`access_control`. +Nextcloud's Automated file tagging app adds the ``Tag a file`` operation to +Nextcloud Flow. It assigns collaborative tags to files and folders based on +configured conditions. These tags can be used by :doc:`retention`, +:doc:`access_control`, and other workflow apps. + +How it works +------------ + +Each rule group contains one or more conditions combined with AND: all +conditions must match for the group to match. Every matching group assigns its +configured tag. + +Rules are evaluated when eligible files or folders are inserted into or updated +in Nextcloud's file cache, not only when files are uploaded. For example, items +created directly on external storage can be evaluated when Nextcloud discovers +them. + +Adding or changing a rule does not itself tag existing files. Assigning a tag to +a folder does not trigger a recursive evaluation of its existing contents. +Tags assigned by a rule are not automatically removed when the rule stops +matching or is deleted. + +Configuration +------------- + +Install and enable the Automated file tagging app as described in +:doc:`../apps_management`, then open +:menuselection:`Administration settings --> Flow` and select the ``Tag a file`` +operation. + +Users can also create personal flows when user flows are enabled; see +:doc:`configuration`. Non-admin users can select only visible, user-assignable +tags as the tags to assign. Administrators can also select restricted and +invisible tags. Assigning restricted and invisible tags --------------------------------------- -The main functionality of this app is to allow users to indirectly assign -restricted and invisible tags to files they upload. +Restricted tags are visible to regular users but cannot be assigned or removed +by them. Invisible tags are also hidden from regular users. Administrators can +manage both types. -This is especially useful for retention and :doc:`access_control`, so people -that got the files shared can not remove the tag to stop the retention or -allow access against the owner's will. +Use these tag types for retention and access control so that regular users cannot +disable a policy by removing its tag. If tagging depends on another tag, protect +that condition tag too: removing it can prevent future items from matching. +Automatic tagging assigns tags; the retention and access-control policies must +be configured separately. Example ------- -After installing the Files automated tagging app as described in :doc:`../apps_management` -navigate to the configuration and locate the Workflow settings. +To tag files inside a folder marked with ``Protected content``: + +1. As an administrator, create restricted tags named ``Protected content`` and + ``Protected file``, and assign ``Protected content`` to the source folder. +2. In Flow, add a ``Tag a file`` operation with a collaborative-tag condition + matching ``Protected content``. +3. Select ``Protected file`` as the tag to assign and save the flow. - .. figure:: images/automated_tagging_sample_rule.png - :alt: Example rule to assign a restricted tag. +When an eligible item is evaluated, the collaborative-tag condition checks both +the item itself and its parent folders. Matching items receive +``Protected file``, including items in nested subfolders. -In the example you can see a simple rule with only one condition. -It will tag all files with the restricted tag ``Protected file`` that are -uploaded into a folder that is tagged with ``Protect content``. No user can -remove the tag ``Protected file`` and therefore access control and retention -both work fine without users being able to work around them. +.. figure:: images/automated_tagging_sample_rule.png + :alt: Example rule to assign a restricted tag. -In this case the folder will also be tagged with tag ``Protected file``, to avoid -this, simply modify the rule to exclude Directory ``httpd/unix-directory`` from it. +The source folder and subfolders can also match when they are evaluated. To +assign the output tag only to files, add a ``File MIME type`` condition with +operator ``is not`` and value ``httpd/unix-directory``. This does not remove tags +already assigned to folders. - .. figure:: images/automated_tagging_sample_rule_exclude_folder.png - :alt: Example rule to assign a restricted tag except to Directory. +.. figure:: images/automated_tagging_sample_rule_exclude_folder.png + :alt: Example rule to assign a restricted tag except to Directory. Available rules --------------- -The available rules can be seen in the access control section: :ref:`available-rules-label`. +See :ref:`available-rules-label` for the shared workflow conditions. + +Keep the evaluation context in mind: + +* **File size** uses upload request headers, not the size stored in the file + cache. Do not rely on it for background scans or other non-upload operations. +* **User group membership** checks the currently authenticated user, not the + file owner. Without an authenticated user, ``is`` does not match and ``is not`` + matches. +* Request-based conditions describe the request that triggers evaluation, not + necessarily the request that originally uploaded the file. Background + processing may not have the same request context. .. note:: + Do not rely on automatic tagging to initialize the root folders of external + storage mounts or group folders. Eligibility depends on the storage and + mount path. Assign any required initial tags manually. Items inside these + folders are evaluated on eligible file-cache insertions and updates. + +Using tags with other actions +----------------------------- + +This app only assigns tags. Other apps can use those tags to select files +for their own policies or actions. Each app must be installed and configured +separately. + +For example: + +* :doc:`retention` can automatically delete tagged files after a configured age. +* :doc:`access_control` can restrict access to tagged files. +* The `PDF Converter app + `_ can convert + supported documents to PDF when a tag is assigned and its configured + conditions match. It requires LibreOffice on the server. + +Refer to each app's documentation for requirements and configuration details. - Please note that the rules do not apply when creating external storages and groupfolders. - The root folders of those need to be tagged manually with the desired initial tags. - Items created inside later on apply the rules as defined. +.. tip:: -Executing actions ------------------ + Nextcloud GmbH provides customers with hands-on help and related + documentation through the `customer portal `_. -It is possible to execute actions like ```convert to PDF``` based on assigned tags. Nextcloud -GmbH assists customers in this with hands-on help and documentation on our -`customer portal `_.