Odoo Datetime Field — Täydellinen Opas Kehittäjille ja Käyttäjille

Johdanto

Päivämäärät ja aikaleimat kulkevat mukana jokapäiväisessä liiketoiminnassa: milloin tilaus tehtiin, mihin aikaan toimitus on sovittu tai milloin työntekijä kirjasi saapumisensa. Odoossa tätä tietoa tallennetaan ja käsitellään vakiokenttänä, jonka avulla kartoitetaan tapahtumien hetket tarkasti ja jäljitettävästi.

Toisin kuin pelkkä päivämääräkenttä, joka kertoo vain kalenteripäivän, aikaleima-kenttä tallentaa myös tunnin ja minuutin. Tämä erotus on merkittävä erityisesti, kun käyttäjiä on eri aikavyöhykkeillä tai kun tapahtumia seurataan minuutin tarkkuudella— silloin pelkkä päivämäärä ei riitä.

Tässä oppaassa käydään läpi keskeiset asiat Odoon aikaleima-kentästä: mitä se tallentaa, miten se käyttäytyy tietomallissa, miten se luodaan Studio-työkalulla tai Pythonilla sekä käytännön esimerkkejä yrityskäytöstä.

Mikä on Odoon Päivämäärä-aikaleima-kenttä

Odoon ORM:ssä fields.Datetime tallentaa päivämäärän ja kellonajan sekunnin tarkkuudella. Tietokantatasolla se vastaa PostgreSQL:n TIMESTAMP-saraketta. Odoo säilyttää arvot sisäisesti UTC-ajassa ja muuntaa ne käyttäjän valitsemaan paikallisaikaan käyttöliittymässä.

Käyttäjän näkökulmasta aikaleima-kenttä näkyy lomakkeessa yhdistettynä päivämäärän ja ajan valitsimeen: kalenterivalikko ja kellonaika samassa kentässä. Listanäkymissä ja raporteissa arvot muotoillaan aktiivisen käyttäjän kieli- ja aikavyöhykeasetusten mukaan.

Alla on esimerkinomainen tapa määritellä aikaleima-kenttä Python-mallissa:

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,
    )

Kentän string-asetus määrittää käyttöliittymän otsikon. default täyttää kentän automaattisesti luontihetken aikaleimalla. readonly estää käsin tehtävät muutokset, mikä on tyypillinen valinta esimerkiksi auditointi-merkinnöille.

Odoo Studion puolella vastaava kenttä näkyy nimellä Date & Time. Studion kautta luotu kenttä saa automaattisesti x_studio_-alkuisen teknisen nimen. Kun kenttä luodaan koodilla tai API:n kautta, määrittelet teknisen nimen itse.

Miten kenttä toimii

Kun määrittelet aikaleima-kentän moduulissa, Odoo luo vastaavan tietokantasarakkeen asennuksen tai päivityksen yhteydessä automaattisesti. Sinun ei yleensä tarvitse kirjoittaa erillisiä SQL-migraatioita.

Yksi usein yllätyksenä tuleva asia kehittäjille ja liiketoiminnan käyttäjille on aikavyöhykkeiden käsittely. Tietokantaan tallennetaan aina UTC-arvo. Kun käyttäjä Pariisissa asettaa kokouksen kello 15:00, tietokantaan tallennetaan 13:00 UTC. Sama tietue näkyy New Yorkin käyttäjälle omassa käyttöliittymässään kello 9:00. ORM hoitaa nämä muunnokset automaattisesti käyttäjäkohtaisen aikavyöhykkeen perusteella.

Tärkeimmät kenttäominaisuudet

Seuraavat attribuutit ovat merkityksellisimpiä aikaleima-kentän kanssa työskennellessä:

• default: Tavallisesti asetetaan arvoon fields.Datetime.now, jolloin kenttä täyttyy luotaessa nykyisellä UTC-aikaleimalla.
• required: Määrittää kentän pakolliseksi lomakkeissa ja mallin tasolla.
• readonly: Estää käsin tehtävät muutokset käyttöliittymässä. Tyypillistä automaattisesti generoituilla aikaleimoilla.
• compute: Liittää Python-menetelmän, joka laskee kentän arvon dynaamisesti muiden kenttien tai liiketoimintalogiikan perusteella.
• store: Yhdistettynä compute-asetukseen tallentaa lasketun arvon tietokantaan, mikä mahdollistaa haku- ja raportointikäytön.
• copy: Ohjaa, kopioidaanko arvo kun tietuetta kopioidaan. Oletus on True; aseta False tapahtuma-aikaleimoille, joita ei pidä siirtää kopioihin.
• index: Luo tietokantaindeksin. Hyödyllinen kentissä, joita käytetään usein suodattimissa, esimerkiksi aikataulutetuissa tapahtumissa suurilla tauluilla.

