Pole Binary Field w Odoo — Kompletny Przewodnik

Wprowadzenie

Pola binarne rzadko robią wrażenie, ale w praktycznym wdrożeniu Odoo spotkasz je na każdym kroku. Gdy użytkownik dołącza podpisaną umowę, załącza kartę techniczną produktu czy wgrywa logo firmy do rekordu, to właśnie pole Binary stoi za obsługą tych plików. Znajomość sposobu przechowywania danych, lokalizacji plików i momentów, kiedy warto wybrać inny typ pola, uprości tworzenie formularzy i rozbudowę modeli Odoo.

W tym przewodniku wyjaśnię, co dokładnie przechowuje pole Binary, jak tryb załączników wpływa na przechowywanie i wydajność, jak dodać lub zmodyfikować pole za pomocą Odoo Studio i Pythona oraz pokażę praktyczne zastosowania w CRM, HR, magazynie i innych obszarach.

Czym jest pole Binary w Odoo

W modelu ORM Odoo pole Binary (fields.Binary) służy do zapisu surowych danych binarnych: plików, dokumentów i obrazów, które użytkownik dołącza do rekordu. W widoku formularza wygląda jak kontrolka do uploadu pliku i po załączeniu umożliwia jego pobranie jednym kliknięciem.

Kluczowa techniczna sprawa to miejsce przechowywania pliku. W nowszych wersjach Odoo pola Binary domyślnie pracują w trybie załączników. Zawartość pliku jest zapisywana w tabeli ir.attachment oraz w filestore na serwerze, a kolumna w modelu przechowuje jedynie odwołanie do rekordu załącznika. Dzięki temu główne tabele bazy danych nie rosną niepotrzebnie, a obsługa plików jest wydajniejsza.

W Odoo Studio pole Binary znajdziesz pod nazwą File w wyborze pól. W formularzach renderuje prosty kontroler upload/pobierz. Dla obrazów Odoo oferuje także dedykowany typ fields.Image, który dodaje skalowanie i podgląd miniatur — o tym więcej dalej.

Przykład definicji pola Binary w module Python pokazuje podstawowy sposób deklaracji.

from odoo import fields, models

class ResPartner(models.Model):
    _inherit = 'res.partner'

    x_signed_contract = fields.Binary(
        string='Signed Contract',
        attachment=True,
    )
    x_signed_contract_filename = fields.Char(
        string='Signed Contract Filename',
    )

Zwróć uwagę na towarzyszące pole tekstowe x_signed_contract_filename. W Odoo powszechną praktyką jest dodanie pola _filename obok Binary — przechowuje ono oryginalną nazwę pliku, dzięki czemu pobierany plik zachowuje sensowną nazwę zamiast domyślnego "download".

Jak działa to pole

Definiując pole Binary w modelu, Odoo automatycznie zajmie się utworzeniem kolumny w bazie podczas instalacji lub aktualizacji modułu — nie wymaga to ręcznej pracy SQL.

Tryby przechowywania

Parametr attachment na polu Binary określa, gdzie faktycznie lądują bajty pliku:

• attachment=True (zalecane): Treść pliku jest zapisywana jako rekord w ir.attachment i powiązana z modelem oraz ID rekordu. Kolumna w tabeli modelu przechowuje jedynie referencję. Dzięki temu tabele modeli pozostają lekkie, a Odoo korzysta z własnego filestore do zarządzania plikami.
• attachment=False: Surowe, zakodowane base64 dane są przechowywane bezpośrednio w kolumnie modelu. To bardzo szybko zapełnia tabele i spowalnia zapytania — unikaj takiego rozwiązania dla czegokolwiek większego niż minimalna miniatura obrazu.

Format danych

Pola Binary przyjmują i zwracają dane jako ciągi zakodowane base64. Gdy pobierasz wartość przez ORM lub XML-RPC, dostaniesz base64-string; zapis wymaga przesłania danych też w postaci base64.

