Différence entre versions

Version du 3 mai 2019 à 13:29

Sommaire

1 Introduction
2 Pré-requis
3 Installation
4 Utilisation

Introduction

Cette documentation décrit la mise en oeuvre du script d'export en masse des documents archivés par l'outil Mapout / M-Storage.

Il s'agit d'un script php, lancé en ligne de commande, avec diverses options permettant de générer des fichiers PDF accompagnés ou non d'un fichier d'index xml.

Pré-requis

L'extraction tourne exclusivement sur la plateforme Windows sur laquelle est installée Mapout / M-Storage.

L'extraction des documents étant réalisée à partir des informations contenues dans la base de données MySQL de l'application Mapweb / M-Storage Web, il sera nécessaire, si cela n'est pas déjà le cas, d'installer M-Storage Web au préalable, puis de lancer la reconstruction des bases et index de chaque répertoire d'archive devant être exportés. Pour cette étape, se reporte aux manuels d'installation et d'utilisation de Mapweb / M-Storage Web.

MapWeb / M-Storage Web requière :

Apache 2.2 ou 2.4
MySQL version 5.1 minimum

Installation

Le script est fourni sous la forme d'un package comprenant les modules php ainsi que php 7.1.8 pour Windows.

1 - Décompresser le package et copier le dossier "MStorageExport" dans le dossier "MapWebFiles" de Apache.

Exemple : C:\Program files\Apache Software Foundation\Apache2.2\htdocs\MapWebFiles\MStorageExport

2- Ajouter un paramètre avec le chemin de la log dans le fichier de configuration de MapWeb / M-Storage Web

Emplacement par défaut : C:\Mapping\Apache Software Foundation\Apache2.2\htdocs\MapWebFiles\custom\config.ini

Ajouter la section suivante, en spécifiant l'emplacement désiré pour le fichier de log :

[debug]
log_file_path = "c:/Mapping/exporter.log"

Utilisation

1 - Avant de lancer la première extraction de documents, il est nécessaire de récupérer les informations suivantes permettant de construire la requête

L'emplacement du programme Mapout.exe ou M-storage.exe
L'emplacement du dossier d'archives à exporter
Le nom des index et des métadonnées utilisées comme filtres et de critères de rupture

2 - Ouvrir une invite de commande (cmd) en tant qu'administrateur et se positionner sur le dossier MapWebFiles :

cd "C:\Program files\Apache Software Foundation\Apache2.2\htdocs\MapWebFiles"

3 - Pour obtenir de l'aide en ligne, saisir la commande suivante

php718\php help.php

4 - Commande de base de l'extraction

php718\php index.php

Paramètres obligatoires

--archive : Emplacement du dossier d'archives à exporter (exemple : D:\Archives\Factures). Il s'agit d'un dossier contenant divers fichiers dont Spool.cpr et Passwd.txt
--dest : Destination des documents à extraire. Il s'agit du chemin complet du fichier PDF à créer, sans l'extension. Si les dossiers spécifiés n'existent pas, ils seront créés automatiquement. Le chemin peut contenir des valeurs de méta données (entre chevrons <xxxx> ) et d'index (entre doubles crochets [[c_xxxxx]] ).
--pgm : Chemin complet du programme M-Storage.exe ou Mapout.exe (selon la version installée)
--action : Action du script
- --action="getCommands" : création de fichiers txt avec la commande M-Storage.exe ou Mapout.exe permettant de créer le fichier PDF. Cette option permet de tester la commande rapidement sans créer les fichiers PDF
- --action="generate" : génération des fichiers PDF

Exemple de commande simple :

php718\php index.php --archive="D:\Archives\Factures" --dest="D:\Export Archives\<NomUser>\[[c_numfac]]_[[c_numcli]]" --pgm="C:\Mapping\M-Storage\m-storage.exe" --action="getCommands"

Paramètres facultatifs

