Champ de référence dans Odoo : Le guide complet

Introduction

La plupart des développeurs Odoo optent pour le champ Many2one lorsqu'ils doivent lier un enregistrement à un autre. Cela fonctionne parfaitement dans la grande majorité des cas. Mais parfois, vous vous retrouvez dans une situation où le document lié pourrait être l'un de plusieurs éléments différents : un bon de commande, un bon de livraison, un ordre de fabrication, ou quelque chose d'autre selon le contexte. C'est exactement ce pour quoi le champ Référence a été conçu.

Le champ Référence est l'un des types de champs les plus flexibles dans l'ORM Odoo. Il vous permet de créer un lien vers un enregistrement de n'importe quel modèle dans une liste prédéfinie, plutôt que de toujours pointer vers le même modèle. L'utilisateur sélectionne d'abord le type de document, puis choisit l'enregistrement spécifique. Le résultat est un lien polymorphe qui peut s'adapter à différents flux de travail.

Ce guide couvre ce que le champ Référence stocke, comment il se comporte dans le modèle de données Odoo, comment le créer et le personnaliser en utilisant Odoo Studio ou Python, et des cas d'utilisation commerciale pratiques où il apporte réellement de la valeur.

Qu'est-ce que le champ Référence dans Odoo

Dans l'ORM Odoo, le champ Référence est un type de champ spécial qui stocke un lien vers un enregistrement de n'importe quel modèle que vous incluez dans sa liste selection. Cela le rend fondamentalement différent d'un champ Many2one, qui pointe toujours vers un modèle fixe.

Dans la base de données, le champ Référence stocke sa valeur sous forme de chaîne de texte simple au format model_name,record_id. Par exemple, une référence à la commande de vente numéro 42 serait stockée sous la forme sale.order,42. Il est important de comprendre cela si vous devez un jour interroger ou filtrer ces enregistrements directement.

Du point de vue de l'interface utilisateur, un champ Référence apparaît comme une saisie en deux étapes. L'utilisateur sélectionne d'abord un type de document dans une liste déroulante (par exemple : Commande de Vente, Facture ou Tâche de Projet), puis choisit l'enregistrement spécifique de ce modèle à l'aide d'un champ de recherche. L'interface est claire et directe une fois que les utilisateurs comprennent la sélection en deux étapes.

Voici à quoi ressemble une définition de champ Référence de base en Python :

