Odoo Reference Field: Täydellinen Opas Suunnitteluun ja Käyttöön

Johdanto

Moni Odoo-kehittäjä tarttuu usein Many2one-kenttään kun halutaan viitata toiseen tietueeseen — se on yksinkertainen ja toimiva ratkaisu useimpiin tarpeisiin. Joskus kuitenkin tilanne vaatii joustavuutta: viitattava dokumentti voi olla myyntitilaus, ostotilaus, työmääräys tai jotain aivan muuta kontekstista riippuen. Tällaisissa tapauksissa Reference‑kenttä tarjoaa siistin ja joustavan tavan pitää yhteys eri mallien välillä ilman erillisiä kenttiä jokaista tyyppiä varten.

Reference‑kenttä on Odoo‑ORM:n monipuolisimpiin kuuluvia kenttätyyppejä: sen avulla yhden kentän arvo voi osoittaa mihin tahansa etukäteen määritellyistä malleista sen sijaan, että se olisi sidottu aina yhteen malliin. Käyttäjä valitsee ensin dokumenttityypin ja sen jälkeen halutun tietueen — tuloksena on polymorfinen linkki, joka mukautuu eri työnkulkujen tarpeisiin.

Tässä oppaassa selitän, mitä Reference‑kenttä tallentaa taustalla, miten sitä käytetään Odoon tietomallissa, miten voit lisätä sen Odoo Studiolla tai Pythonilla ja millaisissa liiketoimintatilanteissa kenttä todella tuo lisäarvoa.

Mikä on Reference-kenttä Odoossa

Odoo‑ORM:ssä Reference on erikoiskenttä, joka säilyttää linkin mihin tahansa valitsemaasi malliin selection-listan avulla. Tämä erottaa sen Many2one‑kentästä, joka osoittaa aina yhteen ennalta määriteltyyn malliin.

Tietokantatasolla Reference‑kenttä tallennetaan tekstinä muodossa model_name,record_id — esimerkiksi myyntitilaus 42 näkyy arvona sale.order,42. Tämä on oleellista, kun teet suoria kyselyjä tai suodatuksia PostgreSQL:ssä.

Käyttöliittymässä Reference‑kenttä toimii kahdessa vaiheessa: käyttäjä valitsee ensin dokumenttityypin alasvetovalikosta (esimerkiksi Myyntitilaus, Lasku tai Projektitehtävä) ja hakee sitten halutun tietueen haulla. Kun toimintalogiikka on ymmärretty, valinta on intuitiivinen ja nopea.

Alla on yksinkertainen esimerkki siitä, miten Reference‑kenttä määritellään Pythonissa:

from odoo import fields, models

class HelpDeskTicket(models.Model):
    _inherit = 'helpdesk.ticket'

    related_document = fields.Reference(
        selection=[
            ('sale.order', 'Sale Order'),
            ('purchase.order', 'Purchase Order'),
            ('account.move', 'Invoice'),
            ('project.task', 'Project Task'),
        ],
        string='Related Document',
    )

selection-parametri on lista tuplia: ensimmäinen osa on tekninen mallinimi (esim. sale.order) ja toinen osa on käyttäjälle näkyvä selitteellinen nimi. Tämän listan avulla hallitset täsmällisesti, mitä malleja käyttäjä voi valita.

Voit myös luoda dynaamisen selection-listan hakemalla malleja suoraan ir.model-taulusta ajon aikana. Tämä sopii hyvin muokattaviin työkaluihin, mutta voi helposti ylikuormittaa käyttäjää, ellei listaa suodateta järkevästi.

Odoo Studiolla Reference‑kenttä löytyy kenttätyyppivalikosta nimellä Reference. Studiolla lisättäessä voit määrittää valittavien mallien listan käyttöliittymässä ilman koodia, mikä helpottaa pikamuutoksia ja antaa liiketoimintakäyttäjille itsepalvelun mahdollisuuden.

Miten kenttä toimii

Reference‑kentän tallennus- ja hakutapa kannattaa ymmärtää hyvin, jotta osaat käyttää sitä oikein Odoo‑kehityksessä.

Tallennus tietokantaan

Toisin kuin Many2one, joka tallentaa vain kokoonpanoa (kokonaisluvun), Reference tallentaa merkkijonon, joka sisältää mallin nimen ja tietueen id:n, esim. sale.order,15. Kenttä on tyypiltään VARCHAR PostgreSQL:ssä, eikä siihen kohdistu tietokantatasoista vierasavaimen eheystarkistusta — tämä on tarkoituksellinen valinta kentän polymorfisuuden vuoksi.

