Principe de l’importation
L’importation de données en masse issues d’une source externe s’effectue par le biais d’un fichier au format XML. Ce fichier sera généralement généré par un pré-traitement sur les données. Ce choix peut paraître technique et contraignant, mais il offre l’avantage de permettre, au travers du format, la validation de la syntaxe des données et d’éviter ainsi les risques de corruption de la base. Techniquement, le traitement comporte en effet plusieurs étapes :
- le fichier XML est lu et vérifié syntaxiquement
- un ensemble d’ordres est généré d’après le contenu du fichier s’il est correct
- les ordres générés sont vérifiés puis exécutés pour créer les observations et divers liens en base.
Préparation du fichier XML
Cette section décrit comment construire un fichier XML d’observations par programme ou manuellement. Pour simplifier l’étape de préparation des données, une méthode de génération du XML sur la base d’un tableur est présentée en fin de page.
Le fichier XML des observations doit répondre au schéma décrit par le fichier plugins/biodiv/xsl/observations.xsd. Son objet racine est observations qui contient une séquence d’objets observation. Une observation contient les éléments décrits dans le tableau ci-dessous [1]. Chaque élément n’apparait qu’au plus une fois par observation. Leur ordre d’apparition est indifférent.
| Elément | Type | Description | Obligatoire ? |
|---|---|---|---|
| xref | string | La référence de l’observation dans la base source. Cette information est notamment utilisée pour éviter l’importation multiple de la même observation. | oui |
| lng | nombre décimal | Longitude dans le système WGS84 (GPS). Le point décimal doit être utilisé, et non la virgule | oui |
| lat | nombre décimal | Latitude dans le système WGS84 (GPS). Le point décimal doit être utilisé, et non la virgule | oui |
| methode | string | Méthode de détermination de l’observation | non |
| saisie | date | Date de saisie dans la base source. Le format est AAAA-MM-JJ | non |
| date_obs | date | Date de l’observation. Le format est AAAA-MM-JJ | oui |
| adresse | string | Lieu de l’observation. Sans indication de la commune | non |
| commune | string | Commune de l’observation. | non |
| insee | entier positif | Code INSEE de la Commune de l’observation. | non |
| observateurs | string | Prénom et nom de l’observateur. S’il y en a plusieurs, ils seront séparés par des virgules. Les observateurs qui sont inscrit sur le site ne doivent pas être listés ici. Seuls les observateurs non inscrits sont listés. | non |
| id_auteur | string | Liste des identifiants des observateurs inscrits sur le site. Les identifiants sont séparés par des virgules. L’identifiant est le numéro N qui apparait dans l’URL https://url-du-site-biodiv/spip.php?auteurNqui renvoie à la page décrivant l’observateur. Indiquer 0 si aucun observateur connu n’est concerné. |
oui |
| cd_nom | entier positif | Identifiant TAXREF [2] de l’espèce, s’il est connu. Cette information permet de relier directement l’observation à la fiche espèce correspondante quand elle existe. | non |
| espece | string | Nom vernaculaire de l’espèce | oui |
| binomial [3] | string | Nom scientifique (latin) binominal de l’espèce | non |
| quantite | entier positif | nombre de spécimen observés | oui |
| denombrement | énumeration | Action effectuée pour déterminer la quantité : Co (comptage : valeur par défaut), Es (estimation), Ca (calcul), NSP (ne sait pas) | non |
| notes | string | Information complémentaire qui se retrouvera dans le champ "détails" de l’observation | non |
| remarques | string | Information complémentaire qui se retrouvera dans le champ "détails" de l’observation | non |
| milieu | string | Information complémentaire qui se retrouvera dans le champ "détails" de l’observation | non |
Un exemple minimal de fichier est donné ci-dessous :
<?xml version="1.0" encoding="utf-8"?>
<observations>
<observation>
<xref>8e0b4038-a04c-41ec-9fd9-041006d7eb3c</xref>
<espece>Milan royal</espece>
<quantite>1</quantite>
<lat>43.600161</lat>
<lng>1.497518</lng>
<date_obs>2022-03-09</date_obs>
<id_auteur>225</id_auteur>
<cd_nom>2844</cd_nom>
</observation>
<observation>
<xref>1041e0f1-a875-41ec-9fd9-041006df56dd</xref>
<espece>Hirondelle rustique</espece>
<quantite>1</quantite>
<lat>43.607475</lat>
<lng>1.492209</lng>
<date_obs>2022-03-20</date_obs>
<id_auteur>225</id_auteur>
</observation>
</observations>
Générer le fichier XML à partir de LibreOffice [4]
Pour simplifier la préparation des données, il est possible de les saisir dans un tableur Calc. La première ligne devra contenir les noms des champs, tels que listés dans le tableau ci-dessus. On créera ensuite une ligne par observation en respectant les contraintes décrites dans le tableau.
Pour exporter en XML les données obtenues, on utilisera la macro exporter_observations.bas qui aura été préalablement chargée dans LibreOffice. Le source de cette macro est fourni dans le fichier joint.
Important :
- avant de lancer la macro, il faut avoir enregistré les données dans un fichier ods, et il faut que ce fichier soit ouvert sur l’onglet contenant les données
- à partir de
nom-de-fichier.ods, la macro créenom-de-fichier.csvetnom-de-fichier.xml. Vous pouvez détruire le fichier CSV qui n’est qu’une étape intermédiaire de calcul. - cette macro exporte le contenu de la feuille courante encapsulé dans des objets
observation, mais elle ne vérifie pas les noms des éléments de la première ligne, ni le type de données.
Générer le fichier XML à partir de Microsoft Excel
Excel dispose de fonctions qui reconnaissent des schémas XML et peuvent les associer à des onglets d’une feuille de calcul. Si vous disposez d’Excel, vous devrez :
- activer les fonctions de traitement XML dans l’interface (via la gestion des options)
- charger le schéma
plugins/biodiv/xsl/observations.xsd - associer ce schéma à un onglet de votre feuille de calcul
- saisir les données dans l’onglet couvert par le schéma
- choisir, dans les fonctions XML, ’Exporter en XML’
L’avantage d’Excel sur LibreOffice pour cette opération est de
- peupler automatiquement la première ligne de l’onglet sur la base du schéma
- effectuer les contrôles de type lors de la saisie
- permettre l’export sans macro additionnelle
L’avantage de LibreOffice est d’être gratuit et Open Source ...
Charger le fichier XML dans la base
Le chargement des observations par lot est accessible aux administrateurs, depuis l’action "Traitement par lots" disponible sur la page de votre espace personnel.
Dans le formulaire correspondant, il suffit alors de :
- sélectionner le fichier XML construit ci-dessus
- choisir la source de données à laquelle il se rapporte
- choisir de contrôler l’unicité des références externes (recommandé)
- exécuter l’import.
Note : Si la source de données pour ces observations n’est pas encore connue, il faudra la déclarer préalablement à l’import.
Notes:
[1] La description est une transposition des informations du schéma, destinée au lecteur peu familier du formalisme xsd. Dans le doute, c’est toujours le schéma qui fait foi.
[2] Référentiel taxonomique du Muséum National d’Histoire Naturelle
[3] Cet élément devrait s’appeler ’binominal’ plutôt que ’binomial’ mais une faute de frappe historique subsiste ...
[4] ou OpenOffice