W praktyce oznacza to kodowanie przed zapisem i dekodowanie po odczycie:

import base64

# Zapis pliku do pola Binary
with open('document.pdf', 'rb') as f:
    encoded = base64.b64encode(f.read()).decode('utf-8')
record.write({'x_signed_contract': encoded})

# Odczyt pliku z pola Binary
raw_bytes = base64.b64decode(record.x_signed_contract)

Najważniejsze atrybuty pola

Oto atrybuty pola Binary, które warto znać i konfigurować w Odoo:

• attachment: Boolean. Czy trzymać plik w ir.attachment (True) czy w kolumnie modelu (False). W nowych wersjach domyślnie True.
• string: Etykieta pola widoczna w interfejsie.
• required: Wymusza wypełnienie pola przed zapisem rekordu.
• compute: Pozwala powiązać pole z metodą Pythona, np. generując PDF na żywo jako pole obliczane.
• store: W połączeniu z compute decyduje o zapisie wyniku do bazy.
• groups: Ogranicza dostęp do pola dla konkretnych grup użytkowników — istotne przy dokumentach wrażliwych.
• copy: Kontroluje, czy wartość jest duplikowana przy kopiowaniu rekordu; zachowanie zależy od trybu attachment i wersji Odoo.

Podklasa fields.Image

fields.Image to specjalizacja fields.Binary (wprowadzona w Odoo 13), która automatycznie skaluje obrazy do zadanych maksymalnych wymiarów, dostarcza rozmiary miniatur i generuje podgląd w formularzu. Dla zdjęć produktów, portretów kontrahentów czy logotypów używaj fields.Image — zmniejsza to rozmiar uploadów i poprawia doświadczenie użytkownika.

Jak pole wyświetla się w widokach

W formularzach Binary domyślnie pokazuje kontrolkę upload/pobierz. Dla obrazów użyj widgetu image, aby uzyskać miniaturę. W widokach listy nie pokazuje się zwykle zawartości pliku (bo ładowanie pliku dla każdego wiersza to duże obciążenie). Zamiast tego lepiej wykorzystać ikonę lub pole logiczne sygnalizujące obecność załącznika.

Przykłady zastosowań biznesowych

Pola Binary pojawiają się praktycznie we wszystkich modułach Odoo — poniżej pięć typowych scenariuszy biznesowych.

CRM: przechowywanie podpisanych NDA i umów przy kontrahentach

W sprzedaży warto mieć podpisaną umowę dostępną bezpośrednio na karcie klienta lub leada. Pole Binary na res.partner lub crm.lead daje handlowcom szybki dostęp do dokumentów bez potrzeby korzystania z zewnętrznego systemu DMS, co upraszcza proces ofertowania i negocjacji.

HR: archiwum dokumentów pracowniczych

Działy HR często muszą przechowywać skany dowodów, zezwoleń na pracę, podpisanych umów czy certyfikatów. Pole Binary na hr.employee pozwala trzymać te pliki w Odoo z wykorzystaniem uprawnień dostępu — przez ustawienie groups tylko HR zobaczy szczegóły, inni zobaczą informacje bez możliwości pobrania pliku. To częsta potrzeba w organizacjach dbających o prywatność danych.

Magazyn: karty techniczne i karty bezpieczeństwa

Produkty techniczne zwykle mają PDF-y z danymi technicznymi, karty bezpieczeństwa lub certyfikaty. Pole Binary na product.template umożliwia zespołom zakupowym i magazynowym szybki dostęp do właściwej dokumentacji bez opuszczania rekordu produktu — często pożądana funkcjonalność w firmach produkcyjnych i dystrybucyjnych.

Sprzedaż: pieczęć firmy lub podpis do wydruków

