| Les deux révisions précédentes Révision précédente Prochaine révision | Révision précédente |
| database:import-formats [2026/06/17 08:03] – [Format OCCTAX d'import] jpmilcent | database:import-formats [2026/06/17 08:30] (Version actuelle) – [Évolutions] jpmilcent |
|---|
| L'archive devra contenir au minimum les fichiers suivants : | L'archive devra contenir au minimum les fichiers suivants : |
| * **//meta_archive.ini//** : fichier contenant les métadonnées sur le fournisseur de l'archive et la version du format d'échange utilisée. | * **//meta_archive.ini//** : fichier contenant les métadonnées sur le fournisseur de l'archive et la version du format d'échange utilisée. |
| * **//synthese.csv//** : les données d'observation à intéger à la synthèse sont les seules requises. | * **//synthese.csv//** : les données d'observation à intégrer au module Synthèse. Peux être remplacer par un fichier //occtax.csv//. |
| Les fichiers suivants pourront aussi être fournis sans être obligatoires : | Les fichiers suivants pourront aussi être fournis sans être obligatoires : |
| * //additional_data.csv// : contient la description des champs additionnels présents dans les différents fichiers à importer. | |
| * //source.csv// : permet de décrire la source des données. Correspond à la table "//gn_synthese.t_sources//". | * //source.csv// : permet de décrire la source des données. Correspond à la table "//gn_synthese.t_sources//". |
| * //dataset.csv// : permet de fournir les informations sur les jeux de données. Correspond à la table "//gn_meta.t_datasets//". | * //dataset.csv// : permet de fournir les informations sur les jeux de données. Correspond à la table "//gn_meta.t_datasets//". |
| * //acquisition_framework.csv// : permet de fournir les informations sur les cadres d'acquisition des jeux de données. Correspond à la table "//gn_meta.t_acquisition_framework//". | * //acquisition_framework.csv// : permet de fournir les informations sur les cadres d'acquisition des jeux de données. Correspond à la table "//gn_meta.t_acquisition_framework//". |
| * //organism.csv// : permet de fournir les informations sur les organismes liées aux utilisateurs, jeux de données et cadres d'acquisition. Correspond à la table "//utilisateurs.bib_organismes//". | * //organism.csv// : permet de fournir les informations sur les organismes liées aux utilisateurs, jeux de données et cadres d'acquisition. Correspond à la table "//utilisateurs.bib_organismes//". |
| * //user.csv// : permet de fournir des informations sur les utilisateurs à l'origine des données. Correspond à la table "//utilisateurs.t_roles//". | * //user.csv// : permet de fournir des informations sur les utilisateurs à l'origine des données. Correspond à la table "//utilisateurs.t_roles//". |
| | * //occtax.csv// : les données d'observation à intégrer au module OccTax. Les données seront automatiquement répercutées dans le module Synthèse via des //triggers// présents dans la base de données. |
| | * //validation.csv// : permet de fournir les statuts de validations actuel et passés des observations. Généralement, utilisé en complément du fichier //occtax.csv//. |
| | * //meta_additional_data.csv// : contient la description des champs additionnels présents dans les différents fichiers à importer. uniquement pour la documentation. Non utilisé. |
| | |
| ==== Principe de la procédure d'import initial ==== | ==== Principe de la procédure d'import initial ==== |
| * Nous utiliserons plusieurs fichiers textes respectant tous le même format CSV (voir ci-dessous) | * Nous utiliserons plusieurs fichiers textes respectant tous le même format CSV (voir ci-dessous) |
| * Le détail des différents fichiers (user, organism, acquistion_framework, dataset, source, synthese) est présentés ci-dessous | * Le détail des différents fichiers (user, organism, acquistion_framework, dataset, source, synthese) est présentés ci-dessous |
| * Un seul fichier est obligatoire //synthese// mais les autres sont nécessaire pour éviter une saisie manuelle sur GeoNature des métadonnées et sur UsersHub des utilisateurs et organismes. | * Un seul fichier est obligatoire //synthese// (ou //occtax//) mais les autres sont nécessaire pour éviter une saisie manuelle sur GeoNature des métadonnées et sur UsersHub des utilisateurs et organismes. |
| * Dans ces fichiers, nous utiliserons les codes alphanumériques des valeurs pour les champs devant contenir des **identifiant de nomenclatures**. Un script Python se connectant à la base de GeoNature permettra de récupérer l'identifiant numérique spécifique à une instance de base de données. | * Dans ces fichiers, nous utiliserons les codes alphanumériques des valeurs pour les champs devant contenir des **identifiant de nomenclatures**. Un script Python se connectant à la base de GeoNature permettra de récupérer l'identifiant numérique spécifique à une instance de base de données. |
| * Pour les lien avec les **organismes**, **cadres d'acquisition** et **jeux de données**, nous utiliserons un mécanisme différent des nomenclatures. Les liens se feront sur les UUID et un script SQL permettra de récupérer les identifiants spécifiques à chaque instance de base de données. Les champs sur lesquels les liens sont basés peuvent être amené à évoluer dans la base d'origine. Lors d'une mise à jour nous nous appuierons aussi sur les champs "//unique_id//" (UUID) de ces entités (s'ils sont fournis) pour retrouver la correspondance avec un enregistrement en base de données. Il est donc important que les bases de données sources stockent l'UUID des ces entités... | * Pour les lien avec les **organismes**, **cadres d'acquisition** et **jeux de données**, nous utiliserons un mécanisme différent des nomenclatures. Les liens se feront sur les UUID et un script SQL permettra de récupérer les identifiants spécifiques à chaque instance de base de données. Les champs sur lesquels les liens sont basés peuvent être amené à évoluer dans la base d'origine. Lors d'une mise à jour nous nous appuierons aussi sur les champs "//unique_id//" (UUID) de ces entités (s'ils sont fournis) pour retrouver la correspondance avec un enregistrement en base de données. Il est donc important que les bases de données sources stockent l'UUID des ces entités... |
| * avoir un nom au singulier, en minuscules et avec des underscores comme séparateur de mots. | * avoir un nom au singulier, en minuscules et avec des underscores comme séparateur de mots. |
| * avoir l'extension //.csv// | * avoir l'extension //.csv// |
| * avoir un des noms suivant : //synthese.csv//, //source.csv//, //dataset.csv//, //acquisition_framework.csv//, //organism.csv// ou //user.csv// | * avoir un des noms suivant : //synthese.csv//, //source.csv//, //dataset.csv//, //acquisition_framework.csv//, //organism.csv//, //user.csv//, //occtax.csv//, //validation.csv// ou //meta_additional_data.csv//. |
| |
| Le format CSV (en réalité plutôt [[https://fr.wikipedia.org/wiki/Tabulation-separated_values|TSV]]) qu'ils contiendront devra respecter les règles suivantes : | Le format CSV (en réalité plutôt [[https://fr.wikipedia.org/wiki/Tabulation-separated_values|TSV]]) qu'ils contiendront devra respecter les règles suivantes : |
| * si nécessaire utiliser le caractère **guillemet** (") pour préfixer et suffixer une valeur de champ | * si nécessaire utiliser le caractère **guillemet** (") pour préfixer et suffixer une valeur de champ |
| * si nécessaire utiliser **deux guillemets** successifs ("") pour échapper le caractère guillemet dans une valeur de champ préfixé et suffixé par des guillemets. | * si nécessaire utiliser **deux guillemets** successifs ("") pour échapper le caractère guillemet dans une valeur de champ préfixé et suffixé par des guillemets. |
| | * respecter l'ordre des champs décrits dans cette documentation |
| | * si possible fournir les fichiers avec l'ensemble des champs décrits même s'ils doivent contenir des valeurs nulles |
| | |
| Il faut vous assurer d'avoir supprimé, remplacé ou protégé les caractères suivant dans les valeurs des champs : | Il faut vous assurer d'avoir supprimé, remplacé ou protégé les caractères suivant dans les valeurs des champs : |
| * si les champs ne sont pas valables pour toutes les lignes, 1 seule possibilité : | * si les champs ne sont pas valables pour toutes les lignes, 1 seule possibilité : |
| * utiliser le champ //additional_data// dont les valeurs doivent être [[https://www.json.org/json-fr.html|au format JSON]] et [[https://jsonformatter.curiousconcept.com/|être valide]]. Le JSON en question devra correspondre à un objet d'un seul niveau avec attribut et valeur. Ex. : <code json>{"attribut1": "valeur1", "attribut2": "valeur2"}</code> | * utiliser le champ //additional_data// dont les valeurs doivent être [[https://www.json.org/json-fr.html|au format JSON]] et [[https://jsonformatter.curiousconcept.com/|être valide]]. Le JSON en question devra correspondre à un objet d'un seul niveau avec attribut et valeur. Ex. : <code json>{"attribut1": "valeur1", "attribut2": "valeur2"}</code> |
| * si les champs sont valables pour toutes les lignes du fichier d'import, 2 possibilités : | * si les champs sont valables pour toutes les lignes du fichier d'import, <del>2</del> 1 possibilité<del>s</del> : |
| * ajouter des colonnes supplémentaires au fichier | |
| * utiliser le champ //additional_data// (voir ci-dessus) | * utiliser le champ //additional_data// (voir ci-dessus) |
| | * <del>ajouter des colonnes supplémentaires au fichier</del> : non implémenté ! |
| |
| Afin de respecter le standard, il est nécessaire de fournir les méta-données de ces champs additionnel en fournissant le fichier //meta_additional_data.csv// (voir META_ADDITIONAL_DATA). Ce fichier contient la descriptions des champs additionnels. | Afin de respecter le standard, il est nécessaire de fournir les méta-données de ces champs additionnel en fournissant le fichier //meta_additional_data.csv// (voir META_ADDITIONAL_DATA). Ce fichier contient la descriptions des champs additionnels. |
| |
| Pour faciliter l'intégration des données, l'utilisation du champ //additional_data// est conseillée.\\ | Pour permettre l'intégration des données, l'utilisation du champ //additional_data// est nécessaire car la possibilité d'ajouter des colonnes supplémentaires aux fichiers CSV n'est pas implémentée.\\ |
| Les champs additionnels ne seront pas forcément traités pour toutes les ressources. Seuls les champs de la ressource SYNTHESE seront transmis au niveau national. | Les champs additionnels ne seront pas forcément traités pour toutes les ressources. Seuls les champs de la ressource SYNTHESE seront transmis au niveau national. |
| |
| |
| ==== Évolutions ==== | ==== Évolutions ==== |
| | * 2026-06-17 : |
| | * Ajout des statuts des différents fichiers. |
| | * Ajout de complément sur le format des fichiers CSV attendus. |
| | * Mise à jour des textes introductifs. |
| * 2026-04-02 : | * 2026-04-02 : |
| * Utilisation de ''VARCHAR(50)'' pour tous les champs ''code_nomenclature_...'' de SYNTHESE. | * Utilisation de ''VARCHAR(50)'' pour tous les champs ''code_nomenclature_...'' de SYNTHESE. |
| | * 2026-03-13 : |
| | * Ajout du format VALIDATION. Nécessaire pour intégrer un historique des validations à la Synthese ou dans le cadre de l'utilisation du format OCCTAX. |
| * 2025-04-30 : | * 2025-04-30 : |
| * Ajout du format OccTax supporté pour les ajouts uniquement. Non nécessaire pour l'instant dans le cadre des SINP. | * Ajout du format OCCTAX supporté pour les ajouts uniquement. Non nécessaire pour l'instant dans le cadre des SINP. |
| * 2024-10-23 : | * 2024-10-23 : |
| * Nous privilégions maintenant l'utilisation des UUID comme identifiant de lien entre les ressources à la place des codes ou noms. | * Nous privilégions maintenant l'utilisation des UUID comme identifiant de lien entre les ressources à la place des codes ou noms. |
| * Utilisation de l'UUID (champ //unique_id// de la ressource //USER//) à la place de l'//identifier// pour le champ //code_digitiser// de la ressource //SYNTHESE//. | * Utilisation de l'UUID (champ //unique_id// de la ressource //USER//) à la place de l'//identifier// pour le champ //code_digitiser// de la ressource //SYNTHESE//. |
| |
| ===== Format SYNTHESE d'import ===== | ===== 🚀 Format SYNTHESE d'import ===== |
| * But : Permet de fournir les informations sur les observations. | * But : Permet de fournir les informations sur les observations. |
| * Table GeoNature : "//gn_synthese.synthese//". | * Table GeoNature : "//gn_synthese.synthese//". |
| </code> | </code> |
| |
| ===== Format SOURCE d'import ===== | ===== 🚀 Format SOURCE d'import ===== |
| * But : Permet de décrire la source des données.\\ | * But : Permet de décrire la source des données.\\ |
| * Table GeoNature : "//gn_synthese.t_sources//".\\ | * Table GeoNature : "//gn_synthese.t_sources//".\\ |
| * **meta_last_action** [CHAR(1)] : permet d'identifier les lignes ajoutées depuis le dernier import ("//I//"), modifiées ("//U//") ou supprimées ("//D//"). | * **meta_last_action** [CHAR(1)] : permet d'identifier les lignes ajoutées depuis le dernier import ("//I//"), modifiées ("//U//") ou supprimées ("//D//"). |
| |
| ===== Format de la table ACQUISITION_FRAMEWORK d'import ===== | ===== 🚀 Format de la table ACQUISITION_FRAMEWORK d'import ===== |
| * But : permet de fournir les informations sur les cadres d'acquisition des jeux de données.\\ | * But : permet de fournir les informations sur les cadres d'acquisition des jeux de données.\\ |
| * Tables GeoNature : "//gn_meta.t_acquisition_framework//" et aux tables liées //cor_acquisition_framework_actor//, //cor_acquisition_framework_objectif//, //cor_acquisition_framework_publication//, //cor_acquisition_framework_voletsinp// et //sinp_datatype_publications//.\\ | * Tables GeoNature : "//gn_meta.t_acquisition_framework//" et aux tables liées //cor_acquisition_framework_actor//, //cor_acquisition_framework_objectif//, //cor_acquisition_framework_publication//, //cor_acquisition_framework_voletsinp// et //sinp_datatype_publications//.\\ |
| * meta_update_date [DATE(YYYY-MM-DD HH:MM:SS)] : date et heure de mise à jour de l'enregistrement du jeu de données. | * meta_update_date [DATE(YYYY-MM-DD HH:MM:SS)] : date et heure de mise à jour de l'enregistrement du jeu de données. |
| * **meta_last_action** [CHAR(1)] : permet d'identifier les lignes ajoutées depuis le dernier import ("//I//"), modifiées ("//U//") ou supprimées ("//D//") | * **meta_last_action** [CHAR(1)] : permet d'identifier les lignes ajoutées depuis le dernier import ("//I//"), modifiées ("//U//") ou supprimées ("//D//") |
| ===== Format ORGANISM d'import ===== | |
| | |
| | ===== 🚀 Format ORGANISM d'import ===== |
| * But : permet de fournir les informations sur les organismes liées aux jeux de données et cadres d'acquisition. | * But : permet de fournir les informations sur les organismes liées aux jeux de données et cadres d'acquisition. |
| * Table GeoNature : "//utilisateurs.bib_organismes//". | * Table GeoNature : "//utilisateurs.bib_organismes//". |
| * Statut : **🚀 Production (utilisable et fonctionnel)** | * Statut : **🚀 Production (utilisable et fonctionnel)** |
| ==== Description du format ORGANISM ==== | |
| |
| | ==== Description du format ORGANISM ==== |
| Pour chaque ligne : ''nom_du_champ [format du champ] (=//nom_champ_table_geonature//) : description du champ.''. Les champs **en gras** sont obligatoires. | Pour chaque ligne : ''nom_du_champ [format du champ] (=//nom_champ_table_geonature//) : description du champ.''. Les champs **en gras** sont obligatoires. |
| |
| * **meta_last_action** [CHAR(1)] : permet d'identifier les lignes ajoutées depuis le dernier import ("//I//"), modifiées ("//U//") ou supprimées ("//D//"). | * **meta_last_action** [CHAR(1)] : permet d'identifier les lignes ajoutées depuis le dernier import ("//I//"), modifiées ("//U//") ou supprimées ("//D//"). |
| |
| ===== Format USER d'import ===== | |
| | ===== 🚀 Format USER d'import ===== |
| * But : permet de fournir les informations sur les utilisateurs, c'est à dire les personnes désireuses d’accéder aux informations demandant un compte. Normalement, ce fichier ne devrait être utilisé que pour l'import initial mais des champs "meta_*" sont fournis s'il s'avérait nécessaire de l'utiliser aussi en mise à jour. | * But : permet de fournir les informations sur les utilisateurs, c'est à dire les personnes désireuses d’accéder aux informations demandant un compte. Normalement, ce fichier ne devrait être utilisé que pour l'import initial mais des champs "meta_*" sont fournis s'il s'avérait nécessaire de l'utiliser aussi en mise à jour. |
| * Table GeoNature : "//utilisateurs.t_roles//" | * Table GeoNature : "//utilisateurs.t_roles//" |
| |
| ==== Description du format USER ==== | ==== Description du format USER ==== |
| |
| Pour chaque ligne : ''nom_du_champ [format du champ] (=//nom_champ_table_geonature//) : description du champ.''. Les champs **en gras** sont obligatoires. | Pour chaque ligne : ''nom_du_champ [format du champ] (=//nom_champ_table_geonature//) : description du champ.''. Les champs **en gras** sont obligatoires. |
| |
| * **meta_last_action** [CHAR(1)] : permet d'identifier les lignes ajoutées depuis le dernier import ("//I//"), modifiées ("//U//") ou supprimées ("//D//"). | * **meta_last_action** [CHAR(1)] : permet d'identifier les lignes ajoutées depuis le dernier import ("//I//"), modifiées ("//U//") ou supprimées ("//D//"). |
| |
| ===== Format OCCTAX d'import ===== | |
| | ===== 🔍 Format OCCTAX d'import ===== |
| * But : Permet de fournir les informations sur les observations à intégrer aux tables du module OccTax de GeoNature. | * But : Permet de fournir les informations sur les observations à intégrer aux tables du module OccTax de GeoNature. |
| * Table GeoNature : "//pr_occtax.*//". | * Table GeoNature : "//pr_occtax.*//". |
| * Standard : [[https://inpn.mnhn.fr/docs-web/docs/download/221989|OccTax v2]]\\ | * Standard : [[https://inpn.mnhn.fr/docs-web/docs/download/221989|OccTax v2]]\\ |
| * Status : ** 🔍 Bêta (fonctionnel mais des corrections peuvent subvenir) ** | * Statut : ** 🔍 Bêta (fonctionnel mais des corrections peuvent subvenir) ** |
| |
| ==== Description du format OCCTAX ==== | ==== Description du format OCCTAX ==== |
| |
| |
| ===== Format VALIDATION d'import ===== | ===== 🔍 Format VALIDATION d'import ===== |
| * But : Permet de fournir les informations sur les validations des observations à intégrer à la table des validations de GeoNature. | * But : Permet de fournir les informations sur les validations des observations à intégrer à la table des validations de GeoNature. |
| * Table GeoNature : ''//gn_commons.t_validations//''. | * Table GeoNature : ''//gn_commons.t_validations//''. |
| * Standard : [[http://standards-sinp.mnhn.fr/occurrences-de-taxon|OccTax v2]]\\ | * Standard : [[http://standards-sinp.mnhn.fr/occurrences-de-taxon|OccTax v2]]\\ |
| * Statut : **📍 Beta (Implémenté, fonctionnement à surveiller !)** | * Statut : ** 🔍 Bêta (fonctionnel mais des corrections peuvent subvenir) ** |
| |
| ==== Description du format VALIDATION ==== | ==== Description du format VALIDATION ==== |
| |
| |
| ===== Format META_ADDITIONAL_DATA d'import ===== | ===== 🧪 Format META_ADDITIONAL_DATA d'import ===== |
| * But : permet de fournir la description des champs additionnels présent dans les fichiers de données à importer.\\ | * But : permet de fournir la description des champs additionnels présent dans les fichiers de données à importer.\\ |
| * Standard : [[http://standards-sinp.mnhn.fr/occurrences-de-taxon|OccTax v2]] extension //AttributAdditionel//.\\ | * Standard : [[http://standards-sinp.mnhn.fr/occurrences-de-taxon|OccTax v2]] extension //AttributAdditionel//.\\ |
| * Status : **⚠️ Alpha (non utilisé ; présent uniquement pour fournir une aide)** | * Statut : **🧪 Alpha (non utilisé ; présent uniquement pour fournir une documentation)** |
| |
| ==== Description du format META_ADDITIONAL_DATA ==== | ==== Description du format META_ADDITIONAL_DATA ==== |
| | Actuellement, ce fichier peut être fourni pour fournir une documentation des informations stockées dans les champs ''additional_data'' des différents fichiers CSV. Il ne permet pas d'ajouter des colonnes aux fichiers CSV car l'ordre et le nom des colonnes doit être respectés dans les différents fichiers CSV.\\ |
| Pour chaque ligne : ''nom_du_champ [format du champ] (=//nom_attribut_standard//) : description du champ.''. Les champs **en gras** sont obligatoires. | Pour chaque ligne : ''nom_du_champ [format du champ] (=//nom_attribut_standard//) : description du champ.''. Les champs **en gras** sont obligatoires. |
| |
jpmilcent