Les modèles d'intégration


Definition

Un modèle d'intégration permet d'importer des données dans une base Service Manager à partir de sources de données externes (fichiers CSV, bases de données).

EndDefinition
  • Il est bâti sur un connecteur indiquant les champs de la table principale et les champs des tables liées pouvant recevoir des données.
    • Une correspondance est faite entre les champs du connecteur et les champs des tables Service Manager.
    • La recherche de l'existence des enregistrements de la source externe dans la base Service Manager se fait à partir de clés d'unicité bâties à partir des champs du connecteur.
  • L'intégration des données s'effectue en exécutant le modèle via l'ordonnanceur smoScheduler de Service Manager.
    • Elle peut être immédiate ou planifiée.
    • Elle peut être précédée d'un traitement de préimport, permettant d'exécuter des scripts SQL préparatoires à l'importation des données : vidage de tables, filtrage des données à intégrer, homogénéisation des données, ...
    • Un traitement de transcodage permet de transformer les valeurs des données externes avant d'être intégrées dans la base Service Manager, afin de les homogénéiser avec le référentiel existant.
  • Un log d'intégration permet de recenser les enregistrements intégrés dans la base Service Manager et les éventuelles erreurs.
  • Les modèles d'intégration peuvent être placés dans des dossiers, permettant de les organiser suivant leur fonction.

Remarques

  • Il est possible d’affecter le même champ de la source externe vers 2 champs cibles différents du connecteur.

    exemple  Champ Téléphone de la source externe affecté aux 2 champs cibles du connecteur Téléphone et Portable

  • Il n'est pas possible de faire l’inverse et d’affecter 2 champs différents de la source externe vers le même champ cible du connecteur.

    exemple  Les 2 champs de la source externe Login et Courriel ne peuvent pas être affectés au même champ E-mail du connecteur

Attention

  • Effectuez toujours une sauvegarde de la base Service Manager avant l'exécution d'un modèle d'intégration. Vous pourrez la remonter en cas de problèmes ou d'erreurs trop importantes.
  • Si vous automatisez l'exécution d'un modèle d'intégration défini à partir d'un fichier CSV, assurez-vous que ce dernier est toujours disponible au même emplacement (dans un répertoire prédéfini du serveur web EasyVista), avec le même nom et la même structure.

Bonnes pratiques

  • Commencez par exécuter le modèle d'intégration sur la base de test. Vous pouvez ainsi corriger les éventuelles erreurs référencées dans le log d'intégration avant d'exécuter le modèle sur la base de production.
  • Par défaut, l'intégration se fait dans la langue de l'utilisateur connecté.
    • Soit utilisez un connecteur multilingue (connecteur suffixé par - Multilingue) pour intégrer simultanément les données externes dans les 6 langues standard de Service Manager.
    • Soit effectuez manuellement (depuis l’interface) la traduction des libellés multilingues que l'intégration n'a pas permis de mettre à jour. Consultez le log d'intégration pour identifier les tables de référence concernées.
  • Pour faciliter la correspondance entre les champs du connecteur et les champs d'un fichier CSV, saisissez une ligne d'en-tête dans le fichier. Sinon, les champs sont identifiés par les valeurs lues sur la première ligne.

    exemple  

    • Fichier CSV avec une ligne d'en-tête : Nom, Prénom
    • Fichier CSV sans ligne d'en-tête : Durand, Pierre
  • Pour limiter le nombre de corrections manuelles après l'intégration des données dans Service Manager, corrigez au maximum la source externe avant de lancer l'intégration.
    • Effectuez des traitements de transcodage sur les données externes si l'intégration met à jour les tables de référence et les catalogues. Cela évite de polluer le référentiel existant avec des valeurs redondantes correspondant à la même référence.

      exemple  

      • Remplacer les valeurs Hewlett P et Hewlett Packard par la valeur HP qui est celle stockée dans Service Manager
      • Remplacer le libellé Mme par Madame qui est celle stockée dans la table des civilités
    • Attribuez une valeur par défaut aux champs qui n'ont pas de valeur dans la source externe s'ils correspondent à des champs obligatoires dans Service Manager.
    • Préférez des clés d'unicité bâties à partir des identifiants plutôt qu'à partir d'une chaîne de caractères. Cela garantit la modification de l'entrée existante dans la table et non la création d'une nouvelle entrée.

      exemple  La localisation 07 = Bureau 1 est modifiée en Bureau 001

      • La localisation est recherchée à partir de son identifiant 07 qui existe dans la base ==> Le libellé est modifié.
      • La localisation est recherchée à partir du nouveau libellé Bureau 001 qui n'existe pas dans la base ==> Une nouvelle entrée Bureau 001 est créée. L'ancienne entrée avec le libellé Bureau 1 n'est pas modifiée.
    • Séparez les niveaux des champs arborescents par le caractère /.

      exemple  Localisation : Pays / Ville / Étage / Bureau ==> Valeurs dans la source externe : USA/Chicago/2/205, Canada/Québec/5/513

    • Saisissez la valeur 1 pour une case cochée et la valeur 0 pour une case non cochée.

      exemple  Employé ayant une fonction de validateur financier ==> Valeur dans la source externe : 1, qui correspond à la case Validateur cochée dans Service Manager

  • Lorsque le déclenchement d'une intégration A dépend de la fin d'exécution d'une intégration B dont la durée de traitement est aléatoire (variabilité due à la volumétrie, au temps d'accès…), planifiez un séquencement entre les modèles plutôt que de définir une périodicité à heure fixe pour l'intégration A.
  • Pour éviter de lancer simultanément la même intégration via l'outil smoIntegration et via les tâches planifiées, n'utilisez pas le même modèle. Dupliquez le modèle initial et renommez la copie en indiquant qu'il s'agit d'un modèle à l'usage exclusif de smoIntégration.
     

