Jeśli konfigurowałeś kiedyś Odoo, zapewne widziałeś wyrażenia domain — to te nawiasowe warunki filtrujące pojawiające się w przyciskach akcji, regułach automatyzacji, zasadach dostępu i szablonach maili. Mniej oczywiste jest jednak to, że w ORM Odoo istnieje specjalny typ pola Domain, stworzony właśnie po to, żeby przechowywać te wyrażenia jako uporządkowane dane i umożliwiać ich edycję z poziomu interfejsu.
Rozumienie, czym są pola domain, przydaje się zarówno deweloperom tworzącym moduły, jak i użytkownikom biznesowym konfigurującym automatyzacje. Ten przewodnik wyjaśnia, co pole Domain przechowuje, jak działa w praktyce, pokazuje przykłady użycia i ostrzega przed najczęstszymi błędami.
Czym jest pole Domain w Odoo
W Odoo „domain” to lista warunków filtrujących służąca do wyszukiwania rekordów. Ma konkretną składnię z krotkami i operatorami logicznymi i przy końcowym zapytaniu ORM przekłada się na fragment WHERE w SQL.
Przykładowe wyrażenie domain może wyglądać następująco:
[('customer_rank', '>', 0), ('active', '=', True)]Oznacza to: zwróć wszystkie rekordy, gdzie customer_rank jest większe od 0 ORAZ pole active ma wartość True.
Pole Domain (fields.Domain) to typ pola w ORM Odoo, który przechowuje takie wyrażenia jako strukturalne dane. W odróżnieniu od zwykłego pola tekstowego, zapewnia walidację i dedykowany widget w UI, dzięki któremu użytkownicy mogą budować warunki wizualnie, bez ręcznego pisania składni.
Jak wygląda w interfejsie
W UI Odoo pole Domain domyślnie wyświetla się przy użyciu edytora domain — wizualnego kreatora reguł. Użytkownik wybiera pole, operator (równe, zawiera, większe niż itp.) i wpisuje wartość. To ten sam edytor, który widzisz przy konfiguracji reguł dostępu czy kryteriów w automatyzacjach.
W bazie danych wartości domain są trzymane jako tekst — dokładniej jako stringowa reprezentacja listy w Pythonie. Typ pola zajmuje się serializacją i walidacją, więc programista pracuje z poprawnymi wartościami w Pythonie, a warstwa przechowywania robi resztę.
To element szerszego projektu modelu danych w Odoo: pola to nie tylko pojemniki na dane — niosą też semantykę, zachowanie w UI i reguły walidacji w jednym miejscu.
Jak pole działa
Pole Domain ściśle współpracuje z ORM i mechanizmem filtrowania rekordów. Poniżej wyjaśnienie, co się dzieje „pod maską” przy zapisie i ewaluacji domain.
Przechowywanie i reprezentacja
Kiedy domain jest zapisany w bazie, Odoo trzyma go jako zserializowany tekst. Wyrażenia mogą zawierać zmienne specjalne jak uid, które przy wykonywaniu zapytania zostają rozwinięte do ID aktualnego użytkownika — co pozwala tworzyć dynamiczne filtry bez twardego kodowania wartości.
ORM bierze ten tekst, bezpiecznie go ewaluując, i przekształca w fragment WHERE w SQL. Proces ten odbywa się przez safe_eval, który obsługuje kontrolowany podzbiór wyrażeń Pythona wraz ze zmiennymi kontekstowymi Odoo.
Widget domain
W interfejsie pola typu fields.Domain używają domyślnie widgetu domain — właśnie tego wizualnego kreatora warunków. Użytkownicy mogą dodawać reguły, łączyć je operacjami AND/OR i podglądać wyniki bez znajomości składni.
To widget sprawia, że domainy są przystępne dla użytkowników biznesowych — nie trzeba znać składni, bo kreator robi tłumaczenie za ciebie.
Kontekst modelu
Pole Domain może być powiązane z konkretnym modelem — wtedy widget wie, jakie pola powinien proponować podczas budowy reguł. Robi się to przez atrybut model_field w definicji pola. Bez powiązania z modelem edytor cofa się do zwykłego pola tekstowego, co znacząco obniża użyteczność.
To powiązanie pokazuje, jak framework Odoo łączy definicję pola z zachowaniem UI — pole „wie”, które model ma filtrować, a interfejs dostosowuje się do tego kontekstu.
Interakcja z innymi rekordami
Pola Domain często występują obok pól relacyjnych, by ograniczać listę dostępnych opcji w Many2one, określać cel automatycznych akcji lub ramy raportów. Wyrażenie domain działa jak filtr na poziomie ORM, więc respektuje zasady bezpieczeństwa i uprawnienia do pól.
Zastosowania biznesowe
Pola Domain pojawiają się praktycznie we wszystkich modułach Odoo. Poniżej pięć rzeczywistych przykładów pokazujących ich zastosowanie w codziennych procesach.
1. Automatyczne akcje i wyzwalacze maili
Przy konfiguracji automatycznej akcji (Ustawienia > Techniczne > Automatyzacja) definujesz domain, który określa, które rekordy uruchomią akcję. Na przykład automatyczny mail dla zaległych faktur może być skierowany tylko do zatwierdzonych (posted), niezapłaconych faktur po terminie. Ten domain zapisuje się w modelu base.automation w polu filter_domain i akcja odpala się tylko dla pasujących rekordów.
2. Zasady dostępu i record rules
Reguły dostępu wykorzystują domainy, aby ograniczyć widoczność rekordów dla określonych grup użytkowników. Na przykład reguła zespołu sprzedaży może pokazywać tylko rekordy przypisane do danego zespołu, oceniane przy każdym zapytaniu. Dzięki temu uzyskujesz kontrolę wierszową bez pisania dodatkowego kodu — każdy filtr w record rule to właśnie domain przechowywany w polu Domain.
3. Filtrowanie w magazynie i operacjach
W logistyce i magazynie domainy kierują planowanymi akcjami oraz regułami uzupełniania, zawężając działania do konkretnych kategorii produktów, lokalizacji czy poziomów zapasów. Przykładowo automatyczne uzupełnianie może być ograniczone do produktów stowalowalnych, których ilość spadła poniżej punktu zamówienia, co zapobiega przetwarzaniu niepotrzebnych rekordów.
4. Pipeline CRM i kwalifikacja leadów
W CRM etapy pipeline, reguły aktywności i przypisywanie leadów opierają się na domainach, aby kategoryzować i kwalifikować potencjalne okazje. Reguły przypisywania potrafią kierować leady do właściwego sprzedawcy na podstawie kraju, branży czy wielkości transakcji — wszystko konfigurowalne z poziomu interfejsu przez pole Domain, bez konieczności zmian w kodzie.
5. Dynamiczne listy w Many2one
Na formularzach domain przypisany do pola Many2one kontroluje, które rekordy pojawią się w liście wyboru. Ograniczenie dostawców do aktywnych i mających niezerowy ranking zmniejsza liczbę błędów wprowadzania i poprawia ergonomię. Domain może też odnosić się do innych pól formularza, dzięki czemu opcje zmieniają się dynamicznie w zależności od wyboru użytkownika.
Tworzenie i modyfikacja pola
Dwie główne ścieżki pracy z polami Domain w Odoo to: użycie Odoo Studio bez kodu albo tworzenie pola w module — Python + XML.
Korzystanie z Odoo Studio
W Odoo Studio nie ma osobnej opcji dodania typu pola Domain w kreatorze pól. W większości przypadków nie jest to potrzebne, bo wizualne edytory domain dostępne są tam, gdzie ich potrzeba — w automatyzacjach, regułach czy akcjach serwerowych.
Jeśli chcesz nałożyć domain na pole Many2one w Studio, możesz edytować właściwości pola i wpisać wyrażenie domain bezpośrednio — Studio sprawdzi składnię i zapisze je w definicji widoku.
Modyfikacje techniczne w Pythonie
W custom module dodanie pola Domain to prosta czynność opisana w dokumentacji deweloperskiej Odoo. Poniżej schematyczny przykład pokazujący istotne elementy definicji pola w ORM:
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'
)Atrybut model_field wskazuje pole, które przechowuje nazwę modelu (tu model_name), dzięki czemu widget wie, które pola proponować w kreatorze. Trzymanie nazwy modelu w oddzielnym polu umożliwia też dynamiczny wybór modelu, jeśli scenariusz tego wymaga.
Dodanie widgetu do widoku formularza
Aby wyświetlić kreator domain w formularzu, w XML widoku odwołaj się zarówno do pola modelu, jak i pola domain:
<field name="model_name" invisible="1"/>
<field name="filter_domain" widget="domain"
options="{'model': 'model_name'}"/>Bez deklaracji widget="domain" i opcji model widget wyświetli pole jako zwykły tekst. Zawsze dodawaj oba elementy, gdy chcesz udostępnić konfigurację domain użytkownikom.
Zapisywanie wartości domain przez XML-RPC API
Jeżeli ustawiasz pole Domain programowo przez API, zawsze przekazuj wartość jako string:
models.execute_kw(db, uid, api_key, 'my.model', 'write',
[[record_id], {
'filter_domain': "[('active', '=', True)]"
}]
)Przekazywanie surowej listy Pythona zamiast stringa to częsty błąd, który wywołuje błędy typów lub ciche niepowodzenia zależnie od wersji Odoo. Zawsze serializuj domain do tekstu przed zapisem przez API.
Dobre praktyki
Te praktyczne nawyki oszczędzą czas i zapobiegną problemom przy pracy z polami Domain w Odoo.
Waliduj składnię przed wdrożeniem
Nieprawidłowy domain powoduje błędy w momencie ewaluacji. Testuj domainy w pasku wyszukiwania Odoo lub w trybie deweloperskim zanim zapiszesz je w automatyzacjach czy regułach dostępu. Szybkie wywołanie search_count przez API to prosty sposób, by sprawdzić, czy domain zwraca oczekiwaną liczbę rekordów.
Używaj zmiennych dynamicznych
Unikaj twardego kodowania ID użytkowników, firm czy dat w domainach. Stosuj zmienne takie jak uid, context_today() czy current_company_id. Dzięki temu domainy pozostaną przenośne i nie popsują się przy przenoszeniu konfiguracji między środowiskami.
Zawsze łącz kontekst modelu
Gdy dodajesz pole Domain do własnego modelu, pamiętaj o ustawieniu model_field i umieszczeniu go w widoku. Bez tego użytkownicy zobaczą zwykły input tekstowy zamiast wizualnego kreatora, co obniża ergonomię i zwiększa ryzyko zapisania niepoprawnych wartości.
Utrzymuj domainy czytelne
Zbyt złożone, zagnieżdżone domainy z operatorami | (OR) i & (AND) szybko stają się trudne w utrzymaniu. Komentuj intencję w kodzie lub rozważ przeniesienie logiki do akcji serwerowej albo pola obliczanego — będą łatwiejsze do testowania i zrozumienia.
Używaj safe_eval do ewaluacji
Przy programatycznej ewaluacji domainów w Pythonie (np. w akcjach serwerowych) korzystaj z wbudowanego safe_eval, a nie z natywnego eval. Jest bezpieczniejszy, obsługuje kontekst Odoo i działa spójnie z tym, jak Odoo samo interpretuje domainy.
Testuj na realistycznych danych
Zawsze sprawdź, czy domain rzeczywiście dopasowuje oczekiwane rekordy przed uruchomieniem w produkcji. To szczególnie istotne przy automatyzacjach i regułach dostępu — błędny filtr może przetwarzać nieodpowiednie rekordy lub blokować dostęp użytkownikom.
Typowe pułapki
Poniżej najczęściej spotykane błędy przy pracy z polami Domain i wskazówki, jak ich unikać.
Mylenie typu pola z samą składnią domain
Słowo „domain” w Odoo ma dwa znaczenia: to składnia filtru (lista krotek) oraz nazwa typu pola fields.Domain, który przechowuje to wyrażenie. Nowicjusze często mylą te pojęcia. Pole Domain to kontener danych; domain to logika filtra wewnątrz niego.
Przekazywanie listy zamiast stringa przez API
Przy zapisie do pola Domain przez XML-RPC trzeba wysłać string, nie obiekt listy Python. Wysłanie surowej listy powoduje błąd lub ciche niepowodzenie w zależności od wersji Odoo. Zawsze serializuj domain do tekstu.
Brak kontekstu modelu w widgetcie
Gdy dodasz pole Domain do formularza, ale nie podasz w opcjach widgetu kontekstu model, użytkownicy zobaczą zwykłe pole tekstowe zamiast kreatora. Widget działa poprawnie tylko wtedy, gdy wie, do którego modelu się odnosi — pamiętaj, by dodać powiązanie model_field w widoku.
Twarde wpisywanie ID rekordów w domainach
Domainy odwołujące się do konkretnych ID rekordów łamią się, gdy rekordy zostaną usunięte lub konfiguracja zostanie skopiowana do innej bazy. Korzystaj z odniesień dynamicznych, takich jak uid lub przez pola relacyjne, by domainy były bardziej odporne.
Zbyt szerokie lub zbyt restrykcyjne reguły record rule
Reguła zbyt łagodna może ujawnić dane użytkownikom, którzy nie powinni ich widzieć; zbyt restrykcyjna może ukryć rekordy bez komunikatu. Testuj reguły z perspektywy grupy docelowej, a nie konta administratora, które omija ograniczenia.
Zapominanie o archiwalnych rekordach
Domyślnie Odoo wyklucza rekordy zarchiwizowane (gdzie active = False) z wyników wyszukiwania. Jeśli tego nie uwzględnisz, możesz mieć nieoczekiwane braki danych. Dodaj ('active', 'in', [True, False]), gdy potrzebujesz uwzględnić archiwalia.
Podsumowanie
Pola Domain to podstawowy element, który stoi za wieloma mechanizmami Odoo — od kontroli dostępu i automatyzacji, po dynamiczne listy i filtry pulpitów. Wyrażenia domain są kręgosłupem filtrowania rekordów, a typ fields.Domain daje deweloperom klarowny, zwalidowany sposób przechowywania i prezentacji tej logiki w modelu danych.
Dla użytkowników biznesowych widget domain udostępnia konfigurację filtrów bez konieczności kodowania. Dla deweloperów pole Domain jest lepszym rozwiązaniem niż trzymanie wyrażeń w zwykłych polach Char z nadpisanym widgetem. Niezależnie czy pracujesz w Odoo Studio, tworzysz moduł w Pythonie czy konfigurujesz przepływy z poziomu UI — zrozumienie pól Domain otwiera dużo możliwości.
Zasady opisane w tym przewodniku są uniwersalne dla różnych wersji i modułów Odoo. Inwestycja czasu w opanowanie pól Domain szybko się zwróci, bo są one faktycznie wszędzie w systemie.
Potrzebujesz wsparcia przy wdrożeniu Odoo?
Dasolo pomaga firmom wdrażać, dostosowywać i optymalizować Odoo pod konkretne procesy biznesowe. Niezależnie czy ustawiasz automatyzacje, tworzysz moduły czy chcesz lepiej wykorzystać istniejący system, nasz zespół ma kompetencje, by poprowadzić projekt pewnie do przodu.
Masz pytania dotyczące pól Domain lub innych elementów Twojego wdrożenia Odoo? skontaktuj się z nami. Chętnie przejrzymy Twoją konfigurację i wskażemy najlepszy kierunek działania.