Odoo Binary Field: Täydellinen Opas Kehittäjälle

Johdanto

Binary-kentät eivät ole näyttäviä, mutta ne ovat joka paikassa toimivassa Odoo‑projektissa. Kun käyttäjä liittää allekirjoitetun sopimuksen, tuotedatan tai yrityksen logon tietueeseen, taustalla on Binary‑kenttä, joka tallentaa tiedoston. Kun ymmärrät, miten tiedot tallentuvat, mihin ne päätyvät ja milloin kannattaa valita toinen kenttätyyppi, muokkaaminen ja räätälöinti sujuvat huomattavasti luotettavammin.

Tässä oppaassa käydään läpi, mitä Binary‑kenttä itse asiassa sisältää, miten liitteet vaikuttavat tallennukseen ja suorituskykyyn, miten kentän lisääminen onnistuu Odoo Studio‑työkalulla tai Python‑koodilla sekä käytännön esimerkit CRM:stä, HR:stä, varastosta ja muista prosesseista.

Mikä on Binary-kenttä Odoossa

Odoon ORM:ssa Binary‑kenttä (fields.Binary) tallentaa raakabinaarista sisältöä: tiedostoja, kuvia ja dokumentteja, joita käyttäjä liittää tietueeseen. Lomakenäkymissä kenttä näkyy lataus‑ ja latauspainikkeena; kun tiedosto on liitetty, sama ohjaus mahdollistaa sen lataamisen yhdellä napsautuksella.

Oleellisin tekninen seikka on missä itse tiedoston data säilytetään. Nykyisissä Odoo‑versioissa Binary‑kentät käyttävät yleensä liite‑tilaa (attachment). Tällöin tiedoston sisältö tallennetaan ir.attachment‑tauluun ja palvelimen filestoreen, eikä suoraan mallin sarakkeeseen. Mallin oma sarake pitää vain viitteen liitetietueeseen, mikä pitää päätaulut kevyempinä ja antaa Odoon käsitellä tiedostoja tehokkaammin.

Odoo Studiosta Binary‑kenttä löytyy kenttävalikosta nimellä File. Se piirtää lomakkeeseen yksinkertaisen lataus‑ ja latausohjaimen. Kuvia varten Odoo tarjoaa myös fields.Image‑tyypin, joka hoitaa koon muuttamisen ja näyttää esikatseluthumbnaileja — tästä lisää myöhemmin.

Alla on esimerkki siitä, miltä Binary‑kenttä näyttää Python‑mallissa:

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

Huomaa mukana oleva x_signed_contract_filename‑merkkikenttä. Tällainen _filename‑parin käyttö on vakiokäytäntö: Odoo tallentaa alkuperäisen tiedostonimen tähän kenttään, jolloin käyttöliittymä voi näyttää oikean nimen latauksissa. Ilman sitä ladattavat tiedostot saattavat saada geneerisen nimen.

Miten kenttä toimii

Kun määrittelet Binary‑kentän malliin, Odoo huolehtii tietokantasarakkeen luomisesta moduulin asennuksessa tai päivityksessä. Et tarvitse erillisiä SQL‑komentoja.

Tallennustavat

attachment‑parametri Binary‑kentässä määrää, mihin tiedoston tavut varsinaisesti tallennetaan:

• attachment=True (suositeltava): Tiedoston sisältö tallennetaan ir.attachment‑tauluun, joka linkitetään tietueeseen model‑nimen ja record ID:n kautta. Mallin sarake sisältää vain viitteen. Tämä pitää mallitaulut pienempinä ja hyödyntää Odoon filestore‑järjestelmää.
• attachment=False: Raakadata (base64‑koodattuna) tallennetaan suoraan mallin tietokantasarakkeeseen. Tämä kasvattaa tauluja ja hidastaa kyselyjä, joten vältä tätä tilaa kaiken muun kuin hyvin pienten esikatselukuvien kohdalla.

Datan muoto

Binary‑kentät käsittelevät dataa base64‑koodattuna. ORM:llä tai XML‑RPC‑rajapinnan kautta luettaessa saat base64‑merkkijonon, ja kirjoittaessa sinun tulee toimittaa base64‑koodattu merkkijono.