Koska viite ei ole tietokantatasolla vierasavain, Odoo ei automaattisesti siivoa Reference‑kenttien arvoja, jos viitattu tietue poistetaan. Jos myyntitilaus poistetaan, Reference‑kenttä voi silti sisältää vanhentuneen merkkijonon. Tämä ero on hyvä muistaa suunnitellessa automaatiota ja tietojen ylläpitoa.

Viitatun tietueen lukeminen Pythonissa

Kun luet Reference‑kenttää Pythonissa, Odoo palauttaa viitatun tietueen rekordiobjektin — voit käyttää sen kenttiä kuten tavallista Many2one‑tulosta. Tyhjä kenttä palauttaa False.

ticket = self.env['helpdesk.ticket'].browse(1)
doc = ticket.related_document

if doc:
    print(doc._name)   # e.g. 'sale.order'
    print(doc.name)    # e.g. 'S00042'
    print(doc.id)      # e.g. 15

Tämä on Odoo ORM:n kätevyyttä: vaikka arvo tallennetaan tekstinä, kehys ratkaisee sen oikeaksi rekordiksi, kun sitä käytetään koodissa.

Tärkeimmät kenttäattribuutit

Seuraavat attribuutit ovat kaikkein olennaisimpia Reference‑kentän konfiguroinnissa Odoossa:

• selection: Lista tuplia, jotka määrittävät valittavat mallit. Tämä voi olla myös metodin nimi (merkkijono), joka palauttaa vastaavan listan dynaamisesti.
• string: Kentän näyttönimi käyttöliittymässä.
• required: Tekee kentästä pakollisen; käyttäjän täytyy valita sekä mallityyppi että tietue ennen tallennusta.
• readonly: Estää kentän muokkaamisen käyttöliittymästä. Hyödyllinen, jos viite asetetaan ohjelmallisesti.
• help: Työkaluvihje, joka auttaa käyttäjää ymmärtämään mitä kenttään tulee valita.
• compute: Reference‑kenttä voidaan laskea Python‑metodilla kuten muutkin kentät. Tämä mahdollistaa viitteen asettamisen automaattisesti liiketoimintasääntöjen perusteella.

Suodatus ja haku

Koska arvo tallennetaan merkkijonona, Reference‑kentässä suodattaminen vaatii oikeanlaista domain‑syntaksia: suodatuksen pitää vastata tallennettua merkkijonoa.

tickets = self.env['helpdesk.ticket'].search([
    ('related_document', '=', 'sale.order,15')
])

Voit myös suodattaa mallityypin perusteella käyttämällä like

tickets = self.env['helpdesk.ticket'].search([
    ('related_document', 'like', 'sale.order,')
])

Muista tämä merkkijonopohjainen suodatuslogiikka suunnitellessasi raportteja tai laskettaessa arvoja Reference‑kenttien perusteella — se ei käyttäydy kuten tavallinen Many2one‑domain.

Liiketoimintatapaukset

Reference‑kentän arvo ymmärretään parhaiten käytännön esimerkkien kautta. Se soveltuu erityisesti tilanteisiin, joissa sama konteksti voi viitata eri dokumenttityyppeihin.

1. Asiakastuki: tiketit, jotka voivat liittyä mihin tahansa dokumenttiin

Asiakastukitiimi käsittelee usein erilaisia tapauksia: laskukiistat, toimitusongelmat, sopimuskysymykset tai tuotepalautukset. Yhden Reference‑kentän avulla tukihenkilö voi liittää tiketin mihin tahansa vastaavaan dokumenttiin ilman, että tarvitsee erillisiä kenttiä jokaista tyyppiä varten — valitaan ensin tyyppi (Lasku, Myyntitilaus, Toimitus) ja sitten oikea tietue.

2. Myynnin toiminnot, jotka lähtevät eri lähteistä

Myyntitiimin aktiviteetit voivat syntyä liidistä, tarjouksesta, sopimuksesta tai tukipyynnöstä. Reference‑kenttä aktiviteettimallissa antaa myyjälle mahdollisuuden merkitä alkuperäisen dokumentin ilman, että malli lukittuu yhteen tietotyyppiin.

3. Muistiinpanot eri moduulien yli

Yritykset saattavat haluta säilyttää keskitetyn muistiinpanomallin, jota voi liittää asiakkaisiin, projektitehtäviin, valmistusmääräyksiin tai ostotilauksiin. Reference‑kenttä mahdollistaa saman muistiinpanon kiinnittämisen eri objektityyppeihin ilman mallin kopiointia.

4. Hyväksyntätyönkulku, joka palvelee useita dokumenttityyppejä

