Campo di Riferimento in Odoo: Guida Completa

Introduzione

La maggior parte degli sviluppatori Odoo ricorre al campo Many2one quando deve collegare un record a un altro. Funziona perfettamente nella stragrande maggioranza dei casi. Ma a volte ci si imbatte in una situazione in cui il documento collegato potrebbe essere uno di diversi tipi: un ordine di vendita, un ordine di acquisto, un ordine di produzione o qualcos'altro a seconda del contesto. È esattamente per questo che è stato creato il campo di riferimento.

Il campo di riferimento è uno dei tipi di campo più flessibili nell'ORM di Odoo. Ti consente di creare un collegamento a un record di qualsiasi modello in un elenco predefinito, piuttosto che puntare sempre allo stesso modello. L'utente prima seleziona il tipo di documento, poi sceglie il record specifico. Il risultato è un collegamento polimorfico che può adattarsi a diversi flussi di lavoro.

Questa guida copre cosa memorizza il campo di riferimento, come si comporta nel modello dati di Odoo, come crearlo e personalizzarlo utilizzando Odoo Studio o Python, e casi d'uso aziendali pratici in cui aggiunge realmente valore.

Cos'è il campo di riferimento in Odoo

Nell'ORM di Odoo, il campo Reference è un tipo di campo speciale che memorizza un collegamento a un record di qualsiasi modello tu includa nella sua selection list. Questo lo rende fondamentalmente diverso da un campo Many2one, che punta sempre a un modello fisso.

Nel database, il campo Reference memorizza il suo valore come una stringa di testo semplice nel formato model_name,record_id. Ad esempio, un riferimento all'ordine di vendita numero 42 sarebbe memorizzato come sale.order,42. Questo è importante da capire se mai avrai bisogno di interrogare o filtrare questi record direttamente.

Dal punto di vista dell'interfaccia utente, un campo Reference appare come un input a due fasi. L'utente prima seleziona un tipo di documento da un elenco a discesa (ad esempio: Ordine di Vendita, Fattura o Compito di Progetto), e poi sceglie il record specifico da quel modello utilizzando un campo di ricerca. L'interfaccia è pulita e semplice una volta che gli utenti comprendono la selezione a due fasi.

Ecco come appare una definizione di base di un campo 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 è un elenco di tuple. Ogni tupla contiene il nome tecnico del modello (come sale.order) e l'etichetta leggibile dall'uomo che gli utenti vedranno nel menu a discesa. Controlli esattamente quali modelli sono disponibili in questo elenco.

Esiste anche una variante dinamica in cui l'elenco di selezione è popolato dalla tabella ir.model a runtime, rendendo disponibili tutti i modelli installati. Questo è utile per strumenti altamente configurabili, ma può diventare opprimente per gli utenti finali se non filtrato correttamente.

In Odoo Studio, il campo Reference è disponibile nel pannello dei tipi di campo ed è etichettato come Reference. Quando lo aggiungi tramite Studio, puoi configurare l'elenco dei modelli selezionabili direttamente dall'interfaccia senza scrivere alcun codice. Questo lo rende una delle opzioni più accessibili tra i campi avanzati di Odoo studio.

Come funziona il campo

Comprendere come il campo Reference memorizza e recupera i dati è fondamentale per utilizzarlo correttamente nei tuoi progetti di sviluppo Odoo.

Archiviazione nel Database

A differenza di un campo Many2one, che memorizza solo un intero (la chiave esterna), il campo Reference memorizza un valore stringa che include sia il nome del modello che l'ID del record. Ad esempio: sale.order,15. Questo è memorizzato in una colonna VARCHAR in PostgreSQL. Significa che il database non applica alcun vincolo di chiave esterna su questa colonna, che è una scelta di design deliberata per supportare la natura polimorfica del campo.

Poiché non esiste una chiave esterna a livello di database, Odoo non pulisce automaticamente i valori del campo Reference quando il record collegato viene eliminato. Se un ordine di vendita viene eliminato, un campo Reference che punta ad esso conterrà ancora il vecchio valore stringa. Questa è una delle differenze comportamentali più importanti da tenere a mente durante lo sviluppo in Odoo.

Accesso al Record Collegato in Python

Quando leggi un valore di campo Riferimento in Python, Odoo restituisce l'oggetto record effettivo del modello referenziato. Puoi accedere ai suoi campi direttamente, proprio come faresti con un risultato Many2one. Se il campo è vuoto, restituisce False.

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. 15

Questo è uno degli aspetti convenienti dell'astrazione ORM di Odoo. Anche se lo storage sottostante è una stringa di testo semplice, il framework lo risolve in un oggetto record appropriato quando lo accedi nel codice.

