Einführung
Odoo-Entwickler greifen oft zum Many2one-Feld, weil es für feste Verknüpfungen ideal ist. Stehen Sie jedoch vor Fällen, in denen ein Bezugspunkt variabel sein muss — etwa mal eine Verkaufsbestellung, mal eine Bestellung beim Lieferanten oder ein Produktionsauftrag — dann stößt Many2one an seine Grenzen. Genau für solche flexiblen Verknüpfungen wurde das Reference-Feld konzipiert.
Das Reference-Feld ist ein besonders anpassungsfähiger Feldtyp im Odoo-Modell: anstatt immer auf ein einziges Modell zu zeigen, erlaubt es eine Auswahl aus vordefinierten Modelltypen. Der Anwender wählt zuerst die Art des Dokuments und dann den konkreten Datensatz — so entsteht eine polymorphe Beziehung, die sich an unterschiedliche Prozesse anpasst.
Diese Übersicht erklärt, was das Reference-Feld tatsächlich speichert, wie es sich im Odoo-Datenmodell verhält, wie Sie es per Studio oder in Python anlegen und wo es echten Mehrwert in Geschäftsprozessen bringt.
Was ist das Reference-Feld in Odoo?
Technisch ist das Reference-Feld ein spezieller Feldtyp, dessen zulässige Zieldatensätze Sie über eine Auswahl (selection) festlegen. Im Unterschied zum Many2one ist das Zielmodell nicht fest kodiert, sondern stammt aus dieser Liste von möglichen Modellen.
Im Hintergrund speichert Odoo den Verweis als einfachen Text im Format model_name,record_id — beispielsweise sale.order,42 für Verkaufsauftrag 42. Dieses Speicherformat ist wichtig, sobald Sie direkt in der Datenbank oder per Suchabfragen arbeiten müssen.
Für Anwender zeigt sich das Reference-Feld als zweistufige Eingabe: zuerst die Dokumentart aus einem Drop-down, danach die Auswahl des konkreten Datensatzes per Suchfeld. Sobald der Ablauf verstanden ist, wirkt die Oberfläche klar und effizient.
Ein typisches Beispiel für die Definition eines Reference-Feldes in Python sieht so aus:
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',
)Der Parameter selection ist eine Liste von Tupeln: jeweils das technische Modell (z. B. sale.order) und die Beschriftung, die Anwender im Dropdown sehen. Sie bestimmen damit exakt, welche Modelle auswählbar sind.
Alternativ kann die Auswahl dynamisch erzeugt werden — z. B. aus der Tabelle ir.model — sodass zur Laufzeit alle passenden Modelle angeboten werden. Diese Variante ist flexibel, kann aber für Anwender unübersichtlich werden, wenn die Liste nicht gefiltert wird.
In Odoo Studio finden Sie den Feldtyp unter den verfügbaren Feldarten als Reference. Studio erlaubt das Anlegen und Konfigurieren der auswählbaren Modelle direkt in der Oberfläche, ohne eine einzige Zeile Code schreiben zu müssen — praktisch für schnelle Anpassungen.
Wie das Feld funktioniert
Ein klares Verständnis darüber, wie das Reference-Feld Daten speichert und auflöst, ist grundlegend, um es korrekt in Odoo-Projekten einzusetzen.
Speicherverhalten in der Datenbank
Im Gegensatz zu Many2one, das lediglich eine Ganzzahl als Fremdschlüssel speichert, liegt beim Reference-Feld ein Textwert vor, der Modellname und Datensatz-ID enthält — z. B. sale.order,15 — und in einer VARCHAR-Spalte abgelegt wird. Dadurch gibt es keine Datenbank-Foreign-Key-Constraint, weil das Feld polymorph ausgelegt ist.
Weil keine DB-Constraint existiert, werden Referenzen nicht automatisch bereinigt, wenn der verknüpfte Datensatz gelöscht wird. Löschen Sie etwa einen Verkaufsauftrag, bleibt der String sale.order,42 stehen — ein Verhalten, das bei Wartung und Validierung berücksichtigt werden muss.
Zugriff auf das verlinkte Objekt in Python
Lesen Sie ein Reference-Feld in Python aus, liefert Odoo ein echtes Recordset-Objekt des referenzierten Modells — genauso zugreifbar wie bei Many2one. Ist kein Wert gesetzt, erhalten Sie 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. 15Das ORM verknüpft also die textuelle Speicherung mit einem echten Model-Record beim Zugriff, was die Programmierung deutlich angenehmer macht, trotz des einfachen Speichermediums im Hintergrund.
Wichtige Feldattribute
Diese Attribute sind für die Konfiguration eines Reference-Feldes in Odoo besonders relevant:
- selection: Liste der auswählbaren Modelle oder der Name einer Methode, die diese Liste dynamisch liefert.
- string: Anzeigename des Feldes in der Oberfläche.
- required: Legt das Feld als Pflichtfeld fest — sowohl Modelltyp als auch Datensatz müssen ausgewählt werden, bevor gespeichert werden darf.
- readonly: Sperrt das Feld in der UI, nützlich, wenn der Wert programmgesteuert gesetzt wird.
- help: Hilfetext, der beim Überfahren des Labels angezeigt wird und Anwendern Orientierung gibt.
- compute: Reference-Felder lassen sich wie andere Felder per Python-Methode berechnen und automatisch füllen — praktisch zur Abbildung von Geschäftslogik.
Filtern und Suchen
Weil intern ein String gespeichert wird, benötigen Such- und Domain-Ausdrücke das passende Format. Um Datensätze zu finden, die auf ein bestimmtes Dokument zeigen, müssen Sie den kombinierten String verwenden:
tickets = self.env['helpdesk.ticket'].search([
('related_document', '=', 'sale.order,15')
])Sie können auch per like nach Modelltyp filtern, wenn Ihnen die ID egal ist:
tickets = self.env['helpdesk.ticket'].search([
('related_document', 'like', 'sale.order,')
])Beachten Sie dieses String-basierte Suchverhalten bei Berichten oder berechneten Feldern: Es unterscheidet sich vom üblichen Many2one-Domainausdruck und erfordert entsprechend spezielle Logik.
Praktische Einsatzszenarien im Unternehmen
Wann sich das Reference-Feld besonders lohnt
1. Hilfeanfragen, die an verschiedene Dokumente anknüpfen können
Support-Tickets beziehen sich oft auf ganz unterschiedliche Dinge — eine Rechnung, eine Lieferung, ein Vertrag oder einen Auftrag. Statt für jeden Typ ein eigenes Feld anzulegen, erlaubt ein einzelnes Reference-Feld dem Agenten, flexibel das passende Dokument zu verknüpfen. Das hält das Datenmodell schlank und die Eingabe für den Anwender übersichtlich.
2. Aktivitäten im CRM mit unterschiedlicher Herkunft
Vertriebsaktivitäten können aus Leads, Angeboten, bestehenden Verträgen oder Support-Fällen entstehen. Ein Reference-Feld auf Aktivitäts- oder Notiz-Modellen erlaubt es Verkäufern, die ursprüngliche Quelle zu markieren, ohne sich auf ein einzelnes Modell festzulegen — ideal für anpassbare CRM-Prozesse.
3. Einheitliche Notizen über mehrere Module hinweg
Viele Firmen möchten ein zentrales Notizmodell, das sich an Kunden, Projekte, Fertigungsaufträge oder Bestellungen hängen lässt. Ein Reference-Feld macht das möglich, ohne die Notizlogik für jedes Objekt zu duplizieren.
4. Genehmigungsprozesse für unterschiedliche Dokumenttypen
Generische Genehmigungsworkflows greifen oft über verschiedene Dokumente hinweg — Bestellungen, Spesen, Urlaubsanträge oder Verträge. Mit einem Reference-Feld auf dem Genehmigungsmodell lässt sich dieselbe Workflow-Logik für alle Dokumenttypen wiederverwenden.
5. Spesen mit flexibler Zuordnung zu Projekt oder Auftrag
In Beratungs- oder Dienstleistungsfirmen muss eine Ausgabe manchmal einem Projekt, manchmal einer Verkaufsbestellung zugeordnet werden. Ein Reference-Feld mit project.project und sale.order in der Auswahl gibt Buchhaltung und Projektmanagern die nötige Flexibilität.
Anlegen und Anpassen des Reference-Feldes
Zwei Wege, ein Reference-Feld hinzuzufügen: per Odoo Studio ohne Code oder klassisch per Python für maximale Kontrolle.
Mit Odoo Studio
Studio erlaubt das schnelle Hinzufügen eines Reference-Feldes über die UI: Feldtyp wählen, die gewünschten Modelle in der Auswahl festlegen — fertig. Studio-Felder erhalten ein x_-Präfix und sind ideal für schnelle Anpassungen durch Fachanwender oder Business-Analysten.
Diese Methode eignet sich für einfache Erweiterungen; für komplexere Anforderungen wie dynamische Auswahllisten oder berechnete Werte stößt Studio jedoch an Grenzen und Entwickler-Code wird nötig.
Technische Umsetzung in Python
Für vollständige Entwicklungsanforderungen definieren Sie das Reference-Feld im Python-Modell. So lassen sich Auswahllisten per Methode dynamisch erzeugen und konditionieren.
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.',
)Die Übergabe einer Methode als selection gibt Ihnen maximale Flexibilität: Sie können modulabhängig filtern, Geschäftsregeln anwenden oder die Liste aus Konfigurationsdaten zusammenstellen.
Anlegen per XML-RPC API
Auch über die XML-RPC API lassen sich Reference-Felder automatisiert erstellen — praktisch für Remote-Konfigurationen oder Migrationsskripte. Als Feldtyp verwenden Sie reference und übergeben die Auswahl als string-kodierte Liste.
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',
}]
)Wichtig: Die selection wird bei API-Erstellung als auswertbarer Python-String übergeben — so speichert Odoo die Liste in ir.model.fields.
Empfohlene Vorgehensweisen
Richtlinien und Empfehlungen im Umgang mit Reference-Feldern
- Halten Sie die Auswahlliste knapp und relevant. Bieten Sie nur die Modelle an, die wirklich sinnvoll sind — eine überlange Liste verwirrt Anwender und erhöht Fehlbedienungen.
- Verwenden Sie Many2one, wenn die Verknüpfung immer auf dasselbe Modell zeigt. Ist das Ziel statisch, ist Many2one performanter, einfacher zu berichten und leichter zu handhaben.
- Prüfen Sie Nullwerte in berechneten Feldern. Ein leeres Reference-Feld liefert False in Python; prüfen Sie das, bevor Sie auf Attribute zugreifen, um Laufzeitfehler zu vermeiden.
- Bereinigen Sie verwaiste Referenzen per automatisierter Aktion. Da die DB keine Fremdschlüssel erzwingt, empfiehlt sich ein Job oder ein Server-Aktion, die regelmäßig Referenzen auf gelöschte Datensätze erkennt und bereinigt.
- Nutzen Sie klar verständliche Beschriftungen in der Auswahl. Der Text, den Anwender im Dropdown sehen, sollte geschäftsnah formuliert sein — etwa ‚Kundenrechnung‘ statt technischer Modellnamen.
- Dokumentieren Sie die Entscheidung in technischen Spezifikationen. Da Reference-Felder anders funktionieren als Many2one, helfen klare Hinweise späteren Entwicklern beim Verständnis von Architektur und Pflege.
Typische Fehlerquellen
Häufige Fehler, auf die Sie achten sollten
Reference-Feld nicht wie Many2one in Domains behandeln
Ein klassischer Fehler ist die Annahme, Domains auf Reference-Feldern würden nur eine Integer-ID erwarten. Ein Domain wie [('document_ref','=',15)] funktioniert nicht — der gespeicherte Wert ist ein String wie sale.order,15 und muss entsprechend zusammengesetzt werden.
Ignorieren verwaister Werte nach Löschungen
Gelöschte Datensätze hinterlassen ihre String-Referenzen. Beim Zugriff liefert Odoo dann False statt eines Recordsets. Ihre Logik muss damit umgehen, sonst entstehen stille Fehler oder falsche Annahmen über Gültigkeit der Referenz.
Dynamische Auswahl zu breit aufspannen
Die Option, alle installierten Modelle über ir.model sichtbar zu machen, klingt verlockend — ist in der Praxis aber meist kontraproduktiv. Hunderte Einträge im Dropdown sorgen für Verwirrung. Beschränken Sie die Auswahl auf sinnvolle Dokumenttypen.
Berichte nicht automatisch gruppierbar erwarten
Weil das Feld als Text gespeichert wird, funktionieren Standard-Gruppierungen und Pivot-Operationen nicht wie bei Many2one. Benötigen Sie Gruppierungen nach Dokumenttyp, legen Sie ein berechnetes Feld an, das das Modelnamentrennt oder eine Hilfsschlüsselspalte befüllt.
Reference und Many2one in Studio verwechseln
In Studio verwechseln Anwender manchmal Reference mit Many2one, weil beide zum Verlinken dienen. Der Unterschied: Many2one ist auf ein Modell festgelegt; Reference lässt die Wahl beim Ausfüllen. Wenn Sie versehentlich das falsche Feld angelegt haben, ist ein Austausch meist unumgänglich.
Fazit
Das Reference-Feld schließt eine Lücke, die Many2one allein nicht abdeckt: flexible Verknüpfungen zu verschiedenen Dokumenttypen. Es lässt sich schnell per Studio anlegen, lässt sich aber auch sauber in Python-Module integrieren und skaliert gut in durchdachten Datenmodellen.
Behalten Sie die textuelle Speicherung, das fehlende automatische Aufräumen und die spezielle Filterlogik im Blick. Sobald diese Eigenheiten berücksichtigt sind, ist das Feld zuverlässig und gut wartbar in Ihrem Odoo-Ökosystem.
Ob generische Genehmigungen, flexible Verknüpfung von Support-Tickets oder ein zentrales Notizsystem über Module hinweg — das Reference-Feld schafft eine elegante, wartbare Lösung ohne doppelte Logik für jede Modellklasse.
Brauchen Sie Unterstützung bei Ihrer Odoo-Einführung?
Bei Dasolo unterstützen wir Unternehmen dabei, Odoo so zu konfigurieren und zu erweitern, dass die Software echte Geschäftsprozesse optimal abbildet. Ob Datenmodellierung, individuelle Feldlogik oder umfassende Erweiterungen: unser Team bringt das nötige Know-how für saubere Implementierungen mit.
Wenn Sie ein Odoo-Projekt planen und unsicher sind, welche Feldtypen oder Datenarchitektur sich am besten eignen — sprechen Sie uns an. Wir analysieren Ihre Anforderungen und empfehlen die passende Lösung.