Aller au contenu principal

Règles de notification

L'écran Règles de notification est le côté écriture du système de notifications — une bibliothèque de ressources notification-rule qui décident :

  • quand une notification se déclenche (code de statut et / ou motif de rejet) ;
  • quel texte elle contient (sujet et corps, ou les valeurs par défaut du dispatcher) ;
  • à qui elle est destinée (un utilisateur / rôle du portail, une liste d'e-mails, ou les deux) ;
  • par quels canaux (boîte de réception du portail, e-mail, appel d'API externe), avec le PDF rendu joint à l'e-mail par défaut.

Les règles sont évaluées par InvoiceStatusCatalog.StatusTransition.apply() après l'écriture en base de chaque changement de statut, par le SetStatusModal manuel, et par les flux CLI (-process, -fetch-import, -fetch-status, -fetch-single, -fetch-all). Un échec d'envoi n'annule jamais la mise à jour de statut sous-jacente.

Le côté lecture du système — la boîte de réception où les utilisateurs acquittent les notifications et la cloche dans la barre d'utilitaires — est documenté sur la page Notifications.

La page fonctionne quel que soit le système source — JD Edwards, SAP, NetSuite ou ERP personnalisé. Les déclencheurs référencent les catalogues standards statuses et rejection-reason-codes, et non des codes propres au système source.

Accès à l'éditeur​

  • Sidebar → Gestion → Règles de notification.
  • Une installation neuve ne contient aucune règle — le dispatcher n'émet rien tant qu'aucune règle n'est créée. Le bouton Add crée la première.

Vue d'ensemble​

Règles de notification+ Add⎘ Copy🗑 Remove💾 SaveRechercher…pa-rejectionAlerte sur rejet PAonpa-successConfirmation de dépôt PAonvalidation-failureErreurs XSD / Schematronoffpa-rejectionAlerte sur rejet PADÉCLENCHEURStatut9904 ×9907 ×MotifREJ_ADR ×CANAUX☑ portal☑ email☐ actionDESTINATAIRETyperole ▾ValeuraccountantsCCsuperviseur@nomana-it.frCONTENU E-MAILSujetInvoice {doc} {dct} {kco} — RejectedCorpsStatus: {statusLabel}Reason: {reasonLabel}attachPdf · joindre la facture rendueAPPEL D'ACTION · désactivéConnecteur / endpoint / paramètres — uniquement quand ☑ action ci-dessusTEST12345RI00070▶ Lancer✓ Émis · 1 portail · 2 e-mailsBarre d'actionsadd / copy / remove / saveListe des règlespastille on / off par lignePuces de déclencheurmulti-sélection statut + motifCanauxportal · email · actionDestinatairecible portail + liste e-mailsSujet et corps{placeholders} résolus à l'envoiPanneau de testexécute la règle de bout en bout

La page se compose d'une liste de règles à gauche et d'un éditeur de règle à droite. Chaque règle est une ressource notification-rule enregistrée dans config-notifications.json ; le dispatcher les recharge au démarrage et après chaque enregistrement.

Actions de la barre supérieure​

ActionEffet
AddOuvre une modale demandant un nom et une description. Crée une nouvelle règle vide — aucun déclencheur, canaux préréglés sur portal, type de destinataire préréglé sur user.
CopyDuplique la règle sélectionnée sous un nouveau nom. Méthode pratique pour dériver une variante B2C d'une règle B2B, ou une règle par région à partir d'une règle générique.
RemoveSupprime la règle sélectionnée après confirmation.
SaveRéécrit l'état de l'éditeur dans config-notifications.json et signale au dispatcher de recharger. Le prochain changement de statut prend en compte la nouvelle règle.

La liste des règles​

Chaque règle du catalogue présente deux indices visuels :

  • Description en italique sous le nom de la règle — même champ que celui demandé par la modale Add, texte libre.
  • Pastille on / off à droite de chaque ligne — liée à la propriété enabled. Une règle marquée off reste dans le catalogue mais n'est pas prise en compte par le dispatcher. Pratique pour itérer sur une règle sans la perdre.

Une zone de recherche en haut de la barre latérale filtre la liste par sous-chaîne sur le nom de règle.

L'éditeur de règle​

L'éditeur est structuré en quatre groupes de sections plus un panneau de test synchrone.

Déclencheur​

Le déclencheur définit quand la règle se déclenche. Deux champs se combinent, tous deux optionnels :

ChampSourceComportement
StatutCatalogue statusesListe de codes statut séparés par virgule (par ex. 9904,9907). La règle se déclenche lorsque le code statut de la nouvelle transition figure dans la liste. Vide = correspondance sur tout statut.
MotifCatalogue rejection-reason-codesListe de codes motif de rejet séparés par virgule (par ex. REJ_ADR,REJ_FMT). La règle se déclenche uniquement lorsque le code motif de la nouvelle transition figure dans la liste. Vide = correspondance sur tout motif.

Les deux champs sont présentés sous forme de multi-sélections à puces — choisir une entrée dans la liste déroulante ajoute une puce ; le × d'une puce la retire. La liste déroulante puise dans les ressources statuses et rejection-reason-codes, exactement les mêmes que celles utilisées par la modale Set Status et l'onglet History de la facture. Une règle ne peut donc référencer que des codes effectivement reconnus par l'application.

Lorsque les deux champs sont renseignés, les deux conditions doivent correspondre (ET logique) pour que la règle se déclenche.

Canaux​

Trois cases à cocher, combinables librement :

  • portal — écrit une ligne dans F564253 pour le destinataire. L'utilisateur la voit dans la boîte Notifications et dans la cloche.
  • email — envoie un message SMTP via le compte mail configuré sur le template e-invoicing.
  • action — déclenche un appel HTTP sortant vers un endpoint d'API Connector.

Une règle qui n'émet aucun canal est sans effet et rejetée à l'enregistrement.

Destinataire​

Le modèle de destinataire comporte deux moitiés indépendantes : une cible portail et une liste d'e-mails.

ChampDescription
TypeChoisit la cible portail — user (un nom d'utilisateur F564250 unique), role (tout utilisateur dont URROLE correspond à ce rôle), ou vide. Lorsque l'authentification est désactivée, l'option vide affiche Diffusion — tous les utilisateurs et écrit une seule ligne F564253 sous la sentinelle *.
ValeurNom d'utilisateur ou nom de rôle sélectionné par Type. Texte libre — l'auto-complétion vient de la base connectée lorsqu'elle est disponible.
CCListe indépendante d'adresses e-mail, séparées par , ou ;. Chaque adresse alimente l'en-tête To: de l'e-mail émis. L'USEMAIL éventuel de la cible portail (présent sur sa ligne F564250) est ajouté automatiquement.

Lorsque la cible portail porte un USEMAIL, le canal email envoie à cette adresse ainsi qu'à chaque entrée de CC, dans une transaction SMTP unique. Si la lecture de F564250 échoue, le canal portail est néanmoins émis — la ligne est alors stockée avec le nom d'utilisateur littéral comme clé, et la boîte de réception reste alimentée même pendant un incident transitoire de la base.

Contenu e-mail​

ChampValeur par défautDescription
SujetInvoice {doc} {dct} {kco} — {statusLabel}Ligne de sujet. Les placeholders sont résolus au moment de l'envoi.
CorpsStatus: {statusLabel} \n Reason: {reasonLabel} \n Action: {actionLabel}Corps en texte brut. Saisie multi-lignes.
Attach PDFYRend le PDF de la facture (via le pdf-template résolu) et l'attache à l'e-mail. Le PDF est rendu une seule fois par envoi et réutilisé pour chaque destinataire ; un échec de rendu est tracé mais ne fait pas échouer l'e-mail.

Placeholders disponibles dans le sujet et le corps : {doc}, {dct}, {kco}, {statusCode}, {statusLabel}, {statusMessage}, {reasonCode}, {reasonLabel}, {actionCode}, {actionLabel}, {ruleName}, {message}.

Le NTSUBJ côté portail reprend le même sujet ; le NTMSGE côté portail prend par défaut juste {statusLabel}, la boîte de réception affichant déjà la référence du document en ligne — sa duplication dans le corps serait redondante.

Appel d'action​

Lorsque le canal action est activé, trois lignes supplémentaires apparaissent :

ChampDescription
ConnecteurListe déroulante des templates de type api-connector. Même jeu que sur Process API.
EndpointListe déroulante alimentée par api.connectors.listEndpoints(connecteur) une fois un connecteur choisi.
ParamètresPré-remplis à partir de la liste de paramètres définie sur l'endpoint. Chaque ligne porte une clé (verrouillée) et une valeur (éditable). Les valeurs acceptent les mêmes {placeholders} que le sujet et le corps de l'e-mail.

L'appel d'action est émis dans la même transaction que l'écriture portail et l'envoi e-mail. Ses échecs sont tracés et n'annulent ni la mise à jour de statut sous-jacente ni les autres canaux.

Panneau de test​

Un panneau Test synchrone se trouve au pied du formulaire. Il accepte un triplet (doc, dct, kco), optionnellement un code statut et un message personnalisé, puis exécute réellement la règle sur tous les canaux activés — l'écriture portail atterrit dans la boîte, l'e-mail part par SMTP, l'appel d'action est émis. La bannière de résultat indique les compteurs d'envoi (✓ Émis · 1 portail · 2 e-mails) ou la première erreur rencontrée.

Le panneau de test n'enregistre pas la règle — il déclenche uniquement ce qui figure actuellement dans le formulaire. Outil de validation des modifications avant un clic sur Save.

Déroulement d'une notification​

Lorsqu'une transition de statut est appliquée (toute écriture en base touchant F564231.UHK74RSCD), le dispatcher parcourt le catalogue en trois temps.

StatusTransition.apply()
   ↓
NotificationDispatcher.fire(doc, dct, kco, status, reason, action, message)
   ↓ — pour chaque règle où enabled = Y
   ↓     correspondance trigger.status (CSV) ∋ status
   ↓     ET  correspondance trigger.reason (CSV) ∋ reason   (ou trigger.reason = '')
   ↓ → résolution du destinataire (cible portail + liste e-mails)
   ↓ → rendu du PDF de la facture une seule fois si attachPdf = Y
   ↓ — pour chaque canal activé :
   ↓     • portal → INSERT dans F564253
   ↓     • email  → un message SMTP avec toutes les adresses sur To:
   ↓     • action → appel HTTP vers connecteur.endpoint avec paramètres résolus
   ↓ toutes les exceptions sont capturées — un échec n'annule jamais la mise à jour

Le dispatcher utilise un singleton avec un pool asynchrone de 2 threads ; le code appelant retourne immédiatement. Un crochet d'arrêt JVM vide le pool avec un sursis de 2 secondes avant l'arrêt du processus, pour que les flux CLI qui se terminent juste après une mise à jour de statut délivrent quand même leurs notifications.

API REST​

La page lit et écrit via les endpoints de templates standards ; le dispatcher expose une route supplémentaire pour le panneau de test.

Méthode + cheminRôle
GET /api/templatesListe tous les modèles ; la page filtre par type = notification-rule.
GET /api/templates/{nom}Charge une règle.
POST /api/templatesCrée une règle (Add).
POST /api/templates/{from}/copy/{to}Duplique (Copy).
PUT /api/templates/{nom}Enregistre les modifications.
DELETE /api/templates/{nom}Supprime une règle.
POST /api/notifications/testÉmet la charge utile de la règle en synchrone sur tous les canaux activés — utilisé par le panneau Test.

Conseils & bonnes pratiques​

  • Démarrer étroit, élargir ensuite. Un déclencheur 9904 + REJ_ADR est plus simple à valider qu'un déclencheur fourre-tout, et le bruit reste limité tant que la liste des destinataires et le corps du message ne sont pas finalisés.
  • Utiliser le panneau Test avant l'enregistrement. Tout particulièrement pour le canal action — le dispatcher capture les échecs ; un connecteur mal configuré reste donc silencieux en production. Le test, lui, fait apparaître l'erreur directement dans la bannière de résultat.
  • Une règle par finalité, pas par code statut. Regrouper plusieurs codes statut derrière une seule règle lorsque le corps est identique (9904, 9907 → Rejet) ; scinder en règles distinctes uniquement lorsque la liste des destinataires ou le corps du message diffèrent.
  • Les PDF sont coûteux. attachPdf rend le PDF de la facture à chaque envoi — acceptable pour des règles à faible volume, onéreux pour des alertes sur l'ensemble du parc. Désactiver le drapeau sur les règles déclenchées en 9900 (créée) ou 9901 (validée), où le PDF apporte rarement de la valeur.
  • Privilégier role à user. Un destinataire fondé sur un rôle survit aux changements d'effectif ; un destinataire user impose une édition à chaque départ. La liste des rôles dans F564251 est la source de vérité.
  • Désactiver plutôt que supprimer. En cours d'itération, basculer la règle sur off au lieu de la retirer — le catalogue conserve l'historique, le dispatcher ignore la règle, et le panneau de test reste disponible.
  • Vérifier la boîte de réception après une livraison. Les règles peuvent finir par référencer des codes obsolètes (un statut renommé dans le catalogue, un motif retiré) — la page Notifications constitue le contrôle croisé le plus rapide pour vérifier la cohérence entre le catalogue de production et les règles définies ici.