Binary Field in Odoo: Complete Developer and Business Guide

Innledning

Binary-feltet er kanskje ikke synlig eller glamorøst, men det er overalt i en virkelig Odoo-installasjon. Når en bruker laster opp en signert kontrakt, legger ved et produktark eller lagrer en bedriftslogo på en post, er det et Binary-felt som sørger for lagring og tilgang i bakgrunnen. Kunnskap om hvordan innholdet lagres, hvor filene plasseres, og når du bør velge et annet felttype er avgjørende når man bygger skjemaer eller utvider modeller.

Denne veiledningen forklarer hva Binary-feltet holder av data, hvordan vedleggsmodusen påvirker lagring og ytelse, hvordan du oppretter og tilpasser feltet via Odoo Studio eller i Python, og viser konkrete bruksområder i CRM, HR, lager og økonomi.

Hva er Binary-feltet i Odoo

I Odoo sitt ORM representeres binære filer av fields.Binary — feltet lagrer rå binærdata: dokumenter, bilder eller andre filer brukeren legger ved på en post. I skjema-visningen presenteres dette vanligvis som en opplastingsknapp, og samme kontroll gir mulighet til å laste ned filen med ett klikk.

Det viktigste tekniske poenget handler om hvor filinnholdet faktisk havner. I moderne Odoo-versjoner brukes normalt attachment-modus: filene ender opp som oppføringer i ir.attachment og i serverens fillager, mens kolonnen i modellen bare inneholder en referanse til vedlegget. Dette holder hovedtabellene lette og lar Odoo håndtere filene mer effektivt.

I Odoo Studio finner du Binary-feltet under navnet File i feltvelgeren. Det rulles ut som en enkel opplasting-/nedlastingskontroll i skjemaer. For bilder finnes også fields.Image som håndterer automatisk skalering og viser forhåndsvisninger — nyttig når du vil ha bedre brukeropplevelse for visuelt innhold.

Slik kan et Binary-felt defineres i en Python-modell:

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',
    )

Merk den tilhørende x_signed_contract_filename Char-feltet. Å legge ved et eget _filename-felt er en standardmønster i Odoo-utvikling: det husker og viser originalt filnavn i grensesnittet. Uten dette kan nedlastede filer få et generisk navn.

Hvordan feltet fungerer

Når du definerer et Binary-felt i modellen, håndterer Odoo rammeverket opprettelsen av kolonnen ved installasjon eller oppgradering av modulen — du trenger vanligvis ingen manuelle SQL-endringer.

Lagringsmoduser

attachment-parameteren på et Binary-felt bestemmer hvor filbytes lagres:

attachment=True (anbefalt): Filinnhold lagres i ir.attachment og lenkes til posten via modellnavn og post-ID. Modellens kolonne inneholder kun en referanse. Dette holder modelltabellene små og utnytter Odoo sitt filsystem.
attachment=False: Rå base64-kodet data lagres direkte i modellens databasekolonne. Det kan få tabeller til å vokse raskt og gjøre spørringer tregere. Unngå denne modusen for alt som er mer enn en liten miniatyrbilde.

Dataformat

Binary-feltene håndterer data som base64-kodede bytes. Ved lesing gjennom ORM eller XML-RPC får du en base64-streng; ved skriving må du sende en base64-streng.

I praksis betyr det at du må kode før skriving og dekode etter lesing:

import base64

# Skrive en fil til et Binary-felt
with open('document.pdf', 'rb') as f:
    encoded = base64.b64encode(f.read()).decode('utf-8')
record.write({'x_signed_contract': encoded})

# Lese en fil fra et Binary-felt
raw_bytes = base64.b64decode(record.x_signed_contract)

Viktige feltattributter

Her er de mest relevante attributtene du kan sette på et Binary-felt i Odoo:

attachment: Boolean. Bestemmer om innholdet lagres i ir.attachment (True) eller direkte i kolonnen (False). Standard i nyere versjoner er True.
string: Tekstetikett som vises i brukergrensesnittet.
required: Gjør feltet obligatorisk før lagring.
compute: Kobler en Python-metode for å generere feltverdien dynamisk, for eksempel å lage en PDF ved behov.
store: I kombinasjon med compute lagres den beregnede verdien i databasen.
groups: Begrens feltets synlighet til bestemte brukergrupper — viktig for sensitive dokumenter.
copy: Styrer om verdien kopieres ved duplisering av poster. Standard varierer med attachment-innstilling og Odoo-versjon.