Attributi Chiave del Campo

Questi sono gli attributi più rilevanti che puoi configurare su un campo Riferimento nel framework Odoo:

• selection: Un elenco di tuple che definiscono quali modelli sono selezionabili. Può anche essere un nome di metodo (stringa) che restituisce dinamicamente un tale elenco.
• string: L'etichetta del campo mostrata agli utenti nell'interfaccia.
• required: Rende il campo obbligatorio. L'utente deve selezionare sia un tipo di modello che un record prima di salvare.
• readonly: Impedisce agli utenti di modificare il valore del campo dall'interfaccia. Utile quando il riferimento è impostato programmaticamente.
• help: Un tooltip mostrato quando l'utente passa il mouse sopra l'etichetta del campo. Utile per guidare gli utenti su cosa selezionare.
• compute: Come qualsiasi altro tipo di campo Odoo, un campo Riferimento può essere calcolato dinamicamente utilizzando un metodo Python. Questo è utile per impostare automaticamente un riferimento basato sulla logica aziendale.

Filtraggio e Ricerca

Poiché il valore è memorizzato come una stringa semplice, il filtraggio su un campo di Riferimento richiede una sintassi di dominio specifica. Per cercare record collegati a un documento specifico, è necessario comporre il valore della stringa da soli:

tickets = self.env['helpdesk.ticket'].search([
    ('related_document', '=', 'sale.order,15')
])

Puoi anche filtrare per tipo di modello utilizzando un operatore like:

tickets = self.env['helpdesk.ticket'].search([
    ('related_document', 'like', 'sale.order,')
])

Tieni presente questo comportamento di filtraggio basato su stringhe quando progetti report o campi calcolati che dipendono dai valori dei campi di Riferimento. Si comporta in modo diverso rispetto a un tipico filtro di dominio Many2one.

Casi d'uso aziendali

Il campo di Riferimento è più prezioso in situazioni in cui lo stesso tipo di collegamento contestuale può puntare a documenti di tipi diversi a seconda della situazione. Ecco cinque esempi pratici da flussi di lavoro aziendali reali.

1. Ticket di Assistenza Collegati a Qualsiasi Documento

Un team di supporto gestisce ticket che possono riguardare cose molto diverse: una controversia su una fattura, un problema di consegna, una domanda su un contratto o un prodotto difettoso. Invece di creare un campo separato per ciascun tipo di documento, un singolo campo di Riferimento sul modello del ticket consente all'agente di collegarsi a qualsiasi documento pertinente. L'agente sceglie prima il tipo (Fattura, Ordine di Vendita, Consegna, ecc.) e poi seleziona il record specifico. Tutto il contesto è in un campo.

2. Attività CRM Collegate a Documenti Sorgente Multipli

In un team di vendita, le attività e i compiti di follow-up a volte originano da fonti diverse: un lead, un preventivo, un contratto esistente o un caso di supporto. Un campo di Riferimento su un modello di attività personalizzato o su una nota CRM consente ai venditori di etichettare il documento di origine senza essere bloccati su un singolo modello. Questo è un abbinamento naturale per il campo di Riferimento in una personalizzazione CRM di Odoo.

3. Note e Annotazioni Attraverso i Moduli

Alcune aziende costruiscono un semplice modello di note interne o annotazioni per registrare osservazioni su diversi oggetti aziendali. Un campo di Riferimento consente di allegare un singolo record di nota a un record cliente, a un'attività di progetto, a un ordine di produzione o a un ordine di acquisto, tutto all'interno dello stesso campo. Questo evita di duplicare il modello di nota per ogni tipo di documento.

4. Flusso di Approvazione dei Documenti

Quando si implementa un flusso di approvazione generico, la richiesta di approvazione deve puntare al documento che viene approvato. Poiché le approvazioni possono applicarsi a ordini di acquisto, report spese, richieste di congedo o contratti, un campo di Riferimento nel modello di approvazione mantiene l'architettura pulita. La stessa logica di approvazione gestisce tutti i tipi di documenti senza necessità di modelli separati per ciascuno.

5. Report Spese Collegati a Progetti o Ordini Clienti

In alcune configurazioni contabili, una spesa deve essere collegata a un progetto cliente o a un ordine di vendita a seconda della natura del costo. Un campo di Riferimento con sia project.project che sale.order nella sua lista di selezione offre al contabile la flessibilità di allegare la spesa al documento pertinente. Questo è particolarmente utile nelle aziende di servizi professionali e di consulenza che utilizzano Odoo.

Creazione o personalizzazione del campo di riferimento

