Das Referenzfeld in Odoo: Der Ultimative Leitfaden

Einführung

Die meisten Odoo-Entwickler greifen auf das Many2one-Feld zurück, wenn sie einen Datensatz mit einem anderen verknüpfen müssen. Es funktioniert in der überwiegenden Mehrheit der Fälle perfekt. Aber manchmal stößt man auf eine Situation, in der das verknüpfte Dokument eines von mehreren verschiedenen Dingen sein könnte: ein Verkaufsauftrag, ein Einkaufsauftrag, ein Fertigungsauftrag oder etwas ganz anderes, je nach Kontext. Genau dafür wurde das Referenzfeld entwickelt.

Das Referenzfeld ist einer der flexibleren Feldtypen im Odoo ORM. Es ermöglicht Ihnen, einen Link zu einem Datensatz aus einem vordefinierten Modell zu erstellen, anstatt immer auf dasselbe Modell zu verweisen. Der Benutzer wählt zunächst den Dokumenttyp aus und wählt dann den spezifischen Datensatz aus. Das Ergebnis ist ein polymorpher Link, der sich an verschiedene Arbeitsabläufe anpassen kann.

Dieser Leitfaden behandelt, was das Referenzfeld speichert, wie es sich im Odoo-Datenmodell verhält, wie man es mit Odoo Studio oder Python erstellt und anpasst und praktische Geschäftsanwendungsfälle, in denen es tatsächlich einen Mehrwert bietet.

Was ist das Referenzfeld in Odoo

Im Odoo ORM ist das Referenzfeld ein spezieller Feldtyp, der einen Link zu einem Datensatz aus einem beliebigen Modell speichert, das Sie in seiner selection-Liste aufnehmen. Dies macht es grundlegend anders als ein Many2one-Feld, das immer auf ein festes Modell verweist.

In der Datenbank speichert das Referenzfeld seinen Wert als einfachen Textstring im Format model_name,record_id. Zum Beispiel würde ein Verweis auf die Verkaufsbestellung Nummer 42 als sale.order,42 gespeichert. Dies ist wichtig zu verstehen, wenn Sie diese Datensätze direkt abfragen oder filtern müssen.

Aus der Sicht der Benutzeroberfläche erscheint ein Referenzfeld als eine Eingabe in zwei Schritten. Der Benutzer wählt zunächst einen Dokumenttyp aus einer Dropdown-Liste (zum Beispiel: Verkaufsauftrag, Rechnung oder Projektaufgabe) und wählt dann den spezifischen Datensatz aus diesem Modell über ein Suchfeld aus. Die Benutzeroberfläche ist sauber und unkompliziert, sobald die Benutzer den zweistufigen Auswahlprozess verstanden haben.

So sieht eine grundlegende Definition eines Referenzfeldes in Python aus:

from odoo import fields, models

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

    related_document = fields.Reference(
        selection=[
            ('sale.order', 'Verkaufsauftrag'),
            ('purchase.order', 'Einkaufsauftrag'),
            ('account.move', 'Rechnung'),
            ('project.task', 'Projektaufgabe'),
        ],
        string='Verwandtes Dokument',
    )

Der selection-Parameter ist eine Liste von Tupeln. Jedes Tupel enthält den technischen Modellnamen (wie sale.order) und das für den Benutzer lesbare Label, das in der Dropdown-Liste angezeigt wird. Sie steuern genau, welche Modelle in dieser Liste verfügbar sind.

Es gibt auch eine dynamische Variante, bei der die Auswahlliste zur Laufzeit aus der ir.model-Tabelle befüllt wird, wodurch alle installierten Modelle verfügbar sind. Dies ist nützlich für hochgradig konfigurierbare Werkzeuge, kann jedoch für Endbenutzer überwältigend werden, wenn es nicht richtig gefiltert wird.

Im Odoo Studio ist das Referenzfeld unter dem Feldtyp-Panel verfügbar und als Referenz gekennzeichnet. Wenn Sie es über Studio hinzufügen, können Sie die Liste der auswählbaren Modelle direkt über die Benutzeroberfläche konfigurieren, ohne Code schreiben zu müssen. Dies macht es zu einer der zugänglicheren Optionen unter den fortgeschrittenen Odoo-Studio-Feldern.

Wie das Feld funktioniert

Zu verstehen, wie das Referenzfeld Daten speichert und abruft, ist der Schlüssel zur korrekten Verwendung in Ihren Odoo-Entwicklungsprojekten.

