Campo Data e Ora in Odoo: Guida Completa

Introduzione

Le date e i timestamp sono integrati in quasi ogni processo aziendale. Quando è stato effettuato questo ordine? Quando è prevista la consegna? Quando si è registrato l'impiegato? In Odoo, il campo Datetime è il modo standard per catturare e memorizzare questo tipo di informazioni.

A differenza del campo Data, che memorizza solo una data del calendario, il campo Datetime cattura sia la data che l'ora esatta. Questa distinzione è più importante di quanto possa sembrare, specialmente in ambienti con utenti in più fusi orari o quando si tracciano eventi a livello di ora e minuto.

Questa guida copre tutto ciò che devi sapere sul campo Datetime in Odoo: cosa memorizza, come si comporta nel modello di dati, come crearlo e configurarlo utilizzando Odoo Studio o Python, e esempi pratici da flussi di lavoro aziendali reali.

Cos'è il campo Datetime in Odoo

Nell'ORM di Odoo, fields.Datetime memorizza un valore combinato di data e ora, fino al secondo. A livello di database, si mappa a una colonna TIMESTAMP in PostgreSQL. Odoo memorizza sempre i valori Datetime in UTC internamente e li converte nel fuso orario locale dell'utente attivo quando li visualizza nell'interfaccia.

Dal punto di vista dell'utente, un campo Datetime appare come un selettore combinato di data e ora nei moduli. Mostra un widget calendario accanto a un input per l'ora. Nelle visualizzazioni elenco e nei report, il valore è formattato secondo le impostazioni di lingua e fuso orario dell'utente attivo.

Ecco come appare un campo Datetime in una definizione di modello Python:

from odoo import fields, models

class SaleOrder(models.Model):
    _inherit = 'sale.order'

    x_confirmed_on = fields.Datetime(
        string='Confirmed On',
        default=fields.Datetime.now,
        readonly=True,
        copy=False,
    )

Il parametro string imposta l'etichetta mostrata nell'interfaccia. Il parametro default riempie automaticamente il campo con il timestamp corrente quando viene creato un nuovo record. Il parametro readonly impedisce la modifica manuale, cosa comune per i timestamp di audit.

In Odoo Studio, questo tipo di campo è chiamato campo Data & Ora. Quando viene creato tramite Studio, ottiene automaticamente un prefisso x_studio_. Quando viene creato tramite codice o l'API XML-RPC, definisci tu stesso il nome tecnico.

Come funziona il campo

Quando definisci un campo Datetime in Odoo, il framework crea automaticamente la corrispondente colonna del database durante l'installazione o l'aggiornamento del modulo. Non è necessario scrivere manualmente le migrazioni SQL.

Una cosa che sorprende molti sviluppatori e utenti aziendali è come Odoo gestisce i fusi orari. Il database memorizza sempre il valore in UTC. Quando un utente a Parigi imposta un orario per un incontro alle 15:00, Odoo salva 1:00 PM UTC nel database. Un utente a New York che legge lo stesso record vedrà 9:00 AM nella propria interfaccia. L'ORM di Odoo gestisce questa conversione in modo trasparente in base al fuso orario configurato nel profilo di ciascun utente.

Attributi Chiave del Campo

Ecco le proprietà più importanti di un campo Datetime nel framework Odoo:

• default: Spesso impostato su fields.Datetime.now per riempire automaticamente con il timestamp UTC corrente quando viene creato un record.
• required: Rende il campo obbligatorio nei moduli e a livello di modello.
• readonly: Impedisce la modifica manuale nell'interfaccia. Comune per i timestamp generati automaticamente.
• compute: Collega un metodo Python che calcola dinamicamente il valore del campo da altri campi o dalla logica aziendale.
• store: Quando combinato con compute, persiste il valore calcolato nel database per l'uso in ricerche e report.
• copy: Controlla se il valore viene duplicato quando si copia un record. Di default è impostato su True. Imposta su False per i timestamp che non devono essere trasferiti ai duplicati.
• index: Crea un indice nel database. Utile per i campi che vengono frequentemente utilizzati nei filtri, come le date programmate su grandi tabelle.

Come appare nelle viste

Nelle viste modulo, un campo Datetime si presenta come un selettore combinato di data e ora. Gli utenti cliccano per aprire un calendario e impostare l'ora direttamente nello stesso input. Nelle viste elenco, il valore appare come una stringa formattata in base alle impostazioni linguistiche dell'utente. Nelle viste di ricerca, i campi Datetime supportano filtri di intervallo di date come prima, dopo e tra un periodo specifico.