--indexfile : si présent, chaque fichier PDF sera accompagné d'un fichier d'index XML portant le même nom
--xsl : chemin d'un fichier xsl permettant de personnaliser le schéma du fichier xml afin de le rendre compatible avec un outil de GED tiers. La présence de ce paramètre active la transformation XSLT. Exemple : --xsl="C:\Mapping\Storage_Alfresco.xsl"
--rupt : index de rupture, permettant de générer plusieurs PDF à partir d'un même spool d'impression. Par exemple, si les archives contiennent des spools d'impression multi-factures, il est possible, en spécifiant l'index du numéro de facture dans le paramètre --rupt, de générer un pdf par facture et non un pdf pour le spool complet. Il est possible d'avoir plusieurs ocurences de ce paramètre pour que la rupture se fasse sur plusieurs index différents. Exemple : --rupt="c_numfac"
--nextpage : lors de l'utilisation d'un ou plusieurs index de ruptures, il est possible que certaines pages ne comportent pas de valeur pour ces index, notamment parce que l'un des index en question n'est présent que sur la première page de chaque document. Dans ce cas, si le paramètre --nextpage est présent, les pages suivantes ne comportant pas de valeur seront incluses dans le document PDF généré.
--filter_XXXXX : divers paramètres de filtres, sur les méta données et sur les index sont possible
- Usage : --filter_XXXXXX="clé=valeur"
- Liste des différents types de filtres
  - -- filtermeta_egal : filtre de type la méta donnée est égale à la valeur
  - -- filtermeta_contains : filtre de type la méta donnée contient la valeur
  - -- filtermeta_begin : filtre de type la méta donnée commence par la valeur
  - -- filterindex_egal : filtre de type l'index est égal à la valeur
  - -- filterindex_contains : filtre de type l'index contient la valeur
  - -- filterindex_begin : filtre de type l'index commence par la valeur
    Exemple : --filterindex_egal="c_site=Paris" --filtermeta_begin="NomSpool=S2016"
- La liste des index disponibles dépend de chaque archive. Cette liste est disponible via la table "criteres" de la base MySql. Tous les index doivent être spécifiés avec leur préfixe "c_".
- La liste des méta données est quant à elle figée. Il s'agit des colonnes de la table "spools" de la base MySQL : Attention : sensibles à la casse. Il est courant que certaines de ces méta données soient détournées pour contenir des données "métier", surtout pour les archives issues de Mapping Windows et Unix/Linux.
  - NomSpool : SPOOLNAME au format "Saaaammjjhhmmssxxxxxxxxx". Cette donnée étant indexée, elle convient très bien à une extraction par période, par exemple avec le paramètre --filtermeta_begin="NomSpool=S201706" pour extraire les documents de juin 2017.
  - DateDuSpoolFichier : DATE au format "aaaammjj"
  - NomTravail : JOBNAME
  - NomUser : USERNAME
  - NumeroJob
  - FichierSpool
  - NumeroSpool
  - OUTQ : OUTQ
  - BiliothequeOUTQ
  - Reference : USERDATA
  - Format : FORMAT MapDraw / M-Designer
  - ProgrammeEdition : PROG
  - BibProgrammeEdition
  - Critere1
  - Critere2
  - Critere3
  - Critere4

Exemple de commande complexe :

php718\php index.php --action="generate" --archive="D:\Archives\012018" --filtermeta_egal="Format=FACTURE" --filterindex_contains="c_nomcli=EXEMPLE" --filtermeta_begin="c_date=20180101" --rupt="c_nomcli" --nextpage --indexfile --dest="D:\Export\[[c_date]]\[[c_nomcli]]_<NomSpool>.pdf" --pgm="D:\Mapping\M-storage\M-storage.exe"

@@ Ligne 40 : / Ligne 40 : @@
 *Le nom des index et des métadonnées utilisées comme filtres et de critères de rupture <br />