Speicherung in der Datenbank

Im Gegensatz zu einem Many2one-Feld, das nur eine Ganzzahl (den Fremdschlüssel) speichert, speichert das Referenzfeld einen Stringwert, der sowohl den Modellnamen als auch die Datensatz-ID enthält. Zum Beispiel: sale.order,15. Dies wird in einer VARCHAR-Spalte in PostgreSQL gespeichert. Das bedeutet, dass die Datenbank keine Fremdschlüsselbeschränkung auf dieser Spalte durchsetzt, was eine bewusste Designentscheidung ist, um die polymorphe Natur des Feldes zu unterstützen.

Da es keinen Fremdschlüssel auf Datenbankebene gibt, bereinigt Odoo die Werte des Referenzfeldes nicht automatisch, wenn der verlinkte Datensatz gelöscht wird. Wenn eine Verkaufsbestellung gelöscht wird, enthält ein auf sie verweisendes Referenzfeld weiterhin den alten Stringwert. Dies ist einer der wichtigsten Verhaltensunterschiede, die Sie während der Odoo-Entwicklung im Hinterkopf behalten sollten.

Zugriff auf den verknüpften Datensatz in Python

Wenn Sie einen Wert eines Referenzfeldes in Python lesen, gibt Odoo das tatsächliche Datensatzobjekt des referenzierten Modells zurück. Sie können auf seine Felder direkt zugreifen, genau wie bei einem Many2one-Ergebnis. Wenn das Feld leer ist, gibt es False zurück.

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

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

Dies ist einer der praktischen Aspekte der Odoo ORM-Abstraktion. Obwohl der zugrunde liegende Speicher ein einfacher Textstring ist, löst das Framework ihn in ein richtiges Datensatzobjekt auf, wenn Sie darauf im Code zugreifen.

Schlüsselfeldattribute

Dies sind die relevantesten Attribute, die Sie in einem Referenzfeld im Odoo-Framework konfigurieren können:

• selection: Eine Liste von Tupeln, die definiert, welche Modelle auswählbar sind. Kann auch ein Methodenname (String) sein, der eine solche Liste dynamisch zurückgibt.
• string: Das Feldlabel, das den Benutzern in der Benutzeroberfläche angezeigt wird.
• required: Macht das Feld obligatorisch. Der Benutzer muss sowohl einen Modelltyp als auch einen Datensatz auswählen, bevor er speichert.
• readonly: Verhindert, dass Benutzer den Feldwert über die Benutzeroberfläche ändern. Nützlich, wenn die Referenz programmgesteuert festgelegt wird.
• help: Ein Tooltip, der angezeigt wird, wenn der Benutzer über das Feldlabel fährt. Hilfreich, um Benutzer zu leiten, was auszuwählen ist.
• compute: Wie jeder andere Odoo-Feldtyp kann ein Referenzfeld dynamisch mit einer Python-Methode berechnet werden. Dies ist nützlich, um eine Referenz basierend auf Geschäftslogik automatisch festzulegen.

Filtern und Suchen

Da der Wert als einfacher String gespeichert wird, erfordert das Filtern eines Referenzfeldes eine spezifische Domänensyntax. Um nach Datensätzen zu suchen, die mit einem bestimmten Dokument verknüpft sind, müssen Sie den Stringwert selbst erstellen:

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

Sie können auch nach Modelltyp mit einem like-Operator filtern:

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

Behalten Sie dieses stringbasierte Filterverhalten im Hinterkopf, wenn Sie Berichte oder berechnete Felder entwerfen, die von Werten des Referenzfeldes abhängen. Es verhält sich anders als ein typischer Many2one-Domänenfilter.

Geschäftsanwendungsfälle

Das Referenzfeld ist besonders wertvoll in Situationen, in denen derselbe Kontextlink je nach Situation auf Dokumente unterschiedlicher Typen verweisen kann. Hier sind fünf praktische Beispiele aus realen Geschäftsabläufen.

1. Helpdesk-Tickets, die mit beliebigen Dokumenten verknüpft sind

Ein Support-Team bearbeitet Tickets, die sich auf sehr unterschiedliche Dinge beziehen können: eine Rechnungsstreitigkeit, ein Lieferproblem, eine Vertragsfrage oder ein defektes Produkt. Anstatt für jeden Dokumenttyp ein separates Feld zu erstellen, ermöglicht ein einzelnes Referenzfeld im Ticketmodell dem Agenten, das relevante Dokument zu verknüpfen. Der Agent wählt zuerst den Typ (Rechnung, Verkaufsauftrag, Lieferung usw.) und dann den spezifischen Datensatz aus. Alle Kontexte sind in einem Feld.

