Notifications

Notifications - documentazione operativa e tecnica

advancednotificationsstable

Overview

Notifications

Gestione notifiche applicative, eventi e feedback utente.

Screenshot reference (manuale utente)

  • manual__notifications__01.png: stato UI notifiche nella sottosezione Notifications.

Architettura funzionale

Descrizione:

la funzionalita raccoglie eventi applicativi, li persiste in _notifications e li propaga in realtime alla UI.

  • Storage: tabella metadata DB dbo._notifications.
  • Write path: endpoint POST /api/Notifications/enqueue che usa dbo.sp_enqueue_notification.
  • Read path: endpoint GET /api/Notifications/unread/{userId}.
  • Realtime path: WebSocket /ws/notifications?userId=... con snapshot push.
  • UI: componente wuic-notification-bell (popover lista notifiche, badge unread, mark-read e clear-read).

Tabella _notifications

Campi principali gestiti dal framework:

  • id: identificativo notifica.
  • user_id: utente destinatario.
  • type: tipo (es. info, warning, success, ...).
  • message: testo mostrato in UI.
  • target_json: destinazione click (route/path di navigazione).
  • payload_json: payload libero per dettaglio applicativo.
  • is_read, read_at: stato lettura.
  • created_at, deleted_at: timeline e soft-delete.
  • created_by, source: tracciabilita origine.

Trigger / automazioni che popolano _notifications

Descrizione:

il pattern consigliato e centralizzare l'inserimento in sp_enqueue_notification, richiamata da trigger o job.

  • Il framework fornisce la stored procedure dbo.sp_enqueue_notification (script: scripts/add-notifications-framework.sql).
  • I trigger SQL applicativi o job backend possono popolare _notifications in due modi:
  • chiamando dbo.sp_enqueue_notification (approccio consigliato);
  • inserendo direttamente in tabella rispettando i campi minimi (user_id, type, message).
  • Pattern tipico: trigger su tabella business (AFTER INSERT/UPDATE) che, al verificarsi di una condizione, crea una notifica per uno o piu utenti.
Snippet 1SQL
DECLARE @dbName NVARCHAR(256) = DB_NAME();
DECLARE @isBrokerEnabled BIT;

SELECT @isBrokerEnabled = is_broker_enabled
FROM sys.databases
WHERE name = @dbName;
  • userId: 100275
  • type: "warning"
  • message: "Ordine in ritardo"
  • targetJson.route: "#/orders/list"
  • targetJson.filter: "status||eq||late"
  • payloadJson.orderId: 12345

Trigger Metadata-Driven Da md_props_bag.notifications.triggerRules

Le regole possono essere centralizzate nel metadata tabella (md_props_bag.notifications.triggerRules) e tradotte in trigger SQL runtime.

  • Struttura regola: event, watchColumns, userIdExpr, typeTemplate, messageTemplate, targetTemplate, payloadTemplate, source, triggerName.
  • Pipeline: metadata route -> generazione trigger SQL server -> sp_enqueue_notification -> websocket bell (/ws/notifications?...).
  • Snippet inline (insert): {"enabled":true,"event":"insert","watchColumns":[],"userIdExpr":"{{owner_user_id}}","messageTemplate":"Nuovo record {{id}}"}.
  • Snippet inline (update): {"enabled":true,"event":"update","watchColumns":["status"],"userIdExpr":"{{owner_user_id}}","messageTemplate":"Aggiornato {{id}}: {{status}}"}.
  • Snippet inline (delete): {"enabled":true,"event":"delete","watchColumns":[],"userIdExpr":"{{owner_user_id}}","targetTemplate":"{\"path\":\"/{{md_route_name}}/list\"}"}.
  • Risultato: regole notifiche versionate a metadata, niente duplicazione logica nei singoli trigger manuali.
  • Riferimento contesto metadata: vedi Metadata (sezione md_props_bag e nodi avanzati).

Prerequisito: SQL Server Service Broker

La modalita SqlDependency richiede che il Service Broker sia abilitato sul database metadati.

Senza Service Broker il watcher non riesce a registrare le query notifications e logga:

> Unable to start SqlDependency for _notifications.

> System.InvalidOperationException: The SQL Server Service Broker for the current database is not enabled...

A partire dalla versione corrente il watcher esegue un fallback automatico a polling quando il broker non e disponibile. Per ottenere le prestazioni ottimali (push istantaneo senza polling) e necessario abilitare il broker.

Nuove installazioni (first-run wizard)

Il wizard first-run abilita automaticamente il Service Broker dopo la creazione del database metadati. Nessuna azione manuale richiesta.

Installazioni esistenti (upgrade / deploy manuale)

Aprire SQL Server Management Studio, selezionare il database metadati nel dropdown ed eseguire:

Snippet 2SQL
SELECT name, is_broker_enabled FROM sys.databases WHERE name = DB_NAME();

Dopo l'esecuzione riavviare l'applicazione (IIS Application Pool recycle). Il watcher rilevera il broker attivo e passera da polling a push nativo.

Lo script e anche disponibile come file standalone: dbms/scripts/first-run/enable-service-broker.mssql.sql.

Verifica rapida

Per verificare lo stato del broker sul database corrente:

Risultato atteso: is_broker_enabled = 1.

SqlDependency / Polling

  • Backend watcher: NotificationSqlDependencyWatcher registrato come hosted service.
  • Modalita configurabili:
  • SqlDependency (default): registra dependency sulla query unread di _notifications e invia snapshot quando cambia il risultato.
  • Polling: fallback con polling periodico ogni PollSeconds. Attivato automaticamente se il Service Broker non e disponibile.
  • Push service: NotificationPushService invia snapshot solo agli utenti con socket connessi.

UI e comportamento utente

  • notification-bell mostra badge con unread count.
  • Apertura pannello: elenco notifiche con data/ora e tipo.
  • Click su notifica:
  • mark-read via POST /api/Notifications/markread/{id};
  • navigazione su route letta da target_json.
  • Azione Rimuovi lette: POST /api/Notifications/clearread/{userId} (soft-delete delle lette).

Progress export/import

  • Le notifiche di progress contengono progressGuid e route di riferimento nel target_json.
  • Click su notifica progress:

- riapre il dialog di progress collegato allo stesso progressGuid;

- non forza redirect se si e già sulla route corrente.

  • Le notifiche riassuntive (fine import/export) usano target_json.path per navigare alla route della griglia.

AppSettings rilevanti

Descrizione:

queste chiavi abilitano il subsystem notifiche e la modalita di ascolto cambi tabella.

  • "Notifications.Enabled": true
  • "Notifications.Mode": "SqlDependency" oppure "Polling"
  • "Notifications.PollSeconds": 5
  • Enabled: abilita/disabilita intero subsystem notifiche.
  • Mode: SqlDependency o Polling.
  • PollSeconds: intervallo in secondi quando Mode = Polling.

Supporto lato frontend:

  • WtoolboxService.appSettings.notifications.enabled (e alias compatibili) puo nascondere la campanella e fermare la connessione realtime lato client.

Risultato:

  • backend e frontend restano allineati sullo stato notifiche;
  • in SqlDependency la UI riceve aggiornamenti push, in Polling usa refresh periodico.

Screenshot

notifications / main
notifications / main