Datetime Field in Odoo: Complete Developer and Business Guide

Introduction

Les dates et les horodatages sont intégrés dans presque tous les processus commerciaux. Quand cette commande a-t-elle été passée ? Quand la livraison est-elle prévue ? Quand l'employé a-t-il pointé ? Dans Odoo, le champ Datetime est la manière standard de capturer et de stocker ce type d'information.

Contrairement au champ Date, qui ne stocke qu'une date calendaire, le champ Datetime capture à la fois la date et l'heure exacte. Cette distinction est plus importante qu'il n'y paraît, surtout dans des environnements avec des utilisateurs répartis sur plusieurs fuseaux horaires ou lors du suivi d'événements à l'heure et à la minute près.

Ce guide couvre tout ce que vous devez savoir sur le champ Datetime dans Odoo : ce qu'il stocke, comment il se comporte dans le modèle de données, comment le créer et le configurer en utilisant Odoo Studio ou Python, et des exemples pratiques tirés de véritables flux de travail d'entreprise.

Qu'est-ce que le champ Datetime dans Odoo

Dans l'ORM Odoo, fields.Datetime stocke une valeur combinée de date et d'heure, jusqu'à la seconde. Au niveau de la base de données, il correspond à une colonne TIMESTAMP dans PostgreSQL. Odoo stocke toujours les valeurs Datetime en UTC en interne et les convertit au fuseau horaire local de l'utilisateur actif lors de leur affichage dans l'interface.

Du point de vue de l'utilisateur, un champ Datetime apparaît comme un sélecteur de date et d'heure combiné dans les formulaires. Il affiche un widget de calendrier à côté d'une entrée horaire. Dans les vues en liste et les rapports, la valeur est formatée selon les paramètres de langue et de fuseau horaire de l'utilisateur actif.

Voici à quoi ressemble un champ Datetime dans une définition de modèle Python :

from odoo import fields, models

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

    x_confirmed_on = fields.Datetime(
        string='Confirmé le',
        default=fields.Datetime.now,
        readonly=True,
        copy=False,
    )

Le paramètre string définit l'étiquette affichée dans l'interface. Le paramètre default remplit automatiquement le champ avec l'horodatage actuel lors de la création d'un nouvel enregistrement. Le paramètre readonly empêche l'édition manuelle, ce qui est courant pour les horodatages d'audit.

Dans Odoo Studio, ce type de champ est appelé un champ Date & Heure. Lorsqu'il est créé via Studio, il obtient automatiquement un préfixe x_studio_. Lorsqu'il est créé via du code ou l'API XML-RPC, vous définissez vous-même le nom technique.

Comment fonctionne le champ

Lorsque vous définissez un champ Datetime dans Odoo, le framework crée automatiquement la colonne de base de données correspondante lors de l'installation ou de la mise à niveau du module. Il n'est pas nécessaire d'écrire des migrations SQL à la main.

Une chose qui surprend de nombreux développeurs et utilisateurs professionnels est la façon dont Odoo gère les fuseaux horaires. La base de données stocke toujours la valeur en UTC. Lorsqu'un utilisateur à Paris fixe une heure de réunion à 15h00, Odoo enregistre 13h00 UTC dans la base de données. Un utilisateur à New York lisant le même enregistrement verra 9h00 dans son interface. L'ORM d'Odoo gère cette conversion de manière transparente en fonction du fuseau horaire configuré dans le profil de chaque utilisateur.

Attributs clés du champ

Voici les propriétés les plus importantes d'un champ Datetime dans le framework Odoo :

default : Souvent défini sur fields.Datetime.now pour remplir automatiquement avec l'horodatage UTC actuel lors de la création d'un enregistrement.
required : Rend le champ obligatoire dans les formulaires et au niveau du modèle.
readonly : Empêche l'édition manuelle dans l'interface. Commun pour les horodatages générés automatiquement.
compute: Lie un méthode Python qui calcule dynamiquement la valeur du champ à partir d'autres champs ou de la logique métier.
store: Lorsqu'il est combiné avec compute, persiste la valeur calculée dans la base de données pour une utilisation dans les recherches et les rapports.
copy: Contrôle si la valeur est dupliquée lors de la copie d'un enregistrement. Par défaut, c'est True. Réglez sur False pour les horodatages qui ne doivent pas être transférés aux duplicatas.
index: Crée un index de base de données. Utile sur les champs qui sont fréquemment utilisés dans les filtres, tels que les dates programmées sur de grandes tables.

Comment cela apparaît dans les vues

