Notifications

Notifications are short messages that administrators publish to the users of the webclient: a planned maintenance window, an incident being worked on, a new release. A notification shows as a banner at the top of every page for as long as it is valid, for all users or only for the members of selected groups.

The banner

Every logged-in user sees the notifications meant for them in a banner under the header, one line each:

• the severity sets the colour and the icon: Information, Warning or Critical
• the title comes first, then the message
• a More information link opens the notification’s link in a new tab, if it has one
• the close button dismisses the notification, if it can be dismissed

Several notifications are listed most severe first, and the newest first within the same severity.

The banner asks the server for the current notifications when a page is loaded, and then every two minutes by default (see Configuration). A hidden browser tab skips these checks and catches up as soon as it is shown again. So a notification appears, changes or disappears without a reload, within one interval.

Screen readers announce a new notification without interrupting the user; a Critical one is announced straight away.

Dismissing a notification

A dismissed notification stays hidden in that browser, in all its tabs, until one of these happens (other open tabs hide it at their next check):

• an administrator saves the notification again, even without changing anything
• an administrator switches it off and on again
• the browser’s site data is cleared. Some browsers are set up to do that on every close, and a private window does it when it is closed: there, a dismissed notification shows again after the browser is restarted

Showing a notification again after a change is intended: whoever changed it wants it to be seen. Dismissals are kept in the browser only. The same user on another browser or device sees the notification again, and the list of dismissals is cleaned up by itself once notifications are no longer shown. Where the browser does not let the page store anything, a dismissal lasts only until the page is reloaded.

A notification that cannot be dismissed stays visible until its validity ends or it is switched off.

Managing notifications

Administrators manage notifications in Admin → Notifications.

The list shows every notification with its status, title, severity, audience and validity:

• the Filter field narrows the list down to the titles containing the text typed; the count next to it tells how many of all notifications are listed
• Active only hides the notifications that are switched off. Switched-on notifications stay listed even while they are scheduled or ended
• the status icon tells whether a notification is switched on. Hovering over it shows its status:

Each row offers these actions, depending on the permissions:

Creating and editing a notification

New notification opens an empty form; a new notification starts switched off, for all users, dismissible and valid from now.

The server refuses a notification that breaks one of these rules, and names the field in the form:

• the validity has to end after it starts
• a notification that cannot be dismissed needs a validity end, so that it cannot stay on screen for good
• a notification whose validity has already ended cannot be switched on; move its validity first
• a notification for Selected groups needs at least one group, and one for All users takes none

A user who belongs to several of a notification’s groups still sees it once.

Permissions

Notifications use the engine’s authorizations on the System resource, with the resource ID *. No separate permission is needed to see the banner: every logged-in user receives the notifications of their audience.

Grant them in Admin → Authorizations → System, see Authorization Management. The server checks every request right away. The webclient reads a user’s permissions when the user logs in, so after a change the entry in Admin and the buttons follow after the next login.

Configuration

Notifications take three settings:

cibseven:
  webclient:
    notifications:
      enabled: true

"notifications": {
  "system": {
    "interval": 120000
  }
}

Database

Notifications are stored in two tables of the engine schema:

They form a schema component of their own. A new installation gets them with the engine’s schema creation, or from the $DATABASENAME_engine_$PLATFORM_VERSION.sql create script. An existing 2.2 installation gets them with the 2.2 to 3.0 update, see the database schema update guide. An engine that maintains its schema itself (databaseSchemaUpdate set to true) also adds them on startup when they are missing.

Validity and change times are stored in UTC.