Puoi anche abbinare un campo Datetime con il widget date_range per visualizzare una selezione di intervallo direttamente nel modulo, utile per finestre di programmazione e compiti legati al tempo.

Datetime vs Data: Scegliere il campo giusto

Una domanda comune nello sviluppo Odoo è quando utilizzare fields.Datetime rispetto a fields.Date. La regola è semplice: usa fields.Date quando l'ora del giorno è irrilevante, e fields.Datetime quando hai bisogno di precisione a livello di ora o minuto.

Usa Data per: scadenze delle fatture, compleanni, date di scadenza dei prodotti, date di rinnovo dei contratti.

Usa Datetime per: timestamp di conferma degli ordini, orari di inizio delle riunioni, registrazioni di presenza dei dipendenti, operazioni di magazzino programmate.

Utilizzare Datetime inutilmente aggiunge complessità ai fusi orari senza alcun reale beneficio. In caso di dubbio, chiediti se l'ora del giorno è realmente importante per il processo aziendale che stai modellando.

Casi d'uso aziendali

Il campo Datetime appare in quasi tutti i moduli di Odoo. Ecco cinque esempi pratici tratti da flussi di lavoro aziendali reali.

CRM: Monitoraggio delle Attività dei Lead

Nel modulo CRM, diversi campi Datetime nativi tracciano quando si sono verificati eventi chiave. Il campo date_open registra quando un lead è stato impostato su In Corso. Il campo date_deadline programma un follow-up. I responsabili delle vendite utilizzano questi campi per misurare i tempi di risposta, identificare opportunità stagnanti e riportare sull'attività del team. I campi Datetime personalizzati possono estendere ulteriormente questo, ad esempio per registrare quando è stata inviata un'offerta o quando ha avuto luogo una chiamata specifica.

Vendite: Timestamp di Conferma degli Ordini

Il campo date_order su sale.order è un campo Datetime. Cattura il momento esatto in cui una vendita è stata confermata. Questo è prezioso per riportare sull'attività di vendita giornaliera o oraria, calcolare quanto tempo impiegano gli ordini a essere elaborati e auditare le modifiche apportate dopo la conferma. Filtrare gli ordini di vendita in base a questo campo è una delle operazioni di reporting più comuni in qualsiasi configurazione di vendita Odoo.

Inventario: Date di Trasferimento Programmate

Il campo scheduled_date su stock.picking è un campo Datetime che i team di magazzino utilizzano per pianificare quando dovrebbe avvenire una ricezione o una spedizione. Le azioni automatizzate in Odoo possono attivare flussi di lavoro in base a come questa data si confronta con l'ora attuale. Ad esempio, un'email automatizzata può essere inviata quando una consegna è in ritardo da un certo numero di ore, consentendo una comunicazione proattiva con i clienti prima che contattino.

Produzione: Orari di Inizio e Fine della Produzione

Gli ordini di produzione utilizzano campi Datetime per registrare quando è iniziata e quando è stata completata la produzione. Questi dati alimentano direttamente la pianificazione della capacità, il reporting sull'efficienza e l'analisi delle prestazioni. Per le aziende che gestiscono più turni, catturare il tempo preciso è essenziale per comprendere l'output di produzione reale rispetto a quello pianificato e identificare i colli di bottiglia in base all'ora del giorno o all'operatore.

HR: Gestione delle Presenze e delle Assenze

Il modulo HR Attendance utilizza campi Datetime per registrare gli orari di check-in e check-out dei dipendenti. Le richieste di assenza si basano su Datetime per definire l'inizio e la fine esatti di un'assenza. I calcoli della busta paga e le regole sugli straordinari spesso dipendono da questi valori che devono essere accurati fino al minuto. Qualsiasi deviazione o timestamp mancante nei registri delle presenze può influenzare direttamente i calcoli delle retribuzioni, rendendo la precisione qui un requisito aziendale reale piuttosto che una preferenza tecnica.

Creazione o personalizzazione del campo Datetime

Ci sono tre modi principali per aggiungere un campo Datetime a un modello Odoo, a seconda della tua configurazione tecnica e se preferisci un approccio senza codice o da sviluppatore.

Utilizzando Odoo Studio (Nessun Codice)

Odoo Studio è lo strumento di personalizzazione integrato che ti consente di aggiungere campi senza scrivere alcun codice. Per aggiungere un campo Datetime tramite Studio:

1. Apri Odoo Studio dal menu principale.
2. Naviga al modulo in cui desideri aggiungere il campo.
3. Trascina un campo Data e Ora dalla barra laterale nel modulo.
4. Imposta l'etichetta, lo stato richiesto e, facoltativamente, un valore predefinito nel pannello delle proprietà del campo.
5. Salva e chiudi Studio.

Studio crea automaticamente il campo con un prefisso x_studio_ e lo aggiunge alla vista del modulo. Non è necessaria alcuna migrazione del database da parte tua. Odoo gestisce tutto automaticamente quando salvi. Questo è l'approccio raccomandato per gli utenti aziendali che devono aggiungere un timestamp a un modulo esistente senza il coinvolgimento di uno sviluppatore.

Utilizzando Python in un Modulo Personalizzato

Per gli sviluppatori che costruiscono moduli Odoo, i campi Datetime sono definiti nei file modello Python. Questo è l'approccio raccomandato per qualsiasi personalizzazione che deve essere controllata in versione e distribuita su più ambienti:

from odoo import fields, models

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

    x_last_contact_date = fields.Datetime(
        string='Data Ultimo Contatto',
        default=fields.Datetime.now,
        copy=False,
    )

Dopo aver definito il campo nel modello, aggiungilo al file XML della vista pertinente affinché appaia nell'interfaccia. Odoo crea automaticamente la colonna TIMESTAMP quando installi o aggiorni il modulo. Non è necessaria alcuna SQL manuale.

Utilizzando l'API XML-RPC

Se gestisci le personalizzazioni di Odoo in modo programmatico, ad esempio come parte di una pipeline di distribuzione o di uno script di configurazione remota, puoi creare campi Datetime tramite l'API XML-RPC:

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_last_contact_date',
        'field_description': 'Data dell'ultimo contatto',
        'model_id': model_id,
        'ttype': 'datetime',
        'state': 'manual',
    }]
)

Il valore ttype: datetime indica a Odoo di creare un campo Datetime. Il valore state: manual indica che questo campo è stato creato al di fuori di un'installazione di modulo, che è l'impostazione corretta per i campi creati tramite Studio o l'API. Questo è il modo in cui Dasolo gestisce la creazione remota di campi per i clienti come parte di script di configurazione automatizzati.

Migliori pratiche

1. Usa fields.Datetime.now come riferimento di funzione, non come chiamata

Quando imposti un valore predefinito, scrivi default=fields.Datetime.now senza parentesi. Se aggiungi le parentesi, Python valuta la funzione una volta quando la classe viene caricata, e ogni record creato per la durata del processo Odoo condividerà lo stesso timestamp congelato. Senza parentesi, Odoo chiama la funzione al momento della creazione del record, dando a ciascun record il proprio timestamp accurato.

2. Imposta copy=False sui timestamp degli eventi

Se un campo registra quando è accaduto qualcosa, come una data di conferma o un timestamp di completamento, imposta copy=False. Quando gli utenti duplicano un record, questi timestamp non dovrebbero essere trasferiti dall'originale. Un ordine di vendita duplicato non dovrebbe mostrare la data di conferma dell'ordine da cui è stato copiato. Senza questa impostazione, i dati storici diventano silenziosamente inaffidabili.

3. Passa sempre UTC quando scrivi tramite l'API

Quando crei o aggiorni record tramite l'API XML-RPC, passa sempre i valori Datetime in UTC utilizzando il formato stringa YYYY-MM-DD HH:MM:SS. L'API non esegue la conversione del fuso orario in scrittura. Qualsiasi stringa tu passi viene memorizzata direttamente nel database come se fosse UTC, quindi passare un'ora locale creerà silenziosamente un errore di offset che è difficile da diagnosticare in seguito.

4. Usa readonly per i timestamp generati automaticamente

I campi che catturano quando è accaduto qualcosa dovrebbero generalmente essere impostati come readonly nell'interfaccia. Questo impedisce agli utenti di modificare manualmente i timestamp che dovrebbero riflettere eventi reali del sistema. Se c'è una ragione legittima per consentire la modifica, controlla l'accesso tramite le impostazioni di sicurezza a livello di campo di Odoo piuttosto che lasciare il campo liberamente modificabile.

5. Scegli Data invece di Datetime quando il tempo non è necessario

