Aromi ruokatilausintegraatio - espoon-voltti/evaka GitHub Wiki

Yleiskuvaus

eVakan Aromi-integraatio on ruokapalveluintegraatio, jonka tavoitteena on toimittaa eVakassa merkittyjen ryhmien lasten läsnäoloennuste seuraavalle kolmelle viikolle Aromi-järjestelmän käyttöön. Erityisen huomattavaa Aromi-integraatiossa on, ettei eVaka itse hallinnoi tai käsittele erityisruokavalioita tai yksiköiden ruokailuaikoja, eikä muodosta suoraan varsinaisia ruokatilauksia.

eVakan puolen integraation tehtävänä on toimittaa Aromille eVakan tilannekuva siitä, ketkä ovat paikalla ja mihin aikoihin päivästä ennustejaksolla. Ennusteita toimitetaan päivittäin, jotta eVakan jatkuvasti kehittyvä ja tarkentuva tieto läsnäoloista saataisiin päivitettyä vierivästi Aromin käyttöön aina siihen asti, kun ruokatilaukset on lyötävä lukkoon. Käytännössä kolmen viikon toimitusjakso ei kata lähetyspäivää seuraavaa kolmea vuorokautta, sillä ennusteen muutokset eivät enää ehtisi vaikuttaa ruokatilauksen muodostumiseen. Näin ollen toiminnallinen ennustejakso on käytännössä 18 päivää ja ulottuu 21 päivän päähän toimituspäivästä.

Aromin vastaanottava pää lukee lähetetyt läsnäolotiedot sisään järjestelmään, jonka jälkeen suoritettava erillinen ajo muodostaa näistä varsinaisia ruokatilauksia. Nämä tilaukset ovat nähtävissä ja myös muokattavissa yksiköiden omista ruokatilauskäyttöliittymistään Aromissa.

Tekninen toiminta

Valmistavat toimenpiteet

Vastuuyksikkökoodi

Aromi-ruokapalvelun piirissä toimivat eVakan ryhmät merkitään Aromista toimitetuilla vastuuyksikkökoodeilla. Tämä mahdollistaa tarkemman ruoan toimituspaikan jäsentelyn Aromin puolella eVakan ryhmän lapsille. Vastuuyksikkökoodi toimii myös läsnäoloennusteen poiminnan peruskriteerinä. Ennustetta laadittaessa tarkastellaan kaikkia lapsia, joilla on ryhmä- tai varasijoitus johonkin ryhmään, jolle on asetettu vastuuyksikkökoodi. Koodien syöttäminen tehdään pääkäyttäjäyhteistyönä manuaalisesti eVakan käyttöliittymän kautta. Syötetystä vastuuyksikkökoodin alusta ja lopusta poistetaan tallennuksen yhteydessä ylimääräiset välilyönnit arvojen syöttämisen vikasietoisuuden parantamiseksi.

Erikoisruokavaliolasten yhdistäminen eVaka tunnuksella

Koska erikoisruokavaliotietoja ei käsitellä eVakan puolella, tulee erikoisruokavaliota noudattavien lasten eVaka-tunnisteet yhdistää Aromin omiin ruokailijatunnisteisiin etukäteen. Tämä tapahtuu manuaalisesti järjestelmien pääkäyttäjien välisenä kommunikaationa, ja mahdolliset muutokset vaativat myös manuaalisia jatkotoimia uusien lasten tietojen yhdistämiseksi. Käytännössä Aromista on saatu erikoisruokavaliolasten lista, joka sisältää lapsen nimet, syntymäajan ja ruokailijatunnuksen. Tähän listaan on täydennetty nimen ja syntymäajan perusteella haettu lapsen eVaka-tunniste. Lapsen eVaka-tunniste lähetetään läsnäoloa vastaavalla CSV-rivillä yhdistämään lapsi mahdolliseen erikoisruokavalioon.

Rajapinta

