Koski integraatio

Koski-integraatio eVakassa

Yleistä Koski-integraatiosta

Opetushallituksen Koski-tietovaranto sisältää valtakunnallisia perusopetuksen, lukiokoulutuksen ja ammatillisen koulutuksen opintosuoritus- ja tutkintotietoja.

Koski-palvelu on avointa lähdekoodia, katso Koski-palvelun tarkempi tekninen dokumentaatio tästä linkistä.

eVakaan on toteutettu suora integraatio Koski-tietovarantoon, jolla esiopetuksen ja perusopetukseen valmistavan opetuksen opinto-oikeustiedot ja opintosuoritukset välitetään ajastetusti.

eVakan sisältämä tieto opinto-oikeuksista voi muuttua esi- ja valmistavan opetuksen piirissä olevien lasten tilanteen mukaisesti. Lapsi voi esimerkiksi siirtyä toiseen esiopetusyksikköön kesken esiopetuskauden. eVakaan on rakennettu logiikka, joka huolehtii jo lähetettyjen tietojen päivittämisestä automaattisesti.

Integraation yleinen tekninen kuvaus

Koski-integraatio eVakassa on osa evaka-service:ä, johon on toteutettu eVakan liiketoimintalogiikka. Tiedot päivitetään eVakasta Koskeen kerran vuorokaudessa ajastetusti.

Ajastus on toteutettu eVakan sisäisellä ajastusmekanismilla, joka käynnistää yhden tausta-ajon jonka tehtävä on selvittää mitä kaikkea Koskeen pitää viedä. Jokaista lisättävää, muuttunutta, tai poistettavaa opiskeluoikeutta kohti ajastetaan heti ajettavaksi tausta-ajo, ja jokainen ajo hoitaa aina yhden opiskeluoikeuden tietojen käsittelyn ja lähettämisen. Tiedot muutetaan Kosken haluamaan muotoon (ks. tietomallien kuvaukset), jonka jälkeen ne lähetetään Koski-palvelun REST-rajapintaan.

eVakan Koski-integraatio ei käytä muutosten tunnistamiseen aikaleimoja, vaan kaikki potentiaalisesti Koskeen lähetettävä data koostetaan joka yö ja sitä verrataan viimeisimpään oikeasti lähetettyyn dataan, joka on tallennettu tietokantaan kirjanpitotauluun. Tämänkaltainen vertailu on huomattavasti raskaampaa kuin pelkkien aikaleimojen vertailu, mutta perustuu todelliseen datan sisältöön eikä siinä synny yhtä helposti bugeja jonka takia vertailun tulos olisi väärä ja dataa jäisi lähettämättä. Espoon tuotantoinstanssissa vuonna 2024 yöllinen ajo tekee tyypillisesti yhden n. 30s pitkän kyselyn, joka on raskas mutta suorituskyky on vielä hyväksyttävällä tasolla, varsinkin kun ajo tapahtuu yöllä.

Koski-integraatio on yksisuuntainen, eli se ei koskaan käy lukemassa opiskeluoikeuden nykyisiä tietoja Koskesta. Tämän takia eVaka on sokea mahdollisille muutoksille mitä Kosken puolella tehdään käyttöliittymän kautta, ja tämänkaltaisia muutoksia ei lähtökohtaisesti tulisi tehdä.

Tunnistautuminen ja palomuuriavaukset

evaka-service tunnistautuu Basic Authentication -menetelmällä Kosken tarjoamaa rajapintaa vasten. eVakan ja Kosken välinen kommunikointi tapahtuu suojatun HTTPS/TLS-yhteyden yli.

Yhteydenottoja Koski-järjestelmään ei ole rajattu palomuurilla.

Integraation tarkempi tekninen kuvaus

Koski-integraatio perustuu lähdedatan keräämiseen eVakan tietokannasta, ja tämän datan perusteella luodaan Kosken tietomallin mukaisia opiskeluoikeuksia. Integraatio voidaan jakaa karkeasti kahteen osaan: SQL-osa joka vastaa lähdedatan koostamisesta, ja Kotlin-koodin osa joka muuntaa aiemmin tietokannasta haetun datan Kosken haluamaan muotoon. Kotlin-osa ei voi hakea tietokannasta vapaasti enää dataa, vaan ajatus on että SQL-osa hakee kaiken tarvittavan valmiiksi.

