Import Monitoring

[jacquesfize]

Ajout de l'import dans le module Monitoring

👨‍💻 Tous les développements sont accessibles dans la Pull Request suivante : > #390

Depuis la version 2.15.0, le module d'import est désormais intégré à GeoNature (PnX-SI/GeoNature#3269). Il permet à chaque module de configurer son propre processus d'importation de données. L’intégration d’un import dans le module Monitoring suit trois grand axes :

1. Création d’un fichier de configuration contenant une classe Python qui gère :
   • le prétraitement,
   • les contrôles de données,
   • l’import final des données dans les tables du module de destination,
   • la suppression des données en cas de suppression de l'import.
   • la génération du graphique présent dans le rapport d'import Bokeh
   • et les statistiques (ex. : nombre d’habitats pour le protocole occhab).
2. Création des migrations Alembic pour générer une table transitoire dédiée aux traitements et aux contrôles des données importées depuis un fichier source.
3. Modification du script d’installation d'un sous-module Monitoring afin d’ajouter une destination d’import à chaque installation de protocole (sous-module Monitoring).

Ce développement a été réalisé dans le cadre d’un financement de PATRINAT et du ministère de la Transition écologique, avec Natural Solutions en charge des travaux d'intégration dans le module Monitoring.

1. Saisie de constantes dans la correspondance des champs

Lors d’un import de nouvelles visites sur un site existant, l’identifiant de ce dernier est nécessaire. Dans le fonctionnement existant, une solution est d'inclure cette valeur directement dans le fichier source. Cependant, cela impose à l’utilisateur de la récupérer manuellement et de modifier le fichier, ce qui est peu pratique.

1.1 ✅ Solution proposée

Nous proposons de pouvoir définir une valeur constante directement dans le formulaire de mise en correspondance des champs, au lieu de la déclarer dans le fichier source. Cette fonctionnalité est disponible pour tous les champs.

Pour cela, nous avons intégrer un toggle qui passer d'un mode à un autre (valeur constante, colonne dans le fichier source).

Capture.video.du.19-06-2025.15_05_29.webm

Cette fonctionnalité repose sur le système de dynamic-forms côté frontend, permettant de générer à la fois des champs HTML simples (texte, nombre, etc.) et des champs plus liés à GeoNature : listes, nomenclatures, taxons, jeux de données, etc.

Déjà discuté sur PnX-SI/gn_module_import#500.

1.2 Évolution des field-mappings

Pour intégrer la notion de "valeur constante", il a fallu modifier le format des field-mapping dans la base de données selon le format suivant :

[
  { "<nom_champ1>": { "constant_value": "2025-04-03" } }, // valeur constante
  { "<nom_champ2>": { "column_src": "<colonne_du_fichier>" } } // valeur issue du fichier
]

1.3 Déplacement de la sélection du JDD et prise en charge du multi-JDD

Accompagnant l'intégration de la valeur constante, la sélection du jeu de données (JDD) a été déplacée dans l’étape de mise en correspondance des champs.

Cette modification répond à l’introduction du multi-JDD, permettant l’importation simultanée de données vers plusieurs jeux de données.

2. Création d’un import depuis le module Monitoring

Comme pour les autres modules intégrant l’import, plusieurs boutons ont été ajoutés pour faciliter les actions depuis l’interface :

• Liste des sites → Import de sites
• Liste des visites → Import de visites dans le site
• Liste des observations → Import d’observations dans la visite

L'identifiant de l'entité (site, visite, etc.) cible est automatiquement récupéré pour peupler le formulaire de mise en correspondance du nouvel import.
Par exemple, lors d’un import de visites depuis un site, le champ id_site est automatiquement renseigné.

2.1 Pré-peuplement du formulaire de mise en correspondances d'un import

Pour peupler l'identifiant d'un site ou d'une visite dans laquelle on importer de la données, il était nécessaire d'ajouter un comportement permettant de définir des valeurs constantes dans le fieldmappings d'un import avant l'étape de mise en correspondances.

✅ Solution proposée

Ces constantes sont définies dans l'URL de la première étape du processus de création de l'import : l'upload. Par exemple, pour l'import de visites dans un site, on redirigera l'utilisateur vers l'URL suivante :

/import/<nom_protocole>/process/<id_import>/upload?id_base_site=102

