Écouteurs de cartes de données dans Matrix42 Professional

Les écouteurs de cartes de données constituent un mécanisme permettant d'implémenter la logique métier dans Matrix42 Professional (ESM). Ils sont conçus pour répondre à des événements spécifiques dans les modèles M42 Pro , permettant ainsi des actions automatisées selon des conditions définies. Lorsqu'un modèle dispose d'un écouteur, toutes les cartes de données créées peuvent le déclencher lors de leur enregistrement :

Ordre d’exécution : voir l’article « Processus Pro sauvegarde dans M42 Pro ».

Configuration des écouteurs de carte de données

Les écouteurs de cartes de données sont configurés à l'aide de fichiers XML qui définissent leurs propriétés et leurs comportements. Le processus de configuration comprend :

1. Création d'une configuration XML : Le comportement et les conditions de l'écouteur sont définis dans un fichier XML. Ce fichier spécifie comment l'écouteur interagira avec les événements de la carte de données.
2. Importation dans le modèle M42 Pro : Une fois la configuration XML créée, elle doit être importée dans le modèle M42 Pro correspondant. Cette étape active l'écouteur dans le modèle.
3. Ajuster l'ordre des écouteurs : Les pré-enregistrements s'exécutent en premier dans leur ordre séquentiel, suivis des post-enregistrements. Il est important de savoir lequel est exécuté en premier. Par exemple, placez les écouteurs validateurs en premier lors de la pré-enregistrement. Déplacez les écouteurs pour respecter l'ordre d'exécution.

Les écouteurs peuvent également être exportés dans le cadre de la configuration XML globale M42 Pro , ce qui permet une réplication et un déploiement faciles dans différents environnements.

Fonctionnalités d'écoute et paramètres de déclenchement

Chaque modèle M42 Pro peut contenir un ou plusieurs écouteurs. Lorsque la carte de données associée à un modèle est enregistrée, tout écouteur enregistré sur ce modèle est notifié de l'événement.

Les auditeurs sont configurés pour répondre à des événements spécifiques en fonction de leurs paramètres de déclenchement, qui peuvent être :

• Déclencheur de pré-enregistrement : l'écouteur s'active avant l'enregistrement de la carte de données. Il modifie uniquement la carte de données source .
• Déclencheur post-enregistrement : L'écouteur s'active après l'enregistrement de la carte de données. Il modifie uniquement les autres cartes de données.
  • Sauf s'il est nécessaire de modifier une carte de données source et de déclencher intentionnellement un second cycle de sauvegarde. Par exemple, pour modifier une valeur d'état sur un ticket avec un écouteur, les gestionnaires DataCardHiddenState et ValueChange doivent être déclenchés pour refléter la modification.

