Odoo Reference Field: Komplett Guide och Praktiska Exempel

Introduktion

De flesta Odoo‑utvecklare använder Many2one när ett fält ska peka på en annan post — och det är ofta helt rätt. Men det finns situationer då den länkade posten kan tillhöra olika modeller beroende på sammanhanget: en offert, en inköpsorder, ett projektuppdrag eller något annat. För sådana flexibla kopplingar är Reference‑fältet byggt.

Reference‑fältet är en polymorf fälttyp i Odoo som tillåter att en och samma kolumn pekar på poster i olika modeller. Istället för att hårdkoda en enda målmodell väljer användaren först vilken modelltyp som ska användas och därefter den specifika posten — resultatet blir en adaptiv länk som kan passa flera arbetsflöden.

Den här guiden förklarar vad Reference sparar i databasen, hur Odoo hanterar fältet i ORM:en, hur du lägger till det via Studio eller i Python, och verkliga affärsexempel där det ger tydlig nytta.

Vad är Reference-fältet i Odoo

I Odoo‑ORM:en är Reference ett specialfält som i sina konfigurationer innehåller en lista över tillåtna modeller (selection). Till skillnad från Many2one är målet inte en fix modell utan en uppsättning möjliga modeller som användaren kan välja mellan.

I databasen lagras värdet som text i formen model_name,record_id, till exempel sale.order,42 för ordernr 42. Den här textrepresentationen är viktig att känna till när man söker, filtrerar eller bygger SQL‑frågor.

I användargränssnittet visas Reference ofta som två steg: först väljer användaren modelltyp i en dropdown (t.ex. Faktura eller Projektuppgift) och därefter söker eller väljer den specifika posten inom den modellen. När användarna väl förstått arbetsflödet är gränssnittet enkelt och tydligt.

Här följer ett exempel på en grundläggande definition av ett Reference‑fält i 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',
    )

Parametern selection är en lista med tupler där varje tuppel innehåller det tekniska modellnamnet och den användarvänliga etiketten som ska synas i dropdownen. Du bestämmer vilka modeller som ska erbjudas.

Det går även att göra listan dynamisk genom att hämta modeller från ir.model vid körning. Det ger hög flexibilitet men kan bli rörigt för slutanvändare om listan inte filtreras noggrant.

I Odoo Studio finns Reference under fälttyperna som "Reference". När du lägger till det via Studio kan du välja vilka modeller som ska vara valbara direkt i gränssnittet, utan kod — en snabb väg för icke‑utvecklare att lägga in polymorfa länkar.

Hur fältet fungerar

Att förstå hur Reference sparas och tolkas är avgörande för att använda det korrekt i utveckling och konfiguration.

Lagring i databasen

Till skillnad från Many2one, som bara lagrar ett heltal som främmande nyckel, sparar Reference både modellnamnet och id:t som en textsträng, exempelvis sale.order,15. I PostgreSQL hamnar det i en VARCHAR-kolumn och det finns ingen databasdriven referensintegritet kopplad till värdet — det är ett medvetet designval för att stödja polymorfism.

Eftersom det inte finns någon databaskonstraint kommer Odoo inte automatiskt att uppdatera eller nollställa Reference‑värden om den länkade posten tas bort. Om en säljorder raderas kommer fältet att kvarstå med den gamla textsträngen — något du måste hantera i din design.

Åtkomst till länkad post i Python

När du läser ett Reference‑fält i Python returnerar ORM:en själva postobjektet från den länkade modellen. Du kan accessa fält på objektet precis som med en Many2one. Om fältet är tomt returneras 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

Trots den textbaserade lagringen löser Odoo upp pekningen och ger dig ett fungerande record‑objekt i koden — en bekvämlighet som ORM:en sköter åt dig.

Viktiga fältattribut

Följande attribut är de mest relevanta när du definierar ett Reference‑fält i Odoo:

