• Created by Unknown User (ophjum1@oph.fi), last modified on Dec 05, 2017

KOSKI-dokumentaatiosivulta löytyy kuvattuna KOSKI-tiedonsiirtoprotokolla ja käytettävä JSON-schema kahdessa eri muodossa, REST-rajapintojen kuvaukset sekä esimerkkidataa. Alta löydät ohjeet sivulle pääsemiseksi ja vinkkejä siitä, miten koulutuksen järjestäjän virkailija voi hyödyntää sivun sisältöä työssään.

Löydät linkin dokumentaatiosivulle KOSKI-etusivun yläpalkista. Sivu on julkinen, ja sinne pääsee myös suoraan osoitteesta https://koski.opintopolku.fi/koski/dokumentaatio.

Dokumentaatiosivulta löytyy linkit KOSKI-tietomallin visualisoituun JSON-schemaan ja samaan schemaan printattavana dokumenttina. Schemasta löytyvät myös pakolliset kentät (visualisoidussa schemassa merkitty tähdellä).

Esimerkki: Scheman hyödyntäminen virheiden korjauksessa

Schemaa voi hyödyntää esimerkiksi tiedonsiirtovirheiden korjaamisessa.

Esimerkissä saat alla olevan virheilmoituksen peruopetuksen oppijan tietojen siirrossa. Viesti ilmoittaa, että suorituksen ensimmäisestä osasuorituksesta puuttuu jokin tieto ("koulutusmoduuli.kieli").

"message": [
      {
        "path": "opiskeluoikeudet.0.suoritukset.0.osasuoritukset.0.koulutusmoduuli.kieli",
        "error": {
          "errorType": "missingProperty"
        }
      }
    ]

Siirtodataa tarkastellessasi (katso tarvittaessa, miten päästä tarkastelemaan siirtodataa Tiedonsiirrot-sivun kohdasta "4. Virheet-välilehti) huomaat, että kyse on kieliaineesta. Voit edetä visualisoidun JSON-scheman avulla kohtaan "opiskeluoikeudet.suoritukset.osasuoritukset.koulutusmoduuli", josta huomaat että kieliaineille on oma rakenteensa.

Kun avaat rakenteen, huomaat, että opiskeltavan kieli on pakollinen tieto, sillä se on merkitty tähdellä.

Tarkastelet uudelleen siirtodataa ja huomaat, että sieltä puuttuu "kieli"-tieto. Korjaat virheen oppilashallintojärjestelmässä (eli lisäät opiskeltavan kielen) tai jos et tiedä, miten se tapahtuu, otat yhteyttä opintohallintojärjestelmätoimittajaasi.

KOSKI-palvelun tiedonsiirtorajapinnat löytyvät dokumentaatiosivun "REST-rajapinnat"-osiosta. Virkailijalle hyödyllistä tietoa sisältää esimerkiksi "PUT /koski/api/oppija"-rajapinta, jonka kuvauksesta saa "Vastaukset ja paluukoodit"-linkkiä klikkaamalla näkyviin tiedonsiirrossa tulevien vastausten sekä paluukoodien ja mahdollisten virheiden selitteet. "Esimerkkivastaus"-sarakkeesta löytyy lisäksi vastaus JSON-muodossa.

"Esimerkkidata annotoituna"-osiosta löytyy esimerkkejä onnistuneesti siirretystä datasta. Esimerkit löytyvät on jaoteltu ja otsikoitu eri koulutusmuodoittain, ja ne saa näkyviin klikkaamalla otsikoiden alta löytyviä linkkejä. Esimerkeistä löytyy JSON-sisällön lisäksi kenttien kuvaukset, joissa on tarvittaessa linkit OKSA-sanastoon ja käytettyihin koodistoihin.