2. CRM-Aktivitäten, die mit mehreren Quelldokumenten verknüpft sind

In einem Verkaufsteam stammen Aktivitäten und Nachverfolgungsaufgaben manchmal aus unterschiedlichen Quellen: einem Lead, einem Angebot, einem bestehenden Vertrag oder einem Supportfall. Ein Referenzfeld in einem benutzerdefinierten Aktivitätsmodell oder CRM-Notiz ermöglicht es den Verkäufern, das ursprüngliche Dokument zu kennzeichnen, ohne an ein einzelnes Modell gebunden zu sein. Dies passt gut zum Referenzfeld in einer Odoo-CRM-Anpassung.

3. Notizen und Anmerkungen über Module hinweg

Einige Unternehmen erstellen ein einfaches internes Notizen- oder Annotationsmodell, um Beobachtungen über verschiedene Geschäftsobjekte zu protokollieren. Ein Referenzfeld ermöglicht es, einen einzelnen Notizdatensatz an einen Kundenstamm, eine Projektaufgabe, einen Fertigungsauftrag oder einen Einkaufsauftrag anzuhängen, alles innerhalb desselben Feldes. Dies vermeidet die Duplizierung des Notizmodells für jeden Dokumenttyp.

4. Dokumentgenehmigungsworkflow

Bei der Implementierung eines generischen Genehmigungsworkflows muss die Genehmigungsanfrage auf das zu genehmigende Dokument verweisen. Da Genehmigungen für Einkaufsaufträge, Spesenabrechnungen, Urlaubsanträge oder Verträge gelten können, hält ein Referenzfeld im Genehmigungsmodell die Architektur sauber. Die gleiche Genehmigungslogik behandelt alle Dokumenttypen, ohne dass separate Modelle für jedes benötigt werden.

5. Spesenabrechnungen, die mit Projekten oder Kundenaufträgen verknüpft sind

In einigen Buchhaltungsaufstellungen muss eine Ausgabe entweder mit einem Kundenprojekt oder einem Verkaufsauftrag verknüpft werden, abhängig von der Art der Kosten. Ein Referenzfeld mit sowohl project.project als auch sale.order in seiner Auswahl ermöglicht es dem Buchhalter, die Ausgabe an das jeweilige Dokument anzuhängen. Dies ist besonders nützlich in professionellen Dienstleistungs- und Beratungsunternehmen, die Odoo verwenden.

Erstellen oder Anpassen des Referenzfeldes

Es gibt zwei Hauptwege, um ein Referenzfeld zu einem Odoo-Modell hinzuzufügen: die Verwendung von Odoo Studio für einen No-Code-Ansatz oder das direkte Schreiben in Python für volle Kontrolle.

Verwendung von Odoo Studio

Odoo Studio macht es einfach, ein Referenzfeld zu jedem Formular hinzuzufügen, ohne den Code zu berühren. Öffnen Sie Studio für das Modell, das Sie erweitern möchten, gehen Sie zum Feldbereich und fügen Sie ein neues Feld vom Typ Referenz hinzu. Sie werden aufgefordert, auszuwählen, welche Modelle in der Dropdown-Liste erscheinen sollen. Studio speichert das Feld als manuelles Feld mit einem x_-Präfix, genau wie andere Odoo-Studio-Felder, die über die Benutzeroberfläche erstellt wurden.

Dieser Ansatz ist ideal für schnelle Anpassungen und für Geschäftsanalysten, die Formulare ohne Entwicklerbeteiligung erweitern möchten. Beachten Sie, dass von Studio erstellte Referenzfelder möglicherweise nur eingeschränkten Support für erweiterte Konfigurationen wie dynamische Auswahlmethoden oder berechnete Werte bieten.

Technische Implementierung in Python

Für einen vollständigen Odoo-Entwicklungsansatz definieren Sie das Referenzfeld direkt in einem Python-Modell. Hier ist ein vollständigeres Beispiel, das zeigt, wie man ein Referenzfeld mit einer dynamischen Auswahlmethode erstellt:

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 Verwendung einer Methode für den selection-Parameter (indem Sie seinen Namen als Zeichenfolge übergeben) bietet Ihnen mehr Flexibilität. Sie können bedingte Logik hinzufügen, basierend auf installierten Modulen filtern oder die Liste dynamisch aus Konfigurationsdatensätzen erstellen.