Dans les vues de formulaire, un champ Datetime s'affiche comme un sélecteur de date et d'heure combiné. Les utilisateurs cliquent pour ouvrir un calendrier et définissent l'heure directement dans le même champ. Dans les vues de liste, la valeur apparaît sous forme de chaîne formatée en fonction des paramètres de langue de l'utilisateur. Dans les vues de recherche, les champs Datetime prennent en charge des filtres de plage de dates tels que avant, après et entre une période spécifique.

Vous pouvez également associer un champ Datetime avec le widget date_range pour afficher une sélection de plage directement dans le formulaire, ce qui est utile pour la planification de fenêtres et les tâches liées au temps.

Datetime vs Date : Choisir le bon champ

Une question courante dans le développement Odoo est de savoir quand utiliser fields.Datetime par rapport à fields.Date. La règle est simple : utilisez fields.Date lorsque l'heure de la journée est sans importance, et fields.Datetime lorsque vous avez besoin de précision au niveau de l'heure ou de la minute.

Utilisez Date pour : les dates d'échéance de factures, les anniversaires, les dates d'expiration des produits, les dates de renouvellement de contrat.

Utilisez Datetime pour : les horodatages de confirmation de commande, les heures de début de réunion, les enregistrements de présence des employés, les opérations d'entrepôt programmées.

Utiliser Datetime inutilement ajoute une complexité de fuseau horaire sans réel bénéfice. En cas de doute, demandez-vous si l'heure de la journée a vraiment de l'importance pour le processus commercial que vous modélisez.

Cas d'utilisation en entreprise

Le champ Datetime apparaît dans presque tous les modules d'Odoo. Voici cinq exemples pratiques issus de véritables flux de travail commerciaux.

CRM : Suivi des activités des leads

Dans le module CRM, plusieurs champs Datetime natifs suivent quand des événements clés se sont produits. Le champ date_open enregistre quand un lead a été mis en cours. Le champ date_deadline planifie un suivi. Les responsables des ventes utilisent ces champs pour mesurer les temps de réponse, identifier les opportunités stagnantes et faire rapport sur l'activité de l'équipe. Des champs Datetime personnalisés peuvent aller plus loin, par exemple pour enregistrer quand un devis a été envoyé ou quand un appel spécifique a eu lieu.

Ventes : Horodatage de confirmation de commande

Le champ date_order sur sale.order est un champ Datetime. Il capture le moment exact où une vente a été confirmée. Cela est précieux pour faire des rapports sur l'activité de vente quotidienne ou horaire, calculer combien de temps les commandes prennent à être traitées, et auditer les changements effectués après confirmation. Filtrer les commandes de vente par ce champ est l'une des opérations de reporting les plus courantes dans n'importe quelle configuration de vente Odoo.

Inventaire : Dates de transfert programmées

Le champ scheduled_date sur stock.picking est un champ Datetime que les équipes d'entrepôt utilisent pour planifier quand une réception ou un envoi doit avoir lieu. Des actions automatisées dans Odoo peuvent déclencher des flux de travail en fonction de la façon dont cette date se compare à l'heure actuelle. Par exemple, un e-mail automatisé peut être envoyé lorsqu'une livraison a été en retard pendant un certain nombre d'heures, permettant une communication proactive avec les clients avant qu'ils ne prennent contact.

Fabrication : Heures de début et de fin de production

Les ordres de fabrication utilisent des champs Datetime pour enregistrer quand la production a commencé et quand elle a été terminée. Ces données alimentent directement la planification de la capacité, le reporting d'efficacité et l'analyse de performance. Pour les entreprises fonctionnant avec plusieurs équipes, capturer l'heure précise est essentiel pour comprendre la production réelle par rapport à la production prévue et identifier les goulets d'étranglement selon l'heure de la journée ou par opérateur.

RH : Gestion de l'assiduité et des congés

Le module d'assiduité RH utilise des champs Datetime pour enregistrer les heures d'enregistrement et de sortie des employés. Les demandes de congé s'appuient sur Datetime pour définir le début et la fin exacts d'une absence. Les calculs de paie et les règles d'heures supplémentaires dépendent souvent de ces valeurs étant précises à la minute près. Tout décalage ou horodatage manquant dans les enregistrements d'assiduité peut affecter directement les calculs de compensation, rendant la précision ici une véritable exigence commerciale plutôt qu'une préférence technique.

Créer ou personnaliser le champ Datetime

Il existe trois principales façons d'ajouter un champ Datetime à un modèle Odoo, selon votre configuration technique et si vous préférez une approche sans code ou développeur.

