Notifications

Part of the IP4CMS portal. ← All module guides

What it's for — Notifications is your personal notification centre inside the portal. It collects the alerts the system raises for you — member status changes, classified-ad outcomes, event registrations and general system alerts — into one list you can read, filter, mark as read and clear. The same notifications can also be pushed to your phone or browser as a device (push) notification when you have registered a device. The list is per-user: you only ever see notifications addressed to you (or to an access scope you belong to).

Where to find it — In the portal side menu, open Notifications. The direct route is /app/notifications. The screen opens on the Notifications list. An unread badge/count is also surfaced in the portal header and refreshes automatically every 30 seconds.

Before you start

• You need to be signed in to the portal — the screen sits behind the standard authentication guard.
• Viewing and managing your own notifications (reading, filtering, marking read, deleting, clearing) requires nothing beyond being signed in. There is no separate licence module or permission gate on the notification centre itself.
• Creating/sending a notification to others is a separate, admin-level action. It requires your tenant's licence to include the communication module and your account to hold the communication:notification:create permission. This is an API/back-office capability — there is no "compose notification" form in this portal module.
• Push (device) notifications only go out if the platform has Firebase Cloud Messaging configured and enabled (FIREBASE_PUSH_ENABLED) and you have registered a device. See Tips & gotchas.

Key tasks

Viewing the notification centre

1. Open Notifications from the side menu (/app/notifications).
2. The page loads your notifications newest-first in a paginated grid. Each row shows:

• Type — an icon and a coloured badge naming the notification type (e.g. Member Status Change, Classified approved, Event Registration, General). Unread rows get a highlighted icon background.
• Title — the notification's headline.
• Message — a truncated preview of the body (hover to see the full text via the tooltip).
• Priority — a Low / Medium / High badge, when the notification carries a priority. High-priority items are flagged in red.
• Status — read/unread state, plus a pulsing dot on unread rows.
• Date — the absolute date and a relative time ("2 hours ago").

1. Use the toolbar to narrow the list:

• Search — type a term and press Enter.
• Type filter — All Types, or a specific type (Member Status Change, System Alert, Event Registration, Classified pending/approved/declined, General).
• Status filter — All Notifications, Unread Only, or Read Only.
• Priority filter — All Priorities, High, Medium or Low.

Filters apply as you change them; the list resets to page 1. Use Clear to reset all filters.

1. Adjust the page size and page through results with the grid's pagination controls.
2. Click Refresh (top right) at any time to reload the list and the unread count.

Note: the Priority filter is offered in the toolbar, but priority is set on a notification when it is created — there is no way to change a notification's priority from this screen.

Reading a notification (and the detail view)

1. In the list, click the View (eye) action on a row, or click the row itself.
2. A detail modal opens showing the full title, message (with line breaks preserved), type, priority (if medium/high), status and date.
3. Opening an unread notification automatically marks it as read and decrements your unread count.
4. If the notification has somewhere to go (an action URL or a related record), the modal shows a Go to Details button. Clicking it marks the item read and navigates you to the relevant screen — for example:

• Member status change → the member (/app/members/:id)
• Event registration → the event (/app/events/:id/detail)
• Classified notifications → the classified (/app/classifieds/:id)

A notification with an explicit action URL navigates straight to that URL instead.

1. Click Close (or click outside the modal) to dismiss it.

Marking notifications as read

• One at a time — on an unread row, click the Mark Read (check) action, or simply open it. Reading a notification stamps a "read at" time and updates the unread badge.
• All at once — click Mark All Read (top right). Every unread notification visible to you is marked read and the unread count drops to zero. The toolbar message confirms how many were marked.

Deleting and clearing notifications

• Delete one — click the Delete (trash) action on a row. The notification is removed from your list. (Deleting is immediate on a single row; there is no per-row confirmation prompt.)
• Clear all — click Clear All (top right). This deletes every notification visible to you (read and unread) and empties the list. The button is disabled while loading or when the list is already empty. Treat this as permanent — there is no undo and notifications are not archived.

Bulk actions caveat. The portal code includes "bulk mark as read" and "bulk delete" helpers (and a delete confirmation dialog), but the standard list grid is configured non-selectable, so there are no row checkboxes to drive them in this screen. In practice you work one row at a time, or use Mark All Read / Clear All for everything at once.