from odoo import fields, models

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

    related_document = fields.Reference(
        selection=[
            ('sale.order', 'Commande de Vente'),
            ('purchase.order', 'Commande d'Achat'),
            ('account.move', 'Facture'),
            ('project.task', 'Tâche de Projet'),
        ],
        string='Document Lié',
    )

Le paramètre selection est une liste de tuples. Chaque tuple contient le nom technique du modèle (comme sale.order) et l'étiquette lisible par l'homme que les utilisateurs verront dans la liste déroulante. Vous contrôlez exactement quels modèles sont disponibles dans cette liste.

Il existe également une variante dynamique où la liste de sélection est peuplée à partir de la table ir.model au moment de l'exécution, rendant tous les modèles installés disponibles. Cela est utile pour des outils hautement configurables mais peut devenir écrasant pour les utilisateurs finaux si ce n'est pas filtré correctement.

Dans Odoo Studio, le champ Référence est disponible sous le panneau des types de champs et étiqueté Référence. Lorsque vous l'ajoutez via Studio, vous pouvez configurer la liste des modèles sélectionnables directement depuis l'interface sans écrire de code. Cela en fait l'une des options les plus accessibles parmi les champs avancés d'Odoo Studio.

Comment fonctionne le champ

Comprendre comment le champ Référence stocke et récupère les données est essentiel pour l'utiliser correctement dans vos projets de développement Odoo.

Stockage dans la Base de Données

Contrairement à un champ Many2one, qui ne stocke qu'un entier (la clé étrangère), le champ Référence stocke une valeur chaîne qui inclut à la fois le nom du modèle et l'ID de l'enregistrement. Par exemple : sale.order,15. Cela est stocké dans une colonne VARCHAR dans PostgreSQL. Cela signifie que la base de données n'impose aucune contrainte de clé étrangère sur cette colonne, ce qui est un choix de conception délibéré pour soutenir la nature polymorphe du champ.

Parce qu'il n'y a pas de clé étrangère au niveau de la base de données, Odoo ne nettoie pas automatiquement les valeurs du champ Référence lorsque l'enregistrement lié est supprimé. Si une commande de vente est supprimée, un champ Référence pointant vers elle contiendra toujours l'ancienne valeur chaîne. C'est l'une des différences comportementales les plus importantes à garder à l'esprit lors du développement Odoo.

Accéder à l'enregistrement lié en Python

Lorsque vous lisez une valeur de champ Référence en Python, Odoo renvoie l'objet d'enregistrement réel du modèle référencé. Vous pouvez accéder directement à ses champs, tout comme vous le feriez avec un résultat Many2one. Si le champ est vide, il renvoie False.

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

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

C'est l'un des aspects pratiques de l'abstraction ORM d'Odoo. Même si le stockage sous-jacent est une chaîne de texte simple, le framework le résout en un objet d'enregistrement approprié lorsque vous y accédez dans le code.

Attributs de champ clés

Voici les attributs les plus pertinents que vous pouvez configurer sur un champ Référence dans le framework Odoo :

• selection : Une liste de tuples définissant quels modèles sont sélectionnables. Peut également être un nom de méthode (chaîne) qui renvoie dynamiquement une telle liste.
• string : L'étiquette du champ affichée aux utilisateurs dans l'interface.
• required : Rend le champ obligatoire. L'utilisateur doit sélectionner à la fois un type de modèle et un enregistrement avant de sauvegarder.
• readonly : Empêche les utilisateurs de modifier la valeur du champ depuis l'interface. Utile lorsque la référence est définie par programmation.
• help : Une infobulle affichée lorsque l'utilisateur survole l'étiquette du champ. Utile pour guider les utilisateurs sur ce qu'ils doivent sélectionner.
• compute : Comme tout autre type de champ Odoo, un champ Référence peut être calculé dynamiquement à l'aide d'une méthode Python. Cela est utile pour définir automatiquement une référence en fonction de la logique métier.

Filtrage et Recherche

Parce que la valeur est stockée sous forme de chaîne de caractères simple, le filtrage sur un champ Référence nécessite une syntaxe de domaine spécifique. Pour rechercher des enregistrements liés à un document spécifique, vous devez composer vous-même la valeur de la chaîne :

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

Vous pouvez également filtrer par type de modèle en utilisant un opérateur like :

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

Gardez ce comportement de filtrage basé sur des chaînes à l'esprit lors de la conception de rapports ou de champs calculés qui dépendent des valeurs des champs Référence. Cela se comporte différemment d'un filtre de domaine typique Many2one.

Cas d'utilisation commerciale

Le champ Référence est le plus précieux dans les situations où le même type de lien contextuel peut pointer vers des documents de différents types selon la situation. Voici cinq exemples pratiques issus de flux de travail commerciaux réels.

1. Tickets d'assistance liés à tout document

Une équipe de support gère des tickets qui peuvent concerner des choses très différentes : un litige de facture, un problème de livraison, une question de contrat ou un produit défectueux. Au lieu de créer un champ séparé pour chaque type de document, un seul champ Référence sur le modèle de ticket permet à l'agent de lier le document pertinent. L'agent choisit d'abord le type (Facture, Commande de vente, Livraison, etc.) puis sélectionne l'enregistrement spécifique. Tout le contexte est dans un seul champ.

2. Activités CRM liées à plusieurs documents sources

Dans une équipe de vente, les activités et les tâches de suivi proviennent parfois de différentes sources : un prospect, un devis, un contrat existant ou un cas de support. Un champ Référence sur un modèle d'activité personnalisé ou une note CRM permet aux commerciaux de taguer le document d'origine sans être enfermés dans un seul modèle. C'est un ajustement naturel pour le champ Référence dans une personnalisation CRM Odoo.

3. Notes et annotations à travers les modules

Certaines entreprises construisent un modèle simple de notes internes ou d'annotations pour enregistrer des observations à travers différents objets commerciaux. Un champ de Référence permet d'attacher un seul enregistrement de note à un enregistrement client, une tâche de projet, un ordre de fabrication ou un bon de commande, le tout dans le même champ. Cela évite de dupliquer le modèle de note pour chaque type de document.

4. Workflow d'Approbation de Document

Lors de la mise en œuvre d'un workflow d'approbation générique, la demande d'approbation doit pointer vers le document à approuver. Étant donné que les approbations peuvent s'appliquer aux bons de commande, aux rapports de dépenses, aux demandes de congé ou aux contrats, un champ de Référence sur le modèle d'approbation maintient l'architecture propre. La même logique d'approbation gère tous les types de documents sans avoir besoin de modèles séparés pour chacun.

5. Rapports de Dépenses Liés à des Projets ou des Commandes Clients

Dans certaines configurations comptables, une dépense doit être liée soit à un projet client, soit à un bon de vente en fonction de la nature du coût. Un champ de Référence avec à la fois project.project et sale.order dans sa liste de sélection donne au comptable la flexibilité d'attacher la dépense au document applicable. Cela est particulièrement utile dans les services professionnels et les cabinets de conseil utilisant Odoo.

Créer ou personnaliser le champ Référence

Il existe deux principales façons d'ajouter un champ de Référence à un modèle Odoo : en utilisant Odoo Studio pour une approche sans code, ou en l'écrivant directement en Python pour un contrôle total.

Utilisation d'Odoo Studio

Odoo Studio facilite l'ajout d'un champ de Référence à n'importe quel formulaire sans toucher au code. Ouvrez Studio sur le modèle que vous souhaitez étendre, allez dans le panneau des Champs, et ajoutez un nouveau champ de type Référence. Vous serez invité à sélectionner quels modèles doivent apparaître dans la liste déroulante. Studio stocke le champ comme un champ manuel avec un préfixe x_, tout comme les autres champs Odoo studio créés via l'interface.

Cette approche est idéale pour des personnalisations rapides et pour les analystes commerciaux qui souhaitent étendre des formulaires sans l'intervention d'un développeur. Gardez à l'esprit que les champs de Référence créés par Studio peuvent avoir un support limité pour des configurations avancées telles que des méthodes de sélection dynamiques ou des valeurs calculées.

Mise en œuvre Technique en Python

Pour une approche complète de développement Odoo, définissez le champ de Référence directement dans un modèle Python. Voici un exemple plus complet montrant comment créer un champ de Référence avec une méthode de sélection dynamique :

from odoo import api, fields, models

class ApprovalRequest(models.Model):
    _name = 'approval.request'
    _description = 'Demande d'Approbation'

    name = fields.Char(string='Nom de la Demande', required=True)

    @api.model
    def _get_document_types(self):
        return [
            ('purchase.order', 'Bon de Commande'),
            ('hr.expense.sheet', 'Rapport de Dépenses'),
            ('hr.leave', 'Demande de Congé'),
            ('sale.order', 'Bon de Vente'),
        ]

    document_ref = fields.Reference(
        selection='_get_document_types',
        string='Document',
        help='Sélectionnez le document auquel cette approbation se rapporte.',
    )

Utiliser une méthode pour le paramètre selection (en passant son nom sous forme de chaîne) vous donne plus de flexibilité. Vous pouvez ajouter une logique conditionnelle, filtrer en fonction des modules installés ou construire la liste dynamiquement à partir des enregistrements de configuration.

Création via l'API XML-RPC

Vous pouvez également créer un champ de Référence par programmation en utilisant l'API XML-RPC d'Odoo. Cela est utile lors du déploiement de champs dans le cadre d'un carnet de configuration à distance. Le type de champ à utiliser est reference et la sélection est passée sous forme de représentation chaîne de la liste :

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_related_document',
        'field_description': 'Document Lié',
        'model_id': model_id,
        'ttype': 'reference',
        'selection': "[('sale.order', 'Commande de Vente'), ('purchase.order', 'Commande d'Achat')]",
        'state': 'manual',
    }]
)