fields.Image-subklassen

fields.Image er en spesialisert variant av fields.Binary (fra Odoo 13) som håndterer automatisk skalering til maksimal dimensjon, tilbyr en egen forhåndsvisningsstørrelse og viser en ekte miniatyr i skjemaer. Bruk fields.Image for produktbilder, profilbilder eller logoer for å unngå store opplastinger og få bedre brukeropplevelse.

Slik vises feltet i visninger

I skjema-visninger vises Binary-feltet som en opplastings-/nedlastingsknapp. For bilder anbefales image-widgeten for å få miniatyrvisning. I listevisninger viser man vanligvis ikke fullt binærinnhold; i stedet bruker man et ikon eller en boolsk indikator for å signalisere at en fil er tilknyttet uten å laste ned store datamengder.

Forretningsscenarier

Binary-feltet brukes i en rekke moduler i praktiske arbeidsflyter. Under følger fem konkrete eksempler fra vanlige forretningsområder.

CRM: Lagre signerte avtaler eller NDA på kunde

Salgsteam vil ofte ha signerte avtaler eller NDA-er direkte knyttet til kunde- eller lead-poster. Et Binary-felt på res.partner eller crm.lead gir rask tilgang til kontrakter uten å måtte bytte verktøy, og holder dokumentasjonen der selgere intuitivt forventer å finne den.

HR: Lagring av medarbeiderdokumenter

HR trenger å arkivere ID-dokumenter, arbeidstillatelser, signerte kontrakter og kursbevis. Et Binary-felt på hr.employee lagrer disse filene innenfor Odoos tilgangskontroll, og ved å bruke groups kan du sikre at kun HR-personell får se sensitive filer.

Lager: Produktskjemaer og sikkerhetsdatablader

For tekniske varer er PDF-spesifikasjoner, sikkerhetsdatablader og sertifikater viktige. Et Binary-felt på product.template gir innkjøp og lagerpersonell enkel tilgang til korrekt dokumentasjon direkte fra produktkortet — en hyppig etterspurt tilpasning i produksjon og distribusjon.

Salg: Firmastempel eller signaturbilde

Noen bedrifter trenger et digitalt stempel eller signatur på utskrevne tilbud og ordrebekreftelser. Et fields.Image-felt på res.company kan lagre dette visuelt elementet, som deretter settes inn automatisk i QWeb-rapporter, noe som sparer tid og reduserer manuell håndtering.

Regnskap: Skannet kvittering på utleggsoppføringer

I utleggshåndtering er det vanlig å legge ved en skannet kvittering som dokumentasjon. Enten man bruker Odoos standardfunksjon eller en skreddersydd modell, gir et Binary-felt en enkel måte å knytte kvitteringer og fakturaer til poster og inkludere dem i godkjenningsflyten.

Opprette eller tilpasse Binary-feltet

Tre måter å legge til et Binary-felt på

Bruk Odoo Studio (ingen kode)

Odoo Studio er lavkodeverktøyet som følger med. Slik legger du til et Binary-felt uten utvikling:

Åpne Odoo Studio fra hovedmenyen.
Gå til skjemaet der feltet skal ligge.
Dra et File-felt fra feltvelgeren og slipp det i skjemaet.
Angi etikett og eventuelle synlighetsregler i egenskapspanelet.
Lagre og lukk Studio.

Studio oppretter feltet med et x_studio_-prefiks og bruker som regel attachment-modus automatisk. Dette er en brukervennlig måte for forretningsbrukere å legge til filopplasting uten utviklerstøtte.

Ved hjelp av Python i en egendefinert modul

For sporbarhet og distribusjon over flere miljøer er det beste å definere Binary-felt i Python i en modul — dette er anbefalt praksis for seriøse Odoo-tilpasninger:

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',
    )

Etter å ha lagt feltet i modellen inkluderer du det i skjemaets XML med binary-widget og filename-attributt som peker til det komplementære Char-feltet. Odoo tar seg av databasekolonnen ved installasjon/oppgradering, og metoden fungerer både på Odoo.sh og on-premise.

Via XML-RPC API

Hvis du oppretter felt programmatisk fra en ekstern script eller deploy-notebook, kan felt opprettes via 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',
    }]
)

Verdien state: 'manual' forteller Odoo at feltet er laget manuelt og ikke av en modul. Felt opprettet via API bruker i nyere versjoner som regel attachment-modus. Denne fremgangsmåten benyttes i automatiserte konfigurasjonsskript og fjern-deploy-workflows.