How push (device) notifications reach you

You don't subscribe to push notifications from this screen. Push delivery is wired up by the app you sign in from (the resident/member app or a portal client that registers a device):

1. When you grant notification permission in the app, the app obtains a Firebase device token and registers it with the platform (it calls POST /notifications/push-token with the token, your platform — ios, android or web — and an app id).
2. From then on, whenever a notification is created for you, the platform looks up your active device tokens and sends the same title and message to your device(s) via Firebase, alongside writing the in-app notification to this list.
3. Signing out / disabling notifications unregisters the device (DELETE /notifications/push-token), so it stops receiving pushes.

There is no operator-facing "manage my devices" panel in this module — registration is automatic and lives in the client app.

How the data connects

What triggers a notification. Notifications are created by the system as a side-effect of events elsewhere in the platform, not hand-written in this screen. The built-in triggers include:

• Member status change — member_status_change notifications to the relevant location managers.
• Classifieds, events, support, SLA and system alerts — the corresponding types (classified_pending/approved/declined, event_registration, support_comment, sla_warning, sla_breach, system_alert, general).

An admin with the right permission can also create one explicitly via POST /notifications.

Where it's stored. Each notification is a row in the tenant's user_notification table, tagged with tenant_id and addressed either to a specific user_id or to an auth_scope_id (an access scope — so everyone in that scope sees it). It carries the type, title, message, optional related-record id, priority, is_read flag and timestamps. Notifications persist until you delete them (or an admin runs an optional cleanup of items older than N days) — they are not auto-expired.

How it reaches you.

• In-app — the list queries user_notification for rows where the user_id is you or the auth_scope_id is one of your scopes, newest first. The unread count uses the exact same matching.
• Push — at creation time, if Firebase push is enabled, the platform resolves your (or the scope's) active, non-revoked device tokens from the user_push_token table and sends the title/message through Firebase Cloud Messaging. If Firebase reports a token as invalid (unregistered/expired), that token is automatically disabled so it won't be tried again.
• Background processing — some senders queue notification creation (and optional email) through the job queue rather than writing it inline, but the end result — a user_notification row plus any push — is the same.

Permissions & access

• Reading and managing your own notifications — any signed-in portal user. The list is strictly scoped to notifications addressed to your user id or to an access scope you belong to; you cannot see or act on another user's notifications. Mark-as-read, delete and clear all enforce the same ownership check on the server.
• Creating/sending notifications — gated behind the communication licence module and the communication:notification:create permission (NOTIFICATION_CREATE_ALL). This is an admin/back-office capability exposed via API, not a button in this module.
• Who receives what — a notification is delivered either to one named user or to an entire access scope (every active user in that scope sees it). System alerts can be fanned out to all active users in the tenant. Push notifications additionally require the recipient to have at least one registered, enabled device.

Tips & gotchas

• Read = "Approved", Unread = "Declined" labels. In the list grid and the detail modal, the read/unread status badge literally renders the words Approved (read) and Declined (unread). This is a cosmetic label quirk in this screen — it has nothing to do with classified approvals. Read the green badge as "read" and the amber badge as "unread".
• Clear All is permanent. It deletes every notification visible to you, read and unread, with no undo and no archive. Use Mark All Read if you just want to quiet the badge.
• No compose screen. This module is a notification centre, not a sender. Sending notifications to other users is done through the API with the communication module and create permission.
• Push needs Firebase + a registered device. If FIREBASE_PUSH_ENABLED is on but no Firebase credentials are configured, in-app notifications still work but no device pushes go out (the server logs a one-time warning). Likewise, if you've never granted notification permission in the app, you'll see notifications in the portal but nothing on your device.
• Invalid device tokens self-heal. If Firebase rejects a token as unregistered/expired, the platform disables it automatically — you don't need to clean up stale devices manually. Re-registering (signing back in on the device) creates a fresh token.
• Scope notifications. Some notifications are addressed to an access scope rather than to you personally, so colleagues in the same scope may see and act on the same item. Marking it read only affects your view of it.
• Auto-refresh. The unread count refreshes on its own roughly every 30 seconds; the list itself refreshes when you open the page, change a filter, take an action, or click Refresh.