Notez que lors de la création d'un champ de Référence via l'API, la valeur selection est passée sous forme de chaîne évaluable en Python plutôt que comme une liste réelle. C'est ainsi qu'Odoo le stocke et le lit à partir de la table ir.model.fields.

Meilleures pratiques

Voici les directives les plus utiles à suivre lors de l'utilisation des champs de Référence dans votre modèle de données Odoo.

• Gardez la liste de sélection courte et significative. N'incluez pas chaque modèle simplement parce que vous le pouvez. Limitez la liste aux types de documents qui ont réellement du sens pour le cas d'utilisation. Une longue liste embrouille les utilisateurs et rend le champ plus difficile à utiliser correctement.
• Utilisez Many2one lorsque vous liez toujours au même modèle. Le champ de Référence est conçu pour des relations polymorphes. Si le modèle lié ne change jamais, un champ Many2one standard est plus simple, plus rapide à interroger et mieux pris en charge par les outils de reporting d'Odoo.
• Vérifiez toujours les valeurs nulles dans les champs calculés. Lorsqu'un champ de Référence est vide, il renvoie False en Python. Tout code qui accède à l'enregistrement lié doit d'abord vérifier cela pour éviter les erreurs.
• Gérez les références orphelines dans les actions automatisées. Étant donné que la base de données n'impose pas l'intégrité référentielle sur les champs de Référence, il est judicieux d'ajouter une action automatisée ou une action planifiée qui vérifie périodiquement et supprime les références obsolètes pointant vers des enregistrements supprimés.
• Utilisez des étiquettes descriptives pour chaque modèle dans la sélection. Le deuxième élément de chaque tuple est ce que les utilisateurs voient dans le menu déroulant. Utilisez des étiquettes claires et conviviales pour les entreprises plutôt que des noms de modèles techniques. Écrivez "Facture Client" plutôt que "account.move".
• Documentez clairement le champ dans vos spécifications techniques. Parce que les champs de Référence se comportent différemment des champs Many2one standard, tout développeur qui hérite de votre code bénéficiera d'une explication claire sur pourquoi une Référence a été choisie et quels modèles elle relie.