Beste praksis

1. Bruk alltid attachment=True

Med mindre du har en helt spesiell grunn, bør filinnhold lagres i ir.attachment. Det holder modelltabellene små og unngår ytelsesproblemer. I praksis er dette standard i nyere Odoo-versjoner — for filer som er større enn små miniatyrbilder er attachment-modus et krav.

2. Kombiner Binary-felt med et filnavn-Char-felt

Alltid legg til et _filename Char-felt ved siden av Binary-feltet. Uten det kan nedlastede filer få et generisk navn som 'download'. Denne enkle linjen i modellen forbedrer brukeropplevelsen merkbart.

3. Bruk fields.Image for bilder

For produktbilder, profilbilder og logoer — bruk fields.Image i stedet for et generisk Binary-felt. Image-feltet setter grenser for opplastningsstørrelse, lager et miniatyrbilde og gir bedre ytelse og brukeropplevelse.

4. Begrens tilgang med groups-parameteren

Sensitive dokumenter som personalmapper, kontrakter eller økonomiske filer bør få tilgangsbegrensning via groups. Dette er viktig både for personvern og for revisjonsspor i regulerte bransjer.

5. Håndter base64-koding korrekt i kode

Når du leser eller skriver binære felter i kode, må du eksplisitt håndtere base64. Bruk base64.b64encode(file_bytes).decode('utf-8') før skriving og base64.b64decode(field_value) ved lesing. Mange feil i integrasjoner oppstår fordi dette trinnet blir oversett.

Vanlige fallgruver

Å sette attachment=False for store filer

Å lagre store filer direkte i en databasekolonne kan blåse opp PostgreSQL-tabeller raskt. Noen titalls PDF-er med attachment=False kan legge hundrevis av megabyte til en tabell og gjøre alle spørringer på modellen tregere. Å rette dette krever ofte migrering og spesialskrevet skript.

Glemme følgelig filnavnsfeltet

Uten et companion-felt for filnavn ender brukere ofte opp med en generisk filnavn ved nedlasting. Dette virker uferdig og er lett å unngå ved å legge til et Char-felt for filnavnet.

Forvirring mellom Binary og Image

Å bruke et vanlig Binary-felt for bilder fratar deg automatisk skalering og miniatyrfunksjoner. Store bilder kan føre til tregere skjemaer og unødvendig lagringsbruk. Omvendt vil fields.Image feilaktig brukt for PDF-er føre til behandling som bilde og feilmeldinger. Velg feltet etter forventet filtype.

Å inkludere Binary-felt i listevisninger

Hvis du viser et Binary-felt direkte i en listevisning, kan Odoo hente full filinnhold for hver rad. For en liste med femti poster kan dette bety megabyte med data ved hver sidevisning. Bruk heller et beregnet boolean-felt eller et ikon for å indikere tilknyttet fil i lister.

Ikke sjekke for False før behandling i kode

Når et Binary-felt ikke har verdi returnerer det False i Python, ikke en tom streng. Hvis du prøver å dekode uten å sjekke for False først, får du en TypeError. Alltid gjør en sjekk: if record.x_document: data = base64.b64decode(record.x_document). Dette er spesielt viktig i compute-metoder og server-aksjoner.

Oppsummering

Binary-feltet er et enkelt, men viktig element i Odoo-modellen. Det gir en innebygd måte å lagre dokumenter og filer som fungerer naturlig med Odoos vedleggssystem og tilgangskontroller.

Hovedvanene å følge: bruk attachment-modus, legg alltid til et filnavn-Char-felt ved siden av Binary-feltet, bruk fields.Image for visuelt innhold, begrens tilgang for sensitive dokumenter, og sørg for korrekt base64-håndtering i egendefinert kode. Disse tiltakene forhindrer de vanligste problemene før de dukker opp i produksjon.

Enten du legger til filopplasting med Odoo Studio, utvikler en modul i Python eller administrerer feltopprettelse via ORM eller XML-RPC, gir en riktig håndtering av Binary-feltene et renere og mer robust Odoo-oppsett fra starten av.

Hos Dasolo bistår vi selskaper med å implementere, tilpasse og optimalisere Odoo i hele organisasjonen. Enten det gjelder modellvalg, filhåndteringsarbeidsflyter eller full modulutvikling, står vårt team klart til å hjelpe. Ta kontakt med oss så tar vi en prat om ditt Odoo-prosjekt.

Binary Field i Odoo: Komplett Guide for Utviklere