Kaikki Koskeen liittyvä data eVakan tietokannassa käydään läpi joka yö, mutta Koskeen lähetetään vain opiskeluoikeudet joihin on tullut jotain muutoksia. Muutosten tunnistus perustuu ensisijaisesti lähdedatan vertailuun, joka tapahtuu suoraan SQL-kyselyissä ja vertailee isoja lähdedataobjekteja esim. aikaleimojen sijaan. Lähdedatan vertailun lisäksi tehdään vielä tuotetun Koski-datan vertailu juuri ennen lähetystä, koska kaikki lähdedatan muutokset eivät lopulta tuota muutoksia Koski-dataan ja näin voidaan välttää turhat opiskeluoikeuksien päivitykset.

Jokaisella opiskeluoikeudella eVakassa on luonnollinen uniikki tunniste joka on (lapsi-ID, yksikkö-ID, tyyppi)-kombinaatio. Yhdellä lapsella voi siis olla tasan yksi tietyntyyppinen opiskeluoikeus per yksikkö, ja toisaalta lapsi voi olla useammassa yksikössä tai samassa yksikössä voi olla erityyppisiä opiskeluoikeuksia. Mahdolliset tyypit ovat PRESCHOOL (esiopetuksen opiskeluoikeus), ja PREPARATORY (perusopetukseen valmistavan opetuksen opiskeluoikeus). Jo lähetetyillä opiskeluoikeuksilla on myös Kosken antama OID, joka kuvaa yhtä todellista Koskeen tallennettua opiskeluoikeutta.

Lähdedatan muutosten tunnistus

Lähdedatan hakua varten eVakan tietokannassa on 3 kpl "set returning function"-kokonaisuutta, joiden voidaan ajatella olevan kuin SQL-viewejä joille voi antaa parametreja. Tavallinen SQL-view ei käy, koska ajohetken päivämäärä on tärkeä parametri jota tarvitaan näiden funktioiden toteutuksissa. Yksi rivi funktion palauttamaa lähdedataa on kooste eVakan tietomallin mukaisesta datasta, jota tarvitaan yhden Kosken tietomallin mukaisen opiskeluoikeuden luontiin, ja nämä kolme funktiota käytännössä vastaavat kysymykseen "mitä Koskessa pitäisi olla". Erilaisia tapauksia on kolme kappaletta:

• koski_active_preschool_study_right: yksi rivi kuvaa yhden lapsen yhtä esiopetuksen opiskeluoikeutta yhdessä yksikössä. Lähdedata on tietokannassa koski_preschool_input_data-tyyppinen kokoelma kenttiä
• koski_active_preparatory_study_right: yksi rivi kuvaa yhden lapsen yhtä valmistavan opiskeluoikeutta yhdessä yksikössä. Lähdedata on tietokannassa koski_preparatory_input_data-tyyppinen kokoelma kenttiä
• koski_voided_study_right: yksi rivi kuvaa yhtä jo lähetettyä opiskeluoikeutta jonka pitäisi olla mitätöity. Lähdedata on käytännössä vain mitätöintipäivämäärä

Lähdedatan lisäksi tietokannassa on koski_study_right-taulu, johon tallennetaan yksi rivi jokaista lähetettyä opiskeluoikeutta kohti. Riville tallennetaan alkuperäinen lähdedata ja lopullinen Kosken tietomallin mukainen JSON, ja näitä käytetään muutosten tunnistukseen ja turhien Koski-operaatioiden vähentämiseen. Tämän taulun rivit käytännössä vastaavat kysymykseen "mitä Koskeen on viety".

