Introduzione
Date e orari sono al centro di quasi tutti i processi aziendali: ordini, consegne, timbrature, appuntamenti. In Odoo il campo Datetime è lo strumento standard per catturare queste informazioni con data e ora precise, permettendo di rispondere a domande pratiche come «quando è stato confermato questo ordine?» o «a che ora è iniziata la produzione?»
A differenza del campo Date, che conserva solo il giorno, il Datetime memorizza anche l’ora e i minuti. Questo dettaglio è determinante quando servono precisione temporale o quando gli utenti lavorano da fusi orari diversi: senza l’ora esatta molte analisi e automazioni perdono significato.
Questa guida spiega in modo pratico tutto ciò che serve sapere sul campo Datetime in Odoo: cosa contiene, come viene gestito nel modello dati, come aggiungerlo via Odoo Studio, modulo Python o API, e esempi concreti tratti da flussi aziendali reali.
Cos'è il campo Datetime in Odoo
Nel framework ORM di Odoo, fields.Datetime rappresenta un valore combinato di data e ora con precisione al secondo. A livello di database corrisponde a una colonna TIMESTAMP in PostgreSQL. Odoo salva internamente i valori in UTC e, quando li mostra, li converte automaticamente nel fuso orario impostato dall’utente corrente.
Per l’utente il campo Datetime si presenta come un unico controllo che unisce calendario e selezione dell’ora. Nei dettagli e nei report i valori vengono formattati in base alla lingua e al fuso orario dell’utente attivo, offrendo una visualizzazione locale coerente nonostante la memorizzazione in UTC.
Ecco come si dichiara un campo Datetime in un 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 definisce l’etichetta mostrata in interfaccia. default imposta automaticamente il valore iniziale (di solito il timestamp corrente). readonly
In Odoo Studio questo tipo di campo si chiama Date & Time e, se creato da Studio, riceve automaticamente il prefisso x_studio_. Se invece lo definisci nel codice o via API, scegli tu il nome tecnico del campo.
Come funziona il campo
Quando dichiari un campo Datetime nel modulo, Odoo si occupa di creare la corrispondente colonna nel database durante l’installazione o l’aggiornamento del modulo. Non è necessario scrivere migrazioni SQL manuali: l’ORM gestisce la sincronizzazione dello schema.
Un aspetto che sorprende spesso è la gestione dei fusi orari. Il DB conserva sempre il valore in UTC: se un utente a Parigi imposta un incontro alle 15:00, il sistema salva 13:00 UTC. Un utente a New York vedrà il valore riportato come 09:00. Tutto questo viene convertito automaticamente dall’ORM in base al fuso impostato nel profilo utente.
Attributi principali del campo
Di seguito le proprietà più importanti del campo Datetime in Odoo, utili per modellare il comportamento desiderato:
- default: comunemente impostato come
fields.Datetime.nowper popolare automaticamente il valore corrente UTC alla creazione del record. - required: rende il campo obbligatorio nei form e a livello di modello.
- readonly: impedisce la modifica manuale in interfaccia, tipico per timestamp generati automaticamente dal sistema.
- compute: associa il campo a un metodo Python che calcola dinamicamente il valore a partire da altri campi o logica di business.
- store: se usato con
compute, salva il valore calcolato in DB in modo da poterlo usare in ricerche e report. - copy: controlla se il valore viene duplicato quando si copia un record. Valore predefinito
True; per timestamp evento usareFalse. - index: crea un indice DB, consigliato per campi usati spesso nei filtri su tabelle grandi, ad esempio date di pianificazione.
Come appare nelle viste
Nei form il Datetime si mostra come picker combinato: calendario e ora nello stesso controllo. Nelle liste appare come stringa formattata secondo la lingua dell’utente. Nei filtri di ricerca supporta intervalli temporali (prima, dopo, tra), utili per query su scadenze e programmazioni.
Puoi anche usare il widget date_range per esporre direttamente in form una selezione di intervallo, comoda per finestre operative o finestre temporali di servizio.
Datetime vs Date: quale scegliere
La scelta tra fields.Datetime e fields.Date è semplice: usa Date quando l’ora non conta; usa Datetime quando serve precisione a ore e minuti.
Usa Date per: scadenze fatture, compleanni, date di scadenza prodotto, rinnovi contrattuali.
Usa Datetime per: conferme ordine con orario preciso, inizio riunioni, timbrature del personale, operazioni di magazzino programmate.
Impostare Datetime dove non serve aggiunge complessità legata ai fusi orari senza vantaggi concreti. Quando hai dubbi, verifica se l’ora del giorno è davvero rilevante per il processo aziendale.
Casi d'uso aziendali
Dove si usa il campo Datetime in azienda
CRM: tracciamento attività lead
Nel CRM diversi campi Datetime tengono traccia dei momenti chiave: quando un lead è stato aperto, quando va seguito, ecc. Questi valori servono per misurare i tempi di risposta, individuare opportunità inattive e creare report sull’attività commerciale. Campi personalizzati possono registrare l’orario di invio di preventivi o l’ora di una specifica chiamata.
Sales: timestamp di conferma ordine
Il campo date_order su sale.order è un Datetime che registra l’esatto momento di conferma della vendita. È fondamentale per reportistica a livello giornaliero o orario, per calcolare i lead time e per verifiche di audit. Filtrare ordini per questa data è un’operazione comune nelle analisi di vendita.
Magazzino: date di trasferimento programmate
Il campo scheduled_date su stock.picking indica quando una spedizione o un ricevimento è pianificato. Automazioni possono far scattare azioni basate su questo valore (es. invio di email quando una consegna è in ritardo di alcune ore), consentendo comunicazione proattiva verso il cliente.
Produzione: orari di inizio e fine lavorazione
Gli ordini di produzione registrano gli orari di avvio e chiusura con campi Datetime. Questi dati alimentano la pianificazione della capacità, il calcolo dell’efficienza e l’analisi delle prestazioni. In realtà con turni multipli l’ora precisa è essenziale per confrontare output pianificato e reale e per individuare colli di bottiglia.
HR: timbrature e gestione permessi
Il modulo HR Attendance usa Datetime per check-in/check-out; le richieste di permesso possono richiedere orari di inizio e fine precisi. Calcoli di busta paga e regole per straordinari dipendono dalla precisione al minuto: errori o assenze di timestamp possono impattare direttamente le retribuzioni, quindi la precisione è requisito operativo.
Creare o personalizzare un campo Datetime
Tre modi per aggiungere un Datetime a un modello Odoo
Metodo no-code con Odoo Studio
Odoo Studio è lo strumento integrato per aggiungere campi senza codice. Per inserire un Datetime con Studio:
- Apri Odoo Studio dal menu principale.
- Vai al form dove vuoi aggiungere il campo.
- Trascina il campo Date & Time dalla barra laterale sul form.
- Configura etichetta, obbligatorietà e, se vuoi, un valore di default nelle proprietà del campo.
- Salva e chiudi Studio.
Studio crea automaticamente il campo con prefisso x_studio_ e lo aggiunge alla vista. Non serve migrazione manuale: Odoo esegue gli aggiornamenti di schema al salvataggio. È la strada ideale per utenti business che vogliono aggiungere timestamp senza coinvolgere sviluppatori.
Metodo per sviluppatori: Python in un modulo custom
Gli sviluppatori definiscono i campi Datetime nei file Python dei moduli: è la soluzione raccomandata quando la personalizzazione deve essere tracciata nel codice e distribuita tra ambienti.
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_last_contact_date = fields.Datetime(
string='Last Contact Date',
default=fields.Datetime.now,
copy=False,
)Dopo aver dichiarato il campo, aggiungilo alla vista XML per renderlo visibile in interfaccia. L’ORM si occupa di creare la colonna TIMESTAMP al momento dell’installazione o aggiornamento del modulo; non servono operazioni SQL manuali.
Metodo programmato: API XML-RPC
Per automazioni o script di provisioning puoi creare campi via API XML-RPC, utile in pipeline di deploy o configurazioni remote:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_last_contact_date',
'field_description': 'Last Contact Date',
'model_id': model_id,
'ttype': 'datetime',
'state': 'manual',
}]
)Il valore ttype: datetime indica la creazione di un campo Datetime; state: manual segnala che il campo è stato creato fuori da un modulo, impostazione tipica per campi aggiunti tramite Studio o API. Questo approccio consente di gestire campi in modo automatizzato durante rollout per i clienti.
Buone pratiche
1. Usare fields.Datetime.now come riferimento (senza parentesi)
Quando imposti un default scrivi default=fields.Datetime.now senza parentesi. Se metti le parentesi, la funzione viene valutata una sola volta al caricamento della classe e tutti i record creati durante la vita del processo condivideranno lo stesso timestamp fisso invece che avere l’ora di creazione reale.
2. Impostare copy=False per timestamp di evento
Per i campi che registrano un evento (es. data di conferma, fine lavorazione), metti copy=False. Se qualcuno duplica un record, quei timestamp non devono essere riutilizzati: mantenerli causerebbe dati storici fuorvianti e report poco attendibili.
3. Passare sempre UTC quando si scrive via API
Quando scrivi o crei record via XML-RPC, invia sempre i valori Datetime in UTC con formato YYYY-MM-DD HH:MM:SS. L’API non effettua conversioni di fuso orario alla scrittura: la stringa che inoltri viene memorizzata così com’è come valore UTC. Fornire orari locali causa discrepanze difficili da individuare dopo.
4. Usare readonly per timestamp generati automaticamente
I campi che riflettono eventi di sistema dovrebbero essere readonly in interfaccia per evitare modifiche manuali che falsano gli eventi. Se serve la modifica per motivi legittimi, gestiscila con permessi e regole di sicurezza a livello di campo, non lasciando il campo liberamente editabile.
5. Preferire Date quando l’ora non serve
Se serve solo una data di calendario (scadenza, rinnovo, termine), usa fields.Date. Un Datetime introduce gestione fuso orario e complessità inutile quando l’ora non ha valore operativo. Mantenere i tipi minimi necessari semplifica modello e manutenzione.
Errori comuni
Confusione sui fusi orari leggendo i valori grezzi
Il problema più ricorrente è leggere valori direttamente dal DB o dall’API e vedere il tempo in UTC, non l’orario locale dell’utente. Molti report o integrazioni costruite su output grezzo finiscono con timestamp sfasati. Le conversioni di fuso orario devono essere fatte lato client prima di mostrare i dati agli utenti e devono far parte della logica di integrazione.
Scrivere orari locali tramite API
Se invii all’API un orario già in fuso locale, il DB lo salverà come se fosse UTC. Un meeting impostato alle 15:00 in Parigi e scritto come 2026-01-01 15:00:00 potrebbe poi essere visualizzato con un’ora diversa a seconda dell’account e della stagione (ora legale/invernale). Questi errori emergono tipicamente in produzione con utenti reali in fusi diversi.
Usare default=fields.Datetime.now() con parentesi
Mettere le parentesi nella default è un errore subdolo: fields.Datetime.now() viene calcolato al caricamento della classe e tutti i record avranno la stessa data/ora. Inizialmente sembra che i timestamp ci siano, ma sono identici e compromettono analisi e integrità temporale. È una falla difficile da scovare perché non produce errori evidenti.
Dimenticare copy=False per timestamp evento
Senza copy=False i record duplicati ereditano tutti i valori Datetime dall’originale. Ciò inquina i report e rende gli audit inattendibili: una copia di un ordine che conserva la data di conferma dell’originale è fonte di confusione. È un dettaglio semplice da impostare ma con grande impatto sulla qualità dei dati.
Usare Datetime quando bastava Date
Scegliere Datetime per una scadenza fattura o una data di scadenza prodotto introduce inutili complessità: un campo mostra una componente oraria non necessaria, servono conversioni di fuso orario ad ogni visualizzazione e l’interfaccia diventa meno immediata senza benefici reali. Preferisci sempre il tipo più semplice che soddisfa il requisito.
Conclusione
Il campo Datetime è tra i più utili in Odoo quando serve precisione. Dalla registrazione dell’apertura di un lead al rilevamento di inizio produzione o alle timbrature del personale, compare in quasi tutti i moduli e alimenta analisi, automazioni e report.
La regola principale da ricordare è il modello di memorizzazione in UTC. Il DB conserva tutto in UTC; l’interfaccia converte per l’utente, ma qualsiasi lettura o scrittura esterna tramite API richiede gestione esplicita dei fusi orari. La maggior parte dei bug legati al tempo nasce da questa incomprensione.
Oltre a questo, usare la sintassi corretta per il default, impostare copy=False dove serve e scegliere Date quando l’ora non è necessaria manterrà il modello dati pulito e i report affidabili.
Da Dasolo offriamo supporto per implementare, personalizzare e ottimizzare Odoo in tutti i reparti. Possiamo aiutarti a progettare un modello dati corretto, aggiungere campi su misura o sviluppare un modulo Odoo completo secondo le tue esigenze. Contattaci Parliamo del tuo progetto Odoo.