Créer un modèle d'import/export

Guide administrateur #

Introduction #

Il est possible d’alimenter la base YellowBox CRM de données externes et/ou d’alimenter à partir de la base YellowBox CRM des outils tiers selon deux méthodes :

• Via l’API et les webservices
  
  
• Via le module d’imports/exports de données avec des fichiers de type texte
  Les fichiers exportés, comme les fichiers importés sont des fichiers ‘à plat’. En d’autres termes, cela signifie que ces fichiers contiennent une ligne structurée avec les valeurs des champs sélectionnés pour chacune des fiches ciblées par l’import ou sélectionnées pour l’export.
  
  Un modèle d’import et/ou d’export peut être exécuté via un processus qui permet alors de planifier des interfaces régulières ou de l’utiliser dans le cadre d’enchainement de traitements divers.
  
  Dans le cas où un modèle n’a pas pour objet d’intégrer un processus car il concerne par exemple l’alimentation initiale de la base ou tout simplement pour effectuer un test, il est possible d’exécuter un import ou un export manuellement via les boutons [] ou [] présents en haut à droite de la liste des traitements de type import/export.

Ce chapitre décrit la formalisation de modèles d’exports ou d’imports uniquement ; concernant la description du fonctionnement de l’API, se référer à la partie ‘Développeurs : API et plugin’.

Un modèle peut être créé dans la liste des modèles ou directement dans un processus.

Les modèles d’import ou d’export peuvent être paramétrés sur une, deux, voire trois tables de la structure de la base de données selon le cas : il est possible par exemple d’importer via un seul fichier des sociétés et leurs contacts. Aussi, dès lors que la table ‘Actions’ est sélectionnée, il est possible de définir de sélectionner également les tables ‘Contacts’ et ‘Sociétés’.

Outres les tables de données, il est possible d’importer et/ou d’exporter les listes de mots clés.

Définir un modèle #

L’accès au menu permettant de consulter/modifier les imports/exports existants ou d’en créer de nouveaux est réalisé via le bouton [] en haut à droite du panneau de commande gauche puis en cliquant sur [Automatismes] puis [Traitements].
L’onglet ‘Traitements’ est par défaut sélectionné.

Cliquer sur le sous-onglet ‘IMPORTS/EXPORTS’ pour obtenir la liste des modèles existants.

Un même modèle peut être utilisé tant pour import que pour export.

A partir de cette liste, il est non seulement possible de rechercher un modèle existant via auto-complétion dans la zone ‘-Tous les imports/exports-’ mais également de filtrer la liste sur les modèles impliquant une table en particulier via la zone ‘-Toutes tables-’.

Pour ouvrir le détail d’un modèle à partir de la liste, cliquer simplement sur sa ligne.
Pour ajouter un nouveau modèle, cliquer sur le bouton [] présent en haut à droite de la liste.

Le Nom du modèle doit alors être saisi.

Même si la trame d’un modèle est commune pour le paramétrage d’un export et/ou d’un import, certains éléments ne sont pas nécessaires selon le cas.

Paramétrage d’un export #

Sélection des champs à exporter #

Deux types de sélections sont possibles :

• Mode SQL
  Ce mode est activable en cliquant sur le bouton [Changer le mode d’export SQL/Critère]. Dans ce cas, la sélection des ‘Tables ciblées’ disparaît au bénéfice d’une zone de saisie d’une ‘Requête SQL’.
  

  
  Les trois boutons présents au-dessus de la zone de saisie de la requête permettent de :
  

  • [Structure de la base]
    Ouvrir un nouvel onglet du navigateur et d’afficher l’ensemble de la structure de la base, avec les noms physiques en base de tous les éléments et tous les liens existants entre tables.

  • [Aide]
    Rappeler la syntaxe attendue et des variables utilisables dans la requête :

    • ‘##reffiche$$’:identifiant de la fiche courante
    • ‘##userid$$’ : identifiant de l’utilisateur connecté
    • ‘##lat$$’ : coordonnées Y de la position actuelle de l’utilisateur
    • ‘##lng$$’ : coordonnée X de la position actuelle de l’utilisateur

  • [Tester]
    Tester la syntaxe de la requête saisie.