Käytännössä tämä tarkoittaa koodaamista ennen kirjoitusta ja dekoodaamista luettaessa:

import base64

# Kirjoitus Binary‑kenttään
with open('document.pdf', 'rb') as f:
    encoded = base64.b64encode(f.read()).decode('utf-8')
record.write({'x_signed_contract': encoded})

# Lukeminen Binary‑kentästä
raw_bytes = base64.b64decode(record.x_signed_contract)

Tärkeimmät kenttäattribuutit

Seuraavat attribuutit ovat olennaisia Binary‑kentän konfiguroinnissa Odoossa:

• attachment: Boolen. Määrittää, tallennetaanko sisältö ir.attachment‑tauluun (True) vai suoraan sarakkeeseen (False). Oletus: True nykymäärityksissä.
• string: Näytettävä otsikko käyttöliittymässä.
• required: Tekee kentästä pakollisen tietuetta tallennettaessa.
• compute: Antaa linkittää Python‑laskentametodin, esimerkiksi PDF:n dynaamiseen luontiin laskettuna kenttänä.
• store: Käytetään compute‑attribuutin kanssa tallentamaan lasketun arvon tietokantaan.
• groups: Rajoittaa kentän näkyvyyden tiettyihin Odoo‑käyttäjäryhmiin — tärkeää arkaluontoisille dokumenteille.
• copy: Määrittää, kopioidaanko kentän arvo tietuetta kopioitaessa. Oletusarvot vaihtelevat liite‑tilan ja Odoo‑version mukaan.

fields.Image‑aliluokka

fields.Image on fields.Binaryn erikoistapaus, joka tuli Odoo 13:ssa. Se muuttaa automaattisesti kuvan kokoa ennalta määritettyihin mittoihin, tarjoaa erillisen esikatselukentän thumbnailille ja näyttää varsinaisen kuvan lomakkeella. Tuotekuville, yrityslogoille ja profiilikuville kannattaa aina käyttää fields.Imagea, jotta vältytään liian suurilta latauksilta ja saadaan käyttäjäystävällinen esikatselu.

Miten kenttä näkyy näkymissä

Lomakkeissa Binary‑kenttä oletuksena piirtää lataus‑ ja tallennuspainikkeen. Kuville kannattaa käyttää image‑widgettiä, jolloin saa thumbnail‑esikatselun. Listanäkymissä Binary‑kenttää harvoin näytetään suoraan, koska jokainen rivi ei‑tarpeettomasti lataisi koko tiedoston sisältöä. Tästä syystä listassa yleensä näytetään esimerkiksi ikoni tai laskettu boolean‑kenttä, joka kertoo onko liite olemassa.

Liiketoiminnan käyttötapaukset

Binary‑kenttiä käytetään monissa Odoon moduuleissa. Seuraavassa viisi käytännön esimerkkiä tyypillisistä yritysprosesseista.

CRM: Allekirjoitettujen sopimusten liittäminen asiakastietoihin

Myyntitiimit haluavat usein pitää NDA:t ja sopimukset suoraan asiakkaan tai liidin tietueella. Binary‑kenttä res.partnerissa tai crm.leadissä antaa myynnille yhdellä klikkauksella pääsyn sopimukseen ilman erillistä dokumentinhallintaa, jolloin asia löytyvät juuri sieltä missä myyntiprosessissa sitä odotetaan.

HR: Työntekijädokumenttien säilytys

HR tarvitsee usein säilyttää henkilötodistuksia, työsopimuksia ja lupia. Binary‑kenttä hr.employee‑mallissa pitää dokumentit Odoon käyttöoikeusjärjestelmän piirissä. groups‑attribuutilla voit määrittää, että vain HR‑henkilöt näkevät tiedostot, kun muut johtajat näkevät lomakkeen mutta eivät pysty lataamaan arkaluontoisia dokumentteja.

Varasto: Tuoteselosteet ja turvallisuustiedotteet

Tekniset tuotteet sisältävät usein PDF‑specit ja turvallisuustiedotteet. Binary‑kenttä product.templateissa mahdollistaa oston ja varaston henkilöstön pääsyn oikeaan dokumentaatioon suoraan tuotetietueelta — yleinen ja helppo räätälöinti valmistus‑ ja jakeluyrityksissä.

