Agent d’import de documents et de données depuis Excel

Présentation générale

Cet outil permet d’importer de manière planifiée des documents processus ou des données du réservoir de données depuis un fichier Excel formaté présent sur le file system de l’instance VDoc.

Cet agent gère :

  • la création
  • la mise à jour (modification d’une ressource existante identifiée par son URI).

Cet agent ne gère pas :

  • la suppression de documents ou de données.

Utilisation

Pour mettre en place cet outil, il faut simplement suivre la procédure suivante :

  • aller dans la section Administration > Planification des agents ;
  • créer un agent en sélectionnant le modèle d’agent Agent d’import de ressources depuis Excel ;
  • aller sur l’onglet Configuration et cliquer sur le bouton Remplacer par la configuration d’origine ;
  • définir les paramètres de la configuration.

Configuration de l’agent

Définition de la configuration
<configuration>
  <input-folder/>
  <delete-excel-after-import/>
</configuration>
Description de la configuration
Balise Description
input-folder Dossier contenant les fichiers Excel à importer.
Précisions :
A l’exécution, l’agent tente d’importer tous les fichiers présents dans ce dossier /!\ ATTENTION y compris les fichiers présents dans les sous-dossiers !
Sous Windows les caractères ‘/’ dans le chemin doivent être remplacés par ‘' (par exemple pour importer les fichiers du dossier Windows “D:\Import-DU-Hermes”, indiquez dans le XML de paramétrage de l’agent la valeur : “D:/Import-DU-Hermes”)
Sous Linux, le chemin sera de la forme “/opt/vdocplatform/contentstore/[votre dossier perso]” (ici pour la plateforme DevOps hébergée chez Visiativ). Le stockage comme sous-dossier de contentstore est la meilleure solution car elle n’a aucun impact lors d’un deploy (contrairement à 1 stockage dans un dossier de custom... qui se retrouve ensuite dans l’ear sous JBoss) et ce dossier est intégré aux sauvegardes.
delete-excel-after-import Précise si le fichier Excel doit être supprimé non après import. La valeur “true” permet de supprimer automatiquement le fichier Excel si l’import s’est terminé avec succès.
Exemple de configuration
<configuration>
<input-folder>C:\Hosted\TNT\data</input-folder>
<delete-excel-after-import>false</delete-excel-after-import>
</configuration>

Paramétrage du fichier Excel d’import

(i) Astuce : plutôt que de créer un fichier Excel d’import de toute pièce, il est fortement conseillé de commencer par configurer puis exécuter l’[[agent d’export de ressources au format Excel»doc:ExportToExcelAgent||rel="__blank"]]. Ainsi vous disposez, à moindre coût, d’un fichier Excel complet et adapté aux ressources à traiter. Cette astuce est encore plus vraie si vous souhaitez mettre à jour des ressources car l’uri d’identification d’une ressource n’est pas toujours facile à constituer.

Avertissement

Ne modifiez pas les 2 premières lignes du fichier Excel d’export car ces lignes d’entête formatent le fichier Excel afin qu’il soit compréhensible par VDoc

Généralités

Importance de l’ordre des onglets et des lignes

Dans le fichier Excel, vous devez impérativement respecter l’ordre des onglets : onglet avec la ressource parente en 1ier puis ensuite les onglets contenant les sous-ressources (tableau dynamique, tableau de sous-processus) eux aussi ordonnés logiquement. En effet l’import traite les onglets dans l’ordre d’affichage dans Excel, si les onglets sont inversés, l’import ne pourra pas par exemple créer les lignes de tableau car il ne trouvera pas le document parent auquel les lignes de tableaux doivent être rattachées.

Notion d’index

Les colonnes de type « INDEX » contiennent un numéro d’ordre unique au sein d’un onglet et permettent d’établir des liens entre les données réparties dans les différents onglets du fichier Excel. Par exemple pour un onglet contenant des données de tableau dynamique :

  • « INDEX » / sys_index.current = 1ère colonne, il s’agit de l’index de la ligne de tableau courante
  • « INDEX » / sys_index.parent = 2ème colonne, il s’agit de l’index de la ressource parente c’est-à-dire de la référence vers le père (document principal) qui figure dans un autre onglet de l’Excel.
  • « INDEX » / sys_index.tab = 3ème colonne, il s’agit du nom de l’onglet dans lequel se trouve l’index parent de la ressource parente. Les index étant uniques par onglet, il faut donc le couple index.parent + index.tab pour référencer la ressource parente.