Yleinen hyväksyntäpyyntö voi koskea ostotilauksia, kululaskuja, lomapyyntöjä tai sopimuksia. Reference‑kenttä hyväksyntäpyyntömallissa pitää arkkitehtuurin yksinkertaisena: sama logiikka voi käsitellä eri dokumentteja ilman erillisiä hyväksyntämalleja.

5. Kululaskut, jotka linkittyvät projekteihin tai myyntitilauksiin

Tilitoimistossa kulu voi liittyä joko projektiin tai myyntitilaukseen. Reference‑kenttä, jossa on sekä project.project että sale.order, antaa kirjanpitäjälle vapauden valita oikean kohteen ja auttaa ammatillisten palveluiden yrityksiä kohdistamaan kulut oikein.

Reference-kentän luominen ja muokkaus

Reference‑kentän lisääminen onnistuu kahdella pääasiallisella tavalla: Odoo Studiolla ilman koodia tai suoraan Pythonilla, kun halutaan täydellistä hallintaa.

Odoo Studiolla

Studiolla kentän lisääminen on yksinkertaista: avaa Studio kohdemallissa, valitse Fields‑paneelista Reference ja määritä valittavat mallit käyttöliittymässä. Studio tallentaa kentän x_‑etuliitteellä kuten muutkin manuaaliset kentät.

Tämä tapa sopii nopeisiin räätälöinteihin ja liiketoiminnan toimijoille, jotka haluavat muokata lomakkeita ilman kehittäjää. Huomaa kuitenkin, että Studio‑kentillä voi olla rajoitteita edistyneemmissä asetuksissa, kuten dynaamisissa selection‑metodeissa tai laskettavissa arvoissa.

Tekninen toteutus Pythonilla

Täyden kehitystyön tekemiseksi määrittele Reference‑kenttä suoraan Python‑mallissa. Se mahdollistaa dynaamisen selection‑metodin ja tarkemman hallinnan.

from odoo import api, fields, models

class ApprovalRequest(models.Model):
    _name = 'approval.request'
    _description = 'Approval Request'

    name = fields.Char(string='Request Name', required=True)

    @api.model
    def _get_document_types(self):
        return [
            ('purchase.order', 'Purchase Order'),
            ('hr.expense.sheet', 'Expense Report'),
            ('hr.leave', 'Time Off Request'),
            ('sale.order', 'Sale Order'),
        ]

    document_ref = fields.Reference(
        selection='_get_document_types',
        string='Document',
        help='Select the document this approval relates to.',
    )

Kun annetaan metodin nimi selection‑parametrina, voit rakentaa dynaamisen listan ehdoin: suodattaa asennetut moduulit, lukea konfiguraatiota tai muokata valintoja käyttöoikeuksien mukaan.

Luo kenttä XML‑RPC:lla

Voit luoda Reference‑kentän myös ohjelmallisesti Odoon XML‑RPC‑rajapinnan kautta. Tämä on kätevää, jos haluat automatisoida kenttien luomisen osana etäkonfiguraatiota.

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_related_document',
        'field_description': 'Related Document',
        'model_id': model_id,
        'ttype': 'reference',
        'selection': "[('sale.order', 'Sale Order'), ('purchase.order', 'Purchase Order')]",
        'state': 'manual',
    }]
)

Huomaa, että XML‑RPC‑kutsussa selection lähetetään merkkijonona, joka arvioidaan Pythoniksi — näin Odoo tallentaa sen ir.model.fields-tauluun.

Hyvät käytännöt

Seuraavat käytännöt auttavat välttämään ongelmia Reference‑kenttien kanssa.

• Pidä selection-lista lyhyenä ja relevanttina. Älä lisää jokaista mahdollista mallia vain koska voit; rajattu ja merkityksellinen lista parantaa käytettävyyttä ja vähentää virheellisiä valintoja.
• Käytä Many2one‑kenttää kun viittaus on aina samaan malliin. Reference on tarkoitettu polymorfisiin suhteisiin; jos kohdemalli ei muutu, Many2one on suoraviivaisempi, helpompi raportoida ja tehokkaampi suodattaa.
• Tarkista aina tyhjät arvot lasketuissa kentissä. Reference palauttaa Pythonissa False tyhjänä — tarkista tämä ennen kuin yrität lukea viitattuja kenttiä.
• Käsittele orpoarvot automaatioilla. Koska tietokanta ei poista viitteitä automaattisesti, on hyvä ottaa käyttöön ajoittain suoritettava tarkistus, joka puhdistaa viittaukset poistettuihin tietueisiin.
• Käytä selittäviä valintojen tekstejä. selection-listan näkyvät nimet ovat käyttäjän kanssa vuorovaikutuksessa olevia tekstejä — valitse liiketoimintakielelle sopiva kuvaus kuten "Asiakaslasku" eikä teknistä mallinimeä.
• Dokumentoi kenttä teknisissä spesifikaatioissa. Koska Reference eroaa Many2onesta käytökseltään, kuvaa selkeästi miksi valinta tehtiin ja mitä malleja kenttä voi sisältää.

