De Maarch // Wiki.

Sommaire 1 Présentation 1.1 Introduction 1.2 Fonctionnement 1.3 Limitations actuelles 2 Installation et configuration 2.1 Pré-requis 2.2 Configuration de la base de données Maarch 2.3 Installation de Maarch AutoImport 2.3.1 Installation des fichiers Maarch AutoImport 2.3.2 Configuration de l’application 2.3.2.1 Configuration du config.xml 2.3.2.2 Configuration du mapping_file.xml 2.3.3 Description des fichiers XML comprenant les informations des documents 3 Execution de l'application 4 Spécifications techniques 4.1 Cheminement des processus 4.2 Verrouillage de l’application 4.3 Fichier de suivi des événements 4.4 Signification des codes erreur 4.5 Organisation des fichiers dans le DocServer 5 Description des fonctions principales

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.2 fonctionne avec Maarch Entreprise 1.2 et Maarch Letterbox 2.9. Nous avons ajouté une collection de factures d'exemples qui viennent s'intégrer naturellement dans la démonstration de Maarch Entreprise.

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…).

Limitations actuelles

• Pour le moment, Maarch autoImport fonctionne uniquement avec des bases de données MySQL, PostgreSQL, Oracle et SQLServer. Nous pouvons développer d'autres connecteurs sur demande.

Installation et configuration

Pré-requis

Maarch AutoImport nécessite l’installation d’une console PHP 5.3 au minimum pour exécuter le script. L’application Maarch doit être préalablement configurée. De même, le DocServer doit être créé et lié à la base de données.

Configuration de la base de données Maarch

Il est nécessaire d’ajuster la taille limite autorisée du DocServer dans la base de données. Dans le cas ou la taille limite est dépassée, l’importation ne sera pas autorisée.

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.

Installation de Maarch AutoImport

Installation des fichiers Maarch AutoImport

Aucune procédure d’installation n’est demandée pour cette application. Seuls les différents fichiers de Maarch AutoImport doivent être déplacés dans un répertoire crée par l’utilisateur. Il suffit juste de modifier les différents fichiers de configuration.

Configuration de l’application

Pour configurer Maarch AutoImport, il faut éditer le fichier config.xml. Ce dernier comporte les informations nécessaires pour la connexion à la base de données et à l’importation des fichiers vers le DocServer. Le mapping_file.xml est le fichier de liaison entre les différents fichiers XML et la base de données. Ci-dessous une explication détaillée de chacun de ces fichiers.

Configuration du config.xml

config.xml est le fichier de configuration de Maarch AutoImport. il permet de se connecter à la base de données ou encore d’envoyer les fichiers vers le DocServer de Maarch.

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

Le mapping_file est le fichier permettant d’indexer les propriétés dans les champs désirés de la base de données. La configuration de ce fichier est impérative pour effectuer l’indexation.

Chaque champ devant être indexé doit être compris dans une balise XML : la balise <ELEMENT>. Cette dernière comporte deux sous balises, la balise <COLUMN> ainsi que la balise <VALUE>.

Le nom du champ de la table de la base de données dans lequel sont envoyées les informations est à placer dans la balise <COLUMN>.

Le nom de la balise des fichiers XML lié pour chaque fichier est à placer dans la balise <VALUE>.

Nouveauté : <VALUE> 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>'NEW'</VALUE>
     </ELEMENT>	
   </MAPPING_FILE>
 </ROOT>

Description des fichiers XML comprenant les informations des documents

Pour effectuer l’indexation d’un document dans Maarch, les informations d’indexation doivent ê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_file.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.

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

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 Â».