Notifications #

The app receives messages from other apps, shows them under the bell in the top right corner, and passes them on to the desktop and mobile clients. Accounts can also get each notification by email. Without the app, nobody is told about new announcements, app updates, or shares that need to be accepted, for example.

Requirements #

The app creates its table oc_notifications when you enable it.

Installation #

In the web interface: open Market from the app menu in the top left corner, search for "Notifications", and install the app.

On the command line:

sudo -u www-data php8.4 occ market:install notifications

If the app is already installed and only disabled:

sudo -u www-data php8.4 occ app:enable notifications

Who sends notifications #

The app itself only creates notifications when an administrator runs occ notifications:generate. Everything else comes from other apps:

Setup #

There is no page in the admin settings and no default for the whole instance. Each account chooses under Settings → Personal → General, in the Mail Notifications section, when an email is sent:

The "Mail Notifications" section is at the bottom of the "General" page.

The email goes out as soon as the notification is created; cron does not collect it first. It is written in the language the receiving account has set.

Administrators set the option for a single account on the command line:

sudo -u www-data php8.4 occ user:setting alice notifications email_sending_option --value always

Only never, action, and always are valid. The command does not check the value, and a typo silently turns off email for that account.

Command line #

notifications:generate sends a notification to one account or to all members of a group. The command help gives 255 characters as the limit for the subject and 4000 for the optional message, but the length is not checked. With --link, clicking the notification opens the given address.

# test notification for one account
sudo -u www-data php8.4 occ notifications:generate --user alice \
  "Maintenance on Friday" "The instance is offline from 6 pm."

# notification for a group, with a link
sudo -u www-data php8.4 occ notifications:generate --group accounting \
  --link https://cloud.example.com/index.php/apps/files "New travel expense policy"

Without --user (short -u) or --group (short -g), the command stops with "Either user or group needs to be given." For an unknown group, it stops with "Group is not known." An unknown account name after --user is not reported; the notification then reaches nobody.

notifications:repairNotifications fixes stored notifications. The first argument selects the repair:

# point link, icon, and actions to this instance,
# for example after an address change or after moving a database
sudo -u www-data php8.4 occ notifications:repairNotifications oldBaseUrl \
  --old-base-url https://old.example.com/cloud

# cut every absolute link down to its path
sudo -u www-data php8.4 occ notifications:repairNotifications relativeLinks

oldBaseUrl rewrites only relative links below the old webroot and absolute links to the old host. Everything after ? and # stays as it is. If you pass only the webroot (--old-base-url /cloud), only relative links are changed. The command takes the new webroot from --new-webroot /path, or from the path of overwrite.cli.url without that option.

relativeLinks, in contrast, cuts every absolute link down to its path, including links to other servers, and drops everything after ? and #. After an address change, oldBaseUrl with the old address is the safer choice. Any other value is rejected with "Invalid subject".

Usage #

When there are notifications, the bell appears in the top right corner. Click it to open the list. Notifications with actions show buttons for them, for example to accept or decline a share. The X dismisses a notification and deletes it.

New notifications appear under the bell at the top right. The X dismisses a notification.

The web interface checks for new notifications every 30 seconds. The desktop and mobile clients show the same notifications.

Limits and notes #

• Without notifications, the bell stays hidden. This is not an error.
• The app cannot be limited to groups. occ app:enable notifications --groups … stops with "notifications can't be enabled for groups."
• If the account has no email address or an invalid one, the notification stays in the web interface but no email goes out. The server log then shows "email for the user isn't set" under notifications, or "user's email … isn't valid" without an app name.
• When an account is deleted, the app removes its notifications.
• Clients read and delete notifications through the OCS API at /ocs/v2.php/apps/notifications/api/v1/notifications. The notifications section under /ocs/v2.php/cloud/capabilities shows whether the app is available.

Troubleshooting #