Yleiset sudenkuopat

Seuraavat virheet toistuvat usein kun Reference‑kenttää käytetään ensimmäistä kertaa.

Ei saa olettaa että domain‑filtterit toimivat kuten Many2one. Suodatukset täytyy rakentaa käyttäen tallennettua merkkijonoa, esimerkiksi 'sale.order,15', ei pelkkää id:tä.

Kehittäjät yrittävät joskus tehdä domainin muotoon [('document_ref', '=', 15)] — tämä ei toimi, koska arvo on merkkijono, ei pelkkä numero.

Unohdetut orpoarvot — poistetut tietueet eivät tyhjennä Reference‑kenttää. Poistetun tilauksen viite jää merkkijonoon ja kentän lukeminen palauttaa False ilman virheilmoitusta.

Koodi, joka olettaa viitteen olevan aina validi, aiheuttaa virheitä; tarkista aina viitattu objekti ennen käyttöä.

Dynaamisen kaikkien mallien listan ylikäyttö. Vaikka voit hakea kaikki asennetut mallit ir.model:stä, se johtaa usein satojen vaihtoehtojen alasvetoon — rajoita valinnat reaalisiin dokumenttityyppeihin.

Liian laaja lista sekoittaa käyttäjiä ja lisää virheellisiä tietoja, joten kuratoi lista liiketoimintatarpeiden mukaan.

Raportoinnin group‑by‑rajoitteet. Koska Reference on teksti, sitä ei voi ryhmitellä tai aggregoida natiivisti samalla tavalla kuin Many2one‑kenttiä. Tarvittaessa tee laskettu kenttä, joka erottaa mallin nimen omaan kenttään, jotta raportointi toimii odotetusti.

Jos tarvitset ryhmittelyjä tai pivot‑analyysejä viitetyistä dokumenteista, luo erillinen laskettu kenttä tai siirrä tiedot strukturoituun muotoon.

Studio‑käyttäjien sekaannus Reference ja Many2one välillä. Molemmat yhdistävät tietueita, mutta toiminnallisuus on erilainen: Many2one on aina sidottu yhteen malliin, Reference antaa käyttäjän valita mallin joka täytöllä.

Jos loit vahingossa Many2one‑kentän kun tarvitsit Referencea, kenttä pitää yleensä luoda uudelleen oikein — sitä ei kannata yrittää muokata jälkikäteen samaan tarkoitukseen.

Yhteenveto

Reference‑kenttä paikkaa Many2one‑kentän rajoitteita silloin kun viitteen täytyy olla joustava ja osoittaa eri dokumenttityyppeihin tilanteen mukaan. Se on helppo määrittää, toimii Studiolla ja integroidaan sujuvasti Python‑malleihin ammattimaisissa toteutuksissa.

Keskeiset huomioon otettavat asiat ovat merkkijonomuotoinen tallennus, vierasavaimen puuttuminen ja suodatus merkkijonon mukaan. Kun nämä erot ymmärretään, Reference‑kenttä käyttäytyy ennustettavasti ja luotettavasti osana Odoo‑tietomallia.

Olipa kyse yleisestä hyväksyntätyönkulusta, tukipyyntöjen linkityksestä eri dokumentteihin tai muistiinpanomallista, joka kattaa useita moduuleja, Reference tarjoaa siistin ja ylläpidettävän tavan välttää logiikan toistoa ja moninkertaista mallien määrittelyä.

Tarvitsetko apua Odoo‑projektissasi?

Dasololla autamme yrityksiä suunnittelemaan, toteuttamaan ja optimoimaan Odoon siten, että järjestelmä seuraa oikeita liiketoimintaprosesseja. Olipa tarpeesi kenttälogiikan rakentaminen, tietomallin suunnittelu tai olemassa olevan instanssin laajentaminen — tiimillämme on kokemusta ja osaamista toteuttaa ratkaisut oikein.

Jos työstät Odoo‑projektia ja kaipaat neuvoja kenttävalinnoissa, data‑arkkitehtuurissa tai kehityskäytännöissä, ota yhteyttä — käydään yhdessä läpi tilanne ja löydetään toimivin ratkaisu.

Ota yhteyttä Dasoloon