File system importer
Généralités
Conditions préalables
L'outil nécessite l'installation de Java 11 ou d'une version ultérieure sur l'ordinateur.
Installation
Pour installer l'outil de synchronisation, extrayez l'archive FileSystemImporter.zip dans un dossier.
Utilisation
L'outil est utilisé pour synchroniser des contenus provenant de Documentum, de fichiers CSV, de SharePoint ou d'un système de fichiers.
C'est un fichier JAR, appelé en ligne de commande, qui prend un fichier de propriétés comme paramètre (option -config). Le paramètre synchro_mode de ce fichier choisit le mode de traitement : csv, xlsx, filesystem, files ou bulk_import_csv.
L'outil est fourni avec des exemples de fichiers :
- synchronisation CSV (synchro-csv.properties).
- système de fichiers (synchro-fs.properties).
- Excel (synchro-xlsx.properties).
- fichiers choisis un à un (synchro-files.properties).
- import massif par CSV (synchro-bulk-import.properties).
Pour la synchronisation des arborescences de fichiers, suivez ces étapes :
- configurez le serveur qui recevra les messages de synchronisation (settings.json).
- configurez les fichiers de propriétés qui spécifieront les fichiers à synchroniser (synchro-fs.properties).
Configuration du serveur
Selon votre architecture, vous devrez configurer l'outil de synchronisation pour qu'il se connecte à Any. Les réglages s'effectuent dans le fichier settings.json, à l'intérieur du dossier config de l'archive décompressée.
Configuration sur site
Si vous disposez d'une installation sur site, vous devez configurer l'outil de synchronisation pour qu'il se connecte au serveur ActiveMQ de Any qui recevra les messages de synchronisation.
Dans le fichier settings.json, modifiez la partie mdb-messaging pour définir les valeurs en fonction de votre environnement. Un paramètre particulier est l'adresse jms-server-address, où les messages de synchronisation seront publiés.
"mdb-messaging": {
"jms_server_address": "tcp://<ActiveMQ Server/Any>:61616",
[...]
Configuration cloud de Any
Si vous utilisez Any en mode Cloud, le fichier settings.json est déjà configuré pour votre environnement. Si vous devez modifier les paramètres, cela se fera dans la partie aws-messaging du JSON, et plus particulièrement dans la partie sqs.
Envoi par l'API REST
Au lieu de déposer les messages dans une file, l'outil peut envoyer chaque document à l'API REST d'Any. Ce mode s'active dès que rest_url est renseigné dans le fichier de propriétés ; sans cette URL, l'outil utilise la file de messages configurée dans settings.json. Il s'applique aux modes csv, xlsx, filesystem et files.
- rest_url : URL d'Any.
- rest_login : utilisateur ayant le rôle « REST API » (voir l'API REST).
- rest_password : mot de passe, en clair ou chiffré. Un mot de passe chiffré nécessite de lancer l'outil avec l'option
-passkey <clé>. Sans clé, le mot de passe est utilisé tel quel.
Pour chiffrer un mot de passe, exécutez :
java -cp FileSystemImporter-<version>.jar eu.c6.crypto.GetEncryptedPassword -password <mot de passe> -passkey <clé>
Copiez la valeur affichée dans rest_password.
Synchronisation CSV et Excel
Pour la synchronisation CSV ou Excel, procédez comme suit :
- configurez le serveur qui recevra les messages de synchronisation (settings.json).
- configurez le fichier CSV ou Excel qui sera utilisé et les propriétés à synchroniser (synchro-csv.properties ou synchro-xlsx.properties).
Configuration de la synchronisation
Pour ce guide, nous supposerons que le fichier de propriétés utilisé par l'outil de synchronisation est synchro-csv.properties (CSV) ou synchro-xlsx.properties (Excel).
Paramètres :
- message_type : ADD, REPLACE, UPDATE ou REMOVE (à renseigner : pas de valeur par défaut).
- source_name : sera transmis à Any et utilisé par le flux de synchronisation.
- synchro_mode : « csv » pour la synchronisation CSV, « xlsx » pour la synchronisation Excel.
- linked_room_id : ID de la room où le document sera lié statiquement.
- application : nom de l'application à laquelle le document appartient.
- input_queue_name : nom de la file d'attente à utiliser pour envoyer le message de synchronisation.
- file : chemin d'accès au fichier CSV ou Excel contenant les données à synchroniser.
- columns_separator : séparateur entre les colonnes de données (fichiers CSV).
- values_separator : séparateur entre plusieurs valeurs dans une cellule.
- repeating_separator : séparateur entre les valeurs répétitives.
- attr_date : liste des colonnes contenant des dates, séparées par des virgules.
- attr_boolean : liste des colonnes contenant des booléens, séparées par des virgules.
- attr_int : liste des colonnes contenant un entier, séparées par des virgules.
- attr_repeating : liste des colonnes contenant des valeurs répétées, séparées par des virgules.
- date_format : format de date (ex. : MM/jj/aaaa hh:mm:ss).
- root_folder_path : chemin du dossier racine contenant le contenu à importer.
Colonnes CSV et Excel
Voici la liste des colonnes disponibles, qui seront gérées automatiquement par Any :
- object_id : identifiant externe unique de l'objet.
- object_name : nom du contenu.
- root_id : ID externe de l'objet parent (utilisé pour le contrôle de version).
- version : numéro de version de l'objet.
- version_tags : balises de version (répétition).
- relation_child : ID externe d'un enfant lié.
- relation_name : nom de la relation.
- relation_versions : versions de l'enfant (répétition).
Remarque : ces colonnes de relations peuvent contenir plusieurs valeurs, séparées par le values_separator.
- file_path : chemin d'accès du contenu principal par rapport à root_folder_path.
- content_type : type de contenu du contenu principal.
- format_path : chemins de formats supplémentaires, séparés par le values_separator.
- format_content_type : types de contenu des formats supplémentaires, séparés par le values_separator.
- attachment_path : chemins d'attachement supplémentaires, séparés par le values_separator.
- attachment_content_type : types de contenu des pièces jointes, séparés par le values_separator.
- component_id : ID externe du composant package.
- component_versions : versions du composant (répétition).
Remarque : ces colonnes de composants peuvent contenir plusieurs valeurs, séparées par le values_separator.
Toutes les autres colonnes que vous placerez dans le fichier CSV ou Excel seront importées en tant que paramètres et utilisées par le mapping de synchronisation.
Exécution de l'outil de synchronisation
Une fois la configuration de l'outil terminée, exécutez la commande suivante dans un terminal :
java -jar FileSystemImporter-<version>.jar -config synchro-csv.properties
ou, pour un fichier Excel :
java -jar FileSystemImporter-<version>.jar -config synchro-xlsx.properties
L'outil créera un dossier de journaux et mettra les journaux d'exécution à l'intérieur.
Synchronisation d'un système de fichiers
Pour la synchronisation du système de fichiers, procédez comme suit :
- configurez le serveur qui recevra les messages de synchronisation (settings.json).
- configurez le fichier de propriétés qui spécifiera les fichiers à synchroniser (synchro-fs.properties).
Configuration de la synchronisation
Pour ce guide, nous supposerons que le fichier de propriétés utilisé par l'outil de synchronisation est synchro-fs.properties.
Paramètres :
- source_name : sera transmis à Any et utilisé par le flux de synchronisation.
- synchro_mode : « filesystem » pour la synchronisation du système de fichiers.
Batchs
La synchronisation du système de fichiers s'effectue par batchs, chaque batch pouvant avoir des paramètres différents.
Chaque batch doit être défini par ses paramètres de démarrage sous la forme filesystem.(batch_number). Le numéro de batch peut contenir des chiffres, des lettres et un trait de soulignement.
Paramètres disponibles :
- root : dossier racine où l'importation commencera.
- mapping : chemin qui représente la façon dont les chemins d'accès aux fichiers importés seront utilisés pour mapper les métadonnées (voir les exemples).
- include : syntaxe de type « glob » pour définir quels fichiers seront envoyés (voir les exemples).
- exclude : syntaxe de type « glob » pour définir quels fichiers ne seront PAS envoyés (voir les exemples).
- room : room à laquelle le contenu est lié statiquement.
- operation : ADD ou REPLACE, à renseigner pour chaque batch.
Exemples :
filesystem.0001.root=./my_root_folder
filesystem.0001.mapping=${country}/${product}/
filesystem.0001.include=**/*.docx;**/*.doc;**/*.pdf;
filesystem.0001.exclude=**/BRAZIL/**;
filesystem.0001.room=my_room
filesystem.0001.operation=REPLACE
Dans cet exemple, le contenu du dossier « my_root_folder » sera importé.
Le nom du premier sous-dossier sera mappé à la métadonnée « country ».
Le nom du deuxième sous-dossier sera mappé à la métadonnée « product ».
Le mapping n'est effectué que pour les valeurs entourées de ${}. Les autres valeurs sont ignorées.
La règle d'inclusion spécifie que seuls les fichiers docx, doc et pdf seront envoyés.
La règle d'exclusion spécifie que tout fichier ayant un sous-dossier nommé BRAZIL sera exclu.
Pour chaque fichier, Any reçoit aussi les propriétés file_name, file_ext, file_folder_(n) (nom de chaque dossier du chemin) et file_folders (liste de ces dossiers), utilisables par le mapping de synchronisation. Le chemin du fichier sert d'ID externe d'objet et de racine (sync.object_id et sync.root_id).
Exécution de l'outil de synchronisation
Une fois la configuration de l'outil terminée, exécutez la commande suivante dans un terminal :
java -jar FileSystemImporter-<version>.jar -config synchro-fs.properties
L'outil créera un dossier de journaux et mettra les journaux d'exécution à l'intérieur.
Synchronisation de fichiers
Le mode files envoie à Any des fichiers choisis un à un, avec un message par fichier. Les métadonnées sont décrites dans le fichier de propriétés et sont les mêmes pour tous les fichiers. Pour cette synchronisation, procédez comme suit :
- configurez le serveur qui recevra les messages de synchronisation (settings.json).
- configurez le fichier de propriétés (synchro-files.properties).
Configuration de la synchronisation
Paramètres :
- synchro_mode : « files » pour la synchronisation de fichiers.
- message_type : opération appliquée (ADD, REPLACE ou UPDATE, voir la Sync API). Par défaut : ADD.
- root_id : ID de racine externe (
sync.root_id). Par défaut, le chemin du fichier. - object_id : ID d'objet externe (
sync.object_id). Par défaut, la version. - version : version du contenu (par défaut : 0.1).
- source_name : par défaut
filesystem.<machine>.<utilisateur>. - sent_by : expéditeur affiché dans Any.
- room : room à laquelle les fichiers sont liés statiquement. Sans valeur, et si l'outil est lancé sans fichier en paramètre, une fenêtre demande la room.
- application, input_queue_name : comme pour la synchronisation CSV. Sans file indiquée, la file d'entrée (
input) est utilisée. - create_as_new_object : true pour que chaque version reste un document indépendant, sans reconstruction de l'arbre des versions.
- ignore_existing : true pour toujours créer le document, même s'il existe déjà avec les mêmes identifiants.
- create_as_external_content : true pour ne pas envoyer le fichier : Any référence le contenu à son emplacement d'origine.
- create_package : true pour créer, après les fichiers, un package dont les composants sont tous les fichiers envoyés (dernière version).
- task_type, task_recipients[n] : rattachent une tâche aux contenus (voir « Tâche » dans la Sync API).
- properties.(nom) : métadonnée envoyée avec chaque fichier. Une valeur multiple s'écrit avec des indices (
properties.authors[0],properties.authors[1]).
Les jokers ${FILENAME}, ${ROOT_ID}, ${OBJECT_ID} et ${VERSION} sont remplacés à la création de chaque message ; ${RANDOM_UUID} génère un identifiant aléatoire dans root_id et object_id. Le numéro de batch est généré automatiquement.
Exécution de l'outil de synchronisation
Passez les fichiers à envoyer en paramètres :
java -jar FileSystemImporter-<version>.jar -config synchro-files.properties <fichier1> <fichier2>
Sans fichier en paramètre, une fenêtre de sélection de fichiers s'ouvre. L'outil créera un dossier de journaux et mettra les journaux d'exécution à l'intérieur.
Import massif par CSV
L'outil d'import massif est utilisé lorsque vous voulez effectuer une reprise de gros volumes de données existantes provenant d'un autre système, pour les injecter dans la base Any. Ce processus a été conçu pour maximiser la vitesse d'import et nécessite une préparation préalable des données afin qu'elles soient compatibles avec la configuration cible (aspects et listes de données). L'outil ne permet que de créer de nouveaux documents : il ne peut pas être utilisé pour mettre à jour ou supprimer des données. L'import s'effectue via des messages postés dans une file d'attente gérée par le serveur de messages de Any. Attention : afin de ne pas saturer le serveur de messages avec les contenus binaires, le traitement des fichiers doit être effectué manuellement, via une copie des fichiers par les scripts fournis par l'outil ou par un dossier partagé.
Pour plus de détails, veuillez consulter le guide « BulkImporter – Guide d'utilisation ».
Pour configurer l'import massif via un CSV, procédez comme suit :
- configurez le serveur qui recevra les messages de synchronisation (settings.json).
- exportez votre configuration Any dans un dossier local (ex. : ./config).
- configurez le fichier CSV qui permet de gérer le paramétrage de l'import massif (synchro-bulk-import.properties).
Configuration
Pour ce guide, nous supposerons que le fichier de propriétés utilisé par l'outil de synchronisation est synchro-bulk-import.properties.
Paramètres :
- source_name : sera transmis à Any et utilisé comme information.
- batch_number : nom du batch transmis à Any et utilisé comme information. Si le nom n'est pas spécifié, ce sera le nom du fichier CSV suivi de la date en millisecondes.
- synchro_mode : « bulk_import_csv » pour l'import massif par CSV.
- linked_room_id : ID de la room où le document sera lié statiquement.
- application : nom de l'application à laquelle le document appartient.
- input_queue_name : nom de la file d'attente à utiliser pour envoyer le message de synchronisation (par défaut : « bulk_import »).
- file : chemin d'accès au fichier CSV contenant les données à importer.
- columns_separator : séparateur entre les colonnes de données.
- repeating_separator : séparateur entre les valeurs multiples.
- values_separator : séparateur entre plusieurs valeurs dans une cellule.
- root_folder_path : chemin du dossier racine contenant les contenus à importer.
- date_format : format de date (ex. : MM/jj/aaaa hh:mm:ss).
- config_any : chemin vers le fichier ZIP de l'export de configuration de Any.
- detect_existing_root : tente de détecter les racines existantes dans Any pour y rattacher les nouvelles versions, sur la base de l'ID de racine de synchronisation.
- copy_on_consume : true/false, détermine la stratégie de copie des fichiers. Si « true », le fichier est copié lors de l'import. Dans ce cas, vos fichiers sources doivent être accessibles par le serveur de messages.
- script_folder_path : chemin valide vers le dossier dans lequel seront créés les scripts de copie des fichiers sources vers le système de fichiers de Any.
- script_any_root_folder_path : chemin racine des fichiers de Any, tel que configuré dans le fichier settings.json du serveur de messages.
Colonnes CSV
Voici la liste des colonnes CSV disponibles, qui seront gérées automatiquement par Any :
- object_id : identifiant externe unique de l'objet.
- name : nom du contenu.
- root_id : ID externe de l'objet parent (utilisé pour le contrôle de version).
- version : numéro de version de l'objet.
- version_tags : balises de version supplémentaires (répétition).
- file_path : chemin d'accès du contenu principal par rapport à root_folder_path.
- content_type : type de contenu du contenu principal.
- format_path : chemins de formats supplémentaires, séparés par le values_separator.
- format_content_type : types de contenu des formats supplémentaires, séparés par le values_separator.
- replace_path : permet de remplacer le début du chemin du fichier cible par un autre chemin.
- (aspect.metadata) : métadonnée à remplir. La métadonnée doit exister dans la base Any et dans l'archive de configuration exportée. Dans le cas de métadonnées avec une correspondance de valeur, vous devez indiquer le code de la valeur.
Toutes les colonnes aspect.metadata que vous placerez dans le fichier CSV seront validées à l'aide de la configuration disponible. Ces valeurs doivent correspondre aux valeurs finales et ne seront pas transformées.
Par défaut, un contenu Any est toujours « latest », sauf si vous avez plusieurs contenus partageant le même « root_id ». Dans ce cas, seul le dernier (de haut en bas dans le fichier) sera le « latest ».
Exécution de l'import massif par synchronisation
Une fois la configuration de l'outil terminée, exécutez la commande suivante dans un terminal :
java -jar FileSystemImporter-<version>.jar -config synchro-bulk-import.properties
L'outil créera un dossier de journaux et y placera les journaux d'exécution. Des fichiers de scripts permettant de copier les fichiers binaires correspondant aux contenus importés seront créés dans le dossier de scripts.
Une fois l'import terminé, vous devez finaliser les traitements avec le job JobBulkImportPostActions. Voir le guide « BulkImporter – Guide d'utilisation » pour plus de détails.