Myynti: Yrityksen leima tai allekirjoitus kuvituksena

Joissain organisaatioissa halutaan tulostettavat tarjoukset, joissa on leima tai valtuutetun allekirjoituksen kuva. fields.Image res.companyssa tallentaa tällaisen kuvan, jonka QWeb‑raporteissa voi sijoittaa automaattisesti, jolloin manuaalinen käsittely vähenee ja riskit puuttuvista allekirjoituksista pienenevät.

Kirjanpito: Skannatut kuitit kulutietueilla

Kulukorvausprosessit vaativat yleensä kuitin liittämistä. Odoon liitejärjestelmä tukee tätä oletuksena, mutta räätälöidyissä kulu‑malleissa Binary‑kenttä tarjoaa yksinkertaisen tavan tallentaa kuitti suoraan tietueelle ja hyödyntää sitä hyväksyntä‑ tai laskutusprosessissa.

Binary-kentän luominen ja muokkaaminen

Binary‑kentän lisäämiseen on kolme pääasiallista tapaa riippuen tarpeesta ja ympäristöstä.

Odoo Studio (ilman koodia)

Odoo Studio on matalan koodin muokkaustyökalu. Binary‑kentän lisääminen onnistuu ilman ohjelmointia seuraavasti:

1. Avaa Odoo Studio päävalikosta.
2. Siirry lomakkeeseen, johon haluat kentän.
3. Vedä kenttävalikosta File‑kenttä lomakkeelle.
4. Aseta otsikko ja näkyvyysasetukset ominaisuuspaneelissa.
5. Tallenna ja sulje Studio.

Studio luo kentän x_studio_‑etuliitteellä ja käyttää oletuksena attachment‑tilaa. Tietokanta-asetuksia ei tarvitse säätää, mikä tekee tästä helpoimman tavan lisätä tiedostojen latausmahdollisuus ilman kehittäjän apua.

Python‑koodi omassa moduulissa

Kun haluat versionhallittavan ja toistettavan ratkaisun, määrittele Binary‑kentät Pythonissa omassa moduulissasi. Tämä on suositeltava tapa tuotantoympäristöissä:

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

Lisää kenttä myös lomakenäkymään XML:ssä käyttäen binary‑widgettiä ja filename‑attribuuttia osoittamaan kumppanikenttää. Odoo luo tarvittavat tietokantarakenteet moduulin asennuksessa tai päivityksessä, ja ratkaisu toimii sekä Odoo.sh:ssa että on‑premise‑asennuksissa.

XML‑RPC‑rajapinnan kautta

Jos hallitset Odoo‑konfiguraatiota ohjelmallisesti esimerkiksi etäkäsikirjoituksella, voit luoda kenttiä myös XML‑RPC:llä:

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

state: 'manual' kertoo, että kenttä luotiin manuaalisesti eikä moduulin mukana. API‑luodut kentät käyttävät nykyversioissa oletuksena liite‑tilaa. Tätä menetelmää käytetään usein automatisoiduissa käyttöönotto‑ ja konfiguraatiotyökaluissa.

Hyvät käytännöt

1. Käytä aina attachment=True

Ellei sinulla ole hyvin painavaa syytä tallentaa raakadataa suoraan sarakkeeseen, valitse attachment‑tila. Se pitää mallitaulut pienempinä, estää hitaita kyselyjä ja hyödyntää Odoon filestorea. Käytä attachment‑tilaa kaikissa tapauksissa, joissa tiedosto on suurempi kuin pienen esikatselukuvan kokoinen.

2. Lisää Binary‑kentälle aina tiedostonimi‑merkkikenttä

Lisää kumppanikenttä, joka päättyy _filename: sen avulla käyttöliittymä näyttää alkuperäisen tiedostonimen. Ilman tätä käyttäjä saa usein geneerisen nimen kuten download, mikä heikentää käyttökokemusta.

3. Käytä fields.Imagea visuaaliselle sisällölle

Tuotekuvat, profiilikuvat ja logot kannattaa tallentaa fields.Image‑kenttään. Se rajoittaa kuvan mittoja, tarjoaa esikatselun ja generoi pienemmän esikatselukentän, mikä säästää tallennustilaa ja parantaa lomakkeen latausaikoja.

