Inleiding
Binaire velden zijn niet glamoureus, maar ze zijn overal in een echte Odoo-implementatie. Elke keer dat een gebruiker een ondertekend contract uploadt, een productdatasheet bijvoegt of een bedrijfslogo op een record opslaat, is er een Binaire veld dat op de achtergrond werkt. Begrijpen hoe het gegevens opslaat, waar die gegevens eindigen en wanneer je een ander veldtype moet gebruiken, maakt een echt verschil wanneer je aangepaste formulieren bouwt of Odoo-modellen uitbreidt.
Deze gids behandelt wat het Binaire veld opslaat, hoe de bijlage-modus opslag en prestaties beïnvloedt, hoe je het kunt maken en aanpassen met Odoo Studio of Python, en praktische zakelijke gebruikscases in CRM, HR, Voorraad en meer.
Wat is het Binaire Veld in Odoo
In de Odoo ORM slaat het Binaire veld (fields.Binary) ruwe binaire gegevens op: bestanden, documenten, afbeeldingen of enige inhoud die een gebruiker naar een record uploadt. Vanuit het perspectief van de gebruiker verschijnt het als een bestand uploadknop in formulierweergaven. Zodra een bestand is bijgevoegd, laat dezelfde knop gebruikers het met één klik downloaden.
Het belangrijkste technische detail is waar die gegevens daadwerkelijk eindigen. Standaard in moderne Odoo-versies gebruiken Binaire velden de bijlage-modus. Dit betekent dat de inhoud van het bestand wordt opgeslagen in de ir.attachment tabel en op de server filestore, niet direct in de modelkolom. De modelkolom bevat alleen een referentie-ID die naar het bijlagenrecord verwijst. Deze aanpak houdt je belangrijkste databasetabellen slank en laat Odoo bestanden efficiënt beheren.
In Odoo Studio is het binaire veld gelabeld als Bestand in de veldkiezer. Het wordt weergegeven als een eenvoudige upload- en downloadcontrole in formulierweergaven. Voor afbeeldingsinhoud biedt Odoo ook een speciaal fields.Image type dat automatische resizing en thumbnail-preview toevoegt. We zullen dat in de relevante secties hieronder behandelen.
Hier is hoe een binaire veld eruitziet in een Python-modeldefinitie:
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_signed_contract = fields.Binary(
string='Ondertekend Contract',
attachment=True,
)
x_signed_contract_filename = fields.Char(
string='Bestandsnaam Ondertekend Contract',
)Let op het bijbehorende x_signed_contract_filename Char-veld. Het combineren van een binaire veld met een Char-veld voor de bestandsnaam is een standaard Odoo-ontwikkelingspatroon. Odoo gebruikt het _filename veld om de oorspronkelijke bestandsnaam in de interface te onthouden en weer te geven. Zonder dit kan de gedownloade bestanden een generieke naam krijgen.
Hoe het Veld Werkt
Wanneer je een binaire veld definieert in het Odoo-datamodel, beheert het framework de kolomcreatie automatisch bij het installeren of upgraden van de module. Geen handmatige SQL is aan jouw kant nodig.
Opslagmodi
De attachment parameter op een binaire veld bepaalt waar de bestandbytes daadwerkelijk worden opgeslagen:
- attachment=True (aanbevolen): Bestandsinhoud wordt opgeslagen in
ir.attachment, gekoppeld aan het record via de modelnaam en record-ID. De modelkolom bevat alleen een referentie-ID. Dit houdt de modeltabellen klein en benut het filestore-systeem van Odoo. - attachment=False: De ruwe base64-gecodeerde gegevens worden rechtstreeks in de databasekolom van het model opgeslagen. Dit zorgt ervoor dat tabellen erg groot worden, wat de queries over het hele model vertraagt. Vermijd deze modus voor alles groter dan een kleine afbeeldings-thumbnail.
Gegevensformaat
Binaire velden slaan gegevens op en geven deze terug als base64-gecodeerde bytes. Wanneer je een binaire veld leest via de Odoo ORM of de XML-RPC API, ontvang je een base64-string. Wanneer je erin schrijft, moet je ook een base64-gecodeerde string opgeven.
In de praktijk betekent dit coderen voordat je schrijft en decoderen nadat je hebt gelezen:
import base64
# Een bestand schrijven naar een Binaire veld
met open('document.pdf', 'rb') als f:
encoded = base64.b64encode(f.read()).decode('utf-8')
record.write({'x_signed_contract': encoded})
# Een bestand lezen van een Binaire veld
raw_bytes = base64.b64decode(record.x_signed_contract)Sleutelveld Attributen
Dit zijn de belangrijkste attributen die je kunt configureren op een Binaire veld in het Odoo-framework:
- attachment: Boolean. Of het moet worden opgeslagen in
ir.attachment(True) of direct in de kolom (False). Standaard: True in recente Odoo-versies. - string: Weergavelabel dat in de interface wordt weergegeven.
- required: Maakt het veld verplicht voordat het record wordt opgeslagen.
- compute: Koppelt een Python-methode om de veldwaarde dynamisch te berekenen, bijvoorbeeld het genereren van een PDF on-the-fly als een Odoo-berekend veld.
- store: Wanneer gebruikt met
compute, slaat de berekende waarde op in de database. - groups: Beperkt de toegang tot het veld tot specifieke Odoo-gebruikersgroepen. Belangrijk voor gevoelige documenten.
- copy: Beheert of de waarde wordt gedupliceerd wanneer een record wordt gekopieerd. Standaarden variëren afhankelijk van de bijlage-modus en Odoo-versie.
De fields.Image Subclass
fields.Image is een gespecialiseerde subklasse van fields.Binary die is geïntroduceerd in Odoo 13. Het voegt automatische afbeeldingsresizing toe tot een configureerbare maximale afmeting, een optionele voorbeeldgrootte voor miniaturen, en rendert een goede afbeeldingspreview in formulierweergaven. Voor het opslaan van productafbeeldingen, partnerfoto's, bedrijfslogo's of enige visuele inhoud, gebruik fields.Image in plaats van een eenvoudig Binaire veld. Het voorkomt overdreven grote uploads en biedt een veel betere gebruikerservaring voor afbeeldingsgegevens.
Hoe het verschijnt in weergaven
In formulierweergaven is de standaardwidget voor een binaire veld een upload- en downloadknop. Voor afbeeldingsinhoud, pas de image widget toe om in plaats daarvan een miniatuurvoorbeeld te krijgen. In lijstweergaven worden binaire velden meestal niet direct weergegeven omdat het laden van volledige bestandsinhoud voor elke zichtbare rij onnodige gegevensoverdracht creëert. De standaardaanpak is om een boolean indicator of een pictogram in lijstweergaven te tonen om aan te geven of er een bestand is bijgevoegd.
Zakelijke Gebruikscases
Het binaire veld verschijnt in veel Odoo-modules in echte implementaties. Hier zijn vijf praktische voorbeelden uit veelvoorkomende bedrijfsworkflows.
CRM: Ondertekenen van NDA's of contracten op klantrecords
Veel bedrijven moeten een ondertekend document rechtstreeks aan een klant- of leadrecord in Odoo CRM hechten. Een binaire veld op res.partner of crm.lead geeft verkoopteams met één klik toegang tot het relevante contract zonder de Odoo-interface te verlaten. Dit elimineert de noodzaak voor een aparte documentbeheertool voor basisbestandsopslag en houdt de informatie precies waar het team verwacht het te vinden tijdens het verkoopproces.
HR: Opslag van werknemersdocumenten
HR-afdelingen moeten regelmatig kopieën van werknemers-ID-documenten, werkvergunningen, ondertekende arbeidsovereenkomsten of opleidingscertificaten opslaan. Een binaire veld op hr.employee slaat deze bestanden veilig op binnen het toegangscontrolesysteem van Odoo. Met behulp van de groups attribuut kun je de zichtbaarheid beperken zodat alleen HR-managers gevoelige documenten kunnen bekijken, terwijl andere managers het formulier zien zonder toegang te hebben tot de daadwerkelijke bestanden. Dit is een veelvoorkomende Odoo-aanpassingsverzoek in bedrijven met strikte gegevensprivacyvereisten.
Voorraad: Product specificatiebladen en veiligheidsgegevens
Technische producten worden vaak geleverd met PDF-specificatiebladen, veiligheidsgegevensbladen of kwaliteitscertificaten van de fabrikant. Een binaire veld op product.template stelt inkoopteams en magazijnpersoneel in staat om de juiste documentatie rechtstreeks vanuit het productrecord in Odoo te benaderen. Dit is een van de meest gevraagde Odoo-aanpassingen in productie- en distributiebedrijven, en het is eenvoudig te implementeren met Odoo Studio of een aangepaste Python-module.
Verkoop: Bedrijfsstempel of afbeelding van een geautoriseerde handtekening
Sommige zakelijke contexten vereisen een bedrijfsstempel of een geautoriseerde handtekening op afgedrukte offertes of orderbevestigingen. Een fields.Image veld op res.company slaat deze visuele activa op, die vervolgens kan worden verwezen in een QWeb-rapporttemplate. Dit stelt afgedrukte documenten in staat om de stempel automatisch op te nemen zonder handmatige behandeling per document, wat tijd bespaart in hoogvolume verkoopoperaties en het risico vermindert om per ongeluk ongetekende offertes te verzenden.
Boekhouding: Bijlage van gescande ontvangstbewijzen op onkostenrecords
Expense management workflows vereisen doorgaans het bijvoegen van een gescande bon of factuur aan elk onkostenrecord als bewijs voor terugbetaling. Voor standaard Odoo-onkosten beheert het bijvoegselsysteem dit van nature. Maar bij aangepaste onkostenmodellen, leveranciersfactuurworkflows of integraties van derden biedt een Binaire veld een nette manier om de ontvangstafbeelding of PDF rechtstreeks op het record op te slaan en deze op te nemen in de goedkeuringsroutinglogica zonder te vertrouwen op het generieke bijvoegselpaneel.
Een Binaire Veld Maken of Aanpassen
Er zijn drie hoofdmethoden om een Binaire veld aan een Odoo-model toe te voegen, afhankelijk van je technische context en hoeveel controle je nodig hebt.
Gebruik Odoo Studio (Geen Code)
Odoo Studio is de ingebouwde low-code aanpassingstool. Om een Binaire veld toe te voegen zonder enige code te schrijven:
- Open Odoo Studio vanuit het hoofdmenu.
- Navigeer naar het formulier waar je het veld wilt.
- Sleep een Bestand veld vanuit de veldkiezer naar het formulier.
- Stel het label en eventuele optionele zichtbaarheidvoorwaarden in het eigenschappenpaneel in.
- Sla op en sluit Studio.
Studio maakt het veld met een x_studio_ voorvoegsel en gebruikt automatisch de bijvoegselmodus. Geen databaseconfiguratie nodig aan jouw kant. Dit is een van de meest toegankelijke Odoo-studio-velden voor zakelijke gebruikers die bestanduploadmogelijkheden op hun formulieren nodig hebben zonder betrokkenheid van een ontwikkelaar.
Gebruik Python in een Aangepaste Module
Voor Odoo-ontwikkeling die versiebeheer nodig heeft en over meerdere omgevingen moet worden uitgerold, is de standaardaanpak om Binaire velden rechtstreeks in Python te definiëren. Dit is de aanbevolen aanpak in elke Odoo-ontwikkelaarsgids voor serieuze Odoo-aanpassingswerk:
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',
)Na het toevoegen van het veld aan het model, voeg het toe aan de formulierweergave XML met de binary widget en de filename attribuut dat verwijst naar het bijbehorende Char-veld. Odoo beheert de databasekolom automatisch bij het installeren of upgraden van de module. Deze aanpak werkt schoon voor alle Odoo-implementatietypes, inclusief Odoo.sh en on-premise installaties.
Gebruikmakend van de XML-RPC API
Als je Odoo-veldcreatie programmatisch beheert, bijvoorbeeld via een extern configuratiescript of een implementatienotitieboek, kun je Binary-velden maken via de XML-RPC API:
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',
}]
)De state: manual waarde vertelt Odoo dat dit veld handmatig is aangemaakt in plaats van geïnstalleerd door een module. Veldcreaties via de API gebruiken standaard de bijlage-modus in de huidige Odoo-versies. Dit is de aanpak die wordt gebruikt in geautomatiseerde Odoo-configuratiescripts en externe implementatieworkflows.
Beste Praktijken
1. Gebruik altijd attachment=True
Tenzij je een zeer specifieke technische reden hebt om bestandinhoud rechtstreeks in de databasekolom op te slaan, gebruik dan de bijlage-modus. Het houdt modeltabellen klein, voorkomt trage queries en laat Odoo bestanden beheren via zijn ingebouwde filestore. Dit is ook het standaardgedrag in recente versies, dus het simpelweg weglaten van de attachment parameter is in de meeste gevallen voldoende. Voor elk bestand groter dan een kleine thumbnail is de bijlage-modus niet optioneel.
2. Koppel Binary-velden aan een filename Char-veld
Voeg altijd een bijbehorend _filename Char-veld toe naast elk Binary-veld dat in een formulierweergave wordt gebruikt. Zonder dit kan de bestand upload widget de originele bestandsnaam niet weergeven of herstellen, en gebruikers die het bestand downloaden eindigen met een generieke naam zoals download. Deze kleine toevoeging vereist één regel code en maakt een merkbaar verschil voor de gebruikerservaring van het formulier.
3. Gebruik fields.Image voor visuele inhoud
Als je productfoto's, partnerportretten, bedrijfslogo's of andere afbeeldingen opslaat, gebruik dan fields.Image in plaats van een eenvoudig Binary-veld. Het beperkt automatisch de uploadgrootte tot de geconfigureerde maximale afmetingen, rendert een thumbnail in de interface en bevat een apart veld voor de verkleinde preview-afbeelding. Het gebruik van het juiste veldtype voor de juiste inhoud is een kernprincipe in een schoon Odoo-datamodelontwerp.
4. Beperk de toegang met de parameter groepen
Binaire velden die gevoelige documenten opslaan, zoals werknemersbestanden, ondertekende contracten of financiële gegevens, moeten toegangsbeperkingen definiëren met behulp van de groepen parameter. Dit beperkt wie het veld kan lezen of schrijven, wat zowel belangrijk is voor gegevensprivacy als voor de vereisten van het auditspoor in gereguleerde omgevingen.
5. Ga zorgvuldig om met base64-codering in code
Bij het lezen of schrijven van binaire velden via code, moet je altijd de base64-codering expliciet behandelen. Gebruik base64.b64encode(file_bytes).decode('utf-8') om bytes om te zetten voordat je schrijft, en base64.b64decode(field_value) om terug te converteren naar bytes na het lezen. Neem niet aan dat de gegevens al in het formaat zijn dat je nodig hebt. Dit is een veelvoorkomende bron van bugs in Odoo ORM-integraties die alleen zichtbaar worden wanneer echte bestanden worden verwerkt.
Veelvoorkomende Valstrikken
Bij het instellen van attachment=False voor grote bestanden
Het direct opslaan van bestandsinhoud in een databasekolom kan je PostgreSQL-tabellen aanzienlijk opblazen. Een paar dozijn PDF-documenten die zijn opgeslagen met attachment=False kunnen honderden megabytes aan een enkele modeltafel toevoegen, waardoor elke query op dat model vertraagt. Dit is een van de meest impactvolle configuratiefouten in Odoo-databasebeheer. Zodra gegevens op deze manier zijn opgeslagen en de tabel groot wordt, vereist migreren naar de bijlage-modus een aangepast script en zorgvuldige planning.
Vergeten het bestandsnaam-companionveld
Zonder een gekoppeld Char-veld voor de bestandsnaam, krijgen gebruikers die een bestand downloaden vanuit een binaire veld vaak een generieke bestandsnaam. Dit is een klein maar aanhoudend probleem dat de implementatie onafgemaakt doet aanvoelen. Het toevoegen van het companionveld duurt minder dan een minuut en moet deel uitmaken van elke definitie van een binaire veld die in een gebruikersinterface wordt weergegeven.
Verwarring tussen Binaire en Afbeelding velden
Het gebruik van een eenvoudig binaire veld voor afbeeldingsinhoud mist de automatische resizing en thumbnail-rendering die fields.Image biedt. Gebruikers kunnen zeer grote afbeeldingsbestanden uploaden die de laadtijden van formulieren vertragen en onnodige opslagruimte verbruiken. Omgekeerd veroorzaakt het gebruik van fields.Image voor niet-afbeeldingsbestanden zoals PDF's fouten omdat Odoo probeert de inhoud als een afbeelding te verwerken. De regel is eenvoudig: stem het veldtype af op het verwachte inhoudstype.
Binaire velden rechtstreeks opnemen in lijstweergaven
Het toevoegen van een binaire veld aan een lijstweergave zorgt ervoor dat Odoo de volledige bestandsinhoud voor elke zichtbare rij laadt. Voor een lijst met vijftig records kan dit betekenen dat er megabytes aan gegevens worden overgedragen alleen om de pagina weer te geven. Als je de aanwezigheid van een bestand in een lijstweergave wilt aangeven, gebruik dan in plaats van het binaire veld direct een berekend boolean veld of een pictogramknop. Dit is een veelvoorkomend prestatieprobleem in Odoo-implementaties dat alleen zichtbaar wordt bij echte datavolumes.
Niet controleren op False voordat je in de code verwerkt
Een Binaire veld zonder waarde retourneert False in Python, niet een lege string en niet lege bytes. Als je probeert een Binaire veldwaarde te decoderen zonder eerst op False te controleren, krijg je een TypeError die de methode laat crashen. Bescherm altijd met: if record.x_document: data = base64.b64decode(record.x_document). Dit is belangrijk in compute-methoden, serveracties en elke code die Binaire waarden voorwaardelijk verwerkt.
Conclusie
Het Binaire veld is een eenvoudige maar belangrijke onderdeel van het Odoo datamodel. Het beheert de opslag van bestanden en documenten op een manier die natuurlijk integreert met de interface van Odoo, het bijvoegselsysteem en het toegangscontrolesysteem.
De belangrijkste gewoonten om te ontwikkelen: gebruik altijd de bijlage-modus, koppel Binaire velden aan een bestandsnaam Char-veld, kies fields.Image voor visuele inhoud, beperk de toegang voor gevoelige documenten en behandel base64-codering zorgvuldig in aangepaste code. Deze praktijken voorkomen de meest voorkomende problemen voordat ze de kans krijgen om in productie op te duiken.
Of je nu een bestandsuploadveld toevoegt via Odoo Studio, een aangepaste Python-module bouwt of het maken van velden beheert via de Odoo ORM of XML-RPC API, het vanaf het begin goed krijgen van Binaire velden leidt tot een schonere en betrouwbaardere Odoo-implementatie in het algemeen.
Bij Dasolo helpen we bedrijven bij het implementeren, aanpassen en optimaliseren van Odoo in alle afdelingen. Of je nu hulp nodig hebt bij het ontwerpen van een datamodel met de juiste veldtypes, het bouwen van aangepaste bestandsbeheerworkflows of het ontwikkelen van een volledige Odoo-module, ons team staat klaar om je te ondersteunen. Neem contact met ons op en laten we praten over jouw Odoo-project.