Erstellung über die XML-RPC-API

Sie können auch ein Referenzfeld programmgesteuert mit der Odoo XML-RPC-API erstellen. Dies ist nützlich, wenn Sie Felder als Teil eines Remote-Konfigurationsnotebooks bereitstellen. Der zu verwendende Feldtyp ist reference und die Auswahl wird als Zeichenfolgenrepräsentation der Liste übergeben:

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_related_document',
        'field_description': 'Verwandtes Dokument',
        'model_id': model_id,
        'ttype': 'reference',
        'selection': "[('sale.order', 'Verkaufsauftrag'), ('purchase.order', 'Bestellauftrag')]",
        'state': 'manual',
    }]
)

Beachten Sie, dass beim Erstellen eines Referenzfeldes über die API der selection-Wert als Python-evaluierbare Zeichenfolge und nicht als tatsächliche Liste übergeben wird. So speichert und liest Odoo es aus der ir.model.fields-Tabelle.

Best Practices

Hier sind die nützlichsten Richtlinien, die Sie beim Arbeiten mit Referenzfeldern in Ihrem Odoo-Datenmodell befolgen sollten.

• Halten Sie die Auswahlliste kurz und aussagekräftig. Fügen Sie nicht jedes Modell hinzu, nur weil Sie können. Beschränken Sie die Liste auf die Dokumenttypen, die für den Anwendungsfall wirklich sinnvoll sind. Eine lange Liste verwirrt die Benutzer und macht das Feld schwerer korrekt zu verwenden.
• Verwenden Sie Many2one, wenn Sie immer mit demselben Modell verknüpfen. Das Referenzfeld ist für polymorphe Beziehungen konzipiert. Wenn sich das verknüpfte Modell nie ändert, ist ein Standard-Many2one-Feld einfacher, schneller abzufragen und besser von Odoo-Berichterstattungstools unterstützt.
• Überprüfen Sie immer auf Nullwerte in berechneten Feldern. Wenn ein Referenzfeld leer ist, gibt es False in Python zurück. Jeder Code, der auf den verknüpften Datensatz zugreift, muss dies zuerst überprüfen, um Fehler zu vermeiden.
• Behandeln Sie verwaiste Referenzen in automatisierten Aktionen. Da die Datenbank die referentielle Integrität bei Referenzfeldern nicht durchsetzt, ist es eine gute Idee, eine automatisierte Aktion oder eine geplante Aktion hinzuzufügen, die regelmäßig nach veralteten Referenzen sucht und diese löscht, die auf gelöschte Datensätze verweisen.
• Verwenden Sie beschreibende Bezeichnungen für jedes Modell in der Auswahl. Das zweite Element jedes Tupels ist das, was die Benutzer im Dropdown sehen. Verwenden Sie klare, geschäftsfreundliche Bezeichnungen anstelle technischer Modellnamen. Schreiben Sie "Kundenrechnung" anstelle von "account.move".
• Dokumentieren Sie das Feld klar in Ihren technischen Spezifikationen. Da sich Referenzfelder anders verhalten als Standard-Many2one-Felder, wird jeder Entwickler, der Ihren Code erbt, von einer klaren Erklärung profitieren, warum eine Referenz gewählt wurde und mit welchen Modellen sie verknüpft ist.

Häufige Fallstricke

Dies sind die häufigsten Fehler, die wir sehen, wenn Entwickler oder Business-Analysten zum ersten Mal mit Referenzfeldern arbeiten.

Es wie ein Many2one in Domain-Filtern behandeln

Entwickler schreiben manchmal Domain-Filter für ein Referenzfeld mit der gleichen Syntax wie ein Many2one, zum Beispiel [('document_ref', '=', 15)]. Das wird nicht funktionieren. Der gespeicherte Wert ist ein String wie sale.order,15, nicht nur eine Ganzzahl. Sie müssen den vollständigen String-Wert erstellen, wenn Sie Domain-Filter für ein Referenzfeld erstellen.

Vergessen, dass gelöschte Datensätze verwaiste Werte hinterlassen

Da es im Datenbank keine Fremdschlüsselbeschränkung gibt, wird der Wert des Referenzfeldes beim Löschen eines referenzierten Datensatzes nicht gelöscht. Wenn eine Verkaufsbestellung gelöscht wird und ein Ticket immer noch sale.order,42 in seinem Referenzfeld hat, gibt das Lesen dieses Feldes False zurück, anstatt einen Fehler auszulösen. Code, der darauf angewiesen ist, dass die Referenz gültig ist, muss immer diesen Fall berücksichtigen.

