Si vous avez déjà configuré Odoo, vous avez forcément croisé ces expressions remplies de crochets qui servent de filtres. On les trouve dans les boutons d’action, les règles automatisées, les règles d’accès et les modèles d’e-mails. Mais Odoo propose aussi un type de champ spécifique — le champ Domain — pensé pour stocker ces filtres comme des données structurées et pour offrir une interface dédiée à leur édition.
Que vous développiez des modules personnalisés ou que vous paramétriez des workflows en tant qu’administrateur métier, comprendre le champ Domain est utile : il ne s’agit pas seulement d’une chaîne de texte, mais d’un objet validé, éditable visuellement et exploitable par l’ORM pour filtrer des enregistrements. Ce guide explique ce que contient exactement ce champ, comment il s’utilise en pratique et les erreurs à éviter.
Qu’est-ce que le champ Domain dans Odoo
Dans Odoo, un « domain » est une liste de conditions qui sert à filtrer des enregistrements. Il suit une syntaxe particulière (tuples, opérateurs logiques) et, au moment de la requête, se traduit en clause WHERE SQL pour récupérer les enregistrements correspondants.
À quoi ressemble une expression de domain
[('customer_rank', '>', 0), ('active', '=', True)]Autrement dit : retourner tous les enregistrements dont customer_rank est supérieur à 0 ET dont active est vrai.
Le champ Domain (fields.Domain) est un type de champ dans l’ORM Odoo destiné à contenir ces expressions. Contrairement à un champ texte classique, il comporte une validation intégrée et s’accompagne d’un widget qui permet à l’utilisateur de construire visuellement des filtres sans écrire de code.
Affichage dans l’interface
Dans l’interface, le champ Domain s’affiche via le widget d’édition de domain : un constructeur visuel qui propose la liste des champs du modèle, les opérateurs (égal, contient, supérieur, etc.) et un champ de valeur. C’est le même outil que vous utilisez pour créer des règles d’accès ou des critères d’action automatique.
Au niveau stockage, la valeur est persistée comme texte — la représentation en chaîne de la liste Python. Le champ se charge de la sérialisation et de la validation, ce qui laisse le développeur travailler avec des domains correctement formés côté Python pendant que la couche de stockage s’occupe du reste.
C’est un bon exemple de la philosophie du modèle de données Odoo : un champ n’est pas juste un contenant, il encapsule aussi du comportement, des contraintes et des indications pour l’interface.
Comment fonctionne ce champ
Intégration avec l’ORM et le filtrage
Que se passe-t-il concrètement quand on sauvegarde ou qu’on évalue un domain ?
Stockage et représentation
À l’enregistrement, Odoo conserve le domain sous forme de chaîne sérialisée. Des variables spéciales comme uid sont résolues au moment de l’exécution, ce qui permet des filtres dynamiques selon l’utilisateur courant. L’ORM évalue ensuite cette chaîne via un mécanisme sécurisé pour en tirer la clause SQL correspondante.
Le moteur d’évaluation d’Odoo utilise safe_eval : il interprète une portion contrôlée de Python et connaît des variables contextuelles propres à Odoo afin de convertir l’expression en condition SQL exploitable par la base de données.
Le widget domain
Le widget est ce qui rend le champ Domain accessible aux utilisateurs métiers : il traduit visuellement la logique des filtres, permet d’ajouter ou de combiner des conditions avec AND/OR, et offre un aperçu sans jamais nécessiter d’écriture manuelle de la syntaxe.
Contexte du modèle
Un champ Domain peut être rattaché à un modèle précis via l’attribut model_field. Cela indique à Odoo quels champs proposer dans le builder. Sans ce contexte, le widget retombe sur un simple champ texte, bien moins ergonomique pour l’utilisateur final.
Ce lien entre définition du champ et comportement UI illustre comment Odoo relie métadonnées et expériences utilisateur : le champ sait quel modèle il filtre, et l’interface s’adapte en conséquence.
Interaction avec d’autres enregistrements
On utilise fréquemment les Domain fields avec des champs relationnels pour restreindre les options d’un Many2one, définir la cible d’une action automatique ou limiter la portée d’un rapport. Le filtrage se fait au niveau de l’ORM, donc il respecte les règles de sécurité et les droits d’accès d’Odoo.
Cas d’usage en entreprise
Exemples concrets en entreprise
Voici cinq usages concrets montrant l’apport des Domain fields dans des processus métiers.
1. Actions automatisées et envois d’e-mails
Lors de la configuration d’une action automatisée, on définit un domain qui précise quels enregistrements déclenchent l’action. Par exemple, un envoi automatique pour factures en retard ciblera uniquement les factures publiées, impayées et échues. Ce filtre est stocké sur le modèle base.automation dans un champ Domain nommé filter_domain et l’action ne s’exécutera que pour les enregistrements correspondants.
2. Règles d’accès et sécurité par enregistrement
Les règles d’accès utilises des domains pour limiter la visibilité ou l’édition à certains enregistrements. Une règle pour une équipe commerciale peut restreindre l’accès aux enregistrements assignés à l’équipe de l’utilisateur courant, évaluée à l’exécution. C’est ainsi qu’Odoo réalise une sécurité au niveau des lignes sans coder de logique personnalisée.
3. Filtrage en gestion des stocks
Pour la replanification et les opérations d’entrepôt, les domains ciblent catégories de produits, emplacements ou niveaux de stock. Une règle de réapprovisionnement automatique peut être limitée aux produits stockables dont la quantité disponible est inférieure au point de commande, évitant des traitements inutiles sur des milliers de références.
4. Pipeline CRM et qualification des leads
Dans le CRM, l’automatisation des étapes, les règles d’activité et l’affectation des leads s’appuient sur des domains pour catégoriser et qualifier les opportunités. On peut, par exemple, affecter un lead au commercial adéquat selon le pays, le secteur ou la taille du projet, sans toucher au code — tout se configure via des expressions stockées dans des champs Domain.
5. Dropdowns Many2one dynamiques
Créer ou personnaliser le champ
Sur un formulaire personnalisé, appliquer un domain à un Many2one restreint les options affichées : limiter un fournisseur aux seuls fournisseurs actifs avec un certain score réduit les erreurs de saisie. Le domain peut être dynamique et référencer d’autres champs du formulaire pour adapter les choix selon la sélection de l’utilisateur.
Approches pour ajouter ou modifier un Domain field
Deux voies principales : privilégier Odoo Studio pour du no-code quand c’est possible, ou créer un champ dans un module Python/XML pour des besoins plus avancés.
Avec Odoo Studio
Studio n’expose pas explicitement un type « Domain » dans son créateur de champs visuel. La plupart du temps, ce n’est pas nécessaire : l’éditeur de domain présent dans les actions automatisées, règles et actions serveur suffit pour construire vos filtres sans développement.
Pour ajouter un filtre à un Many2one depuis Studio, éditez les propriétés du champ et saisissez l’expression de domain ; Studio vérifie la syntaxe et conserve le filtre au niveau de la vue.
Personnalisation technique en Python
Dans un module personnalisé, définir un champ Domain se fait simplement via l’ORM. Exemple minimal :
from odoo import models, fields
class MyModel(models.Model):
_name = 'my.model'
model_name = fields.Char(default='res.partner')
filter_domain = fields.Domain(
string='Filter Domain',
model_field='model_name',
help='Domain expression to filter partner records'
)
L’attribut model_field relie le champ de domain au nom du modèle stocké dans model_name, indiquant ainsi au widget quels champs proposer. Séparer le nom du modèle dans un champ distinct permet aussi de rendre le modèle filtré dynamique si nécessaire.
Ajouter le widget dans une vue formulaire
Pour afficher l’éditeur de domain dans une vue, référencez le model_field et le champ Domain dans le XML de la vue :
<field name="model_name" invisible="1"/>
<field name="filter_domain" widget="domain"
options="{'model': 'model_name'}"/>
Sans la déclaration widget="domain" et l’option modèle, le champ s’affiche comme un simple texte. Pensez donc toujours à inclure ces deux éléments quand vous exposez une configuration de domain aux utilisateurs.
Écrire des valeurs via XML-RPC
Si vous mettez à jour un champ Domain par API, envoyez toujours la valeur sous forme de chaîne :
Bonnes pratiques
models.execute_kw(db, uid, api_key, 'my.model', 'write',
[[record_id], {
'filter_domain': "[('active', '=', True)]"
}]
)
Envoyer une liste Python brute au lieu d’une chaîne est une erreur fréquente qui provoque des exceptions ou des échecs silencieux selon la version d’Odoo. Sérialisez toujours le domain en string avant l’écrire via l’API.
Bonnes habitudes
Ces pratiques simples évitent la plupart des problèmes liés aux Domain fields.
Valider la syntaxe avant déploiement
Une expression invalide provoque des erreurs lors de l’évaluation. Testez vos domains dans la barre de recherche d’Odoo ou en mode développeur avant de les enregistrer dans des actions ou des règles. Un appel search_count par API permet aussi de vérifier que le filtre retourne le nombre d’enregistrements attendu.
Privilégier les variables dynamiques
Évitez de coder en dur des identifiants d’utilisateur, d’entreprise ou des dates. Utilisez uid, context_today() ou current_company_id : cela rend vos filters portables entre bases et prévient les cassures silencieuses lors des migrations ou copies d’environnement.
Lier systématiquement le contexte modèle
Quand vous ajoutez un champ Domain, paramétrez toujours l’attribut model_field et intégrez-le dans la vue. Sans cela, l’utilisateur se retrouve face à un champ texte et augmente le risque d’enregistrer des valeurs incorrectes.
Garder les domains lisibles
Les domaines très imbriqués (avec | et &) deviennent vite illisibles. Commentez vos intentions dans le code Python et, si le filtre devient trop complexe, envisagez une action serveur ou un champ calculé qui rendra la logique plus testable et maintenable.
Utiliser safe_eval pour l’évaluation programmée
Pièges fréquents
Lorsque vous évaluez des domains côté Python (par ex. dans une action serveur), utilisez safe_eval d’Odoo et non eval natif. C’est plus sûr, compatible avec les variables Odoo et cohérent avec le comportement interne de la plateforme.
Tester sur jeux de données réalistes
Avant mise en production, vérifiez que le domain renvoie les enregistrements attendus — particulièrement pour des actions automatisées ou des règles d’accès, où un filtre erroné peut déclencher des traitements inappropriés ou bloquer l’accès des utilisateurs.
Pièges récurrents et comment les éviter
Voici les erreurs que l’on rencontre le plus souvent avec les Domain fields, et les remèdes simples.
Confondre le type de champ et la syntaxe du domain
Dans Odoo, « domain » désigne à la fois la syntaxe de filtrage et le type de champ fields.Domain. Beaucoup confondent ces concepts : le champ Domain est juste le contenant, l’expression qu’il stocke est la logique de filtrage.
Passer une liste au lieu d’une chaîne via l’API
À nouveau : écrire un objet liste Python au lieu d’une chaîne provoque des erreurs. Sérialisez systématiquement le domain avant l’appel XML-RPC/JSON-RPC.
Oublier le contexte modèle dans le widget
Si le widget ne connaît pas le modèle à référencer, il affichera un champ texte. Assurez-vous d’inclure l’option modèle ou le model_field pour préserver l’expérience utilisateur et la validation.
Hardcoder des identifiants d’enregistrement
Référencer des IDs fixes rend les domains fragiles : si l’enregistrement disparaît ou si vous migrez la configuration vers une autre base, le domain casse. Préférez des variables dynamiques ou des critères relationnels.
Conclusion
Règles trop larges ou trop restrictives
Une règle de type record rule trop permissive expose des données sensibles ; une règle trop restrictive peut masquer des enregistrements sans avertissement. Testez toujours du point de vue d’un utilisateur cible, pas depuis un compte admin qui contourne les règles.
Oublier les enregistrements archivés
Par défaut, Odoo exclut les enregistrements archivés (active = False). Si votre domain doit inclure ces enregistrements, intégrez explicitement ('active','in',[True,False]) dans le filtre.
Le rôle des Domain fields dans Odoo
Les Domain fields sont des éléments essentiels qui pilotent une grande partie du comportement d’Odoo : contrôle d’accès, actions automatisées, listes dynamiques et filtres de tableaux de bord. Le type fields.Domain offre aux développeurs une façon propre et validée de stocker cette logique dans le modèle de données. Pour les utilisateurs métiers, le widget rend la configuration des filtres accessible sans écrire de code. Pour les développeurs, le type Domain remplace avantageusement des Char génériques sur lesquels on appliquait un widget, apportant clarté et validation au niveau du modèle.Les principes exposés ici restent valables à travers les versions et les modules d’Odoo. Comprendre les Domain fields représente un investissement rentable : ils sont omniprésents et structurent le filtrage des données dans la plateforme.