Dolibarr avancé : ETL pour réduire les erreurs

Dolibarr avancé : ETL pour réduire les erreurs d’alimentation de données

Comment automatiser l’Extract‑Transform‑Load (ETL) dans Dolibarr et garantir la qualité de vos données ?

1. Pourquoi passer à l’ETL avec Dolibarr ?

Problématique Conséquence Solution ETL
Saisie manuelle dans plusieurs modules (clients, fournisseurs, stock, comptes) Doublons, champs vides, incohérences entre CRM et comptabilité Extraction centralisée → Transformation normalisée → Chargement automatisé
Décisions basées sur des rapports en temps réel Décisions erronées, perte de confiance des utilisateurs Pipeline fiable qui rafraîchit les indicateurs chaque nuit
Besoin de synchroniser des systèmes externes (e‑commerce, CRM marketing, ERP tiers) Processus laborieux, erreurs de mapping Connecteurs API/ODBC ou scripts de connexion à des bases tierces

En bref : l’ETL transforme un processus sujet aux erreurs humaines en une chaîne de production où chaque étape est testée, versionnée et traçable.

2. Architecture type d’un pipeline ETL sous Dolibarr

+----------------+      +----------------------+      +---------------------+

| Source 1       | ---> | Extraction (API /    | ---> | Zone de staging     |

| (BD externes)  |      |  fichiers CSV, etc.) |      | (tables temporaires)|

+----------------+      +----------------------+      +---------------------+

          |                                                   |

          v                                                   v

+----------------+      +----------------------+      +---------------------+

| Source 2       | ---> | Extraction (DB SDBD) | ---> | Transformation       |

| (ERP, CRM…)    |      |  ou API)             |      | Mapping, nettoyage   |

+----------------+      +----------------------+      +---------------------+

                                            |

                                            v

                                      +-----------------+

                                      | Validation &    |

                                      | Contrôle d'ERREUR |

                                      +-----------------+

                                            |

                                            v

                                   +-------------------------------+

                                   | Chargement dans les modules    |

                                   | Dolibarr (CRUD natif ou API)   |

                                   +-------------------------------+

  • Zone de staging : tables temporaires ou fichiers temporaires qui sont repris par des scripts de transformation.

  • Transformation : scripts PHP, Python ou Bash qui appliquent les règles de mapping, les règles de normalisation (ex. : « TVA = 16 % », « Code client = 0», etc.).

  • Chargement : appels aux fonctions addObject, updateObject de Dolibarr ou aux API REST de Dolibarr (plus sûr pour les versions 18+).

3. Étapes détaillées pour un ETL robuste

3.1. Extraction

Méthode Avantages Exemple d’implémentation
Export CSV Simple, aucun driver spécial php -r "require('fpdf.php'); $o= new Dolibarr\Dolibarr; $o->cron_import_csv('listpartners.csv');"
API REST (Dolibarr 18+) Authentification OAuth, découplage curl -X GET "https://dolibarr.example.com/api/v1/contacts?status=active"
SQL Direct (mysql, pgsql) Accès à plusieurs tables simultanément SELECT id, name FROM llx_c_client WHERE export_flag='1';

Conseil : Toujours enregistrer les identifiants dans un fichier .env ou un coffre‑fort (Vault, AWS Secrets Manager) et ne jamais les hard‑coder.

3.2. Staging

  • Tables temporaires : tmp_import_customers, tmp_import_products.

  • Vérifier les charset : Forcer utf8mb4 pour éviter les “àââ” lors du chargement.

  • Journal : Créez une table de log etl_log (job_id, step, status, line_number, message).

3.3. Transformation – Règles essentielles à appliquer

Type de règle Exemple concret Implémentation
Normalisation des intitulés client_type → entity_type (partenaire, Prospect, etc.) $row['entity_type'] = $row['client_type'] === 'prospect' ? 'prospect' : 'customer';
Nettoyage de champs Supprimer les espaces superflus, convertir '' → NULL trim($row['email']), $row['email'] = $row['email'] !== '' ? $row['email'] : NULL;
Déduplication Filtrer les contacts déjà importés (lookup sur external_id) SELECT id FROM llx_crm_contact WHERE external_id='${row['ext_id']} LIMIT 1;
Contrôle de format Date ISO, email RFC 5322, TVA valide DateTime::createFromFormat('d/m/Y', $row['birthdate'])
Mapping multi‑table Une ligne de source produit → llx_product, llx_product_category, llx_product_price $product['category_id'] = getCategoryId($product['cat_code']);

Astuces : Utilisez des transactions (BEGIN; … COMMIT;) pour chaque lot d’enregistrement ; ainsi, en cas d’erreur, tout le lot revient en arrière.

3.4. Chargement

  1. Via les fonctions PHP natives de Dolibarr (préconisé) 

    require_once '/path/to/dolibarr/ldropdb.php';
    
$db = new \Dolibarr\Dolibarr;
    
foreach ($data as $record) {
    
   $object = new Contact($db);
    
   $object->ref = $record['external_id'];        // champ unique utilisé pour mise à jour
    
   $object->email = $record['email'];
    
   $object->name  = $record['name'];
    
   if (!empty($record['status'])) $object->status = $record['status'];
    
   $object->add();   // création ou update selon le flag 'ref' existant
    
}

  2. Via l’API REST (Dolibarr ≥ 18) – plus sûr côté sécurité 

    curl -X PUT "https://dolibarr.example.com/api/v1/contact/${id}" \
    
    -H "Authorization: Bearer $TOKEN" \
    
    -H "Content-Type: application/json" \
    
    -d '{"email":"new@email.tld","status":"client"}'

  3. Gestion des erreurs

    • Loguer chaque échec avec l’ID du lot et le message d’erreur.

    • Marquer les enregistrements “poison” (ex. : valeur hors domaine) pour recommission manuelle.

4. Bonnes pratiques pour limiter les erreurs

Problème fréquent Solution préventive
Erreurs de synchronisation Utiliser des verrous (« SELECT GET_LOCK ») lors de l’écriture simultanée.
Mauvaise gestion des langages Toujours traiter les chaînes en UTF‑8 et valider en mb_detect_encoding.
Mauvaise prise en compte des dépendances Charger d’abord les référentiels (categories, unités) avant les enregistrements détaillés.
Perte de performance Partitionner le lot en sous‑blocs (ex. : 1 000 lignes) pour éviter les blocages de connexion MySQL.
Aucun audit Conserver le dump CSV/JSON original pour chaque exécution d’ETL.
Mise à jour de Dolibarr S’assurer que la version cible possède les mêmes API/objets ; tester les mappings dans un environnement de staging.
Sécurité des credentials Ne jamais mettre en clair les clefs d’API ; recourir à des _environment variables ou à un secret manager.

5. Exemple complet d’une tâche cron ETL (PHP)

<?php

// file : /var/www/etl/daily_export.php

require_once __DIR__.'/../dolibarr/htdocs/main.inc.php';   // charge le chargeur Dolibarr
// 1️⃣  Extraction (exemple : récupération du CSV externe)

$sourceCsv = '/srv/data/exports/customers_'.date('Ymd').'.csv';

if (!file_exists($sourceCsv)) {

    exit("File source not found\n");

}
// 2️⃣  Staging – création de la table temporaire

$db = \Dolibarr\Dolibarr::get Connexion();   // dossier de connexion globale

$db->query('CREATE TEMPORARY TABLE tmp_import_customers ( 

    ext_id VARCHAR(100), 

    name   VARCHAR(255), 

    email  VARCHAR(255), 

    status ENUM('','prospect','client','supplier') NOT NULL 

) ENGINE=MEMORY;');
// 3️⃣  Chargement en mémoire

$handle = fopen($sourceCsv, 'r');

$db->query('LOCK TABLES tmp_import_customers WRITE;');

while (($row = fgetcsv($handle)) !== false) {

    $db->query('INSERT INTO tmp_import_customers VALUES (?,?,?,?)', 

              [$row[0], $row[1], $row[2], $row[3]]);

}

$db->query('UNLOCK TABLES;');

fclose($handle);
// 4️⃣  Transformation – exemple de règle de validation

$valid = true;

$db->query('SELECT ref, ext_id FROM llx_c_client WHERE ext_ref = ext_id');

while ($row = $db->fetch_assoc()) {

    // duplique détectée

    $msg = "Duplication ext_id='". $row['ext_id'] . "'already exists in llx_c_client";

    logError($msg);

    $valid = false;

}
// 5️⃣  Chargement dans Dolibarr

if ($valid) {

    foreach ($db->fetch_all('SELECT * FROM tmp_import_customers') as $c) {

        $contact = new \Dolibarr\Contact($db);

        $contact->ref = $c['ext_id'];           // champ externe

        $contact->name  = $c['name'];

        $contact->email = $c['email'];

        $contact->status = $c['status'];

        $contact->add();   // crée ou met à jour selon existence du ref

    }

}
// 6️⃣  Log final

$audit = fopen('/var/www/etl/logs/etl_'.date('Ymd').'.log','a');

fwrite($audit, "Job ".date('Ymd H:i:s')." – ".$valid?"OK":"ERR\n");

fclose($audit);

?>

Note : le script ci‑dessus doit être appelé depuis le crontab (0 2 * * * /usr/bin/php /var/www/etl/daily_export.php), de manière à fournir un point d’exécution unique et un historique des exécutions.

6. Checklist de déploiement d’un ETL fiable

✅ Action
1 Créer un espace de développement (database & fichiers) isolé du reste de prod.
2 Versionner le code (Git) et le déployer via CI/CD avec tests automatisés.
3 Implémenter des tests unitaires sur les règles de mapping (PHPUnit, PyTest).
4 Mettre en place un process de sauvegarde du dump source avant chaque import.
5 Ajouter le logging structuré (JSON → ElasticSearch, ou fichiers etl_*.log).
6 Configurer des alertes (Zabbix, Prometheus) sur les taux d’erreur > 1 %.
7 Documenter les règles métiers et les exceptions (ex : “les clients avec TVA = 0 sont prospect”).
8 Faire un test de charge (ex. : 10 000 lignes) pour s’assurer du respect des délais SLA.
9 Planifier une fenêtre de maintenance lors des premiers déploiements (hors horaires critiques).
10 Réaliser régulièrement une audit de qualité des données (remplissage de champs obligatoires, conformité RGPD).

7. Conclusions

  • L’ETL n’est pas une fonctionnalité “magique”, mais un cadre de travail qui impose la régularité, la traçabilité et le contrôle à chaque étape du flux de données.

  • En combinant l’API native de Dolibarr (ou les fonctions CRUD) avec des scripts PHP/Python robustes, on peut transformer des flux hétérogènes (CSV, API tierces, bases externes) en entrées fiables pour les modules de gestion (CRM, stock, comptabilité).

  • Les bonnes pratiques de validation, de gestion des erreurs et de journalisation permettent de réduire de façon exponentielle le nombre de tickets liés aux “données incohérentes”.

  • Un pipeline ETL bien conçu devient un actif pour votre organisation : il libère du temps d’équipes opérationnelles, améliore la qualité des reporting et facilite l’évolution future (intégration de nouveaux modules ou de nouveaux fournisseurs de données).

À retenir : chaque ligne de données qui entre dans Dolibarr doit passer par l’étape de validation avant d’être persistée. Investir du temps dans la conception de votre pipeline ETL, c’est investir dans la fiabilité de tout votre ERP/CRM.

Vous avez besoin d’une aide concrète ?

  • Modèles de scripts prêts à être adaptés, ou

  • Assistance pour la mise en place d’un framework d’,ETL basé sur Docker + GitLab CI,

N’hésitez pas à me le préciser ! 🚀

Publications similaires