Aller à : navigation, rechercher

Maarch AutoImport/Guide d'installation et d'exploitation

Présentation

Introduction

D’une utilisation simple et légère, Maarch AutoImport permet d’effectuer une importation en masse de documents dans la base de données Maarch et le DocServer.

La version 3.3 fonctionne avec toutes les versions de Maarch à partir de la version 1.4 (et Maarch Letterbox 2.9, ancienne version de l'application).

Nous avons ajouté une collection de factures d'exemples qui viennent s'intégrer naturellement dans la démonstration de Maarch.

Fonctionnement

Maarch AutoImport scanne l’intégralité des documents désirés pour l’importation.

Pour effectuer une indexation, le fichier doit être lié avec un fichier XML de même nom. Ce dernier contient les informations nécessaires au référencement du document (description, statut, date de création, collection documentaire, etc…).

AutoImport.png

SGBD supportés

Maarch autoImport fonctionne de base avec le SGBD PostgresSQL (par défaut utilisé par l'application Maarch 1.4).

Mais il est également compatible avec :

  • Oracle
  • SQLServer

Nous pouvons développer d'autres connecteurs sur demande.

Installation et configuration

Pré-requis

Maarch AutoImport nécessite :

  • console PHP (5.3 au minimum)
  • Maarch 1.4 configurée
  • Le DocServer doit être créé et lié à la base de données

Configuration de la base de données Maarch

Vous trouverez dans la table parameters une occurrence work_batch_autoimport_id.

Lors de la première utilisation de Maarch AutoImport, il est nécessaire de passer sa valeur à 0. (Ce qui devrait déjà être le cas)

AutoImportworkbatch.png

Installation de Maarch AutoImport

Vous pouvez récupérer les sources de l'autoimport à partir du lien

  svn checkout http://svn.maarch.org/autoimport/branches/3.3

Installation des fichiers Maarch AutoImport

Aucune procédure d’installation n’est demandée pour cette application.

Il suffit juste de modifier les différents fichiers de configuration.

AutoImportFolder.png

Configuration de l’application

Maarch AutoImport possède 2 fichiers de configuration :

  • un fichier de connexion base de données (config_***.xml)
  • un fichier de mapping (mapping_***.xml)


Configuration du config_***.xml

Il permet de se connecter à la base de données ou encore d’envoyer les fichiers vers le DocServer de Maarch.

Plusieurs fichier de configuration vous sont proposés :

  • config_documents.xml => importation dans la collection cold (facture)
  • config_entreprise_cold.xml => autre importation dans la collection cold (facture)
  • config_entreprise_scan.xml => importation dans la collection courrier
  • config_folders.xml => importation dans la collection courrier avec création de dossiers
  • config_invoices.xml => importation spécifique
  • config_invoices_without_xml.xml => importation spécifique (sans xml associés aux documents)
  • config_letterbox.xml => importation pour les anciennes version de Maarch (letterbox)
  • res_mail.xml => non utilisé

(utilisez config_entreprise_scan.xml pour une première utilisation)

Chaque balise est une propriété de configuration. Les valeurs entre ces dernières sont personnalisables.


Description du fichier de configuration :

<CONFIG_NAME> : nom du paramétrage de l'AutoImport.
<MAPPING_FILE> : adresse physique du fichier de mapping.
<SCAN_IMPORT_DIRECTORY> : adresse physique du répertoire à scanner pour l’importation des fichiers. (E:\IMPORTATION\)
<LOCATION> : adresse Ip du serveur de la base de données.
<DATABASE_PORT> : port de la base de données Maarch.
<DATABASE> : nom de la base de données Maarch.
<DATABASETYPE> : type de la base de données Maarch (postgresql, mysql, oracle, mssql).
<DATABASEWORKSPACE> : workspace de la base de données Maarch.
<USER_NAME> : nom de l’utilisateur permettant une connexion à la base de données.
<PASSWORD> : mot de passe de connexion.
<TABLE_NAME> : nom de la table de la base de données où les fichiers doivent être référencés.
<INSERT_MODE> : mettre true si mode d'insertion SQL insert.
<DOCSERVER_NAME> : nom du DocServer.
<DATE_TIME_FORMAT> : format de la date attendu par la base de données.
<AUTO_IMPORT_DIRECTORY> : dossier physique du script Maarch AutoImport. (ex :E:\Maarch_auto_import_php\)
<WITHOUT_XML> : mettre true si documents sans index XML associé.
<BACKUP_BATCH> : mettre true si vous souhaitez faire un backup du lot d'import.
<EXCLUDE_EXISTING_DOCS> : mettre true si vous souhaitez exclure du lot les fichiers déjà présent dans Maarch (fingerprint control).
<EXCLUDE_EXISTING_DOCS_FOLDER> : nom du dossier des fichiers exclus.
<CONTROL_COMPLETE_FILES> : mettre true si vous souhaitez faire un contrôle du lot d'import.
<CREATE_FOLDERS> : mettre true si vous souhaitez importer des dossiers.
<FOLDERS_TABLE_NAME> : nom de la table des dossiers Maarch.
<FOLDERS_MAPPING_FILE> : adresse physique du fichier de mapping des dossiers.

Configuration du mapping_file.xml

La configuration de ce fichier est impérative pour effectuer l’indexation.

Ce fichier permet d'injecter les méta-données "de base" d'un document.


Chaque champ devant être indexé doit être compris dans une balise XML :

  • <COLUMN> Le nom du champ de la table de la base de données dans lequel sont envoyées les informations.
  • <VALUE> La méta-données en question (peut être une constante délimitée par un simple quote. Positionner <FORMAT> à DATE pour forcer la prise en compte du champ DATE_TIME_FORMAT du config.xml pour les champs date.


Exemple de fichier mapping_file.xml configuré :

 <ROOT>
   <MAPPING_FILE>
     <ELEMENT>
       <COLUMN>DOC_DATE</COLUMN>
       <VALUE>DATE_DU_DOCUMENT </VALUE>
       <FORMAT>DATE</FORMAT>
     </ELEMENT>
     <ELEMENT>
       <COLUMN>DESCRIPTION</COLUMN>
       <VALUE>MONTANT</VALUE>
     </ELEMENT>				
     <ELEMENT>
       <COLUMN>TYPE_ID</COLUMN>
       <VALUE>TYPE_ID</VALUE>
     </ELEMENT>
     <ELEMENT>
       <COLUMN>TITLE</COLUMN>
       <VALUE>FACTURE</VALUE>
     </ELEMENT>
     <ELEMENT>
       <COLUMN>IDENTIFIER</COLUMN>
       <VALUE>CLIENT</VALUE>
     </ELEMENT>
     <ELEMENT>
       <COLUMN>CUSTOM_T4</COLUMN>
       <VALUE>ADRESSE</VALUE>
     </ELEMENT>	
     <ELEMENT>
       <COLUMN>STATUS</COLUMN>
       <VALUE>'QUAL'</VALUE>
     </ELEMENT>	
   </MAPPING_FILE>
 </ROOT>

Les <VALUE> qui ne sont pas défini entre simple quote sont des variables se trouvant dans les fichier xml associés aux documents. (voir rubrique suivante)

En effet, il est possible associer pour chaque document un fichier xml avec les informations complètes de celui-ci (<WITHOUT_XML> de config_***.xml à true).


Autrement, il est possible d'importer le document sans fichier xml associé. Les méta-données injectés ne seront que ceux du fichier de mapping précédemment configuré.

Il faudra, par la suite, compléter les informations des documents importés dans l'application.

Description des fichiers XML comprenant les informations des documents

Pour effectuer l’indexation d’un document dans Maarch, les informations d’indexation peuvent être liées dans un autre fichier ne compromettant pas le fichier original. Le fichier comprenant les différentes propriétés d’indexation est un fichier XML portant le même nom que le fichier original.

Les informations devant être indexées dans les champs désirés sont comprises entre des balises, ayant le même nom que la valeur des balises <VALUE> du fichier mapping_***.xml

Exemple de fichier XML de propriété :

 <?xml version='1.0' encoding='iso-8859-1'?>
 <ROOT>
   <DATE_DU_DOCUMENT>2007-01-11 00:00:00</ DATE_DU_DOCUMENT >
   <TYPE_ID>Customer Invoice</TYPE_ID>
   <FACTURE>ACME F-003</FACTURE>
   <CLIENT>ACCOVA RADIATEURS</CLIENT>
   <ADRESSE>7 rue Jean Mermoz</ADRESSE>
   <CP>91080</CP>
   <VILLE>COURCOURONNES</VILLE>
   <MONTANT>803,71</MONTANT>
 </ROOT>

Execution de l'application

Lorsque le fichier config.xml et le fichier mapping_file.xml sont correctement configurés, Maarch AutoImport peut être exécuté pour injecter les documents au sein de Maarch.

Maarch AutoImport se lance par l’intermédiaire d’un interpréteur de commande.


AutoImport006.png

Pour cela, cliquez, via le menu démarrer sur la commande « Exécuter ». Dans la fenêtre d’exécution, saisir cmd puis validez.

Il est dans un premier temps nécessaire d’ouvrir l’interpréteur de commande PHP. Pour cela, il faut se rendre dans le répertoire PHP.

Indices de pilotages DOS : Emplacement par défaut de PHP 5.0 :

 cd « C:\xampp\php\php.exe »

Une fois dans le répertoire de l’interpréteur PHP, il ne reste qu’à lancer ce dernier, accompagné du fichier à exécuter ainsi que du fichier de configuration :

 php [emplacement de l’application] [fichier de configuration]

Exemple de ligne de commande pour lancer l’importation en masse avec le fichier de configuration standard :

 C:\xampp\php\php.exe C:\autoimport\maarch_autoimport\maarch_auto_import.php  C:\autoimport\maarch_autoimport\config.xml 

Une fois la commande validée, l’interpréteur PHP lance le script demandé. Maarch AutoImport est alors lancé.

Les différentes actions exécutées durant le processus d’importation sont stockées dans un fichier de traçage événementiel. Ce dernier se trouve dans le répertoire de Maarch AutoImport et porte le nom de log.txt. Ce document est écrasé après chaque nouvelle exécution du script.

Si l’application rencontre une erreur durant le processus, cette dernière est immédiatement stoppée et l’indexation n’a pas lieu.

un fichier SQL est créé dans le répertoire de l’application. Ce dernier comporte la requête à exécuter dans la base de données pour l’indexation des documents.

Lorsque les documents ont été correctement insérés dans Maarch, le dossier d’importation déplace les documents vers le sous répertoire /backup/. Si une erreur est signalée à l’application durant l’importation, les documents sont envoyés vers le sous-répertoire /failed/.

Spécifications techniques

Cheminement des processus

AutoImport008.jpg

Verrouillage de l’application

Lorsque l’application est en cours d’exécution, cette dernière dépose dans son propre répertoire un fichier nommé AutoImport.lck qui est supprimé lorsque l’exécution se termine.

Ce fichier a pour but d’éviter un traitement erroné des documents. Une seule instance de Maarch AutoImport peut être lancée à la fois.

Fichier de suivi des événements

Dans le répertoire de l’application, vous trouverez un fichier nommé log.txt. Ce dernier trace les différentes évolutions du script durant son lancement. Ce journal vous permet suivre les actions effectuées par l’AutoImport. Ce fichier ce réinitialise à chaque nouveau lancement du script.

Lorsque qu’une erreur est signalée, cette dernière est inscrite dans le fichier journal, ainsi que son code permettant de vous guider pour la résolution du problème.

Signification des codes erreur

Les codes 'erreur' les plus courants :

  • 2 : Espace du DocServer insuffisant pour importer les fichiers.

Votre DocServer est défini comme rempli. Vous ne pouvez plus insérer de nouveaux documents sauf en augmentant la taille limite via la table de la base de données « docserver ». Attention, il est nécessaire de s’assurer que le support de stockage contient la place nécessaire pour de nouvelles indexations.

  • 3 : Copie des fichiers vers le DocServer Impossible.

Maarch AutoImport ne peut envoyer les nouveaux fichiers vers le DocServer. Les causes peuvent être nombreuses, mais il est judicieux de vérifier que le fichier n’a pas été supprimé ou déplacé durant le processus d’importation.
La location physique du DocServer a peut-être été mal définie. Il est important de rappeler que si vous utilisez un système de type Windows, le caractère « \ » à besoin d’être dédoublé « \\ » pour être pris en compte par Php.

  • 4 : Lancement de la requête SQL impossible.

Si la requête SQL ne peut être lancée, il est nécessaire de vérifier le fichier de mapping Mapping_file.xml ainsi que son contenu. Les champs indiqués entre les balises sont peut-être inexistants soit dans la base ou dans les fichiers d’index XML.

  • 5 : Erreur sur la liaison entre le document et son fichier d’index XML.

Ce code erreur peut subvenir aussi si le document n’est pas lié avec un fichier XML ou que ce dernier est illisible.

  • 6 : index XML non trouvé.
  • 7 : Déplacement des documents à importer vers le sous répertoire /Failed/ impossible.

Cette erreur signifie que l’application ne peut poser les documents à importer vers le répertoire de contrôle. Dans ce cas, il peut s’avérer judicieux de vérifier que l’adresse physique du DocServer est bien déclarée dans la base de données.

  • 8 : Impossible de créer le fichier de lock.
  • 9 : Error dans le format de date du fichier de mapping.
  • 10 : Error dans le format de date des fichiers d'index.
  • 11 : Le numéro de batch de lancement de l'autoimport est déjà utilisé.
  • 12 : Le chemin physique du docserver n'existe pas.
  • Dans le cas des erreurs #2, #4, #7, #8, #9, #10, #11, #12 tout le lot est déplacé dans le répertoire failed.

Organisation des fichiers dans le DocServer

Seuls les documents sont envoyés vers le DocServer. Les fichiers XML sont détruits une fois injectés dans la base de données. Dans le répertoire du doc serveur, le tri des documents se fait au premier niveau par année et au second niveau par mois. Le troisième niveau est le numéro du lot de travail de l’AutoImport. Ce numéro peut se modifier dans la base de données via la table parameters mais est fortement déconseillé lorsque des documents sont indexés. Pour organiser les documents dans le DocServer, ces derniers sont renommés et classés par répertoire. Tous les mille documents, un nouveau répertoire est créée pour accueillir le prochain millier de fichier.

Description des fonctions principales

  • Scan : permet de parcourir les différents fichiers dans le répertoire d’importation et vérifie le nombre de documents en cours de traitement.
  • GetWorkBatchAutoImport : relève le numéro de travail du dernier lot de Maarch AutoImport.
  • MoveFiles : déplace les fichiers vers le sous répertoire nécessaire en fonction de la finalisation du processus.
  • UpdateWorkingBatchAutoImport : met à jour le numéro de travail du lot de Maarch AutoImport.
  • SearchImageOfXml : vérifie la présence d’un fichier lié au XML.
  • ExtractFileExt : récupère l’extension du fichier en cours de traitement.
  • ExtractFileName : récupère seulement le nom du fichier en y supprimant l’extension.
  • DocServerSize_init : récupère la taille actuelle du DocServer.
  • DocServerSize_update : met à jour la taille du DocServer.
  • Checking_available_space : vérifie si l’espace demandée pour l’importation est disponible dans le DocServer.
  • buildDirectory : indexe les fichiers désirés au sein du DocServer.
  • Function_log : créée un fichier retraçant les différents évènements ayant eu lieu lors de l’exécution du script.
  • WriteInSqlFile : inscrit dans un fichier les informations des différents XML à importer dans la base de données.
  • BuildSqlQuery : scanne les différents fichiers XML et construit la requête SQL nécessaire. Cette dernière est ensuite écrite dans un fichier via la fonction « WriteInSqlFile ».