Reference Field in Odoo: De Complete Gids

Introductie

In Odoo grijpen developers meestal naar Many2one wanneer ze een record aan één ander record willen koppelen — en dat is in de meeste situaties perfect. Er bestaan echter scenarios waarin de gekoppelde entiteit kan verschillen: soms is het een verkooporder, soms een aankooporder, soms een projecttaak, afhankelijk van de context. Voor die flexibiliteit is het Reference-veld ontworpen.

Het Reference-veld is een polymorf veldtype binnen het Odoo ORM: in plaats van altijd naar één vast model te wijzen, laat het toe dat de gebruiker eerst het type document kiest en daarna het specifieke record. Zo ontstaat één adaptieve koppeling die in verschillende processen gebruikt kan worden.

Deze gids legt uit wat het Reference-veld bewaart, hoe het zich gedraagt in het datamodel van Odoo, hoe je het maakt of aanpast via Odoo Studio of Python, en voor welke bedrijfsprocessen het écht nuttig is.

Wat is het Reference-veld in Odoo

In technische termen is het Reference-veld een speciaal veld dat verwijst naar een record van elk model dat je op voorhand opneemt in de selection-lijst. Dat maakt het wezenlijk anders dan een Many2one, dat altijd naar één vast model linkt.

In de database bewaart een Reference-veld zijn waarde als tekst in het formaat model_name,record_id. Een link naar verkooporder 42 wordt dus bijvoorbeeld opgeslagen als sale.order,42. Dat is belangrijk om te weten als je rechtstreeks in de database filtert of rapporteert.

Voor eindgebruikers ziet het veld eruit als een tweeledige keuze: eerst kies je het type document in een dropdown (bv. Verkooporder, Factuur, Projecttaak), daarna zoek je het specifieke record binnen dat model. De interface is duidelijk zodra gebruikers het tweestappenprincipe doorhebben.

Onderstaande code geeft een basisvoorbeeld van een Reference-veld in Python:

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

De selection-parameter bestaat uit tuples: het technische modelnaam (bv. sale.order) en het leesbare label dat de gebruiker ziet. Zo bepaal je welke modellen beschikbaar zijn in de keuzelijst.

Je kunt de selectie ook dynamisch genereren met een methode die modellen ophaalt uit ir.model. Dat is handig voor zeer configureerbare tools, maar zonder filtering krijgt een eindgebruiker snel een overweldigend lange lijst.

In Odoo Studio vind je het Reference-veld in het veldentype-paneel onder de naam Reference. Via Studio kun je de beschikbare modellen instellen zonder één regel code te schrijven, wat het toegankelijk maakt voor businessanalisten en power users.

Hoe het veld werkt

Goed begrijpen hoe het Reference-veld data opslaat en teruggeeft, is essentieel om het correct en betrouwbaar in Odoo-projecten te gebruiken.

Opslag in de database

In tegenstelling tot Many2one — dat enkel een integer (de foreign key) bewaart — slaat het Reference-veld een string op met zowel modelnaam als record-ID, bijvoorbeeld sale.order,15, in een VARCHAR-kolom in PostgreSQL. Daardoor bestaan er geen database‑level foreign key constraints op dat veld, wat bewust zo is om polymorfisme mogelijk te maken.

Omdat er geen relationele constraint is, ruimt de database niet automatisch verwijzingen op wanneer het doelrecord wordt verwijderd. Een verwijzing naar een verwijderde verkooporder blijft als tekst bestaan. Houd daar rekening mee bij onderhoud en integriteitstaken.

Toegang tot het gekoppelde record in Python

Wanneer je vanuit Python een Reference-veld uitleest, levert Odoo het echte recordobject van het betreffende model terug. Je kunt zijn velden rechtstreeks aanspreken, net zoals bij een Many2one. Als het veld leeg is, krijg je False terug.

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

Dit is een handige eigenschap van de Odoo ORM: hoewel de opgeslagen waarde een tekst is, resolveert het framework die automatisch naar een recordobject wanneer je het in code benadert.

Belangrijke veldattributen

Dit zijn de meest relevante opties die je op een Reference-veld kunt instellen binnen Odoo:

• selection: Een lijst van tuples die bepaalt welke modellen selecteerbaar zijn. Kan ook de naam van een methode zijn (string) die dynamisch die lijst teruggeeft.
• string: Het label dat gebruikers in de interface zien.
• required: Maakt het veld verplicht; gebruiker moet zowel type als record kiezen voor het opslaan.
• readonly: Maakt het veld niet wijzigbaar vanuit de UI. Handig wanneer de referentie programmatisch wordt gezet.
• help: Tooltip bij het veldlabel om gebruikers te begeleiden bij hun keuze.
• compute: Net als andere velden kan een Reference-veld berekend worden met een Python-methode, bijvoorbeeld om de referentie automatisch in te vullen volgens bedrijfsregels.