Miten kenttä näkyy näkymissä

Lomakenäkymissä aikaleima näyttää kalenterin ja kellonajan samassa valitsimessa. Käyttäjä avaa kalenterin ja asettaa ajan samassa kentässä. Listanäkymissä arvo näkyy kieliasetusten mukaisena merkkijonona. Hakunäkymissä kenttä tukee aikavälihaut kuten ennen, jälkeen ja välillä.

Voit myös käyttää date_range-widgettiä, jolloin lomakkeeseen saa suoran valinnan aikavälille — kätevä aikatauluikkunoiden ja tehtävien aikarajojen hallintaan.

Päivä vs. Aikaleima: kumpi valita?

Usein kysytään, milloin käyttää fields.Datetime-tyyppiä ja milloin riittää fields.Date. Yksinkertainen sääntö: valitse Date kun kellonaika ei ole olennainen, ja Datetime kun tarvitset tunti- tai minuutintarkkuutta.

Käytä Date-kenttää esimerkiksi laskun eräpäivissä, syntymäpäivissä, tuotteen viimeisessä käyttöpäivässä tai sopimuksen uusimispäivissä.

Käytä Datetime-kenttää esimerkiksi tilauksen vahvistusajassa, kokouksen alkamisaikoina, työntekijän leimausajoissa tai varaston suunnitelluissa toiminnoissa.

Tarpeetonta aikaleimaa kannattaa välttää: se tuo mukanaan aikavyöhykeongelmat ilman hyötyä. Kysy aina, onko kellonaika oikeasti olennainen prosessin kannalta.

Liiketoiminnan käyttötapaukset

Aikaleima-kenttä löytyy lähes jokaisesta Odoon moduulista. Tässä viisi käytännön esimerkkiä liiketoimintaprosesseista.

CRM: liidien toimintojen seuranta

CRM:ssä useat aikaleimat kertovat tapahtumien ajankohdista. Esimerkiksi date_open voi kertoa milloin liidi siirrettiin käynnissä-tilaan ja date_deadline seuraa seuraavan toimenpiteen määräaikaa. Myynnissä nämä kentät auttavat mitattaessa vasteaikoja, tunnistettaessa vanhoja mahdollisuuksia ja raportoitaessa tiimin aktiivisuutta. Räätälöidyt aikaleimat voivat säilöä esimerkiksi tarjouksen lähetyshetken tai tietyn puhelun ajankohdan.

Myynti: tilauksen vahvistusajankohdat

date_order myyntitilauksissa on aikaleima, joka tallentaa tarkan hetken jolloin myynti vahvistettiin. Tämä tieto on tärkeää tunti- ja päiväkohtaisessa raportoinnissa, läpimenoaikojen laskennassa ja jäljitettävyydessä. Myyntitilauksia suodatetaan usein juuri tämän kentän perusteella.

Varasto: suunnitellut nouto- ja lähetysajat

Varaston scheduled_date-kenttä kertoo milloin vastaanotto tai lähetys on ajoitettu. Automaatiot voivat laukaista toimenpiteitä, kun suunniteltu aika ylittyy tai lähestyy — esimerkiksi lähetetään automaattinen muistutus asiakkaalle, jos toimitus on myöhässä tietyn tuntimäärän.

Valmistus: tuotannon aloitus- ja päättymisajat

Valmistusjärjestelmissä aikaleimat kertovat, milloin tuotanto on alkanut ja päättynyt. Tämä tieto on olennaista kapasiteetin suunnittelussa, tehokkuusanalyysissä ja pullonkaulojen tunnistamisessa, erityisesti jos tehdään useita vuoroja päivän aikana.

Henkilöstöhallinto: leimaukset ja poissaolot