W niektórych procesach wymagane jest automatyczne umieszczenie pieczęci czy podpisu na wydrukowanych ofertach. Pole fields.Image na res.company przechowuje taką grafikę, którą można osadzić w szablonach QWeb — dzięki temu generowane PDF-y mają podpis lub pieczęć bez ręcznej ingerencji.

Księgowość: skany paragonów przy rozliczeniach

W procesie rozliczania wydatków każdy wydatek często wymaga dowodu w postaci skanu paragonu lub faktury. Standardowo system załączników Odoo to obsługuje, ale w niestandardowych modelach pole Binary to porządne rozwiązanie, które pozwala trzymać obraz/paragon bezpośrednio przy rekordzie i uwzględnić go w ścieżce zatwierdzania.

Tworzenie i dostosowywanie pola Binary

Są trzy główne sposoby dodania pola Binary do modelu, zależnie od potrzeb i środowiska.

Przez Odoo Studio (bez kodu)

Odoo Studio to narzędzie low-code dostępne w interfejsie; aby dodać pole Binary bez programowania:

1. Otwórz Odoo Studio z menu głównego.
2. Przejdź do formularza, do którego chcesz dodać pole.
3. Przeciągnij pole File z selektora pól na formularz.
4. W panelu właściwości ustaw etykietę i warunki widoczności.
5. Zapisz i zamknij Studio.

Studio utworzy pole z prefiksem x_studio_ i domyślnie włączy tryb attachment. To najszybszy sposób, by biznesowo dodać upload plików bez udziału developera.

Przez moduł Python (dla programistów)

Jeżeli potrzebujesz kontroli wersjonowania i wdrożeń w środowiskach produkcyjnych, definiuj pola w Pythonie — to rekomendowany sposób dla poważnych rozszerzeń Odoo:

from odoo import fields, models

class HrEmployee(models.Model):
    _inherit = 'hr.employee'

    x_id_document = fields.Binary(
        string='ID Document',
        attachment=True,
        groups='hr.group_hr_user',
    )
    x_id_document_filename = fields.Char(
        string='ID Document Filename',
    )

Po dodaniu pola w module trzeba wstawić je do widoku formularza (widget binary i atrybut filename wskazujący na pole _filename). Odoo samo tworzy kolumnę w bazie podczas instalacji/aktualizacji modułu — metoda ta działa w Odoo.sh i na instalacjach on‑premise.

Przez API XML-RPC

Jeśli konfigurujesz pola zdalnie, np. w skrypcie wdrożeniowym, możesz utworzyć pole Binary przez XML-RPC:

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_custom_document',
        'field_description': 'Custom Document',
        'model_id': model_id,
        'ttype': 'binary',
        'state': 'manual',
    }]
)

Ustawienie state: 'manual' oznacza, że pole powstało ręcznie, a nie przez moduł. W aktualnych wersjach pola stworzone przez API domyślnie używają trybu attachment — ta metoda jest przydatna w automatycznych konfiguracjach i zdalnych skryptach wdrożeniowych.

Dobre praktyki

1. Zawsze używaj attachment=True

Chyba że masz bardzo konkretny powód techniczny, stosuj attachment=True. Pozwala to zachować tabele modeli małymi, uniknąć wolnych zapytań i skorzystać z filestora Odoo. Dla każdego pliku większego niż drobna miniatura tryb attachment to wręcz warunek prawidłowej pracy.

2. Dodaj pole tekstowe z nazwą pliku

Zawsze dołącz pole _filename typu Char obok Binary. Bez niego widget nie pokaże oryginalnej nazwy pliku i użytkownik pobierając plik otrzyma bezsensowną nazwę. To drobna zmiana, która znacząco poprawia wygodę pracy.

3. Dla obrazów używaj fields.Image

Jeżeli przechowujesz zdjęcia produktów, portrety czy logotypy — wybierz fields.Image. Automatycznie ogranicza wymiary, generuje miniatury i lepiej radzi sobie z treścią wizualną niż zwykłe Binary. Dobór właściwego typu pola to podstawa schludnego modelu danych.