Filteren en zoeken

Omdat de waarde tekstueel is opgeslagen, vereisen domain-filters dat je de volledige tekstwaarde samenstelt. Om records te zoeken die naar een bepaald document verwijzen, bouw je de string zelf op:

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

Je kunt ook filteren op modeltype met een like-operator:

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

Houd deze string-gebaseerde zoeklogica in gedachten bij het ontwerpen van rapporten of computed fields die afhankelijk zijn van Reference-waarden: ze werken anders dan typische Many2one‑domeinen.

Praktische bedrijfsgevallen

Het Reference-veld levert de meeste waarde wanneer eenzelfde link in verschillende situaties naar uiteenlopende documenttypes kan wijzen. Hieronder vijf concrete voorbeelden uit de praktijk.

1. Helpdesktickets gekoppeld aan elk type document

Een supportticket kan met van alles te maken hebben: een factuurgeschil, een leveringsprobleem, een contractvraag of een defect product. In plaats van per documenttype een apart veld te maken, kan één Reference-veld op het ticket model de agent toelaten het relevante document te linken: type kiezen en daarna het specifieke record.

2. CRM-activiteiten met verschillende brondocumenten

Activiteiten of opvolgtaken ontstaan vaak vanuit verschillende bronnen: een lead, een offerte, een contract of een supportcase. Een Reference-veld op het activiteitstype laat salesmensen eenvoudig het bronrecord taggen zonder vast te zitten aan één model.

3. Notities en annotaties over modules heen

Sommige bedrijven willen één gezamenlijke notitie‑entiteit die je op klanten, projecttaken, productieorders of aankooporders kan plakken. Een Reference-veld maakt dat mogelijk zonder telkens dezelfde notitie‑structuur voor elk documenttype te dupliceren.

4. Algemeen goedkeuringsproces

In een generieke workflow voor goedkeuringen moet de aanvraag verwijzen naar het te goedkeuren document — dat kan een aankooporder, declaratie, verlofaanvraag of contract zijn. Een Reference-veld op het goedkeuringsmodel houdt de architectuur eenvoudig: één logica voor alle documenten.

5. Kosten koppelen aan project of verkooporder

Soms moet een onkost gekoppeld worden aan een project of aan een verkooporder, afhankelijk van de aard van de kost. Een Reference-veld met project.project en sale.order in de selectie geeft boekhouders de nodige flexibiliteit — handig voor dienstverleners en consultants.

Reference-veld aanmaken of aanpassen

Referentievelden voeg je meestal toe op twee manieren: via Odoo Studio voor no-code, of direct in Python voor volledige controle.

Via Odoo Studio

Met Studio voeg je snel een Reference-veld toe zonder code: open Studio op het formulier, kies Fields en voeg een nieuw veld van het type Reference toe. Je selecteert daar welke modellen in de dropdown moeten verschijnen. Studio slaat het veld op als een manueel veld met x_-prefix.

Dit is ideaal voor snelle aanpassingen en voor analisten die formulieren willen uitbreiden zonder ontwikkelaar. Wees je wel bewust dat Studio‑velden beperkte mogelijkheden kunnen hebben voor geavanceerde configuraties zoals dynamische selectie-methoden of ingewikkelde computed logic.

Technische implementatie in Python

Voor volledige ontwikkelaarscontrole definieer je het Reference-veld rechtstreeks in een Python-model. Onderstaand een uitgebreider voorbeeld met een dynamische selectie-methode:

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

Door voor selection de naam van een methode door te geven maak je de selectie dynamisch: je kunt condities toevoegen, controleren welke modules geïnstalleerd zijn of keuzes uit configuratieregels samenstellen.

Aanmaken via de XML-RPC API

Je kunt een Reference-veld ook programatisch aanmaken via de XML-RPC API van Odoo — handig bij automatische deploys van configuraties. Het veldtype is reference en de selectie geef je door als stringrepresentatie van de lijst:

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

Let op: via de API wordt de selection als een Python-evalueerbare string doorgegeven, niet als een echte lijst — zo leest Odoo het uit ir.model.fields.

Aanbevelingen

Praktische richtlijnen bij gebruik van Reference-velden