HR Attendance käyttää aikaleimoja työntekijöiden check-in ja check-out -kirjauksiin. Myös poissaolot määritellään usein ajoittain, jolloin palkanlaskenta ja ylityöt lasketaan minuuttien tarkkuudella. Puuttuvat tai vääristyneet aikaleimat voivat suoraan vaikuttaa palkanlaskennan oikeellisuuteen, joten tarkkuus on liiketoiminnallinen vaatimus.

Kentän luominen tai muokkaaminen

Aikaleima-kentän voi lisätä Odoo-malliin kolmella pääasiallisella tavalla riippuen teknisestä ympäristöstä ja mieltymyksestä no-code vs. koodipohjaiseen lähestymiseen.

Odoo Studio (kooditon vaihtoehto)

Odoo Studio on sisäänrakennettu työkalu, jolla kenttiä voi lisätä ilman koodia. Aikaleima-kentän lisääminen Studiolla onnistuu muutamalla klikkauksella:

1. Avaa Odoo Studio päävalikosta.
2. Siirry lomakkeeseen, johon haluat lisätä kentän.
3. Vedä sivupalkista Date & Time-kenttä lomakkeeseen.
4. Aseta kentän otsikko, pakollisuus ja tarvittaessa oletusarvo kenttäominaisuuksista.
5. Tallenna ja sulje Studio.

Studio luo kentän automaattisesti x_studio_-prefiksillä ja lisää sen lomakkeeseen. Tietokantaan tehtävät muutokset hoitaa Odoo taustalla — mitään erillistä migraatiota ei tarvita. Tämä on suositeltava tapa liiketoiminnan käyttäjille, jotka haluavat lisätä aikaleiman ilman kehittäjäapua.

Pythonilla omassa moduulissa

Kehittäjille, jotka rakentavat moduuleja versionhallinnassa, aikaleima-kenttä määritellään Python-malleissa. Tämä tapa on suositeltava, kun halutaan hallittuja muutoksia ja helppo käyttöönotto eri ympäristöihin:

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,
    )

Kun kenttä on määritelty mallissa, lisää se näkymä-XML:ään, jotta se näkyy käyttöliittymässä. Odoo luo tietokantasarakkeen asennuksen tai päivityksen yhteydessä — manuaalista SQL:ää ei yleensä tarvita.

XML-RPC API:n kautta

Jos hallinnoit Odoo-muutoksia ohjelmallisesti esimerkiksi deployment-skripteissä, voit luoda kenttiä myös XML-RPC API:n kautta:

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',
    }]
)

ttype: 'datetime' kertoo Odoolle, että kenttä on aikaleima-tyyppinen. state: 'manual' tarkoittaa, että kenttä on luotu ohjelmallisesti moduulin ulkopuolella — oikea valinta Studio- tai API-luoduille kentille. Tämä on käytäntö esimerkiksi automatisoiduissa konfiguraatioskripteissä.

Parhaat käytännöt

1. Käytä fields.Datetime.now funktioreferenssinä, älä kutsua sitä

Kun asetat oletusarvon, kirjoita default=fields.Datetime.now ilman sulkeita. Jos lisäät sulkeet, funktio arvioituu kerran luokan lataushetkellä ja kaikki myöhemmät tietueet saavat saman, väärän aikaleiman. Ilman sulkeita Odoo kutsuu funktiota aina tietuetta luotaessa.

2. Aseta copy=False tapahtuma-aikaleimoille

Jos kenttä tallentaa tapahtumahetken (esim. vahvistusaika tai valmistuksen päättymisajankohta), aseta copy=False. Kun käyttäjä kopioi tietueen, tällaisia aikaleimoja ei yleensä haluta siirtää uuteen kopioon — niiden pitäisi kuvata uuden tietueen omia tapahtumia.

3. Kirjoita aina UTC-aikaa API:n kautta

Kun luot tai päivität tietueita XML-RPC API:lla, lähetä aikaleimat UTC-muodossa YYYY-MM-DD HH:MM:SS. API ei tee aikavyöhykemuunnoksia kirjoitusvaiheessa, joten paikallisaika tallennettuna sellaisenaan johtaa hiljaiseen siirtymään väärään aikaan.

4. Käytä readonly-asetusta automaattisesti generoituissa aikaleimoissa