Garantie des performances réseau

  • Planifiez l'exécution des intégrations en dehors des plages d'accès à Service Manager (la nuit ou le week-end).

Accès menu

Administration > Intégration > Modèles d'intégration

Description des écrans

Modèle d'intégration

Étape 1 : Définition du modèle

       Integration model - Step 1.png

Nom du modèle : Nom du modèle d'intégration.

Nom du dossier : Nom du dossier d'intégration où est sauvegardé le modèle.

Mise à jour : Type de mise à jour à réaliser sur la table principale du connecteur.

  • Ajouter et modifier : Les nouveaux enregistrements sont créés dans la base Service Manager et les enregistrements existants sont mis à jour.
  • Modifier seulement : Seuls les enregistrements existants dans la base Service Manager sont mis à jour. Les nouveaux enregistrements ne sont pas créés.
  • Ajouter seulement : Seuls les nouveaux enregistrements sont créés dans la base Service Manager. Les enregistrements existants ne sont pas mis à jour.

Type de données : Provenance des données externes.

  • CSV : Fichier texte au format .csv.
  • datasource : Base de données. La chaîne de connexion à la base doit être renseignée via Définir, puis la requête SQL de recherche des données à intégrer.
        Open url.png  voir Liste des chaînes de connexion
             Integration model - Step 1 - Datasource configuration.png
Information Exemple
Connection string

Liste des paramètres pour SQLServer :

  • Provider = sqloledb (dans le cas de SQL serveur).
  • Data Source = Nom du serveur contenant la base\nom de l’instance.
  • Initial Catalog = Nom de la base de données.
  • User Id = Identifiant de connexion à la base.
  • Password = Mot de passe de connexion à la base.
Provider=sqloledb;Data Source=EZV_SQL1;Initial Catalog=EVO_BACKOFFICE;
User Id=myLogin;Password=myPassword
Query : Sélection des données
SELECT * FROM EVO_BACKOFFICE.EZV_ADMIN.myTable

Langue : Langue dans laquelle sont écrites les valeurs externes.

  • Par défaut, la langue sélectionnée est celle de l'utilisateur connecté.

Nom du connecteur : Connecteur utilisé pour bâtir le modèle d'intégration.

  • Des règles particulières peuvent être définies pour chaque connecteur  - Open url.png voir Description

Best Practice icon.png  Utilisez un connecteur multilingue (connecteur suffixé par - Multilingue) pour intégrer simultanément les données externes dans les 6 langues standard de Service Manager.

Prendre la première ligne comme entête (Note : Uniquement pour un fichier CSV) : Indique si la première ligne du fichier contient les noms des champs de la source externe (case cochée) ou les valeurs des champs (case non cochée).