CSV-tiedosto

CSV-tiedoston rivi vastaa lapsen päiväkohtaista läsnäolojaksoa jossakin vastuuyksikkökoodilla merkityssä ryhmässä. CSV-tiedostolla toimitetaan ainoastaan läsnäolorivejä ja poissaolo tarkoittaa vain rivin puuttumista aineistosta. Kaikki järjestelmän läsnäolot toimitetaan samassa CSV-tiedostossa. Mikäli läsnäolotietojen keräys ei tuota yhtään osumaa, ajo keskeytetään, eikä CSV-tiedostoa luoda.

Vastaanottava pää lukee CSV-tiedoston läpi ja päivittää Aromin paikallaolojaksoja löytämiensä rivien mukaan. Tämä tarkoittaa siis sitä, että muutosten välittymiseksi tulee muutosta koskevalle päivälle olla vähintään yksi rivi. Aromin päivitysten eheys siis vaatii, että jokaisen aineiston sisältämän päivän tilannekuva on ilmoitettu kokonaisena. Aromin minkään päivän paikallaolotietoja ei näin ollen esimerkiksi voi kokonaan poistaa eVaka-integraation välityksellä. Lähetetty tyhjä aineisto tuottaa virheen myös vastaanottopäässä.

CSV-tiedoston formaatti:

  • merkistö: ISO_8859_1
  • rivinvaihto: CRLF
  • erotinmerkki: ;
  • ei otsikkoriviä, kenttien järjestyksellä merkitystä

CSV:n kentät ja mahdolliset kiinteät arvot:

  • kiinteä tietuetunnus: PKPOT
  • kiinteä ympäristötunnus: EVAKA
  • vastuuyksikkökoodi = ryhmäkohtainen Aromin asiakkuustunniste
  • hoitoontuloaika
    • datetime formaatissa: yyyyMMddHHmm
  • huone, ei käytössä
  • sukunimi
  • etunimi
  • syntymäaika
    • hetu-formaatti: ddMMyy + vuosisatamerkki
  • ikä
    • formaatissa yyy,mm etunollilla
  • ruokailijatunnus = lapsen UUID eVakassa
  • projekti, ei käytössä
  • tyhjää, ei käytössä
  • tyhjää, ei käytössä
  • informaatio lähettävästä järjestelmästä, tyhjää, ei käytössä
  • päiväkotiryhmä = eVakan ryhmän nimi
  • toimituspisteen nimi = eVakan ryhmän nimi
  • hoidosta lähdön kellonaika
    • formaatissa HH:mm

Läsnäoloennusteen muodostaminen

eVakan ajastettu ajo sendAromiOrders käynnistää läsnäolotietojen keräämisen CSV-tiedoston muodostamista varten. Läsnäolojen kerääminen tehdään aina jollekin ulkoapäin ilmoitetulle ajanjaksolle. Oletuksena ajastetun ajon ajanjakso on [(keräyspäivä + 3), (keräyspäivä + 21)], mutta kuitenkin niin, että jakson alkupäivä on aikaisintaan 19.5.2025. Mikäli tällä logiikalla ei saada pääteltyä ehjää keräysjaksoa, ajo keskeytetään.

Läsnäolotietoja kerätään käyttäen samoja perusteita, kuin eVakan muissakin läsnäoloa ennustavissa raporteissa ja integraatioissa, mutta koodipohja ja keräyslogiikka on irrallaan muusta toiminnallisuudesta. Kerääminen tarkistaa jokaisen jakson päivän vastuuyksikkökoodillisten ryhmien paikallaolevat lapset ja muodostaa kunkin lapsen päivittäisestä läsnäolojaksosta uuden rivin CSV-tiedostoon.