Ci sono due modi principali per aggiungere un campo di Riferimento a un modello Odoo: utilizzare Odoo Studio per un approccio senza codice, oppure scriverlo direttamente in Python per avere il pieno controllo.

Utilizzando Odoo Studio

Odoo Studio rende semplice aggiungere un campo di Riferimento a qualsiasi modulo senza toccare il codice. Apri Studio sul modello che desideri estendere, vai al pannello dei Campi e aggiungi un nuovo campo di tipo Riferimento. Ti verrà chiesto di selezionare quali modelli dovrebbero apparire nella lista a discesa. Studio memorizza il campo come un campo manuale con un prefisso x_, proprio come altri campi di Odoo Studio creati tramite l'interfaccia.

Questo approccio è ideale per personalizzazioni rapide e per analisti aziendali che desiderano estendere i moduli senza il coinvolgimento di sviluppatori. Tieni presente che i campi di Riferimento creati con Studio potrebbero avere un supporto limitato per configurazioni avanzate come metodi di selezione dinamici o valori calcolati.

Implementazione Tecnica in Python

Per un approccio completo allo sviluppo Odoo, definisci il campo di Riferimento direttamente in un modello Python. Ecco un esempio più completo che mostra come creare un campo di Riferimento con un metodo di selezione dinamico:

from odoo import api, fields, models

class ApprovalRequest(models.Model):
    _name = 'approval.request'
    _description = 'Richiesta di Approvazione'

    name = fields.Char(string='Nome Richiesta', required=True)

    @api.model
    def _get_document_types(self):
        return [
            ('purchase.order', 'Ordine di Acquisto'),
            ('hr.expense.sheet', 'Report Spese'),
            ('hr.leave', 'Richiesta di Congedo'),
            ('sale.order', 'Ordine di Vendita'),
        ]

    document_ref = fields.Reference(
        selection='_get_document_types',
        string='Documento',
        help='Seleziona il documento a cui si riferisce questa approvazione.',
    )

Utilizzare un metodo per il parametro selection (passando il suo nome come stringa) offre maggiore flessibilità. Puoi aggiungere logica condizionale, filtrare in base ai moduli installati o costruire l'elenco dinamicamente a partire dai record di configurazione.

Creazione tramite l'API XML-RPC

Puoi anche creare un campo di riferimento programmaticamente utilizzando l'API XML-RPC di Odoo. Questo è utile quando si distribuiscono campi come parte di un quaderno di configurazione remota. Il tipo di campo da utilizzare è reference e la selezione viene passata come rappresentazione stringa dell'elenco:

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_related_document',
        'field_description': 'Documento Correlato',
        'model_id': model_id,
        'ttype': 'reference',
        'selection': "[('sale.order', 'Ordine di Vendita'), ('purchase.order', 'Ordine di Acquisto')]",
        'state': 'manual',
    }]
)

Nota che quando crei un campo di riferimento tramite l'API, il valore selection viene passato come stringa valutabile in Python piuttosto che come un elenco reale. Questo è il modo in cui Odoo lo memorizza e lo legge dalla tabella ir.model.fields.

Migliori pratiche

Ecco le linee guida più utili da seguire quando lavori con i campi di riferimento nel tuo modello di dati Odoo.

• Mantieni l'elenco delle selezioni breve e significativo. Non includere ogni modello solo perché puoi. Limita l'elenco ai tipi di documento che hanno realmente senso per il caso d'uso. Un lungo elenco confonde gli utenti e rende il campo più difficile da utilizzare correttamente.
• Utilizza Many2one quando colleghi sempre lo stesso modello. Il campo di riferimento è progettato per relazioni polimorfiche. Se il modello collegato non cambia mai, un campo Many2one standard è più semplice, più veloce da interrogare e meglio supportato dagli strumenti di reporting di Odoo.
• Controlla sempre i valori nulli nei campi calcolati. Quando un campo di riferimento è vuoto, restituisce False in Python. Qualsiasi codice che accede al record collegato deve controllare prima questo per evitare errori.
• Gestisci i riferimenti orfani nelle azioni automatizzate. Poiché il database non applica l'integrità referenziale sui campi di riferimento, è una buona idea aggiungere un'azione automatizzata o un'azione pianificata che controlli periodicamente e rimuova i riferimenti obsoleti che puntano a record eliminati.
• Utilizza etichette descrittive per ciascun modello nella selezione. Il secondo elemento di ciascuna tupla è ciò che gli utenti vedono nel menu a discesa. Utilizza etichette chiare e adatte al business piuttosto che nomi di modelli tecnici. Scrivi "Fattura Cliente" piuttosto che "account.move".
• Documenta chiaramente il campo nelle tue specifiche tecniche. Poiché i campi di riferimento si comportano in modo diverso dai campi Many2one standard, qualsiasi sviluppatore che eredita il tuo codice trarrà vantaggio da una chiara spiegazione del motivo per cui è stato scelto un riferimento e quali modelli collega.

