Concept
Les règles de mapping permettent, lors de l'import, de mettre en relation un champ du fichier Excel avec une propriété ou une donnée de Shinken en fonction du type de l'élément ( hôte, modèle d'hôte, etc ... ).
- Elles s'appliquent pour tous les types d’éléments présents dans l'interface de Shinken.
Elles peuvent être visualisées depuis l'onglet "Mapping vers les propriétés et les données de Shinken" de l'interface de la source.
|
Définition des règles de mapping
Les règles de mapping sont écrites dans l'onglet "Configuration" du fichier Excel.
- Elles servent à faire correspondre les champs collectés par la source aux propriétés et données dans Shinken.
Une propriété est une information nécessaire au moteur Shinken.
|
Une donnée est une valeur qui va être ajoutée en complément des propriétés.
Si la syntaxe utilisant DATA(...) est à privilégier, il est également possible de créer une donnée dans Shinken en lui donnant un nom en majuscule commençant par un underscore ( ex : _NOM_DONNEE_SHINKEN ) et en l'associant au champ récolté par la source. |
Exemple de mapping dans le fichier excel
|
Il y a 8 règles de mapping définies dans l'exemple ci-dessus :
| Type d'action réalisée | Champs dans Excel | Propriétés dans Shinken | Description du mapping | |
|---|---|---|---|---|
Mapping simple vers une Propriété | Serveur / Application | host_name | La valeur dans la colonne "Serveur / Application" deviendra le nom de l'hôte ( propriété host_name ). | |
| Mapping simple vers une Propriété | IP | address | La valeur dans la colonne "IP" sera prise en compte comme adresse pour l'hôte ( propriété address ). | |
| Concaténation de plusieurs champs collectés | CONCAT($Type$ - $OS$, Modèle hôtes - $Datacenter$) | use | Les valeurs dans les colonnes "Type", "OS" et "Datacenter" seront concaténées et le résultat sera utilisé pour lister les modèles de l'hôte ( propriété use ). Par exemple, si l'hôte a les valeurs suivantes :
Sa propriété "use" vaudra :
| |
| Transformation du contenu d'un champ | Status>TRANSFORM(ONGOING=>0,OK=>1) | enabled | La valeur de la colonne "Status" sera transformée et servira à définir si l'hôte est activé ou non ( propriété enabled ):
| |
| Mapping simple vers une Donnée | OS | DATA(OPERATING_SYSTEM) | La valeur de la colonne "OS" sera stockée dans la donnée "OPERATING_SYSTEM". Il s'agit de la syntaxe à privilégier pour les données. IMPORTANT : la forme _OPERATING_SYSTEM au lieu DATA(OPERATING_SYSTEM) est fonctionnelle mais DEPRECIÉE. | |
| Mapping simple vers une Donnée avec un transformation préalable. | OS>TRANSFORM(Linux=>Unix) | DATA(OS_FAMILY) | La valeur de la colonne "OS" sera récupérée et transformée avant d'être stockée dans la donnée "OS_FAMILY" IMPORTANT : la forme _OS_FAMILY au lieu DATA(OS_FAMILY) est fonctionnelle mais DEPRECIÉE. | |
| Mapping simple vers plusieurs Données | MANY_FIELDS_BY_REGEX(EXTRAINFO-(.*)-(.*)) | DATA($1_$2) | La valeur de toutes les colonnes dont le nom :
Deviendront des données dont les noms reprendront les deux parties. $1 correspond à la partie capturée par les premières parenthèses et $2 par les deuxièmes ( Voir le chapitre Opérateur MANY_FIELDS_BY_REGEX pour règles de mapping dynamiques ( expressions régulières ) )
|
Opérateur pour les règles de mapping
Les opérateurs des règles de mapping permettent de transformer les données collectées afin de les adapter au format de Shinken et aux besoins de la supervision.
Les opérateurs suivants ne sont pas disponibles pour cette source, car ils fonctionnent avec des listes et cette source ne fournit pas d’éléments dont la valeur est une liste ; seules des chaînes de caractères séparées par des virgules sont disponibles.
|
Opérateur TRANSFORM pour les transformations
Grâce à l'opérateur TRANSFORM il est possible de transformer du texte.
- Exemple : Le fichier excel fournit la valeur "Préproduction" et l'on veut transformer cette valeur en "PREPROD" à la place.
- Exemple : Le fichier excel fournit la valeur "TODO" et l'on veut transformer cette valeur en "0" à la place.
La syntaxe de TRANSFORM est la suivante :
TRANSFORM(transformation1,transformation2,transformation3) |
- TRANSFORM permet d'indiquer plusieurs transformations, ces dernières sont séparées par des virgules.
- Attention à ne pas mettre d'espace avant ou après une virgule, autrement, il sera pris en compte dans la transformation.
- Il n'y a actuellement pas de limite sur le nombre de transformations autorisées.
Pour écrire une transformation, il faut séparer le texte à transformer par "=>" du texte désiré ( désigné ci-après par le mot "séparateur" ) : TEXTE1=>TEXTE2
Voici un exemple de syntaxe avec 2 transformations :
TRANSFORM(BORDEAUX=>BDX,PARIS=>PAR) |
TRANSFORM permet également de supprimer du texte en laissant vide la partie à droite du séparateur ( => ) censée contenir la modification à apporter au texte.
TRANSFORM(DEAUX=>,IS=>) |
Exemple avec une machine possédant la colonne suivante :
| ENV | Production_Bordeaux |
|---|
Et le mapping suivant :
| Type | Champs dans Excel | Propriétés dans Shinken |
|---|---|---|
| Colonne | ENV>VALUES(=Bordeaux)>TRANSFORM(Production=>Prod,Bordeaux=>bdx) | DATA(TRANSFORM_OPERATION) |
La donnée TRANSFORM_OPERATION contiendra donc la valeur suivante :
Prod_bdx
Le caractère $ est utilisé ici pour indiquer à TRANSFORM d'aller chercher les valeurs à faire apparaître, il n'est donc pas possible de l'utiliser dans un autre but que celui-ci. |
Opérateur CONCAT pour les concaténations
Il est possible de concaténer les valeurs de plusieurs colonnes pour former la valeur d'une propriété d'un élément de Shinken. Cela est possible grâce à l'opérateur : CONCAT.
Exemple : Un hôte possédant les colonnes suivantes :
| OS | Linux |
| ENV | Production |
| LOCATION | Bordeaux |
Et les informations doivent apparaître de la manière suivante dans la donnée nommée MACHINE_INFOS : "Production - Linux - Bordeaux"
La syntaxe se fera de la manière suivante dans le fichier de Mapping.
| Type | Champs dans Excel | Propriétés dans Shinken |
|---|---|---|
| Colonne | CONCAT($OS$ - $ENV$ - $LOCATION$) | DATA(MACHINE_INFOS) |
Le caractère $ est utilisé ici pour indiquer à CONCAT d'aller chercher les valeurs souhaitées, il n'est donc pas possible de l'utiliser dans un autre but que celui-ci. |
Si colonne est vide, alors CONCAT ne fournira pas de valeur pour cette colonne.
Exemple : avec les mêmes données que l'exemple précédent, sauf que "LOCATION" n'a aucune valeur, la donnée MACHINE_INFOS vaudra : " Production - Linux - "
Opérateur MANY_FIELDS_BY_REGEX pour règles de mapping dynamiques ( expressions régulières )
L'opérateur MANY_FIELDS_BY_REGEX permet de mapper plusieurs champs à importer dans Shinken à l'aide d'une expression réguliere en une seule règle.
Couramment, le mapping entre les champs importées par la source et les propriétés de Shinken est exhaustif. Cependant, lors de la récupération des données, il est possible d'avoir un grand nombre de champs différentes à importer dans Shinken.
Dans ce cas, le fonctionnement habituel ne suffit plus, c'est pour cela que les règles de mapping peuvent désormais faire appel à des expressions régulières.
Une expression régulière est une formule qui sert à rechercher ou reconnaître des motifs dans du texte.
Par exemple :
- Trouver toutes les clés qui commencent par "EXTRAINFO-" et qui sont en deux parties séparées par un tiret ( - ).
- ( Pour une aide à propos des expressions régulières, voir la page : Guide des expressions régulières )
Pour les utiliser dans le mapping, il faut les écrire sous le format suivant dans la colonne "Propriétés dans Excel" :
MANY_FIELDS_BY_REGEX(EXPRESSION) |
où "EXPRESSION" est l'expression régulière.
Il est possible de récupérer les groupes matchés dans l'expression régulière ( voir la page suivante pour une aide sur les groupes dans les expressions régulières : Guide des expressions régulières - groupe ) pour construire le nom de la donnée dans Shinken. Pour ce faire, il faut utiliser "$" suivi du numéro du regroupement ( $1, $2, $3, etc. )
Il n'est pas possible d'avoir plus de regroupements dans le nom de la donnée qu'indiqués dans l'expression régulière. On ne peut donc pas faire correspondre la règle "MANY_FIELDS_BY_REGEX(EXTRAINFO-(.*)-(.*))" aux données "DATA($1_$2_$3)" car l'expression ne recherche que deux regroupements. |
Exemple d'expression régulière
|
Avec cette expression régulière, la valeur de toutes les colonnes dont le nom :
- Commence par "EXTRAINFO-"
- Est constitué de deux autres parties séparées par un tiret ( - )
Deviendront des données dont les noms reprendront les deux parties.
- $1 correspond à la partie capturée par les premières parenthèses
- et $2 par les deuxièmes.
Les valeurs dans la colonne "EXTRAINFO-MAC-ADDRESS" seront stockées dans des données qui s'appelleront "MAC_ADDRESS" |
Désactivation d'un mapping
Les mappings peuvent être désactivés, cela permet de conserver un mapping sans qu'il soit importé, afin de ne pas avoir à le supprimer.
- Pour désactiver un mapping, au lieu de choisir une propriété ( ou donnée ) Shinken, il faut utiliser le mot-clé "disable".
Désactivation du champ Status>TRANSFORM(TODO=>0,OK=>1)
|
|
Visualiser la liste des mappings
Pour visualiser la liste des mapping définie pour cette source, il faut se rendre dans l'onglet "Mapping vers les propriétés de Shinken".
Dans cet onglet, se trouve le chemin du fichier de configuration ( 1 ).
Un message d'avertissement apparaîtra si le fichier n'existe pas.- Pour résoudre ce problème, créer le fichier avec le chemin indiqué sur l'interface puis appuyer sur le bouton de rafraîchissement ( 2 ).
- Ce fichier ne peut pas être vide,
- si l'onglet "Configuration" n'est pas rempli, la source générera des erreurs.
Dans l'en-tête de la liste, se trouve également le bouton de rafraîchissement de la liste des mappings ( 2 ).
- Ce bouton permet de rafraîchir la liste des mappings sans devoir redémarrer le Synchronizer.
- Il faudra relancer un import pour réappliquer les nouveaux mappings sur les éléments importés.
|
La liste des mappings ( 3 ) comporte à la fois les mappings définis par l'utilisateur ( ligne bleue ) et les mappings par défaut ( ligne grise ).
La liste affiche pour chaque mapping une série de colonnes :
- Prob. => Affiche les problèmes ou les avertissements si le mapping n'a pas été correctement défini.
- Défini par => Par qui le mapping a été défini ( Par défaut ou par l'utilisateur ).
- Classe => Le type de l'objet concerné par le mapping ( hôte, cluster, etc ).
- Si plusieurs types ont le même mapping deux lignes différentes seront affichées
- La clé dans la source => Le nom de la colonne dans la source excel.
- Description => La description du champ dans la source.
- Clé Shinken => Nom de la propriété ou donnée Shinken vers laquelle la valeur sera copiée.
- Nom de la propriété dans l'interface => Le nom de la propriété ou donnée Shinken dans l'interface.
Certaines des règles de mapping définies par "Défaut" ont une valeur définie dans les champs "Clé de la source" et la "Description", mais aucune valeur dans les champs " Clé Shinken" et " Nom de propriété dans l'interface ".
- Cela signifie que ces mappings ne seront liés à aucune propriété Shinken.
- Ils sont volontairement listés ici pour être vus, et faciliter la création de son propre mapping ( afin de ne pas partir d'une feuille blanche ).