7.1 Importation de documents par CSV
Ce chapitre indique comme importer des documents au format CSV ou ODS.
7.1.1 Constitution du fichier d'importation
Le fichier d'importation peut être au format :
- CSV
- Encodage : UTF-8,
- Séparateur de colonnes :
;
(point-virgule par défaut - configurable en 3.2.12). - Délimiteur de texte :
(vide par défaut - configurable en 3.2.12),
- ODS OpenDocument Spreadsheet (tableur OpenOffice.org .ods)
Ce fichier d'importation est auto-descriptif ; c'est à dire qu'il
- définit l'ordre et la signification des colonnes
- liste les documents à importer
7.1.1.1 Ordre des attributs
Avant de décrire les valeurs des attributs d'un document il est nécessaire d'indiquer à quel attribut correspond chaque valeur.
Pour définir l'ordre des attributs, il faut utiliser une ligne ORDER
.
Chaque ligne ORDER
est propre à une famille (et ne concerne donc pas les
familles qui en héritent).
Cette ligne doit être présente avant les lignes décrivant les documents de la famille concernée.
Les 4 premières colonnes contiennent :
- 1ère colonne :
ORDER
, - 2ème colonne : identifiant de la famille (nom logique)
- 3ème colonne : vide (utilisée pour l'alignement avec la ligne
DOC
), - 4ème colonne : vide (utilisée pour l'alignement avec la ligne
DOC
).
Les autres colonnes définissent l'ordre des attributs à utiliser dans les
lignes DOC
de la même famille qui suivent.
Si plusieurs lignes ORDER
référençant la même familles sont écrites à la suite,
les documents sont importés avec le dernier ordre interprété.
Exemple :
# | famille | |||||
---|---|---|---|---|---|---|
ORDER | ZOO_CLASSE | cl_latinname | cl_commonname | cl_caracteristic | ||
DOC | ZOO_CLASSE | Actinopterygii | Poissons | Nage | ||
DOC | ZOO_CLASSE | Reptilia | Reptiles | Rampe | ||
ORDER | ZOO_CLASSE | cl_commonname | cl_caracteristic | cl_latinname | ||
DOC | ZOO_CLASSE | Oiseaux | Vole | Aves | ||
DOC | ZOO_CLASSE | Mammifères | Allaite | Mammalia |
Dans ce cas, les deux premiers documents utilisent le premier ORDER
, et les
documents suivants le deuxième ORDER
(la deuxième ligne ORDER
a écrasé les
directives de la première).
3.2.19 Lorsque la ligne ORDER
est invalide (e.g. l'attribut déclaré n'existe pas pour la famille), alors
l'import de documents de cette famille est ignoré et une erreur est remontée.
La liste des codes d'erreur relatifs à la directive ORDER
est consultable sur
la documentation PHP de la classe ErrorCodeORDR.
7.1.1.2 Description d'un document
Les quatre premières ont une signification particulière :
- 1ère colonne : toujours
DOC
, 2ème colonne : identifiant de la famille (nom logique)
-
3ème colonne : identifiant du document (numérique ou nom logique)
- s'il est saisi
- si le document référencé existe, il sera mis à jour,
- sinon, le document créé portera cet identifiant,
- sinon
- si l'option d'importation est à mise à jour (option par défaut) et qu'un document est trouvé au moyen des clés d'importation, il est mis à jour,
- sinon, un nouveau document est créé, et porte un nouvel identifiant généré par la base de données.
Il n'est pas possible d'importer une révision figée d'un document. Seules les révisions courantes peuvent faire l'objet de modification. Si un identifiant pointe sur une révision passée c'est la révision courante qui sera modifiée par l'importation.
- s'il est saisi
-
4ème colonne : identifiant du dossier dans lequel le document importé doit être inséré.
- Si un identificateur est précisé le document est référencé dans le dossier (s'il n'y est pas déjà).
- Si l'identificateur n'est pas précisé (vide ou zéro), le document est référencé dans le dossier courant (celui qui est sélectionné dans l'arborescence en cas d'utilisation avec l'interface web d'importation).
- Si l'identifiant est
-
alors le document ne sera référencé dans aucun dossier.
Les colonnes suivantes décrivent les valeurs brutes des attributs du document.
7.1.2 Mécanique d'importation
7.1.2.1 Valeurs des attributs pour l'importation
Les valeurs inscrites dans le document sont insérés avec la
méthode Doc::setValue()
.
7.1.2.1.1 Relations
Les attributs relations (docid
, account
, thesaurus
) peuvent contenir :
- soit le nom logique du document cible;
-
soit l'identifiant système du document cible.
Attention, dans ce cas, le document cible peut ne pas être valable sur n'importe quelle instance de Dynacase.
Si le document référencé est un nom logique qui n'existe pas alors la valeur sera ignorée (un message de warning est émis avec le nom logique qui n'est pas connu). Si la référence est un nombre qui ne fait pas référence à un document, ce nombre sera enregistré. Il sera considéré comme une référence inconnue.
7.1.2.1.2 Énumérés
Les attributs de type énuméré (enum
) doivent contenir la clef.
7.1.2.1.3 Dates
Les dates (date
, timestamp
) doivent être renseignés au format ISO
(YYYY-MM-DD
ou YYYY-MM-DD HH:MM:SS
ou YYYY-MM-DDTHH:MM:SS
).
Dans le cas contraire, la date est interprétée en fonction de la locale de
l'utilisateur réalisant l'importation :
- Si la locale de l'utilisateur est français (paramètre
CORE_LANG
positionné à la valeurfr_FR
), alors la date est interprétée selon le formatDD/MM/YYYY
; - Si la locale de l'utilisateur est anglais (paramètre
CORE_LANG
positionné à la valeuren_US
), alors la date est interprétée selon le formatMM/DD/YYYY
.
Dans tous ces cas la valeur de la date stockée sera au format ISO.
7.1.2.1.4 Attributs multivalués
- Pour les attributs multivalués à un seul niveau (attribut contenu dans un
tableau, ou ayant l'option
multiple=yes
et n'étant pas contenu dans un tableau) :- la chaîne
\n
délimite deux valeurs consécutives, - la chaîne
<BR>
correspond à un saut de ligne au sein d'une valeur.
- la chaîne
- Pour les attributs multivalués à 2 niveaux (cas des relations ayant l'option
multiple=yes
et contenues dans un tableau) :- la chaîne
\n
délimite deux valeurs de premier niveau, - la chaîne
<BR>
délimite deux valeurs de second niveau.
- la chaîne
Par exemple :
-
pour un attribut de type
longtext
contenu dans un tableau, la valeurPremière rangée<BR>suite du texte\nDeuxième rangée
correspond à la structure suivante :index relations 1 Première rangée
suite du texte2 Deuxième rangée -
pour un attribut de type
docid
, ayant l'optionmultiple=yes
et contenu dans un tableau, la valeur1236\n6375<BR>8755<BR>564\n567<BR><BR>4569
correspond à la structure suivante :index relations 1 • 1236 2 • 6375
• 8755
• 5643 • 567
•
• 4569
Note 3.2.12 : Si un
délimiteur de texte est défini, le retour chariot est alors possible sur une
ligne et est interprété comme la chaîne \n
.
7.1.2.2 Hameçons déclenchés lors de l'importation
Les hameçons sont lancés après la mise à jour des valeurs du document.
Lors d'un ajout de documents les hameçons suivants sont lancés :
Doc::preRefresh()
Doc::postRefresh()
Doc::preImport($extra)
Doc::preCreated()
Doc::postCreated()
Doc::postStore()
Doc::postImport($extra)
Lors d'une mise à jour de documents les hameçons suivants sont lancés :
preRefresh()
postRefresh()
preImport($extra)
postStore()
postImport($extra)
Note : Les contraintes ne sont pas vérifiées lors de l'importation des documents. Le caractère obligatoire des attributs n'est pas vérifié non plus.
7.1.2.3 Informations supplémentaires
Lors de l'importation d'un document, il est possible d'indiquer des informations supplémentaires pour réaliser des traitements conditionnels.
Ces informations sont identifiées par des clés commençant par extra:
: ces
valeurs sont passées en paramètre des méthodes preImport
et
postImport
de la famille associée, sous forme d'un tableau
associatif de forme clé => valeur
, avec pour clé la chaîne de caractères
suivant le extra:
dans la description du nom de l'attribut, et comme valeur,
celle correspondante à la colonne.
Exemple :
ORDER | ZOO_CLASSE | cl_latinname | extra:status | extra:special | ||
---|---|---|---|---|---|---|
DOC | ZOO_CLASSE | - | Actinopterygii | alive | protected |
Dans cette exemple, le document Actinopterygii de la famille ZOO_CLASSE aura
comme paramètre passé à preImport
et postImport
:
array( 'status' => 'alive', 'special' => 'protected' );
7.1.2.4 Clés d'importation
Lors d'une importation, Dynacase utilise une heuristique pour déterminer si un document existant doit être mis à jour ou s'il faut un créer un nouveau. Cette heuristique se base sur les clés d'importation de la famille : si un et un seul document de la même famille ou d'une sous-famille a ses clés d'importations égales à celles du document en cours d'importation, alors Dynacase fait une mise à jour dans le cas contraire, Dynacase fait une création de document.
Les clés d'importation pour une famille sont déterminées au moyen d'une ligne
KEYS
.
Chaque ligne KEYS
est propre à une famille (et ne concerne donc pas les
familles qui en héritent).
La clé utilisée par défaut pour reconnaître le document est la propriété title
de ce document.
L'ordre des colonnes est :
- 1ère colonne : toujours
KEYS
, - 2ème colonne : Identifiant de la famille,
- 3ème colonne : vide,
- 4ème colonne : vide,
- 5ème colonne : clef primaire,
- 6ème colonne : clef secondaire.
Les colonnes 5 et 6 servent à définir les attributs ou propriétés qui sont utilisés comme clé. On peut avoir un maximum de deux clés par ligne (dans ce cas, il faudra que les deux clés correspondent pour que le document soit reconnu).
Exemple :
# | famille | |||||
---|---|---|---|---|---|---|
ORDER | ZOO_CLASSE | cl_latinname | cl_commonname | cl_caracteristic | ||
KEYS | ZOO_CLASSE | cl_latinname | ||||
DOC | ZOO_CLASSE | - | Actinopterygii | Poissons | ||
DOC | ZOO_CLASSE | - | Reptilia | Reptiles | Rampe | |
DOC | ZOO_CLASSE | - | Actinopterygii | Nage |
Dans cet exemple, les documents sont reconnus par leur attribut 'cl_latinname'. Donc pour le premier document, la clé est 'Actinopterygii', et pour le deuxième 'Reptilia'. Dans cet exemple le document Actinopterygii est d'abord créé avec le nom Poissons, puis il est mis à jour avec la caractéristique Nage.
Les lignes KEYS
sont appliquées dans l'ordre dans
lesquelles elles ont été écrites.
7.1.3 Modifier l'icône d'un document
Par défaut, l'icône d'un document est l'icône de la famille au moment de la création du document.
Il est possible de modifier l'icône d'un document au moyen d'une ligne
DOCICON
.
L'ordre des colonnes est :
- 1ère colonne : toujours
DOCICON
, - 2ème colonne : identifiant du document (nom logique),
- 3ème colonne : nom du fichier image.
# | famille | |||||
---|---|---|---|---|---|---|
ORDER | ZOO_CLASSE | cl_latinname | cl_commonname | cl_caracteristic | ||
DOC | ZOO_CLASSE | CL_ACTI | - | Actinopterygii | Poissons | |
DOCICON | CL_ACTI | fish.png | - |
Le nom de l'image doit référencer un fichier présent dans le répertoire
./Images
à la racine du répertoire d'installation sur le serveur.
7.1.4 Modifier un tag applicatif d'un document
3.2.23 Les tags applicatifs peuvent être ajoutés ou supprimés par le fichier d'importation CSV.
Il est possible de modifier le tag applicatif d'un document au moyen d'une ligne
DOCATAG
.
L'ordre des colonnes est :
- 1ère colonne : toujours
DOCATAG
, - 2ème colonne : identifiant du document (nom logique),
- 3ème colonne : non utilisée
- 4ème colonne : action à réaliser : ADD, DELETE ou SET (par défaut ADD)
- ADD : Ajout d'un nouveau tag
- DELETE : Suppression du tag indiqué
- SET : Suppression des précédents tag, puis ajout des nouveaux
- Colonnes suivantes : autres tags à ajouter ou à supprimer
# | famille | ||||
---|---|---|---|---|---|
ORDER | ZOO_CLASSE | cl_latinname | cl_commonname | ||
DOC | ZOO_CLASSE | CL_ACTI | - | Actinopterygii | Poissons |
DOC | ZOO_CLASSE | CL_AVES | - | Aves | Oiseau |
#TAGKEY | DOC IDENTIFIER | TAG ACTION | First Tag | Second tag | |
DOCATAG | CL_ACTI | ADD | MyFishTag | ||
DOCATAG | CL_AVES | SET | MyBirdTag | MyOtherTag |
Le tag ne doit pas contenir de retour chariot \n
.
7.1.5 Précautions d'utilisation
Lors de l'import de documents quelques précautions d'usage sont à prendre en compte :
- Les attributs calculés peuvent devenir incohérent, ils sont en effet initialisés avec les valeurs lors de l'import. Ceci peut créer des incohérences.
- Les documents de faisant référence à un
account
ne sont pas ré-importables tel que. Il faut suivre la procédure de ré-import tel que décrite dans ce chapitre.
3.2.18 Les documents ayant des attributs en visibilité "I" ne sont pas importés depuis l'interface d'importation sauf depuis le centre d'administration ou par ligne de commande.