Une fois déclenché, l'écouteur évalue s'il doit répondre à l'événement. Cette décision repose sur des conditions sources définies, qui sont des critères définis dans la configuration de l'écouteur. Ces conditions déterminent si la carte de données source (c'est-à-dire la carte de données enregistrée) correspond aux paramètres requis pour que l'écouteur puisse agir. De même, pour cibler les modifications sur des cartes de données cibles spécifiques d'un autre modèle, les conditions cibles situées au début de la section de la chaîne d'action déterminent la ou les cibles.

• Plusieurs écouteurs : un seul modèle peut prendre en charge plusieurs écouteurs, chacun répondant à des déclencheurs ou des conditions différents.
• Logique conditionnelle : les auditeurs ne réagissent aux événements que si les conditions spécifiées sont remplies, ce qui permet un contrôle précis sur le moment et la manière dont la logique métier est appliquée.

Meilleures pratiques

Attention : à la création de constructions où vous mettez à jour plusieurs fois la même carte de données avec différents écouteurs post-enregistrement. Il existe également des conflits entre les écouteurs et d'autres fonctions basées sur des gestionnaires.

Général

Le XML de l'écouteur peut être commenté avec une section <!-- foobar -->, mais les commentaires sont supprimés une fois que l'écouteur est importé dans M42 Pro (c'est-à-dire que les commentaires sur les écouteurs ne sont utiles que si les « données principales » de l'écouteur sont stockées ailleurs).

• Vous pouvez ajouter plusieurs chaînes d'actions
  • Par exemple, si vous devez toucher plusieurs cartes de données de modèles cibles différents dans un écouteur de sauvegarde de publication, en fonction des mêmes conditions de source
• Évitez d'utiliser des conditions combinées AND-OR-AND... profondes/à plusieurs niveaux afin de rendre le code d'écoute plus compréhensible et essayez plutôt de simplifier les conditions ou d'effectuer la logique la plus complexe dans le code d'expression d'un attribut d'aide.
  • Astuce : l'attribut d'aide d'expression peut être défini comme une chaîne à valeurs multiples pour permettre la définition de plusieurs valeurs dans un attribut d'aide afin que les écouteurs puissent les utiliser comme différents déclencheurs.

XML

• Méthode traditionnelle de création d'une logique métier / d'exécution de fonctionnalités automatiques non basées sur des champs sur un certain modèle.
  Configuré en créant une configuration XML appropriée.
  • Les écouteurs sont mis en service en important ce XML dans un modèle M42 Pro .
  • Les écouteurs peuvent être exportés dans le cadre de la configuration XML M42 Pro .
• Le séquençage de la commande est une chose à prendre en compte.
  • D'abord les pré-enregistrements dans l'ordre, puis les post-enregistrements dans l'ordre par modèle.
• Auditeurs pré-enregistrés :
  • Exécuté et vérifié à chaque sauvegarde de carte de données, après tous les gestionnaires sauf AutoMailSender et TargetDeleter.
  • Utilisé sur les cartes de données du modèle « ce ».
• Auditeurs post-enregistrement :
  • Généralement utilisé sur les cartes de données d’autres modèles liés à la carte de données de « ce » modèle.
  • Peut inclure des conditions cibles.
  • Peut redéclencher une séquence sur un autre modèle.
  • Les gestionnaires sur le modèle cible sont exécutés après ceux-ci

L'envoi de données de chaîne vers un champ de référence avec une action de modification ou de copie peut ne pas fonctionner.

• Traditionnellement, vous devez pousser l'entityid si vous souhaitez établir un lien vers certaines cartes de données.
• La copie d'une référence à une autre devrait fonctionner.
• Il est plus facile de lier des références à des expressions dans la plupart des cas, mais lorsque vous effectuez des transformations par exemple, vous devrez peut-être utiliser des écouteurs pour effectuer certaines références par la suite.

Faites attention à :

• Création de constructions dans lesquelles vous mettez à jour la même carte de données plusieurs fois avec différents écouteurs de sauvegarde après sauvegarde.
• Conflits entre les auditeurs et d'autres fonctions basées sur des gestionnaires.
• Déterminer l'ordre de passage.

RAPPEL : Vous devez mettre à jour les balises statistiques datetime avec l'écouteur si vous fermez des cartes de données avec DateChecker (automatisation de l'écouteur). Cette méthode, pour débutants, est incomplète et codée en dur, ce qui n'est pas flexible à long terme. Notez que cela n'est pas possible si vous devez créer des ValueChanges. Une méthode plus flexible, mais plus complexe, consiste à utiliser l'enregistrement après la sauvegarde, puis à déclencher les gestionnaires appropriés (qui peuvent ensuite varier selon leur configuration après la création des écouteurs).

Importer un écouteur

Lors de l'importation d'un écouteur, M42 Pro valide le contenu et la structure du XML :

• Le message d’erreur affiché est souvent ininterprétable, comme par exemple « XML ne peut pas être vide ».
• Vérifiez que vous avez fermé toutes les balises XML </> et que tous les codes d'attribut sont corrects, etc.
• Consultez la documentation de l'auditeur pour vous assurer que vous n'essayez pas de faire des choses qui ne sont pas possibles, comme comparer des champs de texte ou des champs de référence externes.
• Essayez de supprimer ou de modifier les composants suspects et essayez sans eux.

Utilisation de la journalisation et du débogage

• Vous pouvez essayer d'extraire des informations supplémentaires en ouvrant certaines de ces classes pour la journalisation d'exécution et définir le niveau DEBUG lorsque vous essayez d'importer le XML.
  • com.bitmount.equipment.action.TemplateListenerImport  cochez cette case dans la plupart des cas
  • com.bitmount.equipment.importing.ValidatingEntityXMLImporter
  • com.efecte.datamodel.entity.listener.importing.XMLActionChainImporter
  • com.efecte.datamodel.entity.listener.importing.XMLDataCardListenerImporter
  • com.efecte.datamodel.entity.listener.importing.XMLSourceConditionsImporter
  • com.efecte.datamodel.entity.listener.importing.XMLTemplatesDataCardListenerImporter