4. Rajoita näkyvyyttä groups‑parametrilla

Arkaluonteiset dokumentit, kuten henkilöstön papereihin tai taloustietoihin liittyvät liitteet, tulee suojata groups‑asetuksella. Se määrittää, ketkä voivat lukea tai muokata kenttää ja on tärkeä osa tietosuojakäytäntöjä ja auditointia.

5. Käsittele base64‑koodaus huolellisesti koodissa

Kun luet tai kirjoitat Binary‑kenttää ohjelmallisesti, huolehdi aina base64‑koodauksesta: base64.b64encode(file_bytes).decode('utf-8') ennen kirjoitusta ja base64.b64decode(field_value) luettaessa. Monet bugit syntyvät olettamuksesta, että data olisi jo oikeassa muodossa.

Yleiset sudenkuopat

attachment=False suurten tiedostojen kohdalla

Tiedostojen tallentaminen suoraan tietokantaan voi paisuttaa PostgreSQL‑taulun nopeasti. Jo muutama PDF attachment=False‑tilassa voi lisätä satoja megatavuja yhteen tauluun ja hidastaa kaikkia kyselyjä. Korjaus vaatii usein migraatiotyön ja huolellisen suunnittelun, joten kannattaa välttää tätä virhettä alusta alkaen.

Tiedostonimen kumppanikentän unohtaminen

Ilman _filename‑kenttää käyttäjät saattavat ladata tiedoston, jonka nimi on epäselvä. Tämä on pieni mutta ärsyttävä puute, jonka korjaamiseen riittää usein yksi lisätty merkkikenttä.

Binaryn ja Imagen sekoittaminen

Kuvan tallentaminen tavallisena Binarynä jättää käyttämättä automaattisen koonmuutoksen ja thumbnailit, jolloin käyttäjät voivat ladata liian suuria kuvia. Toisaalta yrittäminen käyttää fields.Imagea PDF:lle johtaa virheisiin, koska Odoo yrittää käsitellä sisältöä kuvatiedostona. Valitse kenttätyyppi sen mukaan, mitä tiedostoja odotat tallentavasi.

Binary‑kentän näyttäminen suoraan listanäkymässä

Kun listaan lisätään Binary‑kenttä, Odoo yrittää ladata kunkin näkyvän rivin sisällön — 50 rivillä se voi siirtää megatavuja tarpeettomasti. Listassa on parempi näyttää laskettu boolean tai ikoni, joka ilmaisee liitteen olemassaolon.

Arvon tarkistamatta käsittely koodissa

Tyhjä Binary‑kenttä palauttaa Pythonissa False, ei tyhjää merkkijonoa tai tavujonoa. Jos yrität dekoodata arvoa ilman False‑tarkistusta, saat TypeErrorin. Varaa aina tarkistus, esimerkiksi: if record.x_document: data = base64.b64decode(record.x_document).

Yhteenveto

Binary‑kenttä on yksinkertainen mutta olennainen osa Odoon tietomallia. Se tarjoaa tavan tallentaa tiedostoja, joka toimii saumattomasti Odoon liitejärjestelmän ja käyttöoikeuksien kanssa.

Keskeiset käytännöt: käytä aina liite‑tilaa, lisää tiedostonimi‑kenttä, valitse fields.Image kuville, rajoita näkyvyys arkaluontoisille tiedoille ja huolehdi base64‑koodauksesta koodissa. Näillä hoidat yleisimmät ongelmat ennen kuin ne näkyvät tuotannossa.

Olipa kyse Odoo Studiosta, räätälöidystä Python‑moduulista tai kenttien luomisesta ORM:n tai XML‑RPC:n kautta, Binary‑kenttien oikea määrittely alusta lähtien tekee Odoo‑ratkaisusta siistimmän ja luotettavamman.

Me Dasololla autamme yrityksiä ottamaan Odoon käyttöön, räätälöimään ja optimoimaan sitä eri toiminnoissa. Tarjoamme tukea tietomallien suunnittelusta tiedostojen hallintaprosessien rakentamiseen ja kokonaismoduulien kehitykseen. Ota yhteyttä ja keskustellaan sinun Odoo‑projektistasi.