-'''2 - Ouvrir une invite de commande (cmd) en tant qu'administrateur.'''
+'''2 - Ouvrir une invite de commande (cmd) en tant qu'administrateur et se positionner sur le dossier MapWebFiles :'''
-<br />
-'''3 - Se positionner sur le dossier MapWebFiles :'''
   cd "C:\Program files\Apache Software Foundation\Apache2.2\htdocs\MapWebFiles"
 <br />
-'''4 - Pour obtenir de l'aide en ligne, saisir la commande suivante'''
+'''3 - Pour obtenir de l'aide en ligne, saisir la commande suivante'''
 <code>php718\php help.php</code>
@@ Ligne 54 : / Ligne 50 : @@
 <br />
-'''5 - Commande de base de l'extraction'''
+'''4 - Commande de base de l'extraction'''
 <code>php718\php index.php</code>
-'''6 - Paramètres obligatoires'''
+'''Paramètres obligatoires'''
 *'''''--archive''''' : Emplacement du dossier d'archives à exporter (exemple : <code>D:\Archives\Factures</code>). Il s'agit d'un dossier contenant divers fichiers dont ''Spool.cpr'' et ''Passwd.txt'' <br />
-*'''''--dest''''' : Destination des documents à extraire <br />
+*'''''--dest''''' : Destination des documents à extraire. Il s'agit du chemin complet du fichier PDF à créer, sans l'extension. Si les dossiers spécifiés n'existent pas, ils seront créés automatiquement. Le chemin peut contenir des valeurs de méta données (entre chevrons <xxxx> ) et d'index (entre doubles crochets <nowiki>[[c_xxxxx]]</nowiki> ).<br />
 *'''''--pgm''''' : Chemin complet du programme M-Storage.exe ou Mapout.exe (selon la version installée) <br />
 *'''''--action''''' : Action du script
@@ Ligne 68 : / Ligne 64 : @@
 **<code>''--action="generate''"</code> : génération des fichiers PDF
+Exemple de commande simple :
-Exemple :
+  php718\php index.php --archive="D:\Archives\Factures" --dest="D:\Export Archives\<NomUser>\<nowiki>[[c_numfac]]</nowiki>_<nowiki>[[c_numcli]]</nowiki>" --pgm="C:\Mapping\M-Storage\m-storage.exe" --action="getCommands"
-  php718\php index.php --archive="D:\Archives\Factures" --dest="D:\Export Archives\<NomUser>\<nowiki>[[c_numfac]]</nowiki>_<nowiki>[[c_numcli]]</nowiki>" --pgm="C:\Mapping\M-Storage\m-storage.exe" --action="generate"
 <br />
-'''7 - Paramètres facultatifs'''
+'''Paramètres facultatifs'''
 *'''''--indexfile''''' : si présent, chaque fichier PDF sera accompagné d'un fichier d'index XML portant le même nom <br />
-*'''''--xsl''''' : chemin d'un fichier xsl permettant de personnaliser le schéma du fichier xml afin de le rendre compatible avec un outil de GED tiers. La présence de ce paramètre active la transformation XSLT. <br />
+*'''''--xsl''''' : chemin d'un fichier xsl permettant de personnaliser le schéma du fichier xml afin de le rendre compatible avec un outil de GED tiers. La présence de ce paramètre active la transformation XSLT.  Exemple : <code>--xsl="C:\Mapping\Storage_Alfresco.xsl"</code><br />
-*'''''--rupt''''' : index de rupture, permettant de générer plusieurs PDF à partir d'un même spool d'impression. Par exemple, si les archives contiennent des spools d'impression multi-factures, il est possible, en spécifiant l'index du numéro de facture dans le paramètre ''--rupt'', de générer un pdf par facture et non un pdf pour le spool complet. Il est possible d'avoir plusieurs ocurences de ce paramètre pour que la rupture se fasse sur plusieurs index différents. <br />
+*'''''--rupt''''' : index de rupture, permettant de générer plusieurs PDF à partir d'un même spool d'impression. Par exemple, si les archives contiennent des spools d'impression multi-factures, il est possible, en spécifiant l'index du numéro de facture dans le paramètre ''--rupt'', de générer un pdf par facture et non un pdf pour le spool complet. Il est possible d'avoir plusieurs ocurences de ce paramètre pour que la rupture se fasse sur plusieurs index différents.  Exemple : <code>--rupt="c_numfac"</code> <br />
 *'''''--nextpage''''' : lors de l'utilisation d'un ou plusieurs index de ruptures, il est possible que certaines pages ne comportent pas de valeur pour ces index, notamment parce que l'un des index en question n'est présent que sur la première page de chaque document. Dans ce cas, si le paramètre ''--nextpage'' est présent, les pages suivantes ne comportant pas de valeur seront incluses dans le document PDF généré. <br />
 *'''--filter_XXXXX''' : divers paramètres de filtres, sur les méta données et sur les index sont possible
 **Usage : ''<code>--filter_XXXXXX="clé=valeur"</code>'' <br />
 **Liste des différents types de filtres