Se un campo deve solo tenere traccia di una data del calendario, come una scadenza di consegna, una data di rinnovo o una data di scadenza della fattura, usa fields.Date. Datetime aggiunge complessità nella gestione dei fusi orari che non ha alcuno scopo quando il componente temporale è sempre irrilevante. Mantenere il tipo di campo il più semplice possibile in base al caso d'uso rende il modello di dati più facile da comprendere e mantenere.

Errori comuni

Confusione sui fusi orari quando si leggono valori grezzi

Questa è la fonte di confusione più frequente con i campi Datetime. Quando leggi un valore direttamente dal database o tramite l'API, vedi il valore UTC, non l'ora locale dell'utente. Molti sviluppatori costruiscono report o integrazioni basati sull'output grezzo dell'API e si ritrovano con timestamp che sono sbagliati di un'ora o più. Applica sempre la conversione del fuso orario sul lato client quando presenti i risultati dell'API agli utenti finali e rendi questo un passaggio esplicito in qualsiasi integrazione tu costruisca.

Scrivere orari localizzati tramite l'API

Se passi un valore Datetime che è già in un fuso orario locale all'API di Odoo, il database lo memorizzerà come se fosse UTC. Un incontro fissato alle 15:00 ora di Parigi, scritto come 2026-01-01 15:00:00 all'API, verrà visualizzato come 16:00 o 17:00 per un utente a Parigi, a seconda dell'ora legale o solare. Questo è uno di quei bug che appare solo in produzione quando utenti reali in fusi orari reali iniziano a utilizzare il sistema.

Utilizzare default=fields.Datetime.now() con parentesi

Aggiungere parentesi al valore predefinito è un errore sottile ma serio. fields.Datetime.now() viene valutato una sola volta quando la classe Python viene caricata. Ogni record creato per l'intera durata del processo di lavoro di Odoo condividerà lo stesso timestamp congelato. I record appariranno corretti inizialmente ma romperanno qualsiasi analisi basata sui tempi di creazione. Questo è un bug silenzioso che può richiedere molto tempo per essere individuato perché i timestamp sembrano esistere, sono solo tutti identici.

Dimenticare copy=False sui timestamp degli eventi

Senza copy=False, un record duplicato porta con sé tutti i valori Datetime dall'originale. Una data di conferma dell'ordine, un'ora di creazione del lead o un timestamp di inizio produzione dal record sorgente appariranno invariati sul nuovo. Questo contamina silenziosamente i report storici e rende inaffidabili le tracce di audit. È un piccolo dettaglio di configurazione che ha un impatto sproporzionato sulla qualità dei dati.

Utilizzare Datetime quando Date è sufficiente

Scegliere Datetime per un campo come una data di scadenza della fattura o una data di scadenza del prodotto aggiunge complessità non necessaria. Gli utenti vedono un componente temporale di cui non hanno bisogno, i calcoli dei fusi orari vengono eseguiti su ogni visualizzazione senza alcun beneficio, e l'interfaccia diventa leggermente più ingombrante senza motivo. Il tipo di campo giusto è il più semplice che modella correttamente il requisito aziendale.

Conclusione

Il campo Datetime è uno dei tipi di campo più utili in Odoo quando la precisione è importante. Dalla registrazione di quando un lead è stato aperto alla registrazione degli orari di inizio produzione e della presenza dei dipendenti, appare in quasi tutti i moduli del sistema.

La cosa chiave da interiorizzare è il modello di archiviazione UTC. Tutto ciò che è memorizzato nel database è in UTC. L'interfaccia gestisce automaticamente la visualizzazione del fuso orario per gli utenti, ma qualsiasi lettura o scrittura esterna tramite l'API deve tenerne conto esplicitamente. La maggior parte dei bug relativi ai fusi orari nelle integrazioni Odoo risale a questo fraintendimento.

Oltre a ciò, utilizzare la sintassi predefinita corretta, impostare copy=False dove appropriato e scegliere Data invece di Datetime quando il tempo non è rilevante manterrà il tuo modello di dati pulito e i tuoi report affidabili.

Da Dasolo, aiutiamo le aziende a implementare, personalizzare e ottimizzare Odoo in tutti i dipartimenti. Che tu abbia bisogno di aiuto per progettare un solido modello di dati, aggiungere campi personalizzati ai tuoi flussi di lavoro o costruire un intero modulo Odoo da zero, il nostro team è pronto ad aiutarti. Contattaci e parliamo del tuo progetto Odoo.