• N'oubliez pas de redéfinir la journalisation au niveau INFO après avoir corrigé les écouteurs, sinon vous produirez d'énormes quantités de fichiers journaux !!
• L'écouteur a été importé avec succès mais ne fonctionne pas comme souhaité
• Vérifiez les journaux d'exécution et définissez le niveau DEBUG et vous devriez voir ce qui se déclenche et ce qui ne se déclenche pas
  • Conditions de la source
    • com.effet.datamodel.entity.listener.condition.(?????)
  • Conditions cibles
    • com.effet.modèle de données.entité.action.chaîne.condition.(?????)
  • Actes
  • com.efecte.datamodel.entity.action.implementations.(?????)
  • (?????) = chaque composant XML
• N'oubliez pas de redéfinir la journalisation au niveau INFO après avoir corrigé les écouteurs, sinon vous produirez d'énormes quantités de fichiers journaux !!
• Paramètres de la plateforme pour les auditeurs
  • datacard.listeners.run.as.root

Changement de statut du ticket

Si vous modifiez la valeur du statut d'un ticket avec l'écouteur, vous devez prendre en compte :

• Les horodatages des statistiques sont mis à jour en conséquence
• L'historique des changements de valeur du statut est mis à jour en conséquence
• Il est possible de masquer/rendre visible la carte de données mise à jour en conséquence
• Si vous définissez un champ avec un écouteur de pré-enregistrement, ne vous attendez pas à ce qu'une expression s'exécute en fonction de celui-ci, à moins que vous ne le fassiez à l'intérieur de l'écouteur !
• Si vous supprimez un attribut lié à un écouteur, l'écouteur est cassé
  • L'écouteur doit être supprimé pour que la configuration soit exportée
  • Dans la plupart des cas, le problème peut être résolu en recréant l'attribut supprimé avec le même code d'attribut.

GuiEdit

GuiEdit –condition ne fonctionne pas dans ces scénarios :

• Gestionnaire ValueButton cliqué en mode affichage
• Gestionnaire de réservation de billets cliqué en mode affichage
• EntityStateMail envoyé en mode affichage
• Commentaire WorklogHandler ajouté en mode affichage

Ajoutez toujours GuiEdit lorsque vous effectuez AlwaysFailDataCardAction pour vous assurer que les modifications d'intégration ne seront pas bloquées par celui-ci et que celles-ci seront toujours les premiers auditeurs de l'ordre.

• Via l'interface d'administration, vous ne pouvez voir que les noms et la séquence des écouteurs et vous devrez exporter l'intégralité de la configuration en XML pour étudier les fonctionnalités réelles des écouteurs.

Ordre d'écoute

Maintenez les auditeurs en ordre de marche : les pré-enregistrements sont exécutés en premier, puis les post-enregistrements.

Appellation

Gardez une méthode de dénomination cohérente !

• Pensez à les nommer de manière claire et informative, par exemple en incluant la plupart d'entre eux :
  • Pré-enregistrement ou post-enregistrement
  • Numéro de commande
  • Brève description
    • ce qu'il fait
    • quoi/pourquoi cela déclenche
  • Si plusieurs personnes administrent ou développent
    • Date de modification
    • Peut-être même les initiales ou l'abréviation de celui qui a modifié

Exemples:

• presave.Copier l'équipe de développement si la valeur est vide et le service sélectionné - 09.10.2019-AA
• presave.SET Résolu dans SLA_04052021_MK
• postsave.4. Définir des références si un e-mail entrant est généré - 04/05/2017
  

Auditeurs – Valeur actuelle vraie vs Valeur actuelle fausse

current_value false = Ancienne/Valeur précédente

current_value true = Nouveau / Valeur actuelle

<source_condition>
  <value>
    <attribute>
      <code>status</code>
      <current_value>false</current_value>
    </attribute>
    <operator>=</operator>
    <compared_value>01 - New</compared_value>
  </value>
</source_condition>
<source_condition>
  <value>
    <attribute>
      <code>status</code>
      <current_value>true</current_value>
    </attribute>
    <operator>=</operator>
    <compared_value>02 - Solving</compared_value>
  </value>
</source_condition>