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

1. définit l'ordre et la signification des colonnes
2. 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. 1ère colonne : ORDER,
2. 2ème colonne : identifiant de la famille (nom logique)
3. 3ème colonne : vide (utilisée pour l'alignement avec la ligne DOC),
4. 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 :

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. 1ère colonne : toujours DOC,

2. 2ème colonne : identifiant de la famille (nom logique)

3. 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.

4. 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 valeur fr_FR), alors la date est interprétée selon le format DD/MM/YYYY ;
• Si la locale de l'utilisateur est anglais (paramètre CORE_LANG positionné à la valeur en_US), alors la date est interprétée selon le format MM/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.
• 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.

Par exemple :

• pour un attribut de type longtext contenu dans un tableau, la valeur Première rangée<BR>suite du texte\nDeuxième rangée correspond à la structure suivante :

  index	relations
  1	Première rangée suite du texte
  2	Deuxième rangée

• pour un attribut de type docid, ayant l'option multiple=yes et contenu dans un tableau, la valeur 1236\n6375<BR>8755<BR>564\n567<BR><BR>4569 correspond à la structure suivante :

  index	relations
  1	• 1236
  2	• 6375 • 8755 • 564
  3	• 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 :

1. Doc::preRefresh()
2. Doc::postRefresh()
3. Doc::preImport($extra)
4. Doc::preCreated()
5. Doc::postCreated()
6. Doc::postStore()
7. Doc::postImport($extra)

Lors d'une mise à jour de documents les hameçons suivants sont lancés :

1. preRefresh()
2. postRefresh()
3. preImport($extra)
4. postStore()
5. 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 :

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. 1ère colonne : toujours KEYS,
2. 2ème colonne : Identifiant de la famille,
3. 3ème colonne : vide,
4. 4ème colonne : vide,
5. 5ème colonne : clef primaire,
6. 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 :

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. 1ère colonne : toujours DOCICON,
2. 2ème colonne : identifiant du document (nom logique),
3. 3ème colonne : nom du fichier image.

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. 1ère colonne : toujours DOCATAG,
2. 2ème colonne : identifiant du document (nom logique),
3. 3ème colonne : non utilisée
4. 4ème colonne : action à réaliser : ADD, DELETE ou SET (par défaut ADD)
   1. ADD : Ajout d'un nouveau tag
   2. DELETE : Suppression du tag indiqué
   3. SET : Suppression des précédents tag, puis ajout des nouveaux
5. Colonnes suivantes : autres tags à ajouter ou à supprimer

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.