Créer un log : Indique si un fichier de log doit être créé à la fin de l'intégration (case cochée) ou non (case non cochée).

Best Practice icon.png  Créez un fichier de log pour consulter les erreurs d'intégration.

Étape 2 : Correspondance des champs

       Integration model - Step 2.png

Source : Liste des champs de la source externe.

Destination : Liste des champs cibles du connecteur. 

  • Pour chaque champ de la colonne Source, sélectionnez dans la colonne Destination le champ auquel il correspond dans la base Service Manager.

Valeur par défaut : Valeur à enregistrer dans la base Service Manager si aucune valeur n'est définie dans la source externe.

Best Practice icon.png  

  • Attribuez une valeur par défaut aux champs qui n'ont pas de valeur dans la source externe s'ils correspondent à des champs obligatoires dans Service Manager.
  • Pour repérer facilement des enregistrements après l'intégration des données, attribuez-leur une valeur par défaut dans l'un des champs libres.

    exemple  Repérer les employés intégrés à partir de l'annuaire LDAP : attribuez la valeur par défaut LDAP au champ AVAILABLE_FIELD_1.

Étape 3 : Définition des propriétés des champs

       Integration model - Step 3.png

Champ d'unicité (Note : Uniquement pour les champs de la table principale du connecteur non référencés dans des tables liées) : Champs du connecteur définissant la clé de recherche unique des enregistrements dans la base Service Manager.

  • Le nombre de champs clés requis est indiqué dans l'entête de la colonne.
  • 2 clés d'unicité sont requises pour les tables liées du connecteur.

    exemple  

    • Unicité(1) = Une seule clé d’unicité est requise ==> Clé login pour l’intégration des employés
    • Unicité(2) = 2 clés d’unicité sont requises ==> Table Caractéristiques liée à la table Matériels

Insertion automatique (Note : Uniquement pour les champs des tables liées) : Lorsque la valeur de la source externe n'existe pas dans la table liée, indique si un nouvel enregistrement doit être créé dans la base Service Manager (case cochée) ou non (case non cochée).

exemple  Le connecteur Matériels utilise la table principale AM_ASSET et la table liée AM_MANUFACTURER. La source externe contient la marque ABC qui n'existe pas dans la table liée.

  • La case est cochée : La marque ABC est créée dans la table liée AM_MANUFACTURER.
  • La case n'est pas cochée : La marque ABC n'est pas créée.

Désaffecter si vide (Note : Uniquement pour les champs non arborescents des tables liées) : Lorsque la valeur de la source externe n'est pas renseignée, indique si la valeur existante dans la base Service Manager doit être réinitialisée (case cochée) ou non (case non cochée).

  • Lorsque la case est cochée, seule la valeur de l'enregistrement est remise à blanc. L'enregistrement n'est pas supprimé.

exemple  La civilité n'est pas renseignée dans la source externe pour l'employé Adam Smith. Dans la base Service Manager, elle est égale à Mr..

  • La case est cochée : La valeur de la civilité est remise à blanc pour l'employé Adam Smith. La valeur Mr. est effacée dans la base Service Manager.
  • La case n'est pas cochée : La valeur actuelle de la civilité Mr. est conservée dans la base Service Manager.

Transcodage : Permet de transformer la valeur de la source externe avant de l'intégrer dans la base Service Manager, afin de l'homogénéiser avec le référentiel existant  - Open url.png voir Description

  • Les clés d'unicité peuvent être transcodées.
  • Cliquez sur l'icône pour ouvrir la fenêtre de transcodage : les règles déjà définies pour le champ du connecteur sont affichées  - Open url.png voir Procédure détaillée
    • Sheet full icon.png : Au moins une valeur de transcodage a déjà été saisie pour le champ.
    • Sheet empty icon.png : Aucune valeur de transcodage n'a été saisie pour le champ.

Planification d'un modèle d'intégration

Note : Ces paramètres ne sont pas pris en compte pour une planification de l'exécution du modèle d'intégration via un ordonnanceur externe.
         Integration model - Scheduling information.png

Activée : Indique si la planification du modèle d'intégration est activée (case cochée) ou non (case non cochée).