-***'''-- filtermeta_egal''' : filtre d'égalité sur une méta donnée
+***'''-- filtermeta_egal''' : filtre de type ''<u>la méta donnée</u>'' '''est''' '''égale à''' ''<u>la valeur</u>''
-***'''-- filtermeta_contains''' : filtre de type "contient" sur une méta donnée
+***'''-- filtermeta_contains''' : filtre de type ''<u>la méta donnée</u>'' '''contient''' ''<u>la valeur</u>''
-***'''-- filtermeta_begin''' : filtre de type "commence par" sur une méta donnée
+***'''-- filtermeta_begin''' : filtre de type ''<u>la méta donnée</u>'' '''commence par''' ''<u>la valeur</u>''
-***'''-- filterindex_egal''' : filtre d'égalité sur un index
+***'''-- filterindex_egal''' : filtre de type <u>''l'index''</u> '''est égal à''' ''<u>la valeur</u>''
-***'''-- filterindex_contains''' : filtre de type "contient" sur un index
+***'''-- filterindex_contains''' : filtre de type <u>''l'index''</u> '''contient''' ''<u>la valeur</u>''
-***'''-- filterindex_begin''' : filtre de type "commence par" sur un index <br />
+***'''-- filterindex_begin''' : filtre de type <u>''l'index''</u> '''commence par''' ''<u>la valeur</u>'' <br />Exemple : ''<code>--filterindex_egal="c_site=Paris" --filtermeta_begin="NomSpool=S2016"</code>'' <br />
-**Exemple : ''<code>--filterindex_egal="c_site=Paris" --filtermeta_begin="NomSpool=S2016"</code>'' <br />
+**La liste des index disponibles dépend de chaque archive. Cette liste est disponible via la table "''criteres''" de la base MySql. Tous les index doivent être spécifiés avec leur préfixe "c_".<br />
-**La liste des index disponibles dépend de chaque archive. Cette liste est disponible via la table "''criteres''" de la base MySql. <br />
+**La liste des méta données est quant à elle figée. Il s'agit des colonnes de la table "''spools''" de la base MySQL :  ''{{Warning}} Attention : sensibles à la casse. Il est courant que certaines de ces méta données soient détournées pour contenir des données "métier", surtout pour les archives issues de Mapping Windows et Unix/Linux.''
-**La liste des méta données est quant à elle figée. Il s'agit des colonnes de la table "''spools''" de la base MySQL :
+***'''NomSpool''' : SPOOLNAME au format "Saaaammjjhhmmssxxxxxxxxx". Cette donnée étant indexée, elle convient très bien à une extraction par période, par exemple avec le paramètre ''--filtermeta_begin="NomSpool=S201706"'' pour extraire les documents de juin 2017.
-***<br />
+***'''DateDuSpoolFichier''' '':'' DATE au format "aaaammjj"
+***'''NomTravail''' : JOBNAME
+***'''NomUser''' : USERNAME
+***'''NumeroJob'''
+***'''FichierSpool'''
+***'''NumeroSpool'''
+***'''OUTQ''' : OUTQ
+***'''BiliothequeOUTQ'''
+***'''Reference''' : USERDATA
+***'''Format''' : FORMAT MapDraw / M-Designer
+***'''ProgrammeEdition''' : PROG
+***'''BibProgrammeEdition'''
+***'''Critere1'''
+***'''Critere2'''
+***'''Critere3'''
+***'''Critere4'''
- ''<code>--filter_XXXXXX="clé=valeur"</code>''   Aide à l'extraction en masse des archives M-Storage :
+Exemple de commande complexe :
-    Toutes les actions se font pas l'intermédiaire du fichier index.php, en respectant la casse :
+  php718\php index.php --action="generate" --archive="D:\Archives\012018" --filtermeta_egal="Format=FACTURE" --filterindex_contains="c_nomcli=EXEMPLE" --filtermeta_begin="c_date=20180101" --rupt="c_nomcli" --nextpage --indexfile --dest="D:\Export\<nowiki>[[c_date]]</nowiki>\<nowiki>[[c_nomcli]]</nowiki>_<NomSpool>.pdf" --pgm="D:\Mapping\M-storage\M-storage.exe"
-        --action="getCommands|generate"                  : [Obligatoire] getCommands : Affiche les commandes M-Storage nécessaires à la création des PDFs dans la sortie standard.
-                                                           Génére un fichier TXT avec la commande au même emplacement que le PDF.
-                                                                         generate : Appelle directement le binaire M-Storage pour générer le PDF.
-        --archive="C:\Your\Archive\Path"                : [Obligatoire] Chemin du dossier contenant l'archive à extraire. Veillez à ne pas mettre d'antislash à la fin du chemin
-        --dest="C:\DestPath\<Metadata>\[[c_index]].pdf" : [Obligatoire] Chemin de destination des PDFs, le nom peut être formaté selon les valeurs des
-                                                          <Metadatas> et/ou des [[c_index]] retournées pour la recherche
-        --pgm="C:\Mapping\M-storage\M-storage.exe"      : [Obligatoire] Chemin de l'exécutable M-Storage
-        --xsl="C:\File\Path\file.xsl"                   : Chemin du fichier XSL. Active la gestion XSL.
-        --filtermeta_egal="Key=value"                   : Ajoute un filtre de recherche sur la métadata <Key> égale à <value>
-        --filtermeta_contains="Key=value"               : Ajoute un filtre de recherche sur la métadata <Key> contient <value>
-        --filtermeta_begin="Key=value"                  : Ajoute un filtre de recherche sur la métadata <Key> commence par <value>
-        --filterindex_egal="c_index=value"              : Ajoute un filtre de recherche sur le critère <c_index> égal à <value>
-        --filterindex_contains="c_index=value"          : Ajoute un filtre de recherche sur le critère <c_index> contient <value>
-        --filterindex_begin="c_index=value"             : Ajoute un filtre de recherche sur le critère <c_index> commence par <value>
-        --rupt="c_index"                                : Ajoute une rupture de document pour le critère <c_index>
-        --nextpage                                      : Inclure les pages suivantes
-        --indexfile                                     : Créer un fichier XML regroupant tous les métadatas et les critères du PDF. Créer au même emplacement que le PDF.
-    Exemple :
-    php index.php --action="getCommands" --archive="D:\Archives\012018\\" --filtermeta_egal="Format=FACTURE" --filterindex_contains="c_nomcli=EXEMPLE"
-    --filterindex_egal="c_date=20180101" --rupt="c_nomcli" --nextpage --indexfile --dest="D:\Export\[[c_date]]\[[c_nomcli]]_<NomSpool>.pdf" --pgm="D:\Mapping\M-storage\M-storage.exe"