Utiliser Odoo Studio (sans code)

Odoo Studio est l'outil de personnalisation intégré qui vous permet d'ajouter des champs sans écrire de code. Pour ajouter un champ Datetime via Studio :

Ouvrez Odoo Studio depuis le menu principal.
Naviguez vers le formulaire où vous souhaitez ajouter le champ.
Faites glisser un champ Date & Heure depuis la barre latérale vers le formulaire.
Définissez l'étiquette, le statut requis et, éventuellement, une valeur par défaut dans le panneau des propriétés du champ.
Enregistrez et fermez Studio.

Studio crée automatiquement le champ avec un préfixe x_studio_ et l'ajoute à la vue du formulaire. Aucune migration de base de données n'est nécessaire de votre part. Odoo gère tout cela automatiquement lorsque vous enregistrez. C'est l'approche recommandée pour les utilisateurs professionnels qui ont besoin d'ajouter un horodatage à un formulaire existant sans l'intervention d'un développeur.

Utiliser Python dans un module personnalisé

Pour les développeurs construisant des modules Odoo, les champs Datetime sont définis dans des fichiers de modèle Python. C'est l'approche recommandée pour toute personnalisation qui doit être contrôlée par version et déployée sur plusieurs environnements :

from odoo import fields, models

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

    x_last_contact_date = fields.Datetime(
        string='Date du dernier contact',
        default=fields.Datetime.now,
        copy=False,
    )

Après avoir défini le champ dans le modèle, ajoutez-le au fichier XML de vue pertinent afin qu'il apparaisse dans l'interface. Odoo crée automatiquement la colonne TIMESTAMP lorsque vous installez ou mettez à jour le module. Aucune SQL manuelle n'est nécessaire.

Utiliser l'API XML-RPC

Si vous gérez les personnalisations d'Odoo de manière programmatique, par exemple dans le cadre d'un pipeline de déploiement ou d'un script de configuration à distance, vous pouvez créer des champs Datetime via 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': 'Date du dernier contact',
        'model_id': model_id,
        'ttype': 'datetime',
        'state': 'manual',
    }]
)

La valeur ttype: datetime indique à Odoo de créer un champ Datetime. La valeur state: manual indique que ce champ a été créé en dehors d'une installation de module, ce qui est le paramètre correct pour les champs créés via Studio ou l'API. C'est ainsi que Dasolo gère la création de champs à distance pour les clients dans le cadre de scripts de configuration automatisés.

Meilleures pratiques

1. Utilisez fields.Datetime.now comme référence de fonction, pas comme appel

Lors de la définition d'une valeur par défaut, écrivez default=fields.Datetime.now sans parenthèses. Si vous ajoutez des parenthèses, Python évalue la fonction une fois lorsque la classe est chargée, et chaque enregistrement créé pendant la durée du processus Odoo partagera le même horodatage figé. Sans parenthèses, Odoo appelle la fonction au moment de la création de l'enregistrement, donnant à chaque enregistrement son propre horodatage précis.

2. Définir copy=False sur les horodatages d'événements

Si un champ enregistre quand quelque chose s'est produit, comme une date de confirmation ou un horodatage d'achèvement, définissez copy=False. Lorsque les utilisateurs dupliquent un enregistrement, ces horodatages ne doivent pas être transférés de l'original. Un bon de commande dupliqué ne doit pas afficher la date de confirmation de la commande dont il a été copié. Sans ce paramètre, les données historiques deviennent silencieusement peu fiables.

3. Toujours passer UTC lors de l'écriture via l'API

Lors de la création ou de la mise à jour d'enregistrements via l'API XML-RPC, passez toujours les valeurs Datetime en UTC en utilisant le format de chaîne YYYY-MM-DD HH:MM:SS. L'API ne réalise pas de conversion de fuseau horaire lors de l'écriture. Quelle que soit la chaîne que vous passez, elle est stockée directement dans la base de données comme si elle était en UTC, donc passer une heure locale créera silencieusement une erreur de décalage qui est difficile à diagnostiquer plus tard.

4. Utilisez readonly pour les horodatages auto-générés

Les champs qui capturent quand quelque chose s'est produit doivent généralement être définis comme readonly dans l'interface. Cela empêche les utilisateurs d'ajuster manuellement les horodatages qui devraient refléter des événements système réels. S'il y a une raison légitime de permettre l'édition, contrôlez l'accès via les paramètres de sécurité au niveau des champs d'Odoo plutôt que de laisser le champ librement modifiable.

5. Choisissez Date au lieu de Datetime lorsque l'heure n'est pas nécessaire