Übermäßige Nutzung der dynamischen Auswahl aller Modelle

Odoo ermöglicht es Ihnen, eine Methode für die selection zu übergeben, die alle installierten Modelle aus ir.model zurückgibt. Während dies mächtig ist, ist es fast immer zu breit für ein benutzerorientiertes Feld. Hunderte von Modellen in einem Dropdown-Menü zu präsentieren, ist verwirrend und führt zu falschen Dateneingaben. Beschränken Sie die Auswahl immer auf eine kuratierte Liste von bedeutungsvollen Dokumenttypen.

Erwartung von nativen Gruppierungen in Berichten

Referenzfelder werden als einfache Textstrings in der Datenbank gespeichert. Sie sind keine Fremdschlüssel, daher funktioniert die Standard-Odoo-Gruppierungs- und Pivot-Funktionalität nicht wie bei Many2one-Feldern. Wenn Sie Datensätze nach ihrem verknüpften Dokument gruppieren oder aggregieren müssen, müssen Sie dies durch benutzerdefinierten Code oder ein berechnetes Feld, das den Modellnamen als separate Auswahl oder Zeichenfeld extrahiert, handhaben.

Verwirrung zwischen Referenz und Many2one in Odoo Studio

Bei der Verwendung von Odoo Studio verwechseln einige Benutzer das Referenzfeld und das Many2one-Feld, da beide es ermöglichen, mit einem anderen Datensatz zu verknüpfen. Der entscheidende Unterschied besteht darin, dass ein Many2one immer mit einem bestimmten Modell verknüpft ist (das Sie bei der Erstellung des Feldes auswählen und das sich nie ändert), während ein Referenzfeld es dem Benutzer ermöglicht, das Modell jedes Mal auszuwählen, wenn er das Feld ausfüllt. Wenn Sie ein Many2one erstellt haben, als Sie ein Referenzfeld benötigten, müssen Sie das Feld neu erstellen, anstatt zu versuchen, das vorhandene anzupassen.

Fazit

Das Referenzfeld schließt eine Lücke, die das Many2one-Feld nicht allein abdecken kann. Wenn eine Verknüpfung flexibel genug sein muss, um je nach Situation auf verschiedene Dokumenttypen zu verweisen, ist das Referenzfeld das richtige Werkzeug im Odoo-Framework. Es ist einfach zu definieren, funktioniert mit Odoo Studio für No-Code-Setups und integriert sich natürlich in Python-Modelle für technische Implementierungen.

Die wichtigsten Punkte, die zu beachten sind, sind das stringbasierte Speicherformat, das Fehlen einer automatischen Bereinigung von Fremdschlüsseln und die Notwendigkeit, mit zusammengesetzten Zeichenfolgenwerten anstelle von einfachen IDs zu filtern. Sobald Sie diese Unterschiede verstehen, verhält sich das Feld vorhersehbar und zuverlässig in Ihrem Odoo-Datenmodell.

Egal, ob Sie einen generischen Genehmigungsworkflow erstellen, Support-Tickets mit verschiedenen Dokumenttypen verknüpfen oder ein flexibles Notizsystem entwerfen, das mehrere Module umfasst, das Referenzfeld bietet Ihnen eine saubere und wartbare Lösung, ohne dass Sie Ihre Logik für jeden Modelltyp duplizieren müssen.

Brauchen Sie Hilfe bei Ihrer Odoo-Implementierung?

Bei Dasolo helfen wir Unternehmen, Odoo zu implementieren, anzupassen und zu optimieren, um ihren tatsächlichen Geschäftsabläufen gerecht zu werden. Egal, ob Sie benutzerdefinierte Feldlogik erstellen, ein Datenmodell von Grund auf neu entwerfen oder eine bestehende Odoo-Installation mit neuen Funktionen erweitern müssen, unser Team hat die technische Tiefe, um es richtig zu machen.

Wenn Sie an einem Odoo-Projekt arbeiten und Anleitung zu Feldtypen, Datenarchitektur oder bewährten Entwicklungspraktiken benötigen, zögern Sie nicht, uns zu kontaktieren. Wir freuen uns, Ihre Situation zu besprechen und Ihnen zu helfen, den richtigen Ansatz zu finden.

Kontaktieren Sie Dasolo