Aikaleimojen, jotka kertovat järjestelmän tapahtumista, tulisi yleensä olla readonly-kenttiä. Tämä estää käyttäjiä muokkaamasta järjestelmän generoimia aikoja. Jos muokkaus on sallittava, hallitse sitä roolipohjaisen käyttöoikeuden avulla, älä jätä kenttää vapaasti muokattavaksi.

5. Valitse Date kun kellonaika ei ole tarpeen

Jos riittää seurata vain kalenteripäivää — esimerkiksi toimituksen viimeinen päivä tai laskun eräpäivä — käytä fields.Date-tyyppiä. Aikaleima lisää turhaa aikavyöhykekäsittelyä ja monimutkaisuutta ilman hyötyä.

Yleisimmät sudenkuopat

Aikavyöhykehämmennys raakadataa lukiessa

Usein ongelmia syntyy, kun luetaan arvoja suoraan tietokannasta tai API:n kautta: näytölle tulostuu UTC-arvo, ei käyttäjän paikallisaika. Integraatiot ja raportit, jotka käyttävät raakadatasta muodostettuja aikaleimoja, päätyvät usein tunteja vääriin aikoihin. Muunna aikaleimat aina asiakkaan tai käyttöliittymän aikavyöhykkeeksi ennen esittämistä.

Paikallisten aikojen kirjoittaminen API:lla

Jos lähetät API:lle paikallisaikaisen merkkijonon, se tallennetaan tietokantaan sellaisenaan UTC:nä. Esimerkiksi Pariisin 15:00 tallennettuna ilman muunnosta voi näkyä vääränä kellonaikana kesä-/talviaikojen vaihtelun vuoksi. Tällaiset virheet ilmenevät usein vasta tuotannossa, kun todelliset käyttäjät eri aikavyöhykkeillä käyttävät järjestelmää.

default=fields.Datetime.now() -sulkeiden käyttäminen

Oletusarvon asettaminen funktiokutsulla (sulkeilla) on yleinen mutta vakava virhe. fields.Datetime.now() arvioidaan vain kerran luokan latautuessa, ja kaikki myöhemmät tietueet saavat saman aikaleiman. Tämä tuottaa hiljaisen virheen, jossa aikaleimoja kyllä on, mutta ne eivät eroa toisistaan.

copy=False unohtaminen tapahtuma-aikaleimoissa

Jos copy=False jätetään pois, kopioitu tietue perii kaikki aikaleimat alkuperäiseltä. Tämä saattaa saastuttaa raportit ja heikentää auditointia, koska uuden tietueen historiatiedot näyttävät virheellisesti vanhan tapahtuman ajat.

Datetime-tyypin valinta, kun Date riittäisi

Aikaleiman käyttäminen esimerkiksi laskun eräpäivän kanssa lisää tarpeetonta monimutkaisuutta: käyttäjät näkevät ajan, jota he eivät tarvitse, ja järjestelmä suorittaa ylimääräisiä aikavyöhykemuunnoksia. Pidä mallin rakenne mahdollisimman yksinkertaisena vaatimuksen mukaisesti.

Yhteenveto

Aikaleima-kenttä on yksi käytännöllisimmistä kenttätyypeistä Odoossa silloin kun tarkka ajankohta on olennaista. Se esiintyy lähes kaikissa moduuleissa liidien avaamisesta tuotannon aikamerkintöihin ja läsnäolon seurantaan.

Keskeisin opetus on ymmärtää UTC-tallennusmalli: tietokantaan tallennetaan aina UTC, ja käyttöliittymä hoitaa näyttömuunnokset. Suurin osa aikavyöhykkeet liittyvistä virheistä syntyy, kun tätä perusperiaatetta ei huomioida integraatioissa tai API-kutsujen käsittelyssä.

Lisäksi oikean oletussyntaksin käyttäminen, copy=False-asetuksen käyttö tarvittaessa ja Date-tyypin valinta kun aika ei ole olennainen, pitävät tietomallin siistinä ja raportit luotettavina.

Me Dasololla autamme yrityksiä ottamaan Odoon haltuun, räätälöimään kenttiä ja optimoimaan järjestelmää eri toiminnoissa. Autamme mielellämme suunnittelemaan selkeän tietomallin, lisäämään tarvittavia kenttiä tai rakentamaan kokonaisen moduulin alusta loppuun. Ota yhteyttä kertakaamme läpi Odoo-projektisi tarpeet ja tehdään siitä toimiva ratkaisu yhdessä.