Ensuite, lors du passage entre l'étape d'upload et de configuration de lecture du fichier source, l'import est crée dans la table gn_imports.t_imports avec un fieldmappings contenant la clé _preset_ contenant une première version du fieldmapping contenant les valeurs constantes indiquées dans l'URL.

{
  "__preset__": {
    "id_base_site": { "constant_value": 102 }
  }
}

Une fois arrivé dans l'étape de correspondance des champs, les champs pré-définis dans _preset_ sont peuplées avec les valeurs indiqués.

3. Ajout d'un protocole dans le module d'import

Cette étape est la plus critique du développement et comprend plusieurs volets :

1. Création d’un fichier actions.py
   Celui-ci définit :
   • les contrôles,
   • le prétraitement,
   • l'import final,
   • la suppression des données,
   • l'affichage de graphiques/statistiques dans le rapport d'import.
2. Modification du script d'installation du module Monitoring, afin d'ajouter les métadonnées nécessaires à l'import.

3.1 Création du fichier actions.py

3.1.1 Contrôles des données

(Faire la liste des contrôles effectuées)

(Interprétation de certains contrôles à partir )

3.2 Modification du script d’installation d’un protocole Monitoring

L'objectif est de permettre l'import de données dans un protocole en insérant les métadonnées adéquates dans le schéma gn_imports.

Le script doit :

1. Créer une nouvelle destination d'import dans gn_imports.bib_destinations (nommée d’après le protocole).
2. Créer les entités du protocole (site, visite, observation) dans gn_imports.bib_entities.
3. Définir les champs de chaque entité dans gn_imports.bib_fields.
4. Lier les champs aux entités via gn_imports.cor_entity_field.

3.2.1 Mise à jour automatique en cas de modification

Dans le module Monitoring, il est possible de mettre à jour la définition des protocoles même après leur installation. En effet, l’interface de saisie repose entièrement sur les fichiers .json.
Cependant, le module d’import nécessite que ces modifications soit appliqués sur le schéma de l'import. Pour cela, il suffit de relancer la commande d’installation du protocole. En cas de changement, un résumé des modifications est affiché.

3.2.2 Conversion JSON → Table bib_fields

Un gros travail de l'intégration de l'import monitoring consiste ) faire la traduction depuis la structure de champs dans Monitorings vers celle des champs définis dans gn_imports.bib_fields . Pour rappel, la table contenant les champs disponibles à l'import ressemble à ça :

CREATE TABLE gn_imports.bib_fields (
	id_field INT PRIMARY KEY,
	name_field VARCHAR(100) NOT NULL,
	fr_label VARCHAR(100) NOT NULL,
	eng_label VARCHAR(100),
	type_field VARCHAR(50),
	mandatory BOOLEAN NOT NULL,
	autogenerated BOOLEAN NOT NULL, -- obsolète
	display BOOLEAN NOT NULL,
	mnemonique VARCHAR,
	source_field VARCHAR,
	dest_field VARCHAR,
	multi BOOLEAN DEFAULT false NOT NULL,
	id_destination INT NOT NULL,
	mandatory_conditions _VARCHAR,
	optional_conditions _VARCHAR,
	type_field_params JSONB
);

Dans l'état actuel du développement, la conversion des champs pour une entité (e.g. visite, site, etc.) se déroule de la manière suivante

• Si elle est géoréférencée, on ajoute les champs :
  • geom_local, wkt (seul champ affiché), geom_4326
• Ajout d’un UUID et d’un identifiant numérique
• Ajout des champs spécifiques au protocole

3.2.3 Quid de la logique conditionnelle sur les champs

Certains champs utilisent des conditions dynamiques (JavaScript) pour définir leur caractère obligatoire ou leur affichage.
⚠️ Dans cette version, ces scripts JS ne sont pas encore pris en charge.

• Si required est un booléen, sa valeur est utilisée.
• Sinon, on considère le champ comme obligatoire par défaut (true).

⚠️ Avant d'importer des données dans le protocole, ce dernier doit être configuré !!!!! ⚠️

[camillemonchicourt]

Intégré dans la version 1.3.0, nécessitant GeoNature 2.17.0 minimum.
Documenté sur https://github.com/PnX-SI/gn_module_monitoring/blob/main/docs/import.md