Entity change log

Introduction

Lorsque les données sont modifiées dynamiquement par des utilisateurs ou des services de type API ou Cron, il peut être complexe de comprendre ce qui s'est passé dans le système.

Pour répondre à ce besoin, la SmartPlatform permet de mettre en place un historique des modifications : l'Entity change log.

exemple de rendu d'une ligne d'entity change log

Périmètre du monitoring entity change log

Cette mise en place n'a pas vocation à être utilisée pour des statistiques.

Fonctionnement

Ajout de l'entity change log

Pendant la conception, nous validons ensemble la pertinence de la mise en place du change log sur chacun des modèles constituant la base de données de votre projet.

Nous configurons ensuite dans la plateforme l'activation du changelog ainsi que sa visibilité pour chacune des interfaces de votre projet.

Techniquement, nous avons choisi un format de stockage en json directement au niveau de l'entité pour avoir une mise en place simple et faciliter le nettoyage.

Historique automatique des actions sur les entités avec change log

Si le change log est activé sur vos entités, la plateforme reportera automatiquement les changements et données des actions suivantes dans son historique :

Création

• Peu importe la source déclenchant la création (formulaire d'ajout, écran d'import, appel API, ...) : vous aurez l'information dans le change log
• Nous stockons la date et l'heure où votre entité a été ajoutée sur votre base de données

Modification

• Idem, tous les canaux de modifications possibles seront identifiés avec une ligne dans l'historique par la date et l'heure du traitement.
• Chacun des champs modifiés sera listé avec le format suivant :
  %Nom du champ% : (%ancienne valeur%) → %Nouvelle valeur%
  Exemples :
  • Nom client : (ANDRE) → ANDRÉ
  • Code postal : (26200) → 26000
• Les changements de statuts du cycle de vie de vos entités seront clairement visibles en reprenant leur code couleur associé, exemple :

Suppression en douceur et archivage

• Le change log vous garantie de ne pas perdre l'information de quand vos suppressions en douceur ou archivage ont eu lieu.
• Cela permettra à votre service support d'avoir une vision complète du cycle de vie de vos objets métier.
• Nous stockons la date et l'heure où votre entité est marquée en base de données comme supprimée en douceur ou archivée.

Envoie d'email

• Toutes les entités de votre projet pouvant recevoir des emails avec le change log d'activé auront une ligne dans leur historique par envoi d'email avec les informations suivantes :
  • Le sujet de l'email envoyé
  • L'email destinataire utilisé au moment de l'envoi
  • L'historique des statuts de l'email si l'envoi a été fait via notre mailer API, exemple :

Comportement générique : origine et auteur des modifications

Sur chaque ligne d'historique du change log, nous stockons le contexte à l'origine du changement (Interface client, Backoffice, Cron, Appel API) ainsi que l'auteur du traitement (correspond à l'utilisateur courant s'il est authentifié).

Stockage d'événements complémentaires

En plus des actions génériques citées ci-dessus qui sont prises en charge automatiquement par la plateforme, nous pouvons à tout moment enregistrer manuellement une ligne d'activité dans le change log d'une entité.

Ce mode d'utilisation vous permettra de suivre n'importe quel événement métier de votre projet sur vos entités, tels que :

• Les réceptions de paiement unique ou par abonnement
• Expiration des licences produits de vos utilisateurs
• Ou encore, tous autres résultats d'action personnalisés que nous pourrions rajouter (priorisation, réassignation, ...)

Affichage et template de rendu du change log

Rendu Timeline

Ce type d'affichage du change log permet d'avoir une vision complète et continue des différents flux d'activité sur votre entité en partant du plus récent au plus ancien :

Ligne de change log enrichie

La plateforme offre aussi la possibilité d'ajouter du texte HTML en description ou en commentaire sur une ligne d'historique pour détailler le traitement qui vient d'avoir lieu.
Ce complément d'information est particulièrement utile pour log d'événements métier de votre projet.

exemple de rendu HTML de description et commentaire

Lien appel API et Cron

Si vos entités cibles sont manipulées par des appels API ou des Cron alors l'entrée du change log aura un lien avec l'id de la ligne du traitement de l'appel API ou Cron concerné. Cela vous permet d'avoir de passer de la vision micro de votre entité au traitement macro dans nos écrans de monitoring.

exemple de rendu avec le lien du cron id de monitoring

Filtrer les champs à enregistrer et rendre visible

Filtrage du change log

Par défaut, les entités avec le change log d'activé auront tous leurs champs modifiés d'enregistré et visibles dans leur historique.

Il arrive parfois que certains de ces champs soient des données purement techniques (index de performance, données compilées).

Il convient donc de filtrer ces champs qui n'apportent pas de valeur ajoutée à être suivis dans le change log et pour optimiser le poids de votre base de données.

Notre configuration du change log sur vos entités nous permet donc de filtrer les champs modifiés qui ne seront jamais enregistrés.

    public function getHistoryDiffFieldsToSkip(): array
    {
        return [
            'search' => true,
            'canonical' => true,
        ];
    }

exemple de code pour ne pas stocker les index de recherche et d'identifiant unique

Après avoir fait cette étape de filtre, nous disposons ensuite d'une dernière configuration pour gérer la visibilité de ces champs.

Visibilité du change log

Pour chaque type d'interface et selon les profils utilisateurs, nous pouvons masquer ou afficher certaines lignes de l'historique et/ou certaines données, par exemple :

• Pour un backoffice administrateur, nous pouvons visualiser l'ensemble des données de vos dossiers de suivi afin d'avoir une vision complète de toutes les interactions.
• Pour une autre interface opérateur de votre projet, nous pouvons ici limiter l'historique visible du dossier à uniquement les appels effectués pour la centrale d'appel.
• Pour une interface client, il est possible de masquer d'autres lignes du change log, voire complétement de l'enlever selon la sensibilité des informations.