Pièges courants

Voici les erreurs que nous voyons le plus souvent lorsque les développeurs ou les analystes commerciaux travaillent avec des champs de référence pour la première fois.

Le traiter comme un Many2one dans les filtres de domaine

Les développeurs écrivent parfois des filtres de domaine pour un champ de référence en utilisant la même syntaxe qu'un Many2one, par exemple [('document_ref', '=', 15)]. Cela ne fonctionnera pas. La valeur stockée est une chaîne comme sale.order,15, et non simplement un entier. Vous devez composer la valeur de chaîne complète lors de la création de filtres de domaine sur un champ de référence.

Oublier que les enregistrements supprimés laissent des valeurs orphelines

Comme il n'y a pas de contrainte de clé étrangère dans la base de données, la suppression d'un enregistrement référencé ne supprime pas la valeur du champ de référence. Si une commande de vente est supprimée et qu'un ticket a toujours sale.order,42 dans son champ de référence, la lecture de ce champ renverra False au lieu de lever une erreur. Le code qui dépend de la validité de la référence doit toujours gérer ce cas.

Utiliser excessivement la sélection dynamique de tous les modèles

Odoo vous permet de passer une méthode pour la selection qui renvoie tous les modèles installés à partir de ir.model. Bien que cela soit puissant, c'est presque toujours trop large pour un champ destiné à l'utilisateur. Présenter des centaines de modèles dans un menu déroulant est déroutant et conduit à une saisie de données incorrecte. Restreignez toujours la sélection à une liste soigneusement choisie de types de documents significatifs.

S'attendre à un groupement natif dans les rapports

Les champs de référence sont stockés sous forme de chaînes de texte simples dans la base de données. Ce ne sont pas des clés étrangères, donc la fonctionnalité standard de groupement et de pivot d'Odoo ne fonctionne pas sur eux comme elle le fait sur les champs Many2one. Si vous devez grouper ou agréger des enregistrements par leur document lié, vous devrez gérer cela par du code personnalisé ou un champ calculé qui extrait le nom du modèle en tant que sélection séparée ou champ de caractère.

Confondre Référence et Many2one dans Odoo Studio

Lors de l'utilisation d'Odoo Studio, certains utilisateurs confondent le champ de référence et le champ Many2one car les deux vous permettent de lier à un autre enregistrement. La différence clé est qu'un Many2one lie toujours à un modèle spécifique (vous le choisissez au moment de la création du champ et il ne change jamais), tandis qu'un champ de référence permet à l'utilisateur de choisir le modèle chaque fois qu'il remplit le champ. Si vous avez créé un Many2one alors que vous aviez besoin d'une Référence, vous devrez reconstruire le champ plutôt que d'essayer d'adapter celui existant.

Conclusion

Le champ de référence comble un vide que le champ Many2one ne peut pas couvrir à lui seul. Lorsqu'un lien doit être suffisamment flexible pour pointer vers différents types de documents en fonction de la situation, le champ de référence est l'outil approprié dans le cadre d'Odoo. Il est simple à définir, fonctionne avec Odoo Studio pour des configurations sans code, et s'intègre naturellement dans les modèles Python pour des implémentations techniques.

Les principales choses à garder à l'esprit sont le format de stockage basé sur des chaînes, l'absence de nettoyage automatique des clés étrangères et la nécessité de filtrer en utilisant des valeurs de chaîne composées plutôt que des ID simples. Une fois que vous comprenez ces différences, le champ se comporte de manière prévisible et fiable dans votre modèle de données Odoo.

Que vous construisiez un flux de travail d'approbation générique, que vous liiez des tickets de support à différents types de documents ou que vous conceviez un système de notes flexible qui s'étend sur plusieurs modules, le champ Référence vous offre une solution propre et maintenable sans avoir besoin de dupliquer votre logique pour chaque type de modèle.

Besoin d'aide avec votre mise en œuvre Odoo ?

Chez Dasolo, nous aidons les entreprises à mettre en œuvre, personnaliser et optimiser Odoo pour s'adapter à leurs flux de travail commerciaux réels. Que vous ayez besoin de construire une logique de champ personnalisée, de concevoir un modèle de données à partir de zéro ou d'étendre une configuration Odoo existante avec de nouvelles fonctionnalités, notre équipe a la profondeur technique nécessaire pour le faire correctement.

Si vous travaillez sur un projet Odoo et avez besoin de conseils sur les types de champs, l'architecture des données ou les meilleures pratiques de développement, n'hésitez pas à nous contacter. Nous sommes heureux de discuter de votre situation et de vous aider à trouver la bonne approche.

Contactez Dasolo