Version de développement

Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.

Utilisation

Notifications unifiées

Configurer et utiliser le système de notifications unifié dans Dokos

Notifications unifiées dans Dokos

Dokos propose désormais un système de notifications unifié, permettant aux utilisateurs de recevoir et gérer leurs notifications directement depuis l'interface, tout en offrant aux développeurs un cadre extensible pour intégrer des notifications personnalisées.

Fonctionnalités clés

Tableau de bord des notifications

Le panneau de notifications unifié est accessible depuis la barre de navigation supérieure. Il affiche toutes vos notifications, classées par application (Dokos, CRM, Helpdesk, etc.) et permet de :

Marquer une notification comme lue : Cliquez sur une notification pour la marquer comme lue.
Marquer toutes les notifications comme lues : Utilisez le bouton dédié pour effacer toutes les notifications non lues.
Filtrer par application : Utilisez les onglets pour afficher uniquement les notifications d'une application spécifique.
Naviguer au clavier : Le panneau est entièrement accessible via le clavier (navigation avec les flèches, sélection avec Entrée).

      
sequenceDiagram
    participant Utilisateur as Utilisateur
    participant Panneau as Panneau de Notifications
    participant Serveur as Serveur Dokos

Types de notifications

Les notifications sont désormais organisées par types, ce qui permet une gestion plus fine des préférences. Chaque type de notification peut être activé ou désactivé individuellement pour les notifications par email.

Exemples de types de notifications intégrés :

Nouveau commentaire : Lorsqu'un commentaire est ajouté à un document que vous suivez.
Document assigné : Lorsqu'un document vous est assigné.
Rappel d'événement : Pour les événements à venir dans votre calendrier.

Préférences de notification

Chaque utilisateur peut configurer ses préférences de notification pour chaque type, directement depuis son profil :

Allez dans Profil > Paramètres de notification.
Dans l'onglet Types de notifications par email, cochez ou décochez les types de notifications pour lesquels vous souhaitez recevoir un email.
Sauvegardez vos modifications.

::: info Les préférences de notification par email sont basées sur une liste d'autorisation : seuls les types de notifications cochés enverront des emails. Par défaut, tous les types sont activés. :::

Pour les développeurs

Intégrer un nouveau type de notification

Pour ajouter un nouveau type de notification dans votre application :

Créer un type de notification :
- Allez dans Développeur > Notifications > Type de notification.
- Cliquez sur Nouveau.
- Remplissez les champs suivants :
  - Nom : Identifiant unique du type (ex: nouveau_commentaire).
  - Module : Module associé (ex: Dokos).
  - Libellé : Nom affiché aux utilisateurs (ex: "Nouveau commentaire").
- Sauvegardez.

Émettre une notification : Utilisez la méthode frappe.send_notification dans votre code Python pour envoyer une notification :

frappe.send_notification({
    "users": ["utilisateur@example.com"],
    "type": "nouveau_commentaire",
    "document": doc,
    "title": "Nouveau commentaire sur {0}".format(doc.name),
    "description": "Un nouveau commentaire a été ajouté par {0}.".format(frappe.session.user)
})

::: warning Assurez-vous que les champs title et description sont sanitizés pour éviter les failles XSS. Utilisez frappe.utils.sanitize_html pour nettoyer le contenu avant de l'envoyer. :::

Personnaliser le rendu : Le panneau de notifications utilise des slots pour permettre la personnalisation du rendu des notifications. Vous pouvez surcharger les slots suivants dans votre application :
- #header : En-tête du panneau.
- #item : Rendu d'une notification individuelle.
- #tab-<valeur> : Contenu d'un onglet spécifique.
- #empty : Message affiché lorsqu'il n'y a pas de notifications.
- #error : Message d'erreur.
Exemple pour personnaliser le rendu d'une notification dans un composant Vue :
```
<template>
  <NotificationPanel>
    <template #item="{ notification }">
      <div class="custom-notification">
        <strong>{{ notification.title }}</strong>
        <p>{{ notification.description }}</p>
      </div>
    </template>
  </NotificationPanel>
</template>
```

Dédoublonnage des notifications

Le système de notifications évite les doublons en utilisant un mécanisme de dédoublonnage basé sur le champ dedupe_on. Si une notification avec les mêmes valeurs pour les champs spécifiés dans dedupe_on existe déjà pour un utilisateur, elle ne sera pas créée.

Pour activer le dédoublonnage dans votre règle de notification :

frappe.get_doc({
    "doctype": "Notification Rule",
    "name": "ma_regle_de_notification",
    "dedupe_on": "document_type,document_name,type"
}).save()

Notifications par email

Les notifications par email sont envoyées uniquement pour les types de notifications activés dans les préférences de l'utilisateur. Pour vérifier si un utilisateur a activé les emails pour un type spécifique :

from frappe.desk.doctype.notification_settings.notification_settings import is_email_notifications_enabled_for_type

