Merge pull request #550 from nextcloud/workflow-docs

Add docs for retention and automated tagging

admin_manual/configuration_files/index.rst

@@ -18,4 +18,3 @@ File Sharing and Management
     files_locking_transactional
     previews_configuration
     file_versioning
-    files_access_control

admin_manual/contents.rst

@@ -10,7 +10,8 @@ Table of Contents
     installation/index
     configuration_server/index
     configuration_user/index
-    configuration_files/index    
+    configuration_files/index
+    file_workflows/index
     configuration_database/index
     configuration_mimetypes/index
     maintenance/index

admin_manual/file_workflows/access_control.rst

@@ -98,6 +98,11 @@ option.
 
 * **File collaborative tag:** Either the file itself, or any of the file
   owner's parent folders needs to be tagged with the tag.
+
+  .. note:: Tags used in access control rules should be restricted tags,
+            otherwise any user can remove the tag to access the file again.
+            The best way to do this is with the :doc:`automated_tagging`.
+
 * **File mimetype:** The mimetype of the file, e.g. ``text/plain``
 * **File size:** The size of the file (*Only available on upload*)
 

admin_manual/file_workflows/automated_tagging.rst

@@ -0,0 +1,31 @@
+==========================
+Automated Tagging of Files
+==========================
+
+Nextcloud's Files Automated Tagging app allows to assign collaborative tags
+to files and folders based on rules, similar to :doc:`access_control`.
+
+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.
+
+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 owners will.
+
+
+    .. figure:: images/automated_tagging_sample_rule.png
+       :alt: Sample rule to assign a restricted tag.
+
+In the sample 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 therefor access control and retention
+both work fine without users being able to work around them.
+
+Available rules
+---------------
+
+The available rules can be seen in the access control section: :ref:`available-rules-label`.

admin_manual/file_workflows/index.rst

@@ -0,0 +1,11 @@
+==============
+File Workflows
+==============
+
+
+.. toctree::
+    :maxdepth: 2
+
+    access_control
+    automated_tagging
+    retention

admin_manual/file_workflows/retention.rst

@@ -0,0 +1,33 @@
+==================
+Retention of Files
+==================
+
+Nextcloud's Files Retention app allows to automatically delete files that
+are tagged with a collaborative tag and have a certain age.
+
+Sample
+------
+
+    .. figure:: images/retention_sample.png
+       :alt: Sample rule to delete files after 14 days.
+
+The rule from the sample will delete all files tagged with ``Temporary file`` after 14 days.
+
+Common misconfigurations
+------------------------
+
+Public collaborative tag
+========================
+
+Similar to :doc:`access_control` retention should use ``restricted`` or ``invisible``
+tags. Otherwise any user can remove the tag and the file is not removed after the given
+period. Use :doc:`automated_tagging` to assign such tags to newly uploaded files.
+
+File age
+========
+
+Currently retention is based on the creation date of the file. The sync client sends
+the **original** creation date to the server, while uploading through the web interface
+will create a new file with a **new** creation date.
+We hope to be able to add a ``upload date`` to the filesystem soon, which would make more
+sense. Until then this potentially unexpected behaviour has to be taken into account.

go.php

@@ -9,7 +9,6 @@ $mapping = array(
     'admin-external-storage'  => '/admin_manual/configuration_files/external_storage_configuration_gui.html',
     'admin-sharing-federated' => '/admin_manual/configuration_files/federated_cloud_sharing_configuration.html',
     'admin-sharing'           => '/admin_manual/configuration_files/file_sharing_configuration.html',
-    'admin-files-access-control' => '/admin_manual/configuration_files/files_access_control.html',
     'admin-transactional-locking' => '/admin_manual/configuration_files/files_locking_transactional.html',
     'admin-background-jobs'   => '/admin_manual/configuration_server/background_jobs_configuration.html',
     'admin-config'            => '/admin_manual/configuration_server/config_sample_php_parameters.html',
@@ -19,6 +18,9 @@ $mapping = array(
     'admin-reverse-proxy'     => '/admin_manual/configuration_server/reverse_proxy_configuration.html',
     'admin-ldap'              => '/admin_manual/configuration_user/user_auth_ldap.html',
     'admin-provisioning-api'  => '/admin_manual/configuration_user/user_provisioning_api.html',
+    'admin-files-access-control' => '/admin_manual/file_workflows/access_control.html',
+    'admin-files-automated-tagging' => '/admin_manual/file_workflows/automated_tagging.html',
+    'admin-files-retention'   => '/admin_manual/file_workflows/retention.html',
     'admin-install'           => '/admin_manual/installation/index.html',
     'admin-dir_permissions'   => '/admin_manual/installation/installation_wizard.html#setting-strong-directory-permissions',
     'admin-source_install'    => '/admin_manual/installation/source_installation.html',