======  Importation et exportation XML de documents ====== 


====== Exportation d'une collection de documents ======

L'exportation des documents peut revêtir deux formes : 
  - documents avec ou sans fichiers
  - documents autonomes (avec sa définition -famille-, etc...) 

Le format d'exportation est un flux XML ou une archive au format d'archive zip.

L'export contient un entête INFO portant les informations :
  - count : nombre de document exporté
  - context : context d'exportation (nom du contexte - machine)
  - date : date d'importation
  - author : nom et prénom de celui qui a lancé l'importation
  - parameters : différents paramètres d'importation
L'entête est soit un fichier xlm, soit une balise <info> dans le flux suivant le format d'export demandé.

===== Flux XML ===== 
Pour chacun des documents, le flux XML intègre les documents. Les attributs fichiers sont encodés dans le flux en base64. 
Une fonction de récupération des schémas est disponible : pour un nom logique de famille elle retourne sont schéma.

===== Archives ZIP ===== 
L'archive contient le fichier INFO ''info.xml''.\\
L'archive contient un fichier xml ''<titre> {id}.xml'' par document. Ce fichier contient une référence vers le schéma. Un seul document schéma est présent par famille dans l'archive.\\ 

Les noms des fichiers xml sont composées du titre suivi de leur nom logique (l'id le cas échéant) encadré par des accolades.

Exemple : (animal {ZOO_ANIMAL}.xsd, totor alligator {3456}.xml, titi l'agouti {5678}.xml, ...).

Les attributs fichiers dans ce cas ne contiennent pas de référence aux fichiers physiques :
<an_photo vaultid="456" mime="image/jpeg">totor.jpeg</an_photo>

Une option permet de demander si les fichiers (attributs) sont exportés ou non.\\
Une option permet de demander si les fichiers sont exportés dans le xml (encodés) ou sous forme de fichier.\\

==== Export avec les fichiers hors XML ====
Dans ce cas les attributs fichiers contiennent une référence aux fichiers physiques contenus dans l'archive
<an_photo vaultid="456" mime="image/jpeg" file="nom du fichier {idfichier}.jpg">nom du fichier .ext</an_photo>

[FIXME]
  - mettre un sous/répertoire par document pour les fichiers : "totor alligator {3456}/totor {456}.jpg"
  - mettre un le nom du document dans le nom du fichier : "totor alligator {3456} totor {456}.jpg"

==== Export avec les fichiers encodé dans le XML ====

<an_photo vaultid="456" mime="image/jpeg" filename="nom du fichier .ext"><![CDATA[........base64 encoded....==]]></an_photo>



===== Données autonomes (archive ZIP) =====
Dans ce cas l'archive contient elle même une archive par document.
totor alligator {3456}.fdoc , titi l'agouti {5678}.fdoc

Une archive document est composée de
  - le schéma de la famille : family.xsd
  - le xml du document : content.xml
  - un répertoire "files" contenant l'ensemble des fichiers attachés au document
  - un répertoire "media" contenant le fichier icône de la famille et celui du document (s'ils diffèrent)
  - etc...

En option supplémentaire il possible de demander l'export du profil.
  - le profil (si profil dédié): profil.xml
  - la configuration (contenant la référence au profil, au contrôle de vue, author, verrou, state): properties.xml

====== Importation de document ======

Les formats d'archives précédemment cités peuvent être importés dans la base.
Si un document contient déjà un id il sera mis à jour sinon il sera créé. 
Le principe actuel d'importation avec les clefs d'importation est conservé pour détecter les documents identiques (mise à jour).

Ces clefs pourront être explicitement déclarées dans le xml du document.

Les contrôles à l'importation:
  - la famille d'importation doit déjà être présente dans le contexte (instance freedom)
  - pour une mise à jour le document doit être de la même famille
  - vérification de la conformité du document (xml) avec le schéma de la famille dans freedom
  - vérification pour les relations (docid) de la compatibilité avec la famille
  - vérification du preImport
  - (Option débrayable) vérification des contraintes d'attributs
  - (Option débrayable) vérification des attributs obligatoires


====== Utilisation ======

L'interface freedom permet de lancer les exportations (depuis les recherches/dossiers) et importations.
Ces actions sont accessibles via une URL.

Une commande wsh permet d'importer une archive accessible localement depuis le serveur freedom. Cette commande a les arguments suivants :
  - file : le chemin vers le fichier
  - analyse : [yes|no] si "yes" fait l'analyse seulement (par défaut "no")
  - output : chemin vers le fichier d'analyse produit (par défaut "import-result.xml")

Un connecteur permet de réaliser les imports en utilisant les mécanismes existants du module freedom-fileconnector.

===== Rapports =====

Il serait intéressant que l'import génère un rapport reprenant
  * la date de l’import et la durée de l’import
  * nombre de documents traités
    * Nombre de créations
    * Nombre de mises à jour
  * Liste des erreurs
    * Une ligne avec l'erreur et le document concerné par erreur