• selection: Definierar vilka modeller som kan väljas. Kan vara en statisk lista eller namnet på en metod som returnerar listan dynamiskt.
• string: Fältnamn/etikett som visas i UI.
• required: Kräver att användaren väljer både modell och post innan posten kan sparas.
• readonly: Gör fältet icke‑ändringsbart i UI — bra om värdet sätts via kod.
• help: Tooltip som förklarar vad fältet används till för slutanvändaren.
• compute: Reference kan beräknas via en Python‑metod, vilket är användbart när du vill sätta referensen utifrån affärslogik.

Filtrering och sökningar

Eftersom värdet är en sträng måste du vid sökningar bygga rätt textvärde. Du kan söka på exakt matchning eller använda textliknande operationer.

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

Du kan även filtrera på modelltyp med hjälp av like-operatorn:

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

Tänk på denna skillnad mot Many2one‑domäner när du bygger rapporter, beräknade fält eller automatiseringar som förlitar sig på Reference‑värden.

Affärsscenarier där Reference hjälper

När är Reference verkligen användbart? Kort sagt: när samma länk måste kunna peka på olika dokumenttyper beroende på situation. Nedan följer fem praktiska exempel från verkliga arbetsflöden.

1. Supportärenden kopplade till valfri dokumenttyp

Supportagenter kan behöva hänvisa till fakturor, leveranser, avtal eller produktposter. Istället för att ha flera separata fält räcker ett Reference‑fält där agenten först väljer typ och sedan posten — allt relevant sammanhålls i en enda kolumn.

2. Säljuppföljning med flera källor

En aktivitet i CRM kan ha sitt ursprung i en lead, ett erbjudande, ett avtal eller ett supportärende. Ett Reference‑fält på aktivitetsmodellen låter säljteamet länka tillbaka till rätt ursprungsdokument utan att binda modellen till en enda typ.

3. Gemensamma anteckningar över moduler

Företag som vill ha en universell anteckningsmodell kan använda Reference för att låta samma anteckning fästas på kundkort, projektuppgift, produktionsorder eller inköp — utan att behöva skapa en specifik anteckningsmodell per objektstyp.

4. Godkännandeflöden för flera dokument

I en generell godkännandeprocess måste förfrågan peka till den faktiska posten som ska godkännas — vilket kan vara inköp, utlägg, semesteransökan eller kontrakt. Ett Reference‑fält på godkännandemodellen håller processen generisk och återanvändbar.

5. Utlägg kopplade till projekt eller kundorder

I vissa bokföringsscenarier behöver ett kostnadsutlägg kunna fästas antingen mot ett projekt eller en försäljningsorder. En Reference som erbjuder både project.project och sale.order ger flexibilitet för redovisningen, särskilt i konsult‑ och tjänsteföretag.

Skapa eller anpassa ett Reference-fält

Det finns två huvudvägar att lägga till ett Reference‑fält: via Odoo Studio för enkla anpassningar eller i Python för full kontroll.

Använda Odoo Studio

I Studio är det enkelt att lägga till ett Reference‑fält utan kod: öppna Studio, gå till Fältpanelen och välj Reference. Därefter pekar du ut vilka modeller som ska finnas i dropdownen. Studio skapar fältet som ett x_-fält och är bra för snabba ändringar av formulär.

Detta är perfekt för snabba affärsanpassningar eller för analytiker som vill lägga till fält utan att involvera utvecklare. Observera att Studio‑fält kan vara mindre flexibla vid krav på dynamiska urval eller beräknade värden.

Teknisk implementation i Python

För mer avancerade lösningar definierar du Reference i en Python‑modell. Nedan visas ett exempel med dynamiskt urval via en metod:

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

Att peka på en metod (via dess namn) för selection ger flexibilitet att bygga listan baserat på installerade moduler eller konfigurationer.

Skapa via XML‑RPC API

Du kan även skapa ett Reference‑fält programmatisk via Odoo:s XML‑RPC API — praktiskt vid automatiserade driftsättningar eller när du skapar fält från en extern konfigurationsprocess. Fälttypen heter reference och selection skickas som en sträng som kan evalueras i Python.

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

Tänk på att selection skickas som en strängrepresentation av listan när du använder API:t — det är så Odoo sparar det i ir.model.fields.