if is_email_notifications_enabled_for_type(user, "nouveau_commentaire"):
    # Envoyer un email
    frappe.sendmail(
        recipients=[user],
        subject="Nouveau commentaire sur {0}".format(doc.name),
        message="Un nouveau commentaire a été ajouté par {0}.".format(frappe.session.user)
    )

::: info Les fonctionnalités comme les rappels d'événements ou les emails de thread (lorsqu'un document vous est assigné) ne passent pas par le système de types de notifications. Elles utilisent leurs propres cases à cocher dans les paramètres de notification et sont gérées via is_email_enabled_for_feature. :::

Migration depuis les anciennes notifications

Si vous utilisiez des notifications personnalisées dans une version antérieure de Dokos, voici comment migrer vers le nouveau système :

Types de notifications :
- Les anciens types de notifications (champs de type Select) sont automatiquement migrés vers le nouveau doctype Type de notification.
- Vérifiez que tous vos types de notifications existants sont bien listés dans Développeur > Notifications > Type de notification.
Préférences utilisateur :
- Les préférences de notification par email sont migrées vers le nouveau système de liste d'autorisation. Les utilisateurs doivent vérifier leurs paramètres dans Profil > Paramètres de notification.
Panneau de notifications :
- Le panneau de notifications unifié remplace les anciens panneaux spécifiques à chaque application. Assurez-vous que vos applications utilisent désormais le composant @framework/ui/Notifications pour afficher les notifications.
Règles de notification :
- Les règles de notification existantes continuent de fonctionner, mais vous pouvez désormais utiliser les nouveaux champs title, description, et type pour une meilleure intégration avec le panneau unifié.

Exemple : Configurer une notification pour un nouveau commentaire

Scénario

Vous souhaitez notifier l'auteur d'un document lorsqu'un nouveau commentaire est ajouté.

Étapes

Créer un type de notification :
- Allez dans Développeur > Notifications > Type de notification.
- Créez un nouveau type avec les valeurs suivantes :
  - Nom : nouveau_commentaire
  - Module : Dokos
  - Libellé : "Nouveau commentaire"
Créer une règle de notification :
- Allez dans Développeur > Notifications > Règle de notification.
- Créez une nouvelle règle avec les valeurs suivantes :
  - Document Type : Comment
  - Condition : doc.reference_doctype and doc.reference_name
  - Destinataires : eval:doc.reference_owner
  - Type de notification : nouveau_commentaire
  - Titre : Nouveau commentaire sur {0}.format(doc.reference_name)
  - Description : Un nouveau commentaire a été ajouté par {0} sur {1}..format(frappe.session.user, doc.reference_name)
  - Dédoublonnage : document_type,document_name,comment_type
Tester la notification :
- Ajoutez un commentaire sur un document.
- Vérifiez que l'auteur du document reçoit une notification dans le panneau unifié.
- Si l'utilisateur a activé les emails pour ce type de notification, il devrait également recevoir un email.

      
flowchart TD
    A[Commentaire ajouté] --> B[Règle de notification déclenchée]
    B --> C[Notification créée]
    C --> D[Notification affichée dans le panneau]
    C --> E{Email activé ?}
    E -->|Oui| F[Email envoyé]
    E -->|Non| G[Fin]

Résolution des problèmes

Les notifications n'apparaissent pas dans le panneau

Vérifiez que l'utilisateur est bien destinataire : Assurez-vous que la règle de notification cible le bon utilisateur.
Vérifiez les filtres du panneau : Le panneau peut être filtré par application. Essayez de réinitialiser les filtres.
Vérifiez les erreurs dans la console : Ouvrez les outils de développement du navigateur et vérifiez les erreurs dans l'onglet Console.

Les emails ne sont pas envoyés

Vérifiez les préférences de l'utilisateur : Assurez-vous que le type de notification est activé dans Profil > Paramètres de notification.
Vérifiez la configuration email : Assurez-vous que le serveur email est correctement configuré dans Paramètres > Email > Paramètres Email.
Vérifiez les logs : Consultez les logs dans Développeur > Logs > Log Email pour voir si l'email a été généré et s'il y a eu des erreurs.

Les notifications sont en double

Vérifiez le dédoublonnage : Assurez-vous que le champ dedupe_on de votre règle de notification est correctement configuré pour éviter les doublons.
Vérifiez les règles de notification : Plusieurs règles peuvent déclencher des notifications pour le même événement. Consolidez vos règles si nécessaire.

Conclusion

Le nouveau système de notifications unifié de Dokos offre une expérience utilisateur cohérente et une intégration simplifiée pour les développeurs. En utilisant les types de notifications, les préférences personnalisables et le panneau unifié, vous pouvez créer des flux de travail plus efficaces et informer vos utilisateurs en temps réel.

Pour aller plus loin, consultez les pages suivantes :

Personnaliser l'interface pour apprendre à intégrer le panneau de notifications dans vos applications personnalisées.
Développer avec Dokos pour découvrir comment créer des règles de notification avancées.