4. Kontroluj dostęp przez groups

Pola z wrażliwymi dokumentami powinny mieć ustawione groups, by ograniczyć dostęp tylko do uprawnionych osób. To ważne z punktu widzenia prywatności i audytu w środowiskach regulowanych.

5. Obsługuj base64 poprawnie w kodzie

Przy odczycie i zapisie z poziomu kodu zawsze jawnie obsługuj base64: użyj base64.b64encode(file_bytes).decode('utf-8') przed zapisem i base64.b64decode(field_value) po odczycie. Brak takiego zabezpieczenia to częsta przyczyna błędów integracji.

Najczęstsze pułapki

Konsekwencje ustawienia attachment=False dla większych plików

Trzymanie treści pliku bezpośrednio w kolumnie bazy powoduje szybkie rozrosty tabel PostgreSQL. Kilkadziesiąt PDF-ów z attachment=False może dodać setki megabajtów do jednej tabeli, co spowalnia wszystkie zapytania. To jedna z poważniejszych pomyłek konfiguracyjnych — migracja takich danych do trybu attachment wymaga skryptu i ostrożnego planowania.

Brak pola z nazwą pliku

Bez towarzyszącego pola z nazwą użytkownicy pobierają pliki z ogólną nazwą, co wygląda nieprofesjonalnie. Dodanie pola _filename to kwestia chwili i powinno być standardem dla każdego Binary widocznego w formularzu.

Mylące użycie Binary zamiast Image

Użycie zwykłego Binary dla obrazów pozbawia aplikację automatycznego skalowania i miniatur — użytkownicy mogą uploadować bardzo duże zdjęcia, które obciążą widoki i pamięć. Natomiast fields.Image dla plików PDF spowoduje błędy, bo Odoo będzie próbowało traktować treść jak obraz. Reguła jest prosta: dobieraj typ pola do oczekiwanego rodzaju treści.

Wstawianie Binary do widoku listy

Umieszczenie pola Binary w liście powoduje ładowanie zawartości pliku dla każdej widocznej pozycji — na liście 50 rekordów to może być megabajty transferu. Zamiast tego użyj pola boolean lub ikony wskazującej obecność pliku.

Nie sprawdzanie False przed przetwarzaniem

Puste pole Binary w Pythonie zwraca False, a nie pusty string ani pusty ciąg bajtów. Próba bezpośredniego dekodowania False skończy się TypeError. Zawsze używaj warunku: if record.x_document: data = base64.b64decode(record.x_document). To zabezpieczenie jest konieczne w metodach compute, akcjach serwera i wszędzie tam, gdzie pliki są przetwarzane warunkowo.

Podsumowanie

Pole Binary to prosty, lecz kluczowy element modelu danych Odoo. Umożliwia przechowywanie plików i dokumentów zintegrowanych z interfejsem, systemem załączników i mechanizmami kontroli dostępu.

Główne nawyki, które warto wyrobić: zawsze korzystaj z trybu attachment, dołączaj pole z nazwą pliku, wybieraj fields.Image dla treści wizualnych, ograniczaj dostęp przez groups i zawsze poprawnie obsługuj base64 w kodzie. Dzięki temu unikniesz najczęstszych problemów zanim pojawią się w produkcji.

Niezależnie od tego, czy dodajesz pole przez Odoo Studio, tworzysz moduł w Pythonie czy zarządzasz polami przez ORM lub XML-RPC, poprawne wdrożenie pól Binary od początku przekłada się na czystsze i bardziej stabilne środowisko Odoo.

W Dasolo wspieramy firmy we wdrożeniach i optymalizacji Odoo w całej organizacji. Pomagamy w projektowaniu modeli danych, budowie workflowów zarządzania plikami oraz tworzeniu kompletnych modułów dopasowanych do procesów klienta. Skontaktuj się z nami Porozmawiajmy o Twoim projekcie Odoo.