• Houd de selectie kort en relevant. Voeg niet elk model toe alleen omdat het kan. Beperk de lijst tot documenttypes die echt zinvol zijn; een lange lijst verwart gebruikers.
• Gebruik Many2one als je altijd naar hetzelfde model linkt. Reference is bedoeld voor polymorfe relaties. Als het doelmodel nooit verandert, is Many2one eenvoudiger, sneller te doorzoeken en beter te gebruiken in rapporten.
• Controleer op null-waarden bij berekende velden. Een leeg Reference-veld geeft in Python False terug. Elke code die het gelinkte record gebruikt moet dat scenario afvangen.
• Ruim verweesde referenties op met geautomatiseerde acties. Omdat de database geen referentiële integriteit afdwingt, is het verstandig een cron of serveractie te hebben die periodiek controleert op en stale referenties verwijdert.
• Gebruik duidelijke labels in de selectie. Het label in de tweede kolom van elke tuple ziet de gebruiker; gebruik zakelijke, begrijpelijke termen zoals "Klantfactuur" in plaats van technische modelnamen.
• Documenteer het veld in technische specificaties. Reference-velden gedragen zich anders dan Many2one; een korte toelichting in je technische documentatie helpt toekomstige ontwikkelaars te begrijpen waarom en met welke modellen het veld werkt.

Veelvoorkomende valkuilen

De fouten die we het vaakst zien bij het gebruik van Reference-velden

Het behandelen als Many2one in domain-filters

Sommige ontwikkelaars proberen hetzelfde filter-syntaxis als bij Many2one te gebruiken, bijvoorbeeld [('document_ref', '=', 15)]. Dat werkt niet: de opgeslagen waarde is een string zoals sale.order,15, niet enkel een integer. Je moet de volledige tekst samenstellen in het filter.

Vergeten dat verwijderde records verweesdheid achterlaten

Omdat er geen foreign key bestaat, ruimt verwijderen van het doelrecord de Reference-kolom niet op. Als een verkooporder verwijderd werd maar een ticket nog sale.order,42 bevat, zal het veld bij uitlezing False teruggeven in plaats van een fout te gooien. Code moet hiertegen bestand zijn.

Overmatig gebruik van dynamische 'alle modellen'-selectie

Het is mogelijk om via een methode alle geïnstalleerde modellen uit ir.model op te halen. Dat is krachtig, maar voor gebruikers meestal te ruim: honderden modellen in een dropdown leidt tot slechte datakwaliteit. Filter altijd naar een behapbare set.

Verwachting van native group-by in rapporten

Reference-velden zijn tekstvelden in de DB en geen foreign keys. Native group-by en pivot functies werken er daarom niet op zoals bij Many2one. Wil je rapporteren op gekoppeld document, maak dan een computed veld dat modelnaam of type apart opslaat.

Verwarring tussen Reference en Many2one in Odoo Studio

In Studio raken gebruikers soms in de war omdat beide velden records koppelen. Het cruciale verschil: Many2one verwijst altijd naar één gekozen model; Reference laat gebruikers het model zelf kiezen bij het invullen. Heb je per vergissing een Many2one aangemaakt terwijl je polymorfie nodig had, dan zul je het veld moeten herbouwen.

Samenvatting

Het Reference-veld vult precies die leemte in waar Many2one tekortschiet: het biedt een eenvoudige, onderhoudbare manier om naar verschillende documenttypes te linken zonder per model duplicatie van logica. Het werkt zowel in Studio voor no-code scenario's als in Python voor ontwikkelwerk.

Belangrijk om te onthouden zijn de tekstgebaseerde opslag, het ontbreken van automatische referentiële opschoning en het feit dat je bij filters samengestelde stringwaarden gebruikt in plaats van zuivere IDs. Als je hiermee rekening houdt, gedraagt het veld zich voorspelbaar.

Of je nu een generieke goedkeuringsflow opzet, supporttickets aan uiteenlopende documenttypes linkt of een flexibel notitiesysteem over meerdere modules bouwt: het Reference-veld voorkomt duplicatie en houdt je datastructuur overzichtelijk.

Hulp nodig met uw Odoo-implementatie?

Bij Dasolo begeleiden we bedrijven bij het implementeren, aanpassen en optimaliseren van Odoo zodat het aansluit op hun echte processen. Of het nu gaat om custom fields, datamodelontwerp of uitbreiding van een bestaand systeem: wij zorgen voor een nette, toekomstvaste aanpak.

Werk je aan een Odoo-project en heb je advies nodig over veldkeuze, data-architectuur of ontwikkelpraktijken? Neem gerust contact op — we bespreken graag je situatie en vinden samen de juiste oplossing.

Contacteer Dasolo