Documentation du module
Présentation
1. Objectif
Le module permet d’exposer dans OpenProd des données issues d’une base SQL externe, sans développement spécifique pour chaque jeu de données.
L’utilisateur définit une connexion, saisit une requête SQL de lecture, puis laisse le module créer le modèle OpenProd et l’interface associée.
Le résultat final est un modèle manuel OpenProd alimenté à partir de la requête distante, avec sa vue liste, sa vue formulaire, son action, son menu et un cron de rechargement.
2. Principe général
- Créer une configuration de connexion SQL externe et tester l’accès.
- Créer une source de données, saisir une requête SQL et prévisualiser le résultat.
- Générer le modèle OpenProd, ses champs, ses vues et son menu.
- Charger ou recharger les données depuis la base distante vers le modèle généré.
Installation
1. Prérequis
Le module repose sur SQLAlchemy et sur les drivers Python correspondant aux connecteurs utilisés :
- psycopg2 pour PostgreSQL
- pymysql pour MySQL
- pymssql pour SQL Server
Le connecteur SQLite est également supporté.
Tous les drivers sont téléchargéq lors de l'installation du module.
2. Point d’attention
Si le driver Python correspondant au connecteur choisi n’est pas installé sur le serveur, le test de connexion et l’ouverture de session échoueront avec un message explicite.
Configuration
Le module ajoute un menu d’administration contenant :
- Sources de données
- Configurations de connexion
2. Configuration de connexion
Une configuration contient notamment :
- un nom unique de configuration
- un connecteur
- un serveur et un port si nécessaire
- une base cible
- un utilisateur et un mot de passe si le connecteur l’exige
- un timeout de connexion
3. Test de connexion
Le bouton Tester la connexion vérifie que la session SQL externe peut être ouverte.
Le résultat est enregistré dans un journal directement sur la configuration.
En cas d’erreur, le message remonte une information exploitable pour l’utilisateur : cible visée, timeout éventuel et détail technique retourné par le driver SQL.
Paramétrage d'une source
1. Informations principales
Une source de données associe :
- un nom unique de source
- une configuration de connexion
- une requête SQL de lecture
- un nom technique de base pour générer le modèle OpenProd
2. Règles sur la requête SQL
La requête est validée avant exécution. Le module n’accepte que des requêtes de lecture.
- les requêtes SELECT sont autorisées
- les requêtes WITH sont acceptées si elles débouchent sur une lecture
- les mots-clés de modification comme INSERT, UPDATE ou DELETE sont refusés
- les requêtes multiples sont interdites
3. Colonne obligatoire
La requête doit obligatoirement exposer une colonne Name.
Cette colonne est transformée en champ x_name dans le modèle généré et sert de base au display_name OpenProd.
4. Variable de date
La variable %date peut être utilisée dans la requête.
Au moment de l’exécution, elle est remplacée par la dernière date de synchronisation connue.
Exemple :
SELECT Name, code, date_modification FROM ma_vue_source WHERE date_modification > %date
5. Prévisualisation
Le bouton Prévisualiser la requête exécute une version limitée de la requête et affiche le résultat directement dans la fiche.
Cette étape sert à contrôler les colonnes retournées et la cohérence du jeu de données avant de générer le modèle.
6. État de la source
Le workflow de la source est volontairement simple :
- Brouillon : la requête et la structure peuvent être modifiées
- Modèle et interface chargés : le modèle existe, la requête est verrouillée, seuls les rechargements sont attendus
Pour modifier la structure après génération, il faut utiliser le bouton Brouillon, puis relancer la création ou mise à jour du modèle et de l’interface.
Utilisation du module
1. Création du modèle et de l’interface
Le bouton Créer ou mettre à jour le modèle et l’interface analyse les colonnes de la requête, crée ou met à jour le modèle manuel OpenProd, ses champs, sa vue liste, sa vue formulaire, son action, son menu et son cron de rechargement.
La conversion des colonnes suit les règles suivantes :
- Name devient x_name
- id devient x_source_id pour éviter les collisions avec l’identifiant OpenProd
- les autres colonnes deviennent des champs x_* sécurisés
- le champ technique x_user_id est ajouté pour tracer l’utilisateur créateur des enregistrements importés
2. Chargement des données
Le bouton Charger ou recharger les données exécute la requête source complète, vide les enregistrements déjà présents dans le modèle généré, puis recrée les lignes à partir du résultat courant.
Le chargement est donc un rechargement complet, et non une mise à jour ligne par ligne.
Cette stratégie simplifie la maintenance et garantit que le contenu du modèle reflète exactement le résultat SQL courant.
3. Ouverture de la liste générée
Le bouton Ouvrir la liste générée ouvre directement l’action créée pour le modèle généré, ce qui permet de consulter les données importées comme n’importe quel objet OpenProd.
4. Vidage des données
Le bouton Vider les données du modèle supprime les lignes importées sans supprimer le modèle, ses champs ni son interface.
5. Rafraichir les données automatiquement
Pour rafraichir les données deux options s'offrent à vous :
- Utiliser le bouton d'action de rafraichissement des données présent dans la vue formulaire
- Activer le cron créé automatiquement en même temps que le modèle et lui donner une valeur temporelle.