Rivi syntyy ensisijaisesti eVakasta löytyvästä varauksesta sen keston mukaisesti, mutta myös toissijaisesti oletettavan läsnäolon tapauksessa joko koko päivän mitalle, mikäli lapsella on vuorhoitoon oikeuttava palveluntarve tai aikavälille 00:00 - 17:00, jos vuorohoitoon ei ole oikeutusta. Lapsi oletetaan läsnäolevaksi, mikäli (vara)sijoitusyksikkö järjestää kyseisenä päivänä lapsen palveluntarpeen mukaista toimintaa, eikä lapsi ole merkitty poissaolevaksi. Epäjatkuvan varauksen tilanteessa muodostetaan kullekin jakson osalle oma rivinsä.

Poikkeuksena varauksen mukaisille ajoille, lapsen lisätietoissa olevan Syö aamiaista -merkinnän ollessa negatiivinen, lapsen varauksista poistetaan ennen klo 10:00:ä olevat osat. Näin ehkäistään turhien aamiaisten tilaaminen lapsille, joille aamiaistarve on kytketty pois päältä. Huomattavaa on, että tästä merkinnästä johtuen esim. 07:00 - 10:00 läsnäolevaksi merkitty lapsi muokataan aamiaisperusteella poissaolevaksi Aromi-integraation aineistoon, sillä tällä ei ole lainkaan ruokatilaustarvetta.

Vastaanottava pää ei käsittele tyhjiä aineistoja, joten mikäli eVakan ennusteeseen ei synny yhtään riviä, keskeytetään ajo ennen CSV:n muodostusta.

Läsnäolotietojen keruun toiminnan testaamiseksi, eVakan Lapsikohtaiset läsnäoloajat -raporttiin on pääkäyttäjäroolille lisätty mahdollisuus ladata myös Aromi-integraation keräämä raportin päivämäärävalinnan mukainen CSV-tiedosto. Raportin lataus on näkyvillä mikäli aromiIntegration feature flag on aktiivinen.

Tiedonsiirto

Rajapinnan tiedonsiirto toimii SFTP-yhteyden kautta. eVaka muodostaa kerätyistä lasten läsnäolotiedoista yhden CSV-tiedoston ja toimittaa sen ympäristöasetuksissa määriteltyyn SFTP-osoitteeseen ajastetun ajon aikana. Perustilanteessa kukin CSV-tiedoston rivi vastaa yhden lapsen läsnäoloa yhtenä päivänä, mutta eVakan epäjatkuvia varauksia voidaan myös ilmoittaa kahtena erillisenä rivinä, jolloin Aromiin muodostuu kahdesta jaksosta koostuva paikallolotieto.

Muodostunut tiedosto nimetään asetuksiin kirjatun nimeämiskäytänteen mukaisesti, ja siirretään asetusten mukaiselle SFTP-palvelimelle. Siirron hoitaa eVakan SFTP-client.

Ajoitukset ja tausta-ajot

Päivittäisiä toimituksia hallinnoiva ajastettu ajo sendAromiOrders toimii oletuksena ajastuksella JobSchedule.daily(LocalTime.of(0, 15))

Asetukset

Käyttöliittymän feature flagit:

  • aromiIntegration - kontrolloi:
    • vastuuyksikkökoodien näkyvyyttä ryhmille
    • vastuuyksikkökoodin näkymistä raakaraportilla
    • Lapsikohtaiset läsnäoloajat -raportin Aromi-CSV:n testausmahdollisuutta

Ympäristömuuttujat / Spring propertyt:

  • evaka.integration.aromi.enabled - ajastetun toiminnallisuuden kytkin
  • evaka.integration.aromi.file_pattern - CSV-tiedoston nimeämismalli kohteessa (esim. "'upload/EVAKA'ddMMyyyy'.csv'")
  • evaka.integration.aromi.sftp.host - SFTP host
  • evaka.integration.aromi.sftp.host_keys - SFTP hostin julkiset avaimet
  • evaka.integration.aromi.sftp.username - SFTP käyttäjänimi
  • evaka.integration.aromi.sftp.password - SFTP salasana