Contenu de la colonne “sys_definition.uri / RESOURCE_DEFINITION”

Cette colonne sys_definition.uri contient l’URI de destination. Si vous vous effectuez un import sur une application n’ayant pas la même URI, il faudra changer l’URI présente dans cette colonne par l’URI de destination adaptée (version de processus ou table de réservoir de données de destination selon le type d’import). Elle est obligatoire pour chaque ligne du fichier Excel d’import.

Contenu de la colonne “sys_resource.uri / RESOURCE”

Cette colonne (habituellement la 3e colonne du fichier Excel) contient l’uri (sorte d’ID unique) de la ressource VDoc. Deux 2 cas se présentent, la création ou la mise à jour de ressources :

  • si vous souhaitez créer une nouvelle donnée : cette colonne doit être laissée vide ou encore peut être absente du fichier Excel d’import
  • si vous souhaitez mettre à jour une donnée existante : cette colonne doit être renseignée dans le fichier Excel d’import avec une uri valide (uri existante dans votre base VDoc, le plus simple étant de procéder à un export afin d’obtenir cette uri pour toutes les données existantes).

Voir aussi la description plus détaillée du fonctionnement de cette colonne URI ici : https://kit.doc.moovapps.com/fr/vdockitextensions/functionnalities/exportresourcewizard/

Problème connu depuis 12/2016 et toujours vrai en version récente (confirmé par exemple dans la version vdoc.kit-1.8.4 for VDoc15.2.3) :

Lors de l’import Excel vous pouvez obtenir une erreur du type “unable to find systems fields” / “unable to found systems fields”. Ce problème survient lorsqu’on essaye de mettre à jour une ressource mais que celle-ci n’est pas présente (n’existe pas côté serveur VDoc) / colonne sys_resource.uri / RESOURCE renseignée avec une valeur non présente sur le serveur VDoc.

Astuces d’utilisation

Les astuces ci-dessous portent essentiellement sur “comment renseigner le fichier Excel d’import”.

  • Si vous souhaitez créer de nouvelles ressources (données ou documents) : n’oubliez pas de vider la colonne sys_resource.uri de votre fichier Excel comme illustré dans la capture d’écran ci-dessous.

    Capture d&rsquo;écran Capture d&rsquo;écran

    Attention : si la colonne sys_Reference est renseignée dans Excel, elle sera alimentée comme les autres champs lors de l’import et pourra créer une impression de “doublon” si elle présente 2 fois dans le fichier Excel ou si une donnée / document avec cette référence indiquée dans Excel (colonne sys_Reference) existe déjà sur le serveur ! (Rappel : la référence n’étant pas unique dans VDoc, vous pouvez avoir plusieurs ressources différentes portant la même référence !).

  • Il est possible de simplifier grandement le fichier Excel d’import :

    • Seules 2 colonnes systèmes sont obligatoires : sys_definition.uri / RESOURCE_DEFINITION et sys_resource.uri / RESOURCE

    Plus d’informations sur ces colonnes ici

    • L’ordre des colonnes “fonctionnelles” est sans importance dans Excel, faites “pratique” par exemple en reprenant l’ordre d’affichage des champs dans le formulaire.

  • Dans le contexte d’une synchronisation de données avec un ERP : il est conseillé d’utiliser le champ sys_Reference de votre donnée pour stocker la “clef unique” de la donnée ERP (= identifiant ERP utilisé comme clef de synchro VDoc / ERP) ainsi :

    • en cas d’import : il sera facile de renseigner la colonne sys_resource.uri du fichier Excel en fonction de vos besoins (rappel : cette colonne se termine par la sys_Reference VDoc), comme détaillé plus haut :
      • si la colonne est vide : création d’une nouvelle donnée
      • si la colonne est renseignée avec un ID ERP / sys_Reference déjà existant dans VDoc : mise à jour de la donnée.
    • en cas d’export : l’ERP pourra simplement utiliser la colonne sys_Reference.

  • Comment importer des ressources (données d’une table ou documents de processus) différentes liées entre elles ? L’ordre d’import des ressources n’a pas d’importance, vous pouvez donc paramétrer 1 seul agent d’import qui importera toutes vos ressources en une seule exécution (plusieurs fichiers Excel par exemple) et liera les ressources correctement entre elles.