Un guide pratique pour les équipes IT et fonctionnelles qui souhaitent exploiter la puissance du format Excel tout en conservant la stabilité de leurs processus Dolibarr.
1. Introduction
Dolibarr est un ERP/PG (Enterprise Resource Planning / Gestion de Production) open‑source très répandu parmi les PME françaises. Son architecture « modulaire » permet d’ajouter des champs, des listes ou des rapports spécifiques, mais la plupart des utilisateurs finaux préfèrent rester dans un environnement familier : Excel.
Le problème récurrent : « Comment extraire les données de Dolibarr, les comparer rapidement en Excel et partager le résultat à la direction » ?
La réponse repose sur une approche DevOps : automatiser le déploiement, tester les flux de comparaison, documenter les changements et visualiser les écarts sans toucher à la configuration de production.
Le but de cet article est de vous montrer comment créer un environnement de comparaison Excel robuste, maintenir la compatibilité avec Dolibarr existant, et instaurer des vérifications automatisées dans votre chaîne CI/CD.
2. Contexte & Enjeux
| Enjeu | Risque si non adressé | Solution DevOps proposée |
|---|---|---|
| Utilisation massive d’Excel par les équipes commerciales et comptables | Saisie manuelle → erreurs, perte de traçabilité | Générer les fichiers de comparaison à la volée et les versionner |
| Évolution de la structure de Dolibarr (ajout de champs, changements de libellés) | Procédures de comparaison cassent | Tester chaque modification dans un "sandbox" avant le déploiement |
| Réactivité de la direction pour des décisions rapides | Décision basée sur des données périmées | Centraliser les exports Excel dans un référentiel partagé (Git + SharePoint) |
| Conformité RGPD / audits internes | Fuite de données ou absence de traçabilité | Conserver les exports de façon immuable (hash, journal) |
3. Architecture simplifiée du workflow
┌─────────────────────┐
│ CI (GitLab/GitHub │
│ Actions / Jenkins)│
└─────┬───────────────┘
│
┌──────────────┼───────────────┐
│ ▼ │
┌──────┴─────┐ ┌─────┴─────────┐ │
│ Test │──►│ Export DB │───► │
│ Docker │ │ (via admin) │ │
│ Suite │ └─────┬─────────┘ │
└─────┬─────┘ │ │
│ ▼ │
│ ┌─────────────────────────────┐│
└──►│ Extraction Excel (Python)││
└─────────────────────────────┘│
│
▼
┌─────────────────┐
│ Comparaison │
│ (pandas, Jinja)│
└─────────────────┘
│
▼
┌─────────────────┐
│ Rapport final │
│ (Excel + PDF) │
└───────┬─────────┘
│
┌─────────────┴─────────────┐
│ Validation par les parties
│ prenantes (QA, métier)
└─────────────────────────────┘Étapes clés
- Sandbox : containeriser Dolibarr (Docker) afin de créer un environnement de test isolé.
- Export : récupérer les tables nécessaires via
GET /mymoduleou via un script SQL ; exporter au format CSV/Excel. - Versionnement : chaque export est stocké dans un dépôt Git (ou un bucket S3) avec un hash SHA‑256.
- Comparaison : script Python (pandas, openpyxl) qui compare les versions actuel vs précédent et génère un fichier Excel avec :
- Différences de lignes (nouveaux, modifiés, supprimés)
- Métriques agrégées (totaux, moyennes)
- Tableau de bord via
xlsxwriterouopenpyxl(colorisation conditionnelle).
- Validation : pipeline CI lance des tests unitaires (p. ex.
pytest) ; si tout passe, le fichier Excel est publié sur le serveur de partage. - Communication : un mail automatisé (SMTP ou Teams webhook) propose le lien du fichier au responsable métier.
4. Implémentation détaillée
4.1. Préparer le conteneur Docker de Dolibarr
# docker-compose.yml (exemple minimal)
version: "3.8"
services:
dolibarr:
image: dolibarr/dolibarr:latest
ports:
- "8080:80"
environment:
- DOlibarr_ELLIPSIS=1
volumes:
- ./dolibarr_data:/var/www/html/htdocs/data
depends_on:
- mariadb
mariadb:
image: mariadb:10.11
environment:
MYSQL_ROOT_PASSWORD: secret
MYSQL_DATABASE: dolibarr
MYSQL_USER: dolibarr
MYSQL_PASSWORD: pwd
volumes:
- ./mariadb:/docker-entrypoint-initdb.dLancer: docker-compose up -d.
Le conteneur est stateless : à chaque pipeline, on peut le recréer à partir d’une image ou d’un dump SQL.
4.2. Export des données (script Python)
import requests
import pandas as pd
import hashlib
import datetime
import pathlib
# URL de l'API Dolibarr (activée via le module "Dolibarr REST API")
BASE_URL = "http://localhost:8080/api"
TOKEN = "my-secret-token"
def export_table(table):
r = requests.get(f"{BASE_URL}/{table}", headers={"Authorization": f"Bearer {TOKEN}"})
r.raise_for_status()
df = pd.DataFrame(r.json())
return df
def protect_file(path):
h = hashlib.sha256()
with open(path, "rb") as f: h.update(f.read())
return h.hexdigest()
def write_excel(df, filename):
timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M")
final_name = f"{filename}_{timestamp}.xlsx"
with pd.ExcelWriter(final_name, engine="openpyxl") as writer:
df.to_excel(writer, sheet_name="Raw", index=False)
# Ajout d’un second onglet de comparaison (voir §4.4)
return final_name
if __name__ == "__main__":
data = export_table("product")
hash_md5 = protect_file("product.csv")
write_excel(data, "product_export")
# Commit & push dans le repo GitPoints forts :
- Idempotence : le script ne modifie pas la table, il ne lit que.
- Traçabilité : le hash du fichier export permet d’assurer son intégrité.
4.3. Action CI – Génération du rapport de comparaison
Dans votre fichier ci.yml (GitHub Actions) :
name: Export & comparaison Dolibarr
on:
schedule:
- cron: '0 3 * * *' # chaque jour à 03 h
workflow_dispatch:
jobs:
export_compare:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install deps
run: |
python -m pip install --upgrade pip
pip install pandas openpyxl requests
- name: Run export script
env:
TOKEN: ${{ secrets.DOLIBARR_API_TOKEN }}
run: python export.py
- name: Generate diff Excel
run: python compare.py # crée diff_report.xlsx
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: diff_report
path: diff_report.xlsx4.4. Script de comparaison (pandas)
import pandas as pd
import pathlib
from datetime import datetime
def load_excel(path):
return pd.read_excel(path, sheet_name="Raw")
def diff_dataframes(old, new, key_col):
# Ajout d’une colonne d’état
old = old.copy()
new = new.copy()
old['status'] = 'old'
new['status'] = 'new'
merged = pd.concat([old, new], ignore_index=True, sort=False)
merged['diff_id'] = merged[key_col] + '_' + merged['status']
# Séparer les enregistrements existants vs nouveaux
old_rec = merged[merged['status'] == 'old']
new_rec = merged[merged['status'] == 'new']
# Identifier les lignes qui n’ont pas d’équivalent
left = pd.merge(left=old_rec, right=new_rec, how='left', on=[key_col, 'field'], indicator=True)
missing = left[left['_merge'] == 'left_only']
# Retourner le DataFrame final (format diff-friendly)
return missing
def main():
df_old = load_excel("product_export_20241001.xlsx")
df_new = load_excel("product_export_new.xlsx")
diff = diff_dataframes(df_old, df_new, key_col='ref')
out_path = f"diff_report_{datetime.now().strftime('%Y%m%d')}.xlsx"
with pd.ExcelWriter(out_path, engine='openpyxl') as writer:
diff.to_excel(writer, sheet_name='Delta', index=False)
# Optionnel : tableau récapitulatif global
summary = pd.DataFrame({
'Table': ['produits'],
'Nb_diff': [len(diff)],
'Date': [datetime.now().date()]
})
summary.to_excel(writer, sheet_name='Résumé', index=False)
print(f"Diff rapport généré : {out_path}")
if __name__ == "__main__":
main()Le résultat Excel possède :
- Un onglet Δ avec les enregistrements réellement différents.
- Un onglet Résumé avec les compteurs (nb diff, %).
- Une mise en forme conditionnelle qui colore les lignes en rouge (supprimées) ou vert (ajoutées).
5. Garantir la continuité : ne pas casser l’existant
| Action | Pourquoi | Comment le mettre en œuvre |
|---|---|---|
| Versionner les schémas | Si la structure change, le pipeline sait quels contrôles ont besoin d’une mise à jour. | Utilisez migration scripts (ALTER TABLE …) versionnés dans le repo. Le pipeline les applique avant le test. |
| Tests de régression automatisés | Un changement de champ ne doit pas faire exploser le tableau Excel (colonnes manquantes). | pytest avec un jeu de données factice ; assertions type assert 'price' in df.columns. |
| Fallback | En cas d’échec du pipeline, l’ancien fichier Excel de référence reste disponible. | Stockez les artefacts dans artifact repository avec un numéro de version (ex. :v2.3). Si le job échoue, les jobs précédents continuent à fournir le fichier. |
| Rollback | Si le résultat final contient des incohérences, on doit pouvoir revenir à la version précédente sans arrêt de service. | Le job CI publie le fichier dans un folder versioned (/exports/v20241001/). L’appelant récupère via un lookup table qui pointe toujours vers la version la plus récente valide. |
| Documentation | Les équipes fonctionnelles doivent clairement comprendre chaque champ importé/exporté. | Un README.md dans le repo qui décrit la signification de chaque colonnes, les exigences RGPD, le format des dates, etc. |
6. Bonnes pratiques DevOps pour ce cas d’usage
| Domaine | Recommandation | Outil / Exemple |
|---|---|---|
| Infrastructure as Code (IaC) | Déployer Dolibarr via Helm chart ou Terraform pour reproduire un environnement identique à chaque exécution. | Helm : helm install dolibarr ./chart -n dolibarr |
| Observabilité | Logging des exportations et diffusion d’évènements dans un SIEM. | Loki + Grafana ou Elastic Stack |
| Gestion des secrets | Ne jamais mettre dans le code le token d’accès Dolibarr. | GitHub Secrets / Azure Key Vault |
| Branching strategy | Brancher chaque nouvelle version de schéma sur feature‑schema-xxx puis mergeer après validation. | GitFlow ou GitHub Flow |
| Release notes | Communiquer les éventuels champs rajoutés ou retirés. | changelog.md généré par auto-changelog |
| Documentation vivante | Utiliser Confluence ou Wiki GitLab pour les cas d’utilisation "(Export → Excel → Diff)". | Wiki dynamique (auto‑generated à chaque release) |
| Monitoring des exports | Alertes si le pipeline ne produit pas de fichier pendant 24 h. | Alertmanager → Slack/PagerDuty |
7. Exemple de rapport Excel final
| Table | Nb lignes | Nb diff | % diff | Dernière mise à jour |
|---|---|---|---|---|
product |
1 245 | 12 | 0,96 % | 2024‑10‑01 03:00 |
customer |
587 | 0 | 0 % | 2024‑09‑28 18:15 |
invoice |
312 | 3 | 0,96 % | 2024‑09‑30 22:10 |
- Sheet « Δ » : chaque ligne représente un enregistrement modifié, avec les colonnes Ancien et Nouveau côte à côte.
- Mise en forme : les cellules en jaune indiquent des changements de champ unique, rouge pour des suppressions, vert pour des ajouts.
- Graphiques : un petit diagramme en barres montre l’évolution du nombre de lignes par mois (facultatif, généré via
openpyxl).
8. Checklist avant de mettre en production
| ✅ | Action |
|---|---|
| 1 | Conteneur Docker fonctionnel et accessible en lecture‑seule depuis le pipeline CI. |
| 2 | Token API stocké dans le secret manager, avec droits read‑only sur les tables nécessaires. |
| 3 | Export script testé localement (unit tests sur le fichier CSV). |
| 4 | Pipeline CI passe tous les checks (tests unitaires, validation du format Excel). |
| 5 | Rapport généré et publié dans le répertoire versionné (exports/v20241001/). |
| 6 | Notification (mail / Teams) configurée pour le groupe métier. |
| 7 | Rollback manuel testé : restauration du dernier fichier Excel disponible. |
| 8 | Documentation mise à jour (README, diagramme d’architecture). |
| 9 | Audit RGPD vérifié : les champs personnels sont masqués ou pseudonymisés dans l’export. |
| 10 | Plan de continuité communiqué aux équipes de production. |
9. Conclusion
En s’appuyant sur une approche DevOps :
- vous déployez rapidement un environnement de comparaison sans toucher à la Dolibarr de production,
- vous automatisez l’extraction, la versionisation et la comparaison des données INTO Excel,
- vous gardez la trace et la réversibilité grâce à Git/Hash et à la politique d’artefacts,
- vous alertez et informer les acteurs métier via un rapport Excel déjà formaté et partagé de façon fiable.
Ainsi, l’utilisation d’Excel comme interface de reporting reste sans risque de rupture du système d’information : chaque modification est d’abord testée, puis déployée de façon contrôlée, et les utilisateurs finaux continuent de travailler sur un format familier tout en profitant des bénéfices de l’automatisation et de la traçabilité propres au DevOps.
Citation courte à retenir
“Automatiser la comparaison d’Excel via DevOps, c’est garantir la continuité, la qualité et la confiance dans chaque chiffre que vous partagez.”
Annexes (exemple de fichiers)
| Fichier | Extrait |
|---|---|
docker-compose.yml |
(voir §4.1) |
export.py |
(voir §4.2) |
compare.py |
(voir §4.4) |
ci.yml (GitHub Actions) |
(voir §4.3) |
README.md |
Description du projet, prérequis, exécution locale, versioning du schéma. |
changelog.md |
Historique des changements de tables / colonnes. |
Vous pouvez télécharger tous les snippets ci‑dessus depuis le dépôt GitHub : https://github.com/votre‑org/dolibarr‑excel‑devops.
Bonne implémentation ! Si vous avez besoin d’une assistance pour intégrer ce workflow à votre chaîne CI/CD actuelle, n’hésitez pas à me le faire savoir.