Introduzione
I campi binari non sono appariscenti, ma in una vera installazione Odoo sono onnipresenti. Ogni volta che qualcuno carica un contratto firmato, allega la scheda tecnica di un prodotto o salva il logo aziendale su un record, dietro c’è un campo Binary che gestisce il file. Sapere come vengono memorizzati quei dati, dove finiscono fisicamente e quando è meglio usare un altro tipo di campo fa la differenza quando costruisci form personalizzati o estendi i modelli Odoo.
Questa guida spiega cosa contiene un campo Binary, come la modalità di attachment influisce su archiviazione e performance, come aggiungerlo o modificarlo con Odoo Studio o in Python, e presenta esempi pratici nei moduli CRM, HR, Magazzino e oltre.
Cos'è il campo Binary in Odoo
Nel framework ORM di Odoo, il campo Binary (fields.Binary) è pensato per conservare dati binari: file, documenti, immagini o qualsiasi contenuto che l’utente carica su un record. In form e viste appare come un controllo per caricare e scaricare file: un clic per aggiungere il documento, un clic per recuperarlo.
Il dettaglio tecnico più importante riguarda il luogo di conservazione del file. Nelle versioni moderne di Odoo i campi Binary usano per impostazione predefinita la modalità di attachment: il contenuto è memorizzato nella tabella ir.attachment e nel filestore del server, mentre la colonna del modello contiene solo un riferimento all’allegato. Questo mantiene leggere le tabelle principali e permette a Odoo di gestire i file in modo efficiente.
In Odoo Studio questo campo è disponibile come campo File nel pannello dei campi. In una form si presenta come un semplice controllo di upload/download. Per le immagini, Odoo offre inoltre fields.Image, un tipo dedicato che gestisce ridimensionamento automatico e anteprime: ne parleremo nelle sezioni specifiche.
Ecco come si definisce un campo Binary all'interno di un modello Python:
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',
)
Osserva il campo Char di supporto x_signed_contract_filename. Affiancare un campo Binary a un Char per il nome file è una pratica standard: Odoo usa il campo _filename per ricordare e mostrare il nome originale del file nell’interfaccia. Senza questo campo, i download possono arrivare con nomi generici.
Come funziona il campo
Quando definisci un Binary nel modello dati, Odoo crea automaticamente le colonne necessarie durante l’installazione o l’aggiornamento del modulo: non serve scrivere SQL manualmente.
Modalità di archiviazione
Il parametro attachment su un campo Binary determina dove vengono salvati i byte del file:
- attachment=True (consigliato): il contenuto viene salvato in ir.attachment e collegato al record tramite model e record ID. La colonna del modello contiene solo un riferimento. Questo mantiene le tabelle leggere e sfrutta il filestore di Odoo.
- attachment=False: i dati binari codificati in base64 vengono memorizzati direttamente nella colonna del modello. Questo fa crescere rapidamente le tabelle e rallenta le query; evitato per tutto ciò che supera la dimensione di una piccola miniatura.
Formato dei dati
I campi Binary memorizzano e restituiscono i dati come stringhe base64. Se accedi al campo dal ORM Odoo o via API XML-RPC ottieni una stringa base64; quando scrivi devi fornire la stessa codifica.
In pratica significa codificare prima di scrivere e decodificare dopo aver letto:
import base64
# Writing a file to a Binary field
with open('document.pdf', 'rb') as f:
encoded = base64.b64encode(f.read()).decode('utf-8')
record.write({'x_signed_contract': encoded})
# Reading a file from a Binary field
raw_bytes = base64.b64decode(record.x_signed_contract)
Attributi chiave del campo
Questi sono gli attributi più rilevanti che puoi configurare su un campo Binary in Odoo:
- attachment: Booleano. Se salvare i dati in ir.attachment (True) oppure nella colonna (False). Default: True nelle versioni recenti.
- string: Etichetta visualizzata nell’interfaccia.
- required: Rende il campo obbligatorio prima del salvataggio del record.
- compute: Collega un metodo Python per calcolare dinamicamente il valore, ad esempio per generare un PDF al volo.
- store: Insieme a compute, indica se salvare il valore calcolato nel database.
- groups: Restringe l’accesso al campo a determinati gruppi di utenti. Utile per documenti sensibili.
- copy: Controlla se il valore viene duplicato quando si copia un record. Il comportamento dipende dalla modalità attachment e dalla versione di Odoo.
La sottoclasse fields.Image
fields.Image è una specializzazione di fields.Binary introdotta in Odoo 13: gestisce il ridimensionamento automatico fino a una dimensione massima configurabile, produce anteprime/thumbnails e mostra la preview nelle form. Per foto prodotto, immagini dei partner o loghi aziendali è preferibile usare fields.Image, perché limita le dimensioni e migliora l’esperienza utente.
Come si vede nelle viste
In una form, il widget predefinito per Binary è il controllo di upload/download. Per le immagini usa il widget image per ottenere la miniatura. Nelle liste, i campi Binary raramente si mostrano direttamente perché caricare il contenuto per ogni riga causa trasferimenti di dati inutili: meglio un indicatore booleano o un’icona che segnali la presenza dell’allegato.
Casi d'uso aziendali
Il campo Binary è impiegato in moltissimi moduli Odoo: ecco cinque esempi pratici tratti dai flussi aziendali più comuni.
CRM: contratti o NDA firmati su anagrafiche cliente
Molte realtà necessitano di conservare il documento firmato a livello del cliente o del lead. Aggiungere un Binary su res.partner o crm.lead dà al team commerciale accesso immediato al contratto senza uscire da Odoo, evitando strumenti esterni per esigenze di archiviazione di base e tenendo il materiale nel contesto del processo di vendita.
HR: archiviazione documenti del dipendente
L’ufficio HR deve spesso conservare copie di documenti d’identità, permessi di lavoro, contratti firmati o attestati. Un Binary su hr.employee mantiene questi file sotto il controllo degli accessi di Odoo: configurando groups puoi permettere la visibilità solo ai responsabili HR, mentre altri manager vedono i record senza poter aprire i documenti sensibili.
Magazzino: schede tecniche e schede di sicurezza
Prodotti tecnici sono accompagnati da PDF con specifiche, SDS e certificati. Un Binary su product.template consente a chi fa acquisti e al magazzino di consultare la documentazione direttamente sul prodotto. È una personalizzazione frequente per aziende manifatturiere e distributive, e si implementa facilmente sia con Studio che con moduli Python.
Vendite: timbro aziendale o firma autorizzata
Per includere un timbro o una firma su preventivi e conferme d’ordine stampati, puoi usare fields.Image su res.company: l’immagine viene poi richiamata nelle stampe QWeb. Così i documenti sono firmati automaticamente, risparmiando tempo quando si lavorano grandi volumi e riducendo il rischio di inviare preventivi non firmati.
Contabilità: ricevute scansionate sugli expense
La gestione note spese richiede generalmente una ricevuta o fattura scansionata come prova. Il sistema di attachment di Odoo copre il caso standard, ma per modelli expense personalizzati o integrazioni esterne un campo Binary dedicato permette di memorizzare l’immagine o il PDF sul record e includerlo nei flussi di approvazione senza dipendere dal pannello generico degli allegati.
Creare o personalizzare il campo Binary
Ci sono tre modi principali per aggiungere un campo Binary a un modello Odoo, a seconda del contesto tecnico e del livello di controllo richiesto.
Con Odoo Studio (No Code)
Odoo Studio è lo strumento low-code integrato. Per aggiungere un Binary senza scrivere codice:
- Apri Odoo Studio dal menu principale.
- Vai alla form dove vuoi inserire il campo.
- Trascina un campo File dal pannello dei campi sulla form.
- Configura l’etichetta e le condizioni di visibilità nelle proprietà.
- Salva e chiudi Studio.
Studio genera il campo con prefisso x_studio_ e abilita automaticamente la modalità attachment. Non serve alcuna configurazione SQL: è la strada più semplice per utenti business che vogliono abilitare l’upload nei form senza sviluppatori.
Con Python in un modulo personalizzato
Per customizzazioni versionate e distribuibili su più ambienti, la pratica consigliata è definire il campo in Python all’interno di un modulo: è il metodo standard per personalizzazioni serie e riproducibili.
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',
)
Dopo aver aggiunto il campo al modello, inseriscilo nella view XML usando il widget binary e l’attributo filename che punta al Char di supporto. Odoo gestisce la colonna in fase di install/upgrade. Questo metodo funziona su tutte le tipologie di deployment, inclusi Odoo.sh e on‑premise.
Con l’API XML-RPC
Se automatizzi la configurazione di Odoo (script remoti o notebook di deployment), puoi creare campi Binary via 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',
}]
)
Lo stato state: 'manual' indica che il campo è stato creato manualmente e non da un modulo. Anche i campi creati via API usano per default la modalità attachment nelle versioni recenti. Questo approccio è comune negli script di configurazione automatica e nei flussi di deployment remoti.
Buone pratiche
1. Usa sempre attachment=True
Salvo esigenze tecniche molto specifiche, usa la modalità attachment. Mantiene le tabelle leggere, evita query lente e sfrutta il filestore di Odoo. Nelle versioni recenti è il comportamento predefinito, quindi in molti casi puoi semplicemente non specificare attachment e lasciare che Odoo applichi la modalità corretta. Per qualunque file più grande di una miniatura non è opzionale.
2. Affianca un campo Char per il nome file
Aggiungi sempre un campo Char con suffisso _filename assieme al Binary. Senza di esso il widget non conserva il nome originale e gli utenti scaricano file con nomi generici come download. Basta una riga di codice per migliorare sensibilmente l’esperienza.
3. Usa fields.Image per contenuti visivi
Per foto prodotto, ritratti o loghi utilizza fields.Image: limita automaticamente le dimensioni, mostra la miniatura e salva la versione ridimensionata. Scegliere il tipo di campo adeguato evita problemi di performance e migliora l’usabilità.
4. Restringi l’accesso con groups
Documenti sensibili — contratti, file del personale, documenti finanziari — dovrebbero avere restrizioni tramite groups per limitare lettura e scrittura. Questo è fondamentale per la privacy e per requisiti di audit in contesti regolamentati.
5. Gestisci con cura la codifica base64 nel codice
Quando leggi o scrivi un Binary da codice, occupati esplicitamente della codifica base64: usa base64.b64encode(file_bytes).decode('utf-8') prima della scrittura e base64.b64decode(value) per tornare ai byte. Molti bug di integrazione nascono dall’assunzione errata sul formato dei dati.
Errori frequenti
Pericolosità di attachment=False con file grandi
Salvare i contenuti direttamente nella colonna del database può gonfiare le tabelle PostgreSQL in modo notevole. Pochi PDF memorizzati con attachment=False possono aggiungere centinaia di megabyte a una singola tabella e rallentare tutte le query su quel modello. È uno degli errori di configurazione più impattanti: tornare indietro richiede script di migrazione e pianificazione.
Dimenticare il campo filename di supporto
Senza il Char di supporto per il nome file, gli utenti scaricano file con nomi generici: è una piccola fastidiosa imperfezione che trasmette l’idea di implementazione incompleta. Aggiungere il campo richiede un minuto e dovrebbe essere standard per ogni Binary visibile all’utente.
Confondere Binary e Image
Usare un Binary per immagini perde il ridimensionamento e le anteprime fornite da fields.Image, permettendo il caricamento di immagini molto grandi che appesantiscono le form e lo storage. Allo stesso tempo usare fields.Image per PDF genera errori perché Odoo tenterà di trattare il file come immagine. Regola semplice: usa il tipo di campo in base al contenuto atteso.
Inserire Binary direttamente nelle liste
Mostrare un campo Binary in una vista list forza Odoo a caricare il contenuto completo per ogni riga visibile; in una lista di cinquanta record questo può significare trasferire megabyte solo per renderizzare la pagina. Per le liste, preferisci un campo booleano calcolato o un’icona che segnali la presenza dell’allegato.
Non controllare False prima di processare in codice
Un Binary senza valore restituisce False in Python, non una stringa vuota né byte vuoti. Tentare di decodificarlo senza verificare genera TypeError. Proteggi sempre con: if record.x_document: data = base64.b64decode(record.x_document). Questo vale per compute, server actions e qualunque elaborazione condizionale.
Conclusione
Il campo Binary è semplice ma fondamentale nel modello dati di Odoo. Gestisce file e documenti in modo integrato con l’interfaccia, il sistema di attachment e il controllo degli accessi.
Le abitudini principali da adottare: usare sempre la modalità attachment, affiancare il Binary a un campo filename, scegliere fields.Image per contenuti visivi, limitare l’accesso ai documenti sensibili e gestire correttamente la codifica base64 nel codice. Seguendo queste regole si evitano i problemi più comuni prima che diventino critici in produzione.
Che tu aggiunga un upload tramite Odoo Studio, costruisca un modulo Python personalizzato o crei campi via ORM/XML-RPC, curare i Binary fin dall’inizio porta a un’implementazione Odoo più pulita e affidabile.
Da Dasolo supportiamo aziende nell’implementazione, personalizzazione e ottimizzazione di Odoo in tutti i reparti. Se ti serve aiuto per progettare un modello dati con i tipi di campo corretti, costruire flussi di gestione file o sviluppare un modulo completo, il nostro team è a disposizione. Contattaci e parliamo del tuo progetto Odoo.