Trappole comuni

Questi sono gli errori che vediamo più spesso quando gli sviluppatori o gli analisti aziendali lavorano con i campi di Riferimento per la prima volta.

Trattarlo come un Many2one nei Filtri di Dominio

A volte gli sviluppatori scrivono filtri di dominio per un campo di Riferimento utilizzando la stessa sintassi di un Many2one, ad esempio [('document_ref', '=', 15)]. Questo non funzionerà. Il valore memorizzato è una stringa come sale.order,15, non solo un intero. Devi comporre il valore della stringa completa quando costruisci filtri di dominio su un campo di Riferimento.

Dimenticando che i Record Cancellati Lasciano Valori Orfani

Poiché non esiste un vincolo di chiave esterna nel database, la cancellazione di un record di riferimento non cancella il valore del campo di Riferimento. Se un ordine di vendita viene cancellato e un ticket ha ancora sale.order,42 nel suo campo di Riferimento, la lettura di quel campo restituirà False invece di sollevare un errore. Il codice che si basa sulla validità del riferimento deve sempre gestire questo caso.

Sovrautilizzando la Selezione Dinamica di Tutti i Modelli

Odoo ti consente di passare un metodo per la selection che restituisce tutti i modelli installati da ir.model. Sebbene questo sia potente, è quasi sempre troppo ampio per un campo rivolto all'utente. Presentare centinaia di modelli in un menu a discesa è confuso e porta a un'inserimento dati errato. Limita sempre la selezione a un elenco curato di tipi di documento significativi.

Aspettandosi un Raggruppamento Nativo nei Rapporti

I campi di Riferimento sono memorizzati come stringhe di testo semplice nel database. Non sono chiavi esterne, quindi la funzionalità standard di raggruppamento e pivot di Odoo non funziona su di essi come fa sui campi Many2one. Se hai bisogno di raggruppare o aggregare record in base al loro documento collegato, dovrai gestire questo tramite codice personalizzato o un campo calcolato che estrae il nome del modello come una selezione separata o un campo char.

Confondendo Riferimento e Many2one in Odoo Studio

Quando si utilizza Odoo Studio, alcuni utenti confondono il campo di Riferimento e il campo Many2one perché entrambi consentono di collegarsi a un altro record. La differenza chiave è che un Many2one collega sempre a un modello specifico (lo scegli al momento della creazione del campo e non cambia mai), mentre un campo di Riferimento consente all'utente di scegliere il modello ogni volta che compila il campo. Se hai creato un Many2one quando avevi bisogno di un Riferimento, dovrai ricostruire il campo piuttosto che cercare di adattare quello esistente.

Conclusione

Il campo di Riferimento colma un gap che il campo Many2one non può coprire da solo. Quando un collegamento deve essere abbastanza flessibile da puntare a diversi tipi di documento a seconda della situazione, il campo di Riferimento è lo strumento giusto nel framework Odoo. È semplice da definire, funziona con Odoo Studio per configurazioni senza codice e si integra naturalmente nei modelli Python per implementazioni tecniche.

Le principali cose da tenere a mente sono il formato di archiviazione basato su stringhe, l'assenza di pulizia automatica delle chiavi esterne e la necessità di filtrare utilizzando valori di stringa composti piuttosto che ID semplici. Una volta comprese queste differenze, il campo si comporta in modo prevedibile e affidabile nel tuo modello di dati Odoo.

Che tu stia costruendo un flusso di approvazione generico, collegando ticket di supporto a diversi tipi di documenti o progettando un sistema di note flessibile che attraversa più moduli, il campo Riferimento ti offre una soluzione pulita e manutenibile senza la necessità di duplicare la tua logica per ogni tipo di modello.

Hai bisogno di aiuto con la tua implementazione di Odoo?

Da Dasolo, aiutiamo le aziende a implementare, personalizzare e ottimizzare Odoo per adattarlo ai loro flussi di lavoro aziendali reali. Che tu abbia bisogno di costruire logica di campo personalizzata, progettare un modello di dati da zero o estendere un'installazione Odoo esistente con nuove funzionalità, il nostro team ha la competenza tecnica per farlo correttamente.

Se stai lavorando a un progetto Odoo e hai bisogno di indicazioni sui tipi di campo, sull'architettura dei dati o sulle migliori pratiche di sviluppo, non esitare a contattarci. Siamo felici di discutere la tua situazione e aiutarti a trovare l'approccio giusto.

Contatta Dasolo