Si un champ doit uniquement suivre une date calendaire, comme une date limite de livraison, une date de renouvellement ou une date d'échéance de facture, utilisez fields.Date. Datetime ajoute une complexité de gestion des fuseaux horaires qui ne sert à rien lorsque le composant horaire est toujours sans importance. Garder le type de champ aussi simple que le cas d'utilisation l'exige rend le modèle de données plus facile à comprendre et à maintenir.

Pièges courants

Confusion de fuseau horaire lors de la lecture des valeurs brutes

C'est la source de confusion la plus fréquente avec les champs Datetime. Lorsque vous lisez une valeur directement à partir de la base de données ou via l'API, vous voyez la valeur UTC, pas l'heure locale de l'utilisateur. De nombreux développeurs construisent des rapports ou des intégrations basés sur la sortie brute de l'API et se retrouvent avec des horodatages décalés d'une heure ou plus. Appliquez toujours la conversion de fuseau horaire côté client lors de la présentation des résultats de l'API aux utilisateurs finaux, et faites de cette étape une étape explicite dans toute intégration que vous construisez.

Écriture d'heures localisées via l'API

Si vous passez une valeur Datetime qui est déjà dans un fuseau horaire local à l'API Odoo, la base de données l'enregistrera comme si c'était UTC. Une réunion fixée à 15h00 heure de Paris, écrite comme 2026-01-01 15:00:00 à l'API, sera affichée comme 16h00 ou 17h00 pour un utilisateur à Paris, selon l'heure d'été ou d'hiver. C'est l'un de ces bugs qui n'apparaissent en production que lorsque de vrais utilisateurs dans de vrais fuseaux horaires commencent à utiliser le système.

Utilisation de default=fields.Datetime.now() avec des parenthèses

Ajouter des parenthèses au défaut est une erreur subtile mais grave. fields.Datetime.now() est évalué une fois lorsque la classe Python est chargée. Chaque enregistrement créé pendant toute la durée de vie du processus de travail Odoo partagera ce même horodatage figé. Les enregistrements sembleront corrects au départ mais casseront toute analyse basée sur les heures de création. C'est un bug silencieux qui peut prendre beaucoup de temps à repérer car les horodatages semblent exister, ils sont juste tous identiques.

Oublier copy=False sur les horodatages d'événements

Sans copy=False, un enregistrement dupliqué conserve toutes les valeurs Datetime de l'original. Une date de confirmation de commande, une heure de création de lead ou un horodatage de début de production de l'enregistrement source apparaîtront inchangés sur le nouveau. Cela contamine silencieusement les rapports historiques et rend les pistes d'audit peu fiables. C'est un petit détail de configuration qui a un impact disproportionné sur la qualité des données.

Utilisation de Datetime lorsque Date est suffisant

Choisir Datetime pour un champ comme une date d'échéance de facture ou une date d'expiration de produit ajoute une complexité inutile. Les utilisateurs voient un composant horaire dont ils n'ont pas besoin, des calculs de fuseau horaire s'exécutent à chaque affichage sans aucun avantage, et l'interface devient légèrement plus encombrante sans raison. Le bon type de champ est le plus simple qui modélise correctement l'exigence commerciale.

Conclusion

Le champ Datetime est l'un des types de champ les plus utiles dans Odoo lorsque la précision est importante. De la suivi de l'ouverture d'un lead à l'enregistrement des heures de début de production et de la présence des employés, il apparaît dans presque tous les modules du système.

La chose clé à internaliser est le modèle de stockage UTC. Tout ce qui est stocké dans la base de données est en UTC. L'interface gère automatiquement l'affichage des fuseaux horaires pour les utilisateurs, mais toute lecture ou écriture externe via l'API doit en tenir compte explicitement. La plupart des bugs liés aux fuseaux horaires dans les intégrations Odoo proviennent de ce malentendu.

Au-delà de cela, utiliser la bonne syntaxe par défaut, définir copy=False lorsque c'est approprié, et choisir Date plutôt que Datetime lorsque le temps est sans importance gardera votre modèle de données propre et vos rapports fiables.

Chez Dasolo, nous aidons les entreprises à mettre en œuvre, personnaliser et optimiser Odoo dans tous les départements. Que vous ayez besoin d'aide pour concevoir un modèle de données solide, ajouter des champs personnalisés à vos flux de travail, ou construire un module Odoo complet à partir de zéro, notre équipe est prête à vous aider. Contactez-nous et parlons de votre projet Odoo.

Champ Datetime dans Odoo : Le Guide Complet