Alias d’informations d’entités¶

L'objectif est de permettre aux administrateurs de définir un type et un alias pour chaque clé d'information d'entité.
Les alias offrent une recherche plus intuitive et peuvent contenir des espaces et des caractères accentués (par exemple Client, équipement réseau, etc.).
La définition d'un type permet notamment de formater correctement les dates lors des exports CSV.

Contexte et objectifs¶

Dans les versions précédentes de Canopsis, les données issues des informations d'entité (entity.infos) étaient identifiées uniquement par leur clé interne et par une valeur brute. Cela posait deux problèmes :

Lisibilité et recherche : les clés techniques ne sont pas toujours parlantes pour les utilisateurs. Par exemple, l'information entity.infos.customer.value peut être difficile à mémoriser. Les utilisateurs souhaitaient pouvoir créer un alias tel que Client afin de rechercher et filtrer cette information de manière plus intuitive.
Incohérence des types : les valeurs numériques étaient parfois interprétées comme des timestamps Unix et exportées dans des colonnes CSV sans conversion de date. Le système ne possédait pas de métadonnées permettant de distinguer un entier simple d'un timestamp.

La fonctionnalité d'alias résout ces deux problèmes en apportant :

Une typologie des informations permettant de préciser si la valeur est une chaîne, un nombre, un booléen, un tableau de chaînes ou un timestamp.
Cette typologie est ensuite utilisée dans les formulaires de recherche et d'export.
La possibilité de définir un alias lisible pour chaque clé. L'alias est utilisé dans l'interface (menus, recherches, colonnes de table) et dans les exports CSV. L'alias peut contenir des espaces, des caractères spéciaux ou accentués et offre un accès plus simple aux informations.

La page Informations d'entité apparaît dans le menu Exploitation. Elle permet de gérer les propriétés (type et alias) associées à chaque clé d'information :

La page liste les entrées pour lesquelles un type est défini. L'alias est facultatif.
Un formulaire de recherche permet de filtrer par clé, description ou alias. Un filtre par type est également disponible.
Le tableau peut être trié par clé d'information, alias ou type.

Création d'une propriété¶

Cliquer sur le bouton Ajouter des propriétés ouvre une fenêtre modale comportant les champs suivants :

Clé d'information : liste déroulante avec autocomplétion reprenant toutes les clés disponibles dans le dictionnaire de l'environnement.
Description : champ texte optionnel (255 caractères max.)
Alias : champ texte optionnel (255 caractères max.). L'alias peut contenir des espaces ou des caractères accentués.
Type : sélection obligatoire parmi les types suivants : Chaîne de caractères, Nombre, Booléen, Horodatage, Tableau de chaînes.

Lorsque l'utilisateur valide :

Le type prédéfini dans le dictionnaire est pré‑sélectionné pour simplifier la saisie.
Il est impossible d'enregistrer deux fois la même clé d'information ou d'utiliser un alias déjà attribué.
En cas d'erreur (clef en double ou alias existant), un message d'erreur s'affiche et l'enregistrement est refusé.

Édition et suppression¶

L'édition d'une propriété ouvre le même formulaire. La clé ne peut pas être modifiée, mais la description, l'alias et le type peuvent être ajustés. Toute tentative de définir un alias déjà existant est bloquée.
La suppression d'une propriété retire l'alias et le type de la clé d'information. La clé reste dans le dictionnaire mais n'a plus de métadonnées associées. Si un alias est supprimé, les recherches ou patterns existants continuent de fonctionner (ils reviennent à la forme complète entity.infos.xxx). Les types définis sont supprimés : le sélecteur de type revient à sa valeur par défaut.

Utilisation des alias dans l'interface¶

Une fois un alias défini, il est disponible dans plusieurs fonctionnalités :

Recherches avancées et patterns d'entités¶

Dans la recherche avancée et dans les motifs d'entité (patterns), les alias sont listés dans une section Alias avec une icône spéciale (symbole @) indiquant qu'il s'agit d'un alias. Au survol de l'icône, une info‑bulle affiche la clé d'information originale.
Les alias et les clés complètes (entity.infos.xxx) sont tous deux proposés dans les menus. Si l'utilisateur sélectionne la clé complète, l'alias est automatiquement utilisé et s'affiche dans l'interface. Le but est d'unifier l'affichage et d'éviter les doublons dans les critères de recherche.
Lorsqu'un alias est sélectionné pour filtrer des entités par leur valeur, le sélecteur de type se remplit automatiquement avec le type défini. Si l'utilisateur choisit un type différent, un avertissement apparaît pour signaler le conflit.
Pour les types Horodatage, la valeur est saisie via un calendrier (datepicker).

Templates GO et suggestions¶

Dans les suggestions pour les modèles Templates GO (Payload de webhook par exemple), les alias sont affichés, mais la valeur enregistrée correspond toujours à la clé complète.

Noms des colonnes¶

Dans les widgets affichant des tableaux (par exemple, le bac alarmes), les colonnes qui correspondent à des informations d'entité utilisent la priorité suivante pour leur étiquette :

Nom personnalisé (défini dans les paramètres du widget).
Alias (s'il existe).
Nom réel de la clé (entity.infos.xxx).

Cette règle rend la table plus lisible et cohérente : si un alias est défini, il est utilisé par défaut comme titre de colonne, à moins qu'un nom personnalisé n'ait été renseigné.

Export CSV¶

Lors de l'export CSV depuis un widget (par exemple, l'export du bac à alarmes), les valeurs d'informations d'entité sont converties en fonction de leur type :

Les valeurs marquées comme Horodatage sont converties en dates lisibles. Par exemple, le timestamp 1729512396 deviendra une date dans le fichier CSV.
Les autres types sont exportés tels quels (chaîne, nombre, booléen, tableau de chaînes).

Définition et gestion des types¶

Lorsqu'un type est défini sur une clé d'information, ce type est présélectionné dans tous les formulaires où l'on utilise cette clé (patterns, recherche avancée, etc.). Il est affiché comme type défini.
Si l'utilisateur sélectionne un autre type, un message d'avertissement signale que cela diffère du type configuré. L'avertissement peut être ignoré, mais réapparaît lors de la réouverture du formulaire.
La définition d'un type dans le dictionnaire n'entraîne pas de migration de données. Elle sert uniquement d'indication pour l'interface et les exports. Par conséquent, des valeurs existantes peuvent continuer d'utiliser un type différent (par exemple, Nombre au lieu de Horodatage), mais l'utilisateur est encouragé à corriger les incohérences via l'alias.

Résumé des bonnes pratiques¶

Définir un alias pour chaque information dont l'intitulé technique est difficile à comprendre ou à utiliser. Utiliser des noms explicites (éventuellement multi‑mots ou accentués) pour faciliter la recherche.
Définir un type cohérent dès la création de l'information. Utiliser le type Horodatage pour toutes les valeurs représentant des dates afin de garantir un affichage et un export corrects.
Éviter d'utiliser une même clé d'information avec des types différents ; il est recommandé d'harmoniser les clés ou de les renommer si les types divergent.