Introduzione
Di solito, quando si vuole collegare un record a un altro in Odoo, la scelta istintiva è Many2one: semplice e affidabile. Ma capita spesso che il documento collegato non sia sempre dello stesso tipo: a volte è un ordine di vendita, altre un ordine d’acquisto, una scheda di produzione o altro ancora. Per questi scenari serve uno strumento più flessibile: il campo Reference.
Il campo Reference è un tipo di campo del framework Odoo pensato per collegare in modo polimorfico a record di modelli diversi. In pratica l’utente sceglie prima il tipo di documento e poi l’elemento specifico: il risultato è un collegamento adattabile a flussi di lavoro variabili, senza dover creare un campo distinto per ogni modello possibile.
Questa guida spiega cosa memorizza il campo Reference, come si comporta nel modello dati di Odoo, come aggiungerlo o personalizzarlo tramite Studio o codice Python e in quali contesti aziendali porta reale valore aggiunto.
Cos’è il campo Reference in Odoo
Nel cuore dell’ORM di Odoo il campo Reference è speciale perché non punta a un singolo modello fisso: la sua lista selection definisce quali modelli possono essere scelti, consentendo così di riferirsi a record appartenenti a modelli diversi senza vincoli fissi come avviene con Many2one.
A livello di database il valore è memorizzato come stringa testuale nel formato model_name,record_id. Ad esempio: sale.order,42 per un ordine di vendita. Questa forma è importante da conoscere quando si eseguono query dirette o filtraggi sui dati.
Dal punto di vista dell’interfaccia utente, il campo Reference è un selettore in due passi: prima si sceglie il tipo di documento (es. Ordine di Vendita, Fattura, Task di Progetto), poi si seleziona il record desiderato tramite ricerca. È una UX semplice ma che richiede l’abitudine al doppio passaggio.
Ecco come si presenta, concettualmente, la definizione di un Reference in Python:
from odoo import fields, models
class HelpDeskTicket(models.Model):
_inherit = 'helpdesk.ticket'
related_document = fields.Reference(
selection=[
('sale.order', 'Sale Order'),
('purchase.order', 'Purchase Order'),
('account.move', 'Invoice'),
('project.task', 'Project Task'),
],
string='Related Document',
)Il parametro selection è una lista di coppie: il nome tecnico del modello e l’etichetta leggibile per l’utente. Da qui si decide quali modelli saranno disponibili nel menu a tendina.
Esiste anche un approccio dinamico: la lista di selezione può essere generata al volo leggendo ir.model, rendendo disponibili tutti i modelli installati. Utile per strumenti altamente configurabili, ma rischia di confondere gli utenti se non filtrata con criterio.
In Odoo Studio il campo Reference è incluso tra i tipi disponibili ed è etichettato come Reference. Aggiungendolo via Studio si definisce la lista dei modelli direttamente dall’interfaccia senza scrivere codice, il che lo rende accessibile anche ai consulenti funzionali e agli analisti di business.
Come funziona il campo
Comprendere come il Reference memorizza e recupera i dati è fondamentale per usarlo correttamente in sviluppo e nelle personalizzazioni Odoo.
Memorizzazione nel database
A differenza di Many2one, che salva solo un intero (la chiave esterna), il Reference salva una stringa contenente sia il nome del modello sia l’ID del record, ad esempio sale.order,15. In PostgreSQL questo viene memorizzato in una colonna VARCHAR, quindi non esiste un vincolo di foreign key che garantisca l’integrità referenziale a livello di DB.
Proprio perché non c’è una foreign key sul DB, Odoo non pulisce automaticamente i valori Reference quando il record referenziato viene eliminato. Se un ordine di vendita viene cancellato, il campo Reference rimarrà con la stringa obsoleta: è un dettaglio da tenere presente nella progettazione delle integrazioni e delle routine di manutenzione.
Accesso al record collegato in Python
Quando leggi un Reference da Python, Odoo risolve la stringa e restituisce il record object del modello referenziato: puoi accedere ai suoi campi come fai con un Many2one. Se il campo è vuoto, il valore restituito è False. Questo comportamento semplifica molto il codice applicativo.
ticket = self.env['helpdesk.ticket'].browse(1)
doc = ticket.related_document
if doc:
print(doc._name) # e.g. 'sale.order'
print(doc.name) # e.g. 'S00042'
print(doc.id) # e.g. 15Il framework si occupa di risolvere la stringa testuale in un vero record object quando lo si accede in runtime, rendendo trasparente l’astrazione nonostante la conservazione come testo nel DB.
Attributi principali del campo
Di seguito gli attributi più rilevanti che puoi impostare su un campo Reference in Odoo:
- selection: la lista di coppie che definisce i modelli selezionabili; può essere anche il nome di un metodo che la costruisce dinamicamente.
- string: l’etichetta visualizzata nell’interfaccia.
- required: rende il campo obbligatorio: l’utente deve scegliere modello e record prima di salvare.
- readonly: impedisce modifiche da UI, utile quando il riferimento viene impostato da logica applicativa.
- help: tooltip per guidare l’utente su cosa selezionare.
- compute: anche un Reference può essere computed tramite metodo Python, per settare il riferimento automaticamente in base a regole di business.
Filtri e ricerche
Poiché il valore è una stringa, i filtri su Reference richiedono di lavorare con la sintassi testuale. Per cercare i record collegati a un documento specifico bisogna costruire la stringa completa:
tickets = self.env['helpdesk.ticket'].search([
('related_document', '=', 'sale.order,15')
])Puoi anche filtrare per tipo di modello usando operatori like o simili:
tickets = self.env['helpdesk.ticket'].search([
('related_document', 'like', 'sale.order,')
])Tieni presente questo comportamento quando progetti report, campi calcolati o automazioni che dipendono dai valori di Reference: non si filtra come un Many2one convenzionale.
Casi d’uso aziendali
Quando conviene usare il campo Reference? È ideale ogni volta che un collegamento contestuale può puntare a tipi di documento diversi. Ecco cinque scenari pratici dove si rivela particolarmente utile.
1. Ticket di assistenza collegabili a qualsiasi documento
Un team di supporto può gestire segnalazioni che riguardano fatture, consegne, contratti o prodotti difettosi. Invece di creare tanti campi separati, un singolo Reference sul ticket permette all’operatore di selezionare il tipo di documento e il record pertinente, mantenendo tutto il contesto in un unico posto.
2. Attività CRM collegate a diversi documenti sorgente
Nelle vendite, un'attività può nascere da una lead, da un preventivo, da un contratto o da un ticket di assistenza. Un Reference su un modello di attività permette ai venditori di associare facilmente l’elemento di origine senza essere vincolati a un solo modello fisso.
3. Note e annotazioni trasversali ai moduli
Alcune aziende preferiscono avere un unico modello di note interne che può essere agganciato a clienti, task di progetto, ordini di produzione o ordini d’acquisto. Un Reference consente di riutilizzare la stessa struttura di nota su più oggetti senza duplicare il modello.
4. Flussi di approvazione generici
Un processo di approvazione spesso deve riferirsi a documenti diversi: ordini d’acquisto, richieste di rimborso, permessi o contratti. Un Reference sull’entità di approvazione mantiene il design pulito: la stessa logica di approvazione può gestire più tipi di documento.
5. Note spese legate a progetto o ordine cliente
In contesti di consulenza o servizi professionali, una spesa può essere imputata a un progetto o a un ordine cliente. Un campo Reference che include project.project e sale.order lascia all’utente la flessibilità di scegliere il collegamento più appropriato per il costo.
Creare o personalizzare il campo Reference
Ci sono due strade principali per aggiungere un campo Reference a un modello: la via no-code con Odoo Studio o l’implementazione programmata in Python per chi desidera pieno controllo.
Usare Odoo Studio
Con Studio è immediato aggiungere un Reference su una maschera senza scrivere codice: apri Studio sul modello, vai nella sezione campi e inserisci un nuovo campo di tipo Reference. Ti verrà chiesto quali modelli includere nella selezione. Lo spazio dei campi creati da Studio sarà prefissato con x_, come per gli altri campi manuali creati dall’interfaccia.
Questo metodo è perfetto per personalizzazioni rapide e per analisti funzionali. Tuttavia i campi creati via Studio possono risultare limitati per configurazioni avanzate, come selection dinamiche o logiche compute complesse.
Implementazione tecnica in Python
Per un approccio di sviluppo completo conviene definire il campo Reference direttamente nel modulo Python. Ecco un esempio che mostra l’uso di un metodo dinamico per popolare la selection:
from odoo import api, fields, models
class ApprovalRequest(models.Model):
_name = 'approval.request'
_description = 'Approval Request'
name = fields.Char(string='Request Name', required=True)
@api.model
def _get_document_types(self):
return [
('purchase.order', 'Purchase Order'),
('hr.expense.sheet', 'Expense Report'),
('hr.leave', 'Time Off Request'),
('sale.order', 'Sale Order'),
]
document_ref = fields.Reference(
selection='_get_document_types',
string='Document',
help='Select the document this approval relates to.',
)Passare il nome di un metodo come valore di selection permette di aggiungere logica condizionale: filtrare in base ai moduli installati, alle impostazioni aziendali o a specifiche regole di business.
Creazione tramite API XML-RPC
È possibile creare un campo Reference anche via API XML-RPC, utile quando si distribuiscono configurazioni da remoto. Il ttype da usare è reference e la selection viene passata come stringa rappresentabile in Python:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_related_document',
'field_description': 'Related Document',
'model_id': model_id,
'ttype': 'reference',
'selection': "[('sale.order', 'Sale Order'), ('purchase.order', 'Purchase Order')]",
'state': 'manual',
}]
)Ricorda che via API la selection viene fornita come stringa valutabile in Python: così Odoo la registra nella tabella ir.model.fields e la ricostruisce al caricamento.
Buone pratiche
Linee guida pratiche quando lavori con i Reference in Odoo
- Mantieni la lista di selezione corta e rilevante. Evita di inserire tutti i modelli solo perché è tecnicamente possibile: una lista troppo lunga confonde gli utenti e aumenta il rischio di errori di compilazione.
- Usa Many2one quando il collegamento è sempre verso lo stesso modello. Se il riferimento non cambia mai, Many2one è più semplice, più efficiente nelle query e più compatibile con gli strumenti di reporting di Odoo.
- Controlla sempre i valori nulli nei campi computati. Un Reference vuoto restituisce
Falsein Python: ogni logica che legge il record collegato deve gestire questa condizione per evitare eccezioni. - Gestisci i riferimenti orfani con azioni automatizzate. Poiché non esiste integrità referenziale a livello DB, è utile avere azioni pianificate o regole automatiche che verificano e puliscono eventuali Reference che puntano a record cancellati.
- Usa etichette descrittive per le voci di selezione. La seconda parte della coppia nella
selectionè ciò che vedono gli utenti: preferisci termini aziendali chiari (es. “Fattura Cliente”) anziché nomi tecnici di modello. - Documenta il campo nelle specifiche tecniche. I Reference si comportano diversamente rispetto ai Many2one: lasciare una spiegazione chiara del perché della scelta e dei modelli collegati aiuta i futuri sviluppatori a comprendere l’architettura.
Errori comuni
Errori e fraintendimenti che osserviamo frequentemente con i Reference
Confondere i domain filter con quelli di Many2one
Uno degli errori più comuni è costruire un dominio come se si stesse filtrando un Many2one, ad esempio [('document_ref', '=', 15)]. Questo non funziona: il valore memorizzato è una stringa completa come sale.order,15, quindi devi comporre la stringa intera nel filtro.
Dimenticare che la cancellazione lascia valori orfani
Quando un record referenziato viene eliminato, il Reference non viene aggiornato automaticamente. Di conseguenza il campo può contenere sale.order,42 anche se l’ordine non esiste più; leggere il campo restituirà False senza eccezioni. Il codice che assume la validità della referenza deve sempre prevedere questo caso.
Abuso della selezione dinamica con tutti i modelli
Attivare una selection che legge tutti i modelli da ir.model può risultare potente ma quasi sempre eccessivo per l’utente finale: centinaia di modelli in un dropdown generano confusione e dati incoerenti. Meglio limitare la lista a tipologie realmente rilevanti.
Aspettarsi raggruppamenti nativi nei report
Poiché i Reference sono stringhe nel DB e non chiavi esterne, funzioni come group-by o pivot di Odoo non funzionano su di essi come su Many2one. Se hai bisogno di aggregare per tipo di documento, crea un campo calcolato che estragga il nome del modello o una scelta separata per il raggruppamento.
Confondere Reference e Many2one in Odoo Studio
In Studio alcuni utenti scambiano i due tipi perché entrambi consentono di collegare record. La differenza cruciale è che Many2one è vincolato a un singolo modello scelto in fase di creazione, mentre Reference lascia l’utente scegliere il modello ad ogni compilazione. Se serve un Reference ma è stato creato un Many2one, non è possibile “convertirlo” facilmente: bisogna ricreare il campo corretto.
Conclusione
Il campo Reference colma una lacuna che Many2one non può coprire: quando il collegamento deve poter puntare a tipi di documento diversi a seconda del contesto, il Reference è lo strumento adeguato in Odoo. È semplice da definire, compatibile con Studio per soluzioni no-code e integrabile nei modelli Python per sviluppi avanzati.
I punti chiave da ricordare sono il formato a stringa per la memorizzazione, l’assenza della pulizia automatica da parte del DB e la necessità di filtrare usando stringhe composte piuttosto che soli ID. Con queste premesse il campo si comporta in modo prevedibile e affidabile nel modello dati.
Sia che tu debba realizzare un workflow di approvazione generico, collegare ticket di supporto a documenti eterogenei o progettare un sistema di note multi-modulo, il campo Reference offre una soluzione ordinata e manutenibile senza duplicare logica per ogni tipo di modello.
Hai bisogno di supporto per la tua implementazione Odoo?
Da Dasolo affianchiamo le aziende nell’implementazione, personalizzazione e ottimizzazione di Odoo in base ai processi reali. Se servono campi personalizzati, modellazione dati o estensioni funzionali, il nostro team ha esperienza tecnica e di processo per farlo correttamente.
Se stai lavorando a un progetto Odoo e vuoi un confronto su tipi di campo, architettura dei dati o best practice di sviluppo, contattaci: valutiamo insieme il caso e proponiamo l’approccio più adatto.