Best Practice icon.png  Ne cochez pas cette case si vous planifiez l'exécution du modèle d'intégration via un ordonnanceur externe.

Périodicité : Indique la fréquence d'exécution du modèle d'intégration.

  • La périodicité est prise en compte à partir de la date de prochain calcul. 
  • Les paramètres varient suivant le type de périodicité sélectionné.
    • Tous les [N] mois / jours / heures : Saisissez la fréquence souhaitée, exprimée en Temps Universel.
    • Dépend de : Permet un séquencement de tâches avec un autre modèle. Sélectionnez dans la liste déroulante le modèle d'intégration après lequel l'exécution doit se déclencher.

Date de prochain calcul (Note : Uniquement si la périodicité est différente de l'option Dépend de) : Date / heure à laquelle doit s'effectuer la prochaine exécution du modèle d'intégration.

  • La date permet d'initialiser le jour de démarrage de la périodicité.

    exemple  Périodicité d'exécution : Tous les 7 jours à 7h  ; La première date de calcul est un samedi ==> Le modèle s'exécute tous les samedis

    Best Practice icon.png  Saisissez une date antérieure à la date du jour pour que le début de la planification démarre immédiatement.

Fichier d'intégration : Emplacement du fichier .csv d'intégration.

  • Attention : Le fichier doit toujours être à disposition sur le serveur web EasyVista, dans le répertoire Resources/<Account>/Integration (<Account> identifie la base Service Manager dans laquelle les données doivent être intégrées).

Procédures et Assistants

Comment créer un modèle d'intégration

CreationProcedure

Étape 1 : Création du modèle d'intégration

1. Allez sur le menu Administration > Intégration > Modèles d'intégration.

2. Cliquez sur + Nouveau.

Étape 2 : Définition des propriétés générales du modèle

1. Saisissez le nom et le dossier du modèle.

2. Sélectionnez le type de mise à jour souhaité.

3. Indiquez la provenance des données externes.

  • Intégration d'un fichier
    • Sélectionnez le type de données CSV.
    • Cliquez sur Télécharger et sélectionnez le fichier.
  • Intégration des données d'une base
    • Sélectionnez le type de données datasource.
    • Cliquez sur Définir.
    • Renseignez l'instruction de connexion à la base  - Open url.png  voir Liste des chaînes de connexion
    • Saisissez la requête SQL de recherche des données à intégrer.

4. Sélectionnez le connecteur.

5. (Optionnel - Note : Uniquement pour un fichier CSV) Indiquez les options souhaitées pour les champs Prendre la première ligne comme entête et Créer un log.

6. Cliquez sur Suivant.

Étape 3 : Correspondance entre les champs du connecteur et les champs de la source de données externes

1. Sélectionnez chaque champ du connecteur (colonne Destination) correspondant à chaque champ de la source externe (colonne Source).

  • Pour ignorer certains champs de la source de données externes :
    • Cochez la case correspondante en début de ligne.
    • Cliquez sur Minus icon.png.
      Les champs ne sont pas supprimés : seule la correspondance n'est pas établie.
  • Pour recréer la liaison sur un champ de la source de données externes ignoré précédemment :
    • Cliquez sur Plus icon.png pour ajouter une nouvelle ligne.
    • Sélectionnez le champ dans la liste déroulante Source.
    • Indiquez la correspondance dans la colonne Destination.

2. Cliquez sur Suivant.

3. Renseignez les propriétés des champs

  • Cochez les champs définissant la clé d'unicité.
  • Cochez la case Insertion automatique si vous voulez créer un nouvel enregistrement dans la base Service Manager lorsque la valeur de la source externe n'existe pas dans la table liée.
  • Cochez la case Désaffecter si vide si vous voulez remettre à blanc la valeur existante dans la base Service Manager lorsque la valeur de la source externe n'est pas renseignée.
  • Renseignez les valeurs de transcodage  - Open url.png voir Procédure détaillée
     

Étape 4 : Sauvegarde du modèle d'intégration

1. Cliquez sur Terminer.

Note : Les erreurs bloquantes sont signalées en rouge et l'étape concernée est automatiquement affichée.

EndCreationProcedure

Comment transcoder les valeurs de la source externe

Normalization_Procedure

Étape 1 : Affichage de la fenêtre de transcodage

1. Allez sur le modèle d'intégration via le menu Administration > Intégration > Modèles d'intégration.

2. Allez sur l'étape 3 via Suivant.

3. Cliquez sur Sheet full icon.png ou Sheet empty icon.png en regard du champ à transcoder.

  • Sheet full icon.png : Au moins une valeur de transcodage a déjà été saisie pour le champ.
  • Sheet empty icon.png : Aucune valeur de transcodage n'a été saisie pour le champ.

La fenêtre de transcodage est affichée.
         Integration model - Step 3 - Normalization.png
 

Étape 2 : Saisie des valeurs de transcodage

1. Saisissez dans la colonne Valeur (source) la valeur d'origine du champ dans la source externe.

2. Saisissez dans la colonne Valeur référence (destination) la nouvelle valeur à intégrer dans la base Service Manager.

3. Cliquez sur Enregistrer.

4. Fermez la fenêtre.
Vous revenez sur la liste des propriétés des champs du modèle. Sheet full icon.png est affiché en regard du champ Source.

Ajout d'une valeur de transcodage pour le champ

  • Cliquez sur Plus icon.png.
  • Renseignez la valeur comme précédemment.

Suppression d'une valeur de transcodage

  • Cochez la case en regard de la ligne.
  • Cliquez sur Minus icon.png.

Comment lancer un modèle d'intégration via l'ordonnanceur smoScheduler de Service Manager

    Open url.png Reportez-vous à la procédure Comment automatiser une intégration pour exécuter un modèle d'intégration via un ordonnanceur externe ou une application tierce

Exécution immédiate du modèle

ImmediateIntegration_Procedure

1. Allez sur le menu Administration > Intégration > Modèles d'intégration.

2. Cliquez sur Edit icon.png en regard du modèle d'intégration.

3. Allez sur la dernière étape du modèle via Suivant.

4. Cliquez sur Lancer.

  • Le modèle d'intégration est mis dans la file d'attente de l'ordonnanceur smoScheduler. Il est exécuté après les tâches en cours.
  • La liste des logs d'intégration est affichée à la fin du traitement.
  • Le statut Réussie indique que l'intégration a été effectuée avec succès.

5. Vérifiez les enregistrements mis à jour.

  • Cliquez sur les liens hypertextes Ajoutés / Modifiés dans l'onglet Enregistrements pour afficher la liste des enregistrements mis à jour.
  • Cliquez sur l'onglet Erreurs pour afficher les erreurs d'intégration et les messages d'avertissement.
EndImmediateIntegration_Procedure

Planification de l'intégration

ScheduledIntegration_Procedure

1. Allez sur le menu Administration > Intégration > Modèles d'intégration.

2. Cliquez sur Calendar icon.png en regard du modèle d'intégration.
La fenêtre des informations de planification est affichée.

3. Cochez la case Activée et renseignez les informations de planification  - Open url.png voir Description

Note : Le fichier .csv doit être à disposition sur le serveur web EasyVista, dans le répertoire Resources/<Account>/Integration (<Account> identifie la base Service Manager dans laquelle les données doivent être intégrées).

Best Practice icon.png  Saisissez une date antérieure à la date du jour pour que le début de la planification démarre immédiatement.

4. Cliquez sur Terminer.
Les données sont intégrées lors de la prochaine exécution du modèle d'intégration.

5. Corrigez les éventuelles erreurs en consultant le log d'intégration.

EndScheduledIntegration_Procedure

Les assistants

Déplacer : Modifie le dossier auquel est rattaché le modèle d'intégration.

Cas particuliers d'utilisation

  • Modèle d'intégration basé sur le connecteur Employés avec photos  - Open url.png voir Mise en oeuvre
  • Mise à jour de la base de connaissance Service Manager via le modèle d'intégration bâti sur le connecteur dédié Erreurs connues et connaissances (Self Help Extractor)  - Open url.png voir Mise en oeuvre
Tags:
Modifié par Christine Daussac le 2021/05/28 13:06
Créé par Administrator XWiki le 2013/03/14 16:22

Raccourcis

L'actualité mensuelle
•  Newsletter

Tous les changements
•  Service Manager
•  Service Apps
•  Self Help
•  Service Bots

Powered by XWiki ©, EasyVista 2021