Ajastettu yöllinen tausta-ajo hakee näistä kolmesta paikasta tietokannasta kaiken datan, ja vertailee sitä opiskeluoikeuskohtaisesti aiemmassa lähetyksessä käytettyyn vastaavaan dataan joka löytyy koski_study_right-taulusta. Jos näissä on ero, ajastetaan erillinen tausta-ajo joka tarkastelee tarkemmin kyseistä opiskeluoikeutta, ja hoitaa päivityksen Koskeen. Ajastettu yöllinen ajo siis ajastaa 0-N kpl tausta-ajoja, jotka tekevät varsinaisen työn ja jokainen ajo käsittelee vain yhtä opiskeluoikeutta.

Yksittäisen opiskeluoikeuden käsittely

Yksittäisen opiskeluoikeuden käsittely tapahtuu tausta-ajossa, jonka ajastettu yöllinen tausta-ajo on ajastanut. Lähdedatan muutokset tarkistetaan tämän opiskeluoikeuden tunnisteen perusteella, ja ajo keskeytyy välittömästi jos tässä vaiheessa huomataan että lähdedata onkin ajan tasalla. Jos eroja havaitaan, haetaan lähdedatan lisäksi lisädataa joka ei vaikuta vertailuun mutta sitä käytetään Koski-datan tuottamiseen. Lähdedatan ja lisädatan perusteella luodaan Kosken tietomallin mukainen opiskeluoikeus pelkästään Kotlin-toteutuksen avulla ilman uusia tietokantahakuja. Tätä Koski-dataa verrataan kirjanpitotauluun tallennettuun edellisen ajon dataan, ja ajon seuraava vaihe riippuu vertailun tuloksesta:

• jos Koski-data on sama kuin kirjanpitotaulussa, ei ole mitään lähetettävää joten kirjanpitotauluun tallennetaan muuttunut lähdedata ja ajo ei lähetä Koskeen mitään. Koska lähdedata on tämän jälkeen ajan tasalla kirjanpitotaulussa, seuraava yöllinen ajo ei enää ajasta tätä opiskeluoikeutta jos lähdedataan ei tule uusia muutoksia
• jos Koski-data on eri kuin kirjanpitotaulussa, tai kirjanpidossa ei ole tietoa edellisestä lähetyksestä, se lähetetään Koskeen. Lähetyksen jälkeen sekä lähdedata että lähetetty Koski-data tallennetaan kirjanpitotauluun, joten jatkossa sekä lähdedatan että Koski-datan vertailut estävät uudet tarpeettomat lähetykset

Nykyisen ratkaisun mahdollisesti yllättäviä yksityiskohtia

• eVakan Koski-integraatio ylläpitää Koskeen vietyä dataa koko historian ajalta, eli jos eVakan data muuttuu niin että sillä on vaikutus opiskeluoikeuteen, eVaka käy päivittämässä sen Koskeen riippumatta siitä milloin opiskeluoikeus on tai on ollut voimassa
• osa Kosken opiskeluoikeuteen päätyvästä datasta on lisädataa, jonka muuttuminen ei aiheuta yksinään opiskeluoikeuksien päivityksiä mutta se poimitaan mukaan jos muuten tehdään päivitys. Tämän takia esim. yksikön johtajan vaihtuminen ei aiheuta välittömästi kaikkien yksikön historian opiskeluoikeuksien päivitystä, mutta toisaalta jos vanhaan opiskeluoikeuteen tulee päivitys, Koski-integraatio poimii siihen yksikön uuden johtajan vaikka opiskeluoikeus olisi päättynyt jo kauan sitten
• Koski hyväksyy vain yhden aikavälin pidennetyn oppivelvollisuuden ja kuljetusedun tietoihin. eVakan tietomalli ei pakota tätä rajausta, joten Koski-integraatio etsii molempien tietojen kohdalla pisimmän yhtenäisen pätkän jossa ei ole aukkoja ja lähettää sen. Jos eVakan datassa on aukkoja, tästä seuraa että muut kuin pisimmät aikavälit eivät näy Koskessa. Integraatio voisi vaihtoehtoisesti heittää tässä tilanteessa virheen, mutta tästä seuraisi toistuvia virheitä joka yö kunnes tuen tarpeen tietojen syöttäjä käy korjaamassa merkinnät eVakaan