diff --git a/admin_manual/configuration_server/activity_configuration.rst b/admin_manual/configuration_server/activity_configuration.rst index 121ea5d084e..6950bcc068c 100644 --- a/admin_manual/configuration_server/activity_configuration.rst +++ b/admin_manual/configuration_server/activity_configuration.rst @@ -2,83 +2,113 @@ Activity app ============ -You can configure your Nextcloud server to automatically send out e-mail notifications -to your users for various events like: +The Activity app tracks events across your Nextcloud instance and can +notify users via the activity stream, email, and push notifications. +It is shipped and enabled by default. -* A file or folder has been shared -* A new file or folder has been created -* A file or folder has been changed -* A file or folder has been deleted +.. figure:: ../images/activity-settings-admin.png -Users can see actions (delete, add, modify) that happen to files they have access to. -Sharing actions are only visible to the sharer and sharee. + *The Activity admin settings page showing default notification + preferences for new accounts.* -Enabling the activity app -------------------------- -The Activity App is shipped and enabled by default. If it is not enabled -simply go to your Nextcloud Apps page to enable it. +Configuring your Nextcloud for the Activity app +------------------------------------------------ -Configuring your Nextcloud for the activity app ------------------------------------------------ +Enabling email notifications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To configure your Nextcloud to send out e-mail notifications a working -:doc:`email_configuration` is mandatory. +To send activity notification emails, a working +:doc:`email_configuration` is required. -Furthermore it is recommended to configure the background job ``Webcron`` or -``Cron`` as described in :doc:`background_jobs_configuration`. +It is also recommended to configure the background job to ``Webcron`` +or ``Cron`` as described in :doc:`background_jobs_configuration`. +The ``Ajax`` mode may delay or skip email delivery. -There is also a configuration option ``activity_expire_days`` available in your -``config.php`` which allows you to clean-up older activities from the database. -.. _label-activities-groupfolders: +Admin settings +^^^^^^^^^^^^^^ -Activities in groupfolders or external storages ------------------------------------------------ +As an administrator, you can: -By default activities in groupfolders or external storages are only generated for the current user. -This is due to the logic of groupfolders and external storages. There is a config flag -``activity_use_cached_mountpoints`` that makes activities in groupfolders and external storages work -like in normal shares when set to ``true``. +* Enable or disable notification emails globally using the + **Enable notification emails** checkbox in **Settings** > + **Administration** > **Activity**. +* Configure the default notification preferences for new accounts. + Existing users keep their personal settings. The defaults apply + to accounts created after the change. -.. warning:: - This config option comes with the following limitations: +Configuration reference +----------------------- - 1. If "Advanced Permissions" (ACLs) are enabled in a groupfolder, the activities don't respect the permissions and therefore all users see all activities, even for files and directories they don't have access to. **This potentially leaks sensitive information!** See `this issue `_ for more information. - 2. Users that had access to a groupfolder, share or external storage can see activities in their stream and emails that happen after they are removed until they login again - 3. Users that are newly added to a groupfolder, share or external storage can not see activities in their stream nor emails that happen after they are added until they login again +The following ``config.php`` options control Activity app behavior. -Better scheduling of activity emails ------------------------------------- +.. list-table:: + :header-rows: 1 + :widths: 30 15 55 -In certain scenarios it makes sense to send the activity emails out more regularly, -e.g. you want to send the hourly emails always at the full hour, daily emails before -people start to work in the morning and weekly mails shall be send on monday morning, -so people can read up when starting into the week. + * - Option + - Default + - Description + * - ``activity_expire_days`` + - ``365`` + - Number of days to retain activity records. A daily background + job deletes all activities older than this value. Set to ``0`` + to disable expiration. + * - ``activity_use_cached_mountpoints`` + - ``false`` + - When ``true``, activities in team folders and external storages + are generated for all users with access, not just the current + user. See :ref:`label-activities-groupfolders` for details and + caveats. + * - ``activity_expire_exclude_users`` + - ``[]`` + - An array of user IDs whose activity records are never deleted + by the expiration job. See :ref:`label-activities-exclude-users`. -A console command is available to trigger sending those emails. -This allows to set up special cron jobs on your server with the known -granularity, instead of relying on the Nextcloud cron feature which is not very flexible -on scheduling. -To implement the samples mentioned above, the following three entries are necessary:: +.. _label-activities-groupfolders: + +Activities in team folders or external storages +----------------------------------------------- + +By default, activities in team folders or external storages are only +generated for the current user. This is due to the underlying logic +of these storage backends. The config flag +``activity_use_cached_mountpoints`` makes activities work like in +normal shares when set to ``true``. + +:: + + 'activity_use_cached_mountpoints' => true, + +.. warning:: + + This config option comes with the following limitations: + + 1. If "Advanced Permissions" (ACLs) are enabled in a team folder, + activities do not respect the permissions and all users see all + activities, even for files and directories they do not have + access to. **This potentially leaks sensitive information!** See + `this issue `_ + for more information. + 2. Users that had access to a team folder, share or external + storage can see activities in their stream and emails that + happen after they are removed until they log in again. + 3. Users that are newly added to a team folder, share or external + storage cannot see activities in their stream nor emails that + happen after they are added until they log in again. - # crontab -u www-data -e - 0 * * * * php -f /var/www/nextcloud/occ activity:send-mails hourly - 30 7 * * * php -f /var/www/nextcloud/occ activity:send-mails daily - 30 7 * * MON php -f /var/www/nextcloud/occ activity:send-mails weekly -If you want to manually send out all activity emails which are queued, you can run -``occ activity:send-mails`` without any argument. +.. _label-activities-exclude-users: -Excluding users from the activity expiration --------------------------------------------- +Excluding users from activity expiration +---------------------------------------- -For certain users, it might make sense to never expire their activity data, for example -administrators. -You can set the config value `activity_expire_exclude_users` in your Nextcloud config to -exclude these users from expiration:: +For certain users, it might make sense to never expire their activity +data, for example administrators. Set the config value +``activity_expire_exclude_users`` in your ``config.php``:: 'activity_expire_exclude_users' => [ 'admin', @@ -86,4 +116,68 @@ exclude these users from expiration:: 'second_admin' ] -For these users, their activity records will never deleted from the database. +For these users, their activity records will never be deleted from the +database. + + +Better scheduling of activity emails +------------------------------------- + +In certain scenarios it makes sense to send the activity emails more +regularly. For example, you may want to send the hourly emails always +at the full hour, daily emails before people start to work in the +morning, and weekly emails on Monday morning. + +A console command is available to trigger sending those emails. This +allows you to set up custom cron jobs with specific timing instead of +relying on the Nextcloud background job:: + + # crontab -u www-data -e + 0 * * * * php -f /var/www/nextcloud/occ activity:send-mails hourly + 30 7 * * * php -f /var/www/nextcloud/occ activity:send-mails daily + 30 7 * * MON php -f /var/www/nextcloud/occ activity:send-mails weekly + +If you want to manually send out all queued activity emails, you can +run ``occ activity:send-mails`` without any argument. + + +Troubleshooting +--------------- + +Users are not receiving notification emails +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Verify that email is configured correctly. Send a test email from + **Settings** > **Administration** > **Basic settings**. +2. Check that **Enable notification emails** is turned on in + **Settings** > **Administration** > **Activity**. +3. Verify that the user has email notifications enabled in their + personal notification settings (**Settings** > **Personal** > + **Notifications**). +4. Ensure the background job is running. If you use ``Cron``, check + that the system cron job is executing + ``php -f /var/www/nextcloud/cron.php`` regularly. +5. Check the Nextcloud log (``data/nextcloud.log``) for mail-related + errors. + +Activities are missing for shared files or team folders +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, activities in team folders and external storages are only +generated for the acting user. See +:ref:`label-activities-groupfolders` for how to enable activities for +all users with access. + +Database growing large due to activity data +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Activity app stores all events in the database. On instances with +many users or high file turnover, this can lead to significant +database growth. To manage this: + +* Set ``activity_expire_days`` to a lower value (e.g. ``90`` or + ``180``) to automatically clean up older records. +* Monitor the ``oc_activity`` and ``oc_activity_mq`` tables directly + if you need to assess current size. +* Ensure the Nextcloud background job is running so that the daily + expiration job executes. diff --git a/admin_manual/images/activity-settings-admin.png b/admin_manual/images/activity-settings-admin.png new file mode 100644 index 00000000000..b9387bbab22 Binary files /dev/null and b/admin_manual/images/activity-settings-admin.png differ