Bra arbetsrutiner

Riktlinjer att följa när du designar med Reference‑fält

• Håll selection‑listan kort och relevant. Ta inte med alla modeller bara för att det går; ett begränsat urval minskar felaktiga val och gör fältet lättare att använda.
• Använd Many2one där länken alltid går till samma modell. Om målmodellen aldrig varierar är Many2one enklare, snabbare att söka och bättre kompatibel med Odoo‑rapporter.
• Kontrollera alltid för null i beräknade fält. I Python returnerar ett tomt Reference‑fält False; aldrig antar att ett objekt alltid finns där.
• Hantera föräldralösa referenser i automatiseringar. Eftersom databasen inte tar bort eller uppdaterar Reference‑värden automatiskt, lägg gärna in ett schemalagt jobb som rensar upp uråldriga eller ogiltiga referenser.
• Ge tydliga och användarvänliga etiketter i selection. Visa affärstexter som "Kundfaktura" istället för tekniska modellnamn som account.move.
• Dokumentera fältet i tekniska specar. Eftersom Reference beter sig annorlunda än Many2one underlättar en tydlig motivering och lista över ingående modeller för framtida utvecklare.

Vanliga fallgropar

De vanligaste misstagen vi ser när team börjar använda Reference

Att behandla det som en Many2one i domäner

En vanlig felaktig antagning är att man skriver en domän som om fältet bara innehöll ett id, t.ex. [('document_ref', '=', 15)]. Det fungerar inte — värdet är en sträng som kräver formatet model,id.

Glömma att raderade poster lämnar ogiltiga värden

Eftersom det inte finns någon främmande nyckel kommer raderade målposter lämna kvar textsträngar i Reference‑fältet. När du läser fältet i kod får du False för sådana referenser; din logik måste därför hantera ogiltiga eller saknade målposter.

Överanvända dynamiskt "alla modeller"-urvalet

Att automatiskt visa alla installerade modeller från ir.model ger ofta en oöverskådlig dropdown med hundratals alternativ. Begränsa alltid listan till relevanta dokumenttyper för användarna.

Räkna inte med inbyggd gruppering i rapporter

Eftersom Reference lagras som text fungerar inte Odoos standard group‑by/pivot på samma sätt som för Many2one. Vill du gruppera på länkad dokumenttyp behöver du ofta en beräknad fältvariant som extraherar modellnamn eller skapar en separat val‑/textkolumn för rapportering.

Förväxla inte Reference och Many2one i Studio

I Studio förväxlar en del användare Reference med Many2one eftersom båda länkar till andra poster. Skillnaden är att Many2one alltid pekar på en bestämd modell medan Reference låter användaren välja modell per post. Om du råkat välja fel typ måste fältet ofta återskapas.

Sammanfattning

Reference fyller ett tydligt behov där en länk måste vara flexibel nog att peka på flera olika dokumenttyper. Det är enkelt att definiera, fungerar i Studio för no‑code‑ändringar och kan implementeras i Python för mer avancerade scenarier.

Kom ihåg string‑formatet vid lagring, avsaknaden av automatisk rensning och att sökningar kräver sammansatta strängvärden. När du tar hänsyn till dessa skillnader blir fältet förutsägbart och stabilt i din datamodell.

Oavsett om du bygger ett generellt godkännandeflöde, låter supportärenden referera till olika dokument eller vill ha en central anteckningsmodell över moduler, ger Reference ett rent och underhållsbart sätt att undvika duplicerad logik för varje modelltyp.

Behöver du hjälp med din Odoo-implementering?

På Dasolo hjälper vi företag att implementera och skräddarsy Odoo så att systemet speglar verkliga affärsflöden. Vi kan designa datamodeller, bygga speciallogik och optimera implementationer så att ni undviker vanliga fallgropar.

Håller ni på med ett Odoo‑projekt och behöver råd kring fälttyper, datamodell eller utvecklingspraxis? Kontakta oss gärna — vi går igenom er situation och föreslår en praktisk lösning.

Kontakta Dasolo