• Mode partenaire via la sélection des champs (mode par défaut)
  Dans ce cas, il convient de sélectionner dans les tables à exporter et l’ordre les champs contenant les valeurs à exporter pour chacune des fiches.

  • Tables ciblées
    

    • Table principale
      Permet de définir la table impliquée par le traitement : tous ses champs sont alors sélectionnables.
    • Table liée
      Par défaut cette zone est alimentée par la table principale de la table sélectionnée dans la zone du dessus. Il est possible de faire pointer sur une autre table liée à la première table sélectionnée ou de la vider.
      
      

  • Sélection des champs
    

    • Type de mise à jour
      Non utilisé en mode export
      • Critère pour table principale
        Non utilisé en mode export
      • Critère pour table liée
        Non utilisé en mode export
      • Critère pour deuxième table liée
        Non utilisé en mode export
    • Tableaux de sélection
      La partie gauche présente l’ensemble des champs exportables et la partie droite l’ensemble des champs pris en compte dans l’export.
      Pour ajouter un champ dans la partie droite, il suffit de cliquer sur le champ désiré dans la colonne de gauche, puis de cliquer sur le chevron pour le faire basculer dans la colonne de droite (et inversement sur le chevron pour le supprimer de la liste).
      Les boutons et permettent de sélectionner l’ensemble des champs en une seule fois. Le champ ‘Ne pas importer’ permet de créer une colonne vide si nécessaire.
      
      Les boutons et permettent de modifier l’ordre des champs pour qu’il corresponde au format du fichier à exporter. Ces flèches décaleront toutes les lignes sélectionnées.

  • Propriétés du fichier
    

    • Caractère de fin de ligne
      Permet de mettre un retour chariot entre chaque fiche exportée.
    • Séparateur de champ
      Définit le caractère choisi comme séparateur entre chaque valeur exportée d’une fiche.
    • Retour chariot des commentaires
      Définit si les caractères CR/LF de saut de ligne sont remplacés par le caractère sélectionné dans le fichier généré.
    • Encodage
      Déterminer l’encodage (codepage) du fichier généré.
    • Supprimer la première ligne
      Ote la ligne d’entête si actif.
    • Exécuter les règles
      Non utilisé en mode export
    • Ne pas archiver
      Non utilisé en mode export

Paramétrage d’un import #

Sélection des champs à importer #

Le mode SQL n’a pas de sens pour un modèle d’import. Le paramétrage est réalisé via le mode de sélection des champs.

• Mode partenaire via la sélection des champs (mode par défaut)
  Dans un premier temps il est nécessaire de sélectionner quelles sont la ou les tables qui sont impliquées dans l’import des données contenues dans le fichier texte (Tables ciblées) qui est fourni et quelle est la structure des lignes (Sélection des champs).

  • Tables ciblées
    

    • Table principale
      Permet de définir la table impliquée par le traitement : tous ses champs sont alors sélectionnables.
    • Table liée
      Par défaut cette zone est alimentée par la table principale de la table sélectionnée dans la zone du dessus. Il est possible de faire pointer sur une autre table liée à la première table sélectionnée ou de la vider.
      
      

  • Sélection des champs
    Une fois les tables sélectionnées doit être déterminé le type de traitement réalisé sur chacune des fiches contenues dans le fichier en termes de création et/ou de mises à jour.

    • Type de mise à jour
      Lorsqu’une ligne du fichier texte à importer est traitée, plusieurs comportements sont possibles. Il convient alors de sélectionner le type de mise à jour à effectuer :

      • Création et maj de tous les champs
        Crée les enregistrements s’ils n’existent pas et met à jour les champs des enregistrements trouvés, et ce pour la table principale comme pour la table liée. Crée également le lien entre les enregistrements des deux tables.

      • Création et maj des champs vides
        Crée les enregistrements s’ils n’existent pas et met à jour les champs des enregistrements trouvés mais uniquement si ceux-ci sont vides. S’ils contiennent une valeur, elle ne sera pas écrasée par la nouvelle. Ceci est valable pour la table principale comme pour la table liée. Crée également le lien entre les enregistrements des 2 tables.

      • Création sans mise à jour
        Crée les enregistrements s’ils n’existent pas mais ne fait rien sur les enregistrements existants, et ce pour la table principale comme pour la table liée. Crée également le lien entre les enregistrements des 2 tables.

      • Mise à jour sans création
        Met à jour les enregistrements trouvés (que les champs soient vides ou pas) mais ne crée pas les enregistrements non trouvés. Crée également le lien entre les enregistrements des 2 tables, dans le cas où l’un comme l’autre existent et si ce lien n’existait pas déjà.

      • Création (table principale uniquement) et maj de tous les champs
        

        • Pour la table principale : crée les enregistrements s’ils n’existent pas et met à jour les champs des enregistrements existants, qu’ils soient vides ou pas.
        • Pour la table liée : ne crée pas d’enregistrement s’il n’est pas trouvé et met à jour les champs des enregistrements existants, qu’ils soient vides ou pas.
        • Création du lien entre l’enregistrement de la table principale et celui de la table liée, s’il existe.

      • Création (table principale uniquement) et maj des champs vides

        • Pour la table principale : crée les enregistrements s’ils n’existent pas et met à jour les champs des enregistrements existants, uniquement s’ils sont vides.
        • Pour la table liée : ne crée pas d’enregistrement s’il n’est pas trouvé et met à jour les champs existants, uniquement s’ils sont vides.
        • Création du lien entre l’enregistrement de la table principale et celui de la table liée, s’il existe.

      • Création (table principale uniquement) sans mise à jour

        • Pour la table principale : crée les enregistrements mais ne fait rien sur les enregistrements existants.
        • Pour la table liée : ne crée pas les enregistrements s’ils n’existent pas et ne met pas à jour ceux qui existent.
        • Création du lien entre l’enregistrement de la table principale et celui de la table liée s’il existe.

      • Critère pour table principale
        Ce critère concerne le ou les champs sur lesquels portent le dédoublonnage de fiches. Deux possibilités à ce niveau :

        • Sélectionner un des champs de la structure du fichier pour dédoublonner
        • Sélectionner ‘Doublon YellowBox’ : permet d’utiliser le dédoublonnage paramétré au niveau de la table (avec possibilité de concaténation de champs).

      • Critère pour table liée
        Idem critère précédent.

      • Critère pour deuxième table liée
        Ce critère n’est affiché que dans le cas où l’import concerne principalement la table ‘Actions’. Les choix de paramétrage sont identiques aux deux critères précédents.

    • Tableaux de sélection
      La partie gauche présente l’ensemble des champs des tables impliquées et la partie droite l’ensemble des champs pris en compte par l’import.
      Pour ajouter un champ dans la partie droite, il suffit de cliquer sur le champ désiré dans la colonne de gauche, puis de cliquer sur le chevron pour le faire basculer dans la colonne de droite (et inversement sur le chevron pour le supprimer de la liste).
      
      Les boutons et permettent de sélectionner l’ensemble des champs en une seule fois dans un sens ou dans l’autre.
      
      Le champ ‘Ne pas importer’ permet de tenir compte de la colonne sans pour autant qu’elle ait une correspondance avec un champ de la base.
      
      Les boutons et permettent de modifier l’ordre des champs pour qu’il corresponde au format de votre fichier. Ces flèches décaleront toutes les lignes sélectionnées. Les champs doivent être sélectionnés dans la colonne de droite dans l’ordre dans lequel ils sont présents dans le fichier texte à importer.

  • Propriétés du fichier
    Il convient ici de décrire le format du fichier fourni pour importation des données.

    • Caractère de fin de ligne
      En règle générale, il convient de sélectionner ‘Retour chariot’(correspond au caractères CRLF). Sinon ajuster par rapport aux caractères fournis.

    • Séparateur de champ
      Permet de déterminer avec quel caractère sont séparées les valeurs fournies.

    • Retour chariot des commentaires
      Le caractère saisi est interprété lors du traitement d’import comme un retour chariot.

    • Encodage
      Permet de caler la page de caractères utilisée dans le fichier à importer.

    • Supprimer la première ligne
      Permet de ne traite pas la première ligne comme étant une fiche à traiter,mais bien une ligne d’entête.

    • Exécuter les règles
      Permet d’éxecuter pour chacune des lignes traitées du fichier les règles à création, validation,… comme si la fiche est créée ou mise à jour manuellement.

    • Ne pas archiver
      En fin de traitement le fichier importé est automatiquement déplacé dans un dossier ‘Archives’.
      Dans certains cas, plusieurs imports du même fichier doivent être effectués : pour éviter de générer trop de sous-dossiers ‘Archives’, il est possible de désactiver ce déplacement.
      
      t

Cliquer sur le bouton [Valider] en bas à droite de l’écran de paramétrage pour sauvegarder le modèle.
Le modèle est alors disponible pour être utilisé comme traitement dans les processus.

Point particulier sur les listes de mots clés #

YellowBox CRM permet d’exporter ou d’importer une liste de mots clés.

• Comme pour les autres imports/exports, il est nécessaire de saisir un nom pour le modèle.

• Il convient ensuite de sélectionner au niveau de la table principale des Tables ciblées la valeur Mots clés.
  Un nouveau champ apparaît alors permettant la sélection parmi toutes les listes de mots-clés existantes, celle qui fait l’objet du traitement.

• La structure du fichier exporté comme importé est imposée :

  • Dans le cas où le multilingue n’est pas activé
    Le fichier est structuré avec une seule colonne contenant le mot clé

  • Dans le cas où le multilingue est activé La structure du fichier généré ou à importer est décrite directement dans le modèle.
    De manière générale, elle est composée des éléments suivants :

    • La valeur de consolidation
      Valeur commune à toutes les langues
    • La valeur de la première langue
    • La valeur de la seconde langue
    • Etc
      
      

• Renseigner ensuite les propriétés désirées :
  

  • Caractère de fin de ligne
    En règle générale, il convient de sélectionner ‘Retour chariot’ (correspond au caractères CRLF). Sinon ajuster par rapport aux caractères désirés ou fournis (selon que ce soit un export ou un import).
  • Séparateur de champ
    Permet de déterminer avec quel caractère sont séparées les valeurs fournies.
  • Retour chariot des commentaires
    Le caractère saisi est interprété lors du traitement d’import comme un retour chariot.
  • Encodage
    Permet de caler la page de caractères utilisée dans le fichier à importer.
  • Supprimer la première ligne
    Permet de ne traite pas la première ligne comme étant une fiche à traiter,mais bien une ligne d’entête.

Pour les exports : toutes les valeurs de la liste de mots clés sélectionnée seront exportées dans un fichier composé d’une seule colonne. Si la case ‘Supprimer la première ligne’ n’est pas cochée, la première ligne aura la valeur ‘traductionfr’.

Pour les imports : ceux-ci sont réalisés en mode Annule et remplace : toutes les valeurs déjà associées à la liste de mots clés sélectionnée sont supprimées.

Exécuter un export manuellement #

Pour effectuer un export manuel de données, il convient de cliquer sur le bouton [] présent en haut à droite de la liste des traitements de type import/export.

A partir de la boite de dialogue ouverte, il est possible de :

• Paramétrer directement les caractèristiques du fichier à générer selon les modalités de création d’un modèle d’export explicitées au-dessus (avec la possibilité de l’enregistrer en tant que modèle si désiré).

• Sélectionner un modèle déjà paramétré via le bouton [] présent en haut à droite de la boite de dialogue.
  Dans ce cas, tous les paramètres sont récupérés et reste à renseigner la recherche sur laquelle porte l’export des données.
  

• Modifier si nécessaire le nom du fichier qui est généré dans la zone ‘Nom du document créé’.
  

Avant de cliquer sur le bouton [Exécuter] enregistrer l’export paramétré comme modèle, si souhaité, en cliquant sur [].

Lorsque l’export est terminé, une alerte est générée. Cette alerte propose un lien qui permet d’ouvrir la fiche document qui a été créée, et ouvrir ou télécharger le fichier généré.

Exécuter un import manuellement #

Pour effectuer un import manuel de données, il convient de cliquer sur le bouton [] présent en haut à droite de la liste des traitements de type import/export.

A partir de la boite de dialogue ouverte, il est possible de :

• Sélectionner le fichier à importer.
• Comme pour l’export, paramétrer directement les caractèristiques du fichier à importer selon les modalités de création d’un modèle d’import explicitées au-dessus (avec la possibilité de l’enregistrer en tant que modèle si désiré).
• Sélectionner un modèle déjà paramétré via le bouton [] présent en haut à droite de la boite de dialogue.
  
• Prévisualiser le fichier à importer via le bouton [] présent en haut à droite de la boite de dialogue.
  

Lorsque le paramétrage de l’import est terminé, cliquez sur le bouton [Exécuter] présent en bas de la boite de dialogue. Comme pour un export, il est possible de sauvegarder le paramétrage réalisé avant exécution via le bouton [].

L’import est alors exécuté immédiatement en tâche de fond.
Lorsqu’il est terminé, un récapitulatif est disponible dans la messagerie interne.

Cas des imports/exports planifiés créés avant la version 10.9 #

Lors de la bascule en version 10.9 de YellowBox CRM, l’ensemble des imports/exports planifiés paramétrés ont fait l’objet d’une migration permettant de générer les processus correspondants.

Le détail des traitements opérés par cette migration est accessible dans la documentation des nouveautés 10.9.