Introduction
Les champs binaires sont discrets mais omniprésents dans toute installation Odoo professionnelle. Chaque fois qu’un utilisateur ajoute un contrat signé, une fiche technique produit ou le logo d’une société à une fiche, un champ binaire gère le fichier en coulisse. Savoir comment ces données sont stockées, où elles se retrouvent et quand privilégier un autre type de champ change tout dès qu’on conçoit des formulaires personnalisés ou qu’on étend des modèles Odoo.
Ce guide explique ce que contient un champ binaire, l’impact du mode d’attachement sur le stockage et les performances, comment le créer via Odoo Studio ou en Python, et illustre des cas concrets dans le CRM, les RH, la gestion des stocks et plus encore.
Qu’est-ce que le champ binaire dans Odoo
Dans l’ORM Odoo, le champ binaire (fields.Binary) sert à conserver des données binaires brutes : fichiers, documents ou images qu’un utilisateur téléverse sur une fiche. Dans les vues de formulaire, il se présente généralement sous la forme d’un contrôle pour uploader et télécharger un fichier en un clic.
Le point technique majeur porte sur l’endroit où les octets finissent par être gardés. Dans les versions récentes d’Odoo, le mode par défaut place les fichiers en mode attachement : le contenu est enregistré dans la table ir.attachment et dans le filestore du serveur, tandis que la colonne du modèle contient seulement une référence vers cet enregistrement. Cette organisation évite d’alourdir les tables métier et profite du mécanisme natif de gestion des fichiers d’Odoo.
Dans Odoo Studio, l’option apparaît sous le nom « File ». Le widget propose un simple bouton d’upload/téléchargement dans les formulaires. Pour les images, Odoo propose aussi un type dédié, fields.Image, qui ajoute redimensionnement automatique et aperçu miniature — utile lorsqu’on veut une expérience visuelle optimisée.
Exemple de définition d’un champ binaire dans un modèle Python :
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_signed_contract = fields.Binary(
string='Signed Contract',
attachment=True,
)
x_signed_contract_filename = fields.Char(
string='Signed Contract Filename',
)
Remarquez le champ compagnon x_signed_contract_filename. Associer un champ Binary à un champ Char pour le nom de fichier est un pattern courant : Odoo s’appuie sur ce suffixe _filename pour conserver et afficher le nom d’origine. Sans ce champ, les téléchargements aboutissent souvent avec un nom générique.
Comment fonctionne ce champ
Quand vous déclarez un champ binaire dans le modèle, Odoo crée automatiquement la colonne lors de l’installation ou mise à jour du module — aucune opération SQL manuelle n’est requise.
Modes de stockage
Le paramètre attachment d’un champ binaire contrôle où les octets du fichier sont réellement stockés :
- attachment=True (recommandé) : Le contenu est enregistré dans ir.attachment, lié au document par le nom du modèle et l’ID de l’enregistrement. La colonne du modèle ne contient qu’une référence. Ce mode garde les tables métier légères et utilise le filestore d’Odoo.
- attachment=False : Les données encodées en base64 sont stockées directement dans la colonne du modèle. Les tables grossissent vite et les requêtes deviennent lentes — éviter ce mode pour tout fichier dépassant la taille d’une vignette.
Format des données
Les champs binaires utilisent l’encodage base64 pour stocker et transmettre les fichiers. Lorsque vous lisez un champ via l’ORM ou l’API XML-RPC, vous obtenez une chaîne base64 ; idem à l’écriture : il faut fournir une chaîne base64.
Concrètement, cela implique d’encoder avant d’écrire et de décoder après lecture :
import base64
# Writing a file to a Binary field
with open('document.pdf', 'rb') as f:
encoded = base64.b64encode(f.read()).decode('utf-8')
record.write({'x_signed_contract': encoded})
# Reading a file from a Binary field
raw_bytes = base64.b64decode(record.x_signed_contract)
Attributs essentiels du champ
Voici les paramètres les plus utiles à configurer sur un champ binaire dans Odoo :
- attachment : Booléen. Détermine si le contenu est enregistré dans ir.attachment (True) ou dans la colonne du modèle (False). Valeur par défaut : True dans les versions récentes.
- string : Libellé affiché dans l’interface.
- required : Rend le champ obligatoire avant enregistrement.
- compute : Permet de lier une méthode Python pour calculer la valeur, utile par exemple pour générer un PDF à la volée.
- store : Associé à compute, indique de sauvegarder la valeur calculée en base.
- groups : Restreint la visibilité aux groupes d’utilisateurs Odoo sélectionnés — crucial pour les documents sensibles.
- copy : Contrôle la duplication du contenu lors d’un copier d’enregistrement. Le comportement par défaut varie selon le mode attachment et la version d’Odoo.
La sous-classe fields.Image
fields.Image est une spécialisation de fields.Binary apparue avec Odoo 13. Elle applique un redimensionnement automatique jusqu’à une dimension maximale configurable, fournit une vignette pour l’aperçu et affiche un rendu image dans les formulaires. Pour les photos produits, portraits ou logos, privilégiez fields.Image : elle limite les uploads trop volumineux et améliore l’expérience utilisateur.
Affichage dans les vues
En formulaire, le widget par défaut offre un bouton d’upload/téléchargement. Pour les images, utilisez le widget image pour obtenir une vignette. En listes, on évitera d’afficher le champ binaire brut car Odoo chargerait le contenu complet pour chaque ligne — mieux vaut montrer une icône ou un indicateur booléen signalant la présence d’un fichier.
Cas d’usage en entreprise
Le champ binaire se retrouve dans de nombreux modules Odoo. Voici cinq usages concrets et fréquents en entreprise.
CRM : stocker NDA ou contrats signés sur la fiche client
Les équipes commerciales ont souvent besoin d’attacher un contrat signé directement à une fiche client ou opportunité. Un champ binaire sur res.partner ou crm.lead donne un accès en un clic au document depuis l’interface Odoo, sans recourir à une solution externe de gestion documentaire, et garde l’information là où les commerciaux la cherchent.
RH : conservation des documents employés
Les RH doivent archiver pièces d’identité, permis, contrats signés ou certificats de formation. Un champ binaire sur hr.employee permet de centraliser ces documents sous le contrôle des permissions Odoo. En combinant groups et droits d’accès, seuls les responsables RH peuvent consulter les fichiers sensibles, tandis que d’autres managers voient la fiche sans y accéder.
Stocks : fiches techniques et fiches de sécurité
Pour les produits techniques, on attache souvent des fiches techniques PDF, fiches de sécurité ou certificats qualité. Un champ binaire sur product.template offre aux achats et à l’entrepôt l’accès direct aux documents depuis la fiche produit — une personnalisation courante et simple à implémenter.
Ventes : tampon de l’entreprise ou signature autorisée
Certaines entreprises intègrent un tampon ou une signature autorisée sur les devis et confirmations imprimés. Un fields.Image sur res.company stocke cet élément visuel et permet son insertion automatique dans les rapports QWeb, évitant des manipulations manuelles et garantissant que chaque document imprimé contient la même signature.
Comptabilité : justificatif scanné sur les notes de frais
La gestion des notes de frais nécessite souvent d’attacher le reçu scanné ou la facture au justificatif. Le système d’attachements d’Odoo gère cela nativement, mais pour des modèles personnalisés un champ binaire fournit une solution simple pour conserver la copie du reçu et l’intégrer dans les workflows d’approbation.
Créer ou personnaliser un champ binaire
Trois méthodes pour ajouter un champ binaire selon vos besoins techniques et de gouvernance.
Via Odoo Studio (sans code)
Odoo Studio permet d’ajouter un champ binaire sans écrire une ligne de code. Les étapes :
- Ouvrir Odoo Studio depuis le menu principal.
- Aller sur le formulaire cible.
- Glisser-déposer un champ « File » depuis le sélecteur de champs sur le formulaire.
- Configurer le libellé et les conditions de visibilité dans le panneau de propriétés.
- Enregistrer et fermer Studio.
Studio crée le champ préfixé x_studio_... et utilise par défaut le mode attachement. Aucune configuration base de données n’est nécessaire côté utilisateur — c’est la méthode la plus accessible pour ajouter rapidement une zone d’upload.
Via Python dans un module personnalisé
Pour des personnalisations versionnées et déployables, on définit les champs directement en Python dans un module. C’est la méthode recommandée pour les projets sérieux :
from odoo import fields, models
class HrEmployee(models.Model):
_inherit = 'hr.employee'
x_id_document = fields.Binary(
string='ID Document',
attachment=True,
groups='hr.group_hr_user',
)
x_id_document_filename = fields.Char(
string='ID Document Filename',
)
Après avoir déclaré le champ, ajoutez-le dans la vue formulaire avec le widget binary et l’attribut filename pointant vers le champ Char compagnon. Odoo gère la colonne en base lors de l’installation ou la mise à jour du module — cette approche fonctionne sur Odoo.sh comme sur des installations locales.
Via l’API XML-RPC
Si vous automatisez la configuration (scripts de déploiement, notebooks), vous pouvez créer des champs binaires via l’API XML-RPC :
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_document',
'field_description': 'Custom Document',
'model_id': model_id,
'ttype': 'binary',
'state': 'manual',
}]
)
Le paramètre state: 'manual' signifie que le champ est créé manuellement (pas par un module). Les champs créés par l’API utilisent aussi par défaut le mode attachement dans les versions actuelles — pratique pour des scripts d’initialisation automatisés.
Bonnes pratiques
1. Toujours utiliser attachment=True
Sauf besoin technique très spécifique, optez pour attachment=True. Cela protège vos tables métier de la croissance explosive et évite des ralentissements de requêtes. Pour tout fichier plus volumineux qu’une petite vignette, le mode attachement est la norme.
2. Toujours ajouter un champ Char pour le nom de fichier
Ajoutez systématiquement un champ _filename à côté du Binary. Sans lui, l’interface ne peut pas restaurer le nom d’origine et les téléchargements s’appellent souvent « download ». Cette simple ligne améliore nettement l’expérience utilisateur.
3. Privilégier fields.Image pour les images
Pour photos produits, portraits ou logos, utilisez fields.Image : elle limite la taille maximale, génère des vignettes et évite le stockage inutile d’images gigantesques. Adapter le type de champ au contenu attendu est une règle de base pour un modèle de données propre.
4. Restreindre l’accès via groups
Les documents sensibles (fichiers employés, contrats, pièces comptables) doivent être protégés via l’attribut groups. Cette pratique préserve la confidentialité et facilite les audits en environnements réglementés.
5. Gérer correctement l’encodage base64 dans le code
Lorsque vous manipulez des champs binaires en code, encodez et décodez explicitement : base64.b64encode(file_bytes).decode('utf-8') pour écrire, base64.b64decode(value) pour lire. Beaucoup de bugs d’intégration proviennent d’un encodage mal géré — testez toujours avec de vrais fichiers.
Pièges fréquents
Les risques d’utiliser attachment=False pour des fichiers volumineux
Stocker des fichiers directement en base peut rapidement alourdir vos tables PostgreSQL. Quelques PDFs sauvegardés en attachment=False suffisent pour ajouter des centaines de mégaoctets à une table, ralentissant toutes les requêtes liées. Corriger ce choix après coup nécessite une migration sur-mesure et une planification soigneuse.
Oublier le champ nom de fichier
Sans le champ Char compagnon, les téléchargements portent souvent un nom générique, ce qui donne une impression d’inachevé pour l’utilisateur. Ajouter ce champ prend une minute et doit être systématique sur tout champ binaire visible en formulaire.
Confondre Binary et Image
Utiliser un Binary pour des images prive l’interface du redimensionnement automatique et des vignettes fournis par fields.Image, laissant l’utilisateur téléverser des fichiers trop lourds. À l’inverse, fields.Image sur un PDF provoquera des erreurs car Odoo tentera de traiter le fichier comme une image. Règle simple : choisir le type selon le contenu attendu.
Inclure des champs binaires dans les vues liste
Afficher un champ binaire dans une vue liste force le chargement du contenu complet pour chaque ligne visible — sur cinquante enregistrements, cela peut représenter des mégaoctets transférés à chaque rafraîchissement. Préférez un champ booléen calculé ou une icône pour indiquer la présence d’un fichier.
Ne pas vérifier False avant traitement
Un champ binaire vide renvoie False en Python, pas une chaîne vide ni des octets vides. Tenter de décoder False déclenche un TypeError. Toujours vérifier : if record.x_document: data = base64.b64decode(record.x_document). Ceci est essentiel dans les méthodes compute, actions serveur ou tout code traitant des fichiers.
Conclusion
Le champ binaire est simple mais essentiel dans le modèle de données Odoo. Il permet d’intégrer le stockage de fichiers et documents au système, en respectant les contrôles d’accès et le filestore natif.
Les habitudes à adopter : privilégier attachment=True, ajouter un champ nom_de_fichier, utiliser fields.Image pour les images, restreindre l’accès pour les documents sensibles et maîtriser l’encodage base64 en code. Ces bonnes pratiques évitent les problèmes les plus fréquents avant qu’ils n’apparaissent en production.
Que vous ajoutiez un champ via Studio, codiez un module Python ou gériez la création via l’ORM ou XML-RPC, bien concevoir les champs binaires dès le départ rend votre implémentation Odoo plus propre et plus robuste.
Chez Dasolo, nous accompagnons les entreprises pour implémenter, personnaliser et optimiser Odoo sur tous les métiers. Besoin d’aide pour choisir les bons types de champs, organiser des flux de fichiers ou développer un module complet ? Notre équipe peut vous assister. Contactez-nous pour discuter de votre projet Odoo.