Arvo-API v. 2.0 kuvaukset

Arvo-API v. 2.0 -rajapintakokonaisuus on käytössä ammatillisen koulutuksen järjestäjillä. Ammattikorkeakoulut ja yliopistot käyttävät Arvo-API v. 1.0 -rajapintakokonaisuutta. Arvo-API v. 2.0 on käyttöönotettavissa myös yliopistoilla ja ammattikorkeakouluilla.

Alla olevaan taulukkoon on koottu Arvo-API v. 2.0 -rajapintojen kuvaukset. Tiedonkeruiden sisältöön kannattaa tutustua myös yhdessä oman organisaation Arvo-vastuukäyttäjän kanssa.

Tutustu myös Arvon rajapintojen Swaggeriin: https://arvo.csc.fi/api-docs/index.html#/export-v2

Myös seuraavat linkit saattavat antaa vastauksia kysymyksiin tietosisältöön liittyen:

• Keskeisiä käsitteitä
• Tiedonkeruulomakkeen rakenne ja sisällöt: Tiedonkeruulomakkeen sisältö 
• Eri kysymystyypit ja asteikot: Kysymysryhmän luominen ja muokkaaminen#Kysymystyypit
• Tiedonkeruiden sisällöt (mm. kysymykset, rakenne):
  • ammatillisen opiskelijapalautteet: Kyselyiden sisältö (ammatillisen opiskelijapalautteet)
  • ammatillisen työelämäpalaute: Kyselyt
• Arvon rajapintojen käyttöönotto ammatillisilla koulutuksen järjestäjillä
• Arvon yksinkertaistettu tietomalli löytyy palvelukortilta: Palvelukortti 

Arvo-API v. 2.0 käyttö

Arvo-API v. 2.0 -rajapinnat ovat käytössä ammatillisen koulutuksen palautetiedonkeruissa: 

• opiskelijapalaute: Ammatillisen opiskelijapalaute
• työelämäpalaute: Työelämäpalaute
  

Yleisiä huomioita

• rajapinnoissa päivämäärät ja kellonajat on ilmoitettu UTC-aikaleimoilla, aikaleiman mukana on aikavyöhyke, esim. 31.07.2023 15.04.23 UTC + 00
  • kukin rajapintakäyttäjä voi vaihtaa omaan raportointiinsa käyttöön tarvitsemansa aikavyöhykkeen
    • Suomen aikaa käyttäessä huomioitava kesä- ja talviaika
• työelämäpalautteiden työpaikkaohjaajakyselyssä on toteutettu sekä niputettujen tunnusten että koko datan nouto
  
  • oletuksena tunnukset annetaan rajapinnoista niputettuna
  • uusia nippuja rajapintojen kautta on mahdollista saada 2 viikon välein
  • kun haetaan työpaikkakyselyiden datoja, jaksot yhdistetään työpaikkakyselyn tunnukseen ja tämän pohjalta saadaan lista jaksoista ja listan pohjalta työpaikkajaksojen kesto
• Huomioi rajapintojen kautta tulevien datojen laatu, uusimpien tiedonkeruiden laatu on parempi kuin tiedonkeruun alkuaikoina
• Rajapintahaut on tarkoitus tehdä kuormituksen välttämiseksi kullekin koulutuksen järjestäjälle annettuna kellonaikana, ks. sivu Arvo-API:n porrastettu käyttöönotto.
• Palvelunestohyökkäyksiä ja muuta häirintää varten hakujen määrä on rajoitettu IP-osoitekohtaisesti 100 hakuun/minuutti. Määrän ylittäminen estää pyynnöt 10 minuutin ajaksi. Kun haet ensimmäisen kerran datoja, lataa kaikki ja sen jälkeen  korkeintaan kerran päivässä uudet datat. Kun uusi tiedonkeruu alkaa, lataa tällöin ensimmäisen kerran kaikki ja sen jälkeen vain uudet datat.

Arvo-API v. 2.0:

Esimerkkikutsu

curl -X 'GET' \
  'https://arvo-dev.csc.fi/api/export/v2/tiedonkeruut' \
  -H 'accept: application/json' \
  -H 'API-Key: oma-apiavain'

Lokalisoitu teksti

Objekti joka sisältää tekstin kieliversiot, esim:

Sivutus

Sivutettujen rajapintojen tiedot palautetaan Pagination-objektissa

next_url-kentässä oleva seuraavan sivun pyyntö sisältää parametrit: 

Tiedonkeruut (/api/export/v2/tiedonkeruut)

Sisältää valtakunnallisten tiedonkeruiden perustiedot. Vanhimpiin kyselyihin tieto tiedonkeruusta on lisätty jälkikäteen, tämän vuoksi tiedoissa voi olla puutteita.

Palauttaa listan koulutuksen järjestäjän tiedonkeruita (1/kysely/vuosi)

Parametrit

Tietosisältö

Kysely (/api/export/v2/kyselyt)

Kyselyt-rajapinta tarjoaa koulutuksen järjestäjän version valtakunnallisesta tiedonkeruusta, rajapinta sisältää valtakunnallisten kysymysten lisäksi omat kysymykset ja muokatut johdantotekstit sekä uudelleenohjauslinkin.

Palauttaa listan kyselyitä, tiedonkeruun tunnisteella tai kyselyid:llä rajattuna useimmissa tapauksissa aina yhden.

Parametrit

Tietosisältö

Kysely sisältää koko kyselylomakkeen hierarkisena dokumenttina (kysely->kysymysryhmät->kysymykset->monivalintavaihtoehdot)

ISO-date

Kysymysryhmä

Kysymys

Kyselyn kysymys tai väittämä

Jatkokysymys

Monivalintavaihtoehto

Kysymyksen metatiedot

Vastaajatunnukset (/api/export/v2/vastaajatunnukset)

Tiedonkeruuseen/kyselyyn luodut vastaajatunnukset

Parametrit

Tietosisältö

Taustatiedot

Kohteet-rajapinnan kautta haettavat taustatiedot ovat vastaajatunnuksen luomisvaiheessa tunnukselle asetettuja taustatietoja ja ne haetaan tietovarastosta järjestelmän kautta luotaville tunnuksille. Ne eivät sisällä vastaajan antamia taustatietoja. Koodimuotoiset taustatiedot annetaan koodiarvoina, jotka pitää itse yhdistää Opetushallituksen Koodistopalvelusta saataviin selitteisiin, ks. Koodistopalvelu (vanha palvelukortti).

Oidit ja oppilaitoskoodiin liittyvät tiedot löytyvät Opintopolun Organisaatiopalvelusta ja muut edellä mainitusta Koodistopalvelusta. Näiden rajapinnat ovat julkisia, mutta käyttöä varten tarvitsee luoda Caller-ID, ks. Opintopolun ohjesivut Organisaatiopalvelu (vanha palvelukortti) ja Kutsujan tunnisteen (caller-id) lisääminen rajapintakutsuihin.

[{"tutkinnon_osa": String(koodiarvo),
  "osaamisen_hankkimistavat": [String(koodiarvo)],
  "oppisopimuksen_perustat": [String(koodiarvo)],
  "paikallinen_tutkinnon_osa": Boolean,
  "paikallinen_tutkinnon_osa_nimi": String }]

tutkinnon_osa: Opintopolun tutkinnonosat-koodiston koodi
osaamisen_hankkimistavat: oppisopimus, koulutussopimus, oppilaitosmuotoinenkoulutus
oppisopimuksen_perustat: 01 = työ-, virka- tai palvelussuhde , 02 = yrittäjä
paikallinen_tutkinnon_osa: onko kyseessä paikallinen tutkinnon osa
paikallinen_tutkinnon_osa_nimi: koulutuksenjärjestäjäkohtainen "oma" tutkinnon osan nimi

Vastaus (/api/export/v2/vastaukset)

Yksittäisen vastauksen tiedot. Monivalintakysymysten tapauksessa jokainen valittu valihtoehto on oma vastauksensa, jolla on sama kysymysid ja vastaajaid.

Parametrit

Tietosisältö

Muutetut tunnukset (/api/export/v2/muutetut-tunnukset)

Palauttaa muuttuneet tunnukset.

Työpaikkaohjaajakyselyn tapauksessa kaikki tunnukset päivitetään siinä vaiheessa kun ne lisätään nippuihin ja työpaikkajakson kesto lasketaan.

Parametrit

Tietosisältö

Sama kuin vastaajatunnukset-rajapinnassa.

Poistetut tunnukset (/api/export/v2/poistetut-tunnukset)

Palauttaa poistettujen vastaajatunnusten id:t ja poistoajat, jotta ne voi poistaa omasta tietovarastosta.

Parametrit

Tietosisältö

Opiskeluoikeudet (/api/export/v2/opiskeluoikeudet)

Korkeakoulujen käyttöön tarkoitettu rajapinta vastaajatunnukseen liittyvän virran opiskeluoikeus-tiedon hakuun.

Parametrit

Tietosisältö

Tietojen haku rajapinnoista:

Opiskelijapalautteet:

Kyselyn tietojen haku:

• Hae /tiedonkeruu rajapinnasta tiedonkeruut ja etsi niistä haluttu tiedonkeruu kyselytyypillä, tarkenteella (jos tarvetta) ja tiedonkeruuvuodella. 
  • esim. ammatillisen opiskelijapalaute, aloittaneet, 2024
  • tiedonkeruun tunniste on aina muotoa kyselytyyppi-tarkenne-vuosi joten tämä on myös pääteltävissä
• Hae kyselyn sisältö /kyselyt-rajapinnasta tiedonkeruun tunnisteella
  • Tämä riittää tehdä kerran sen jälkeen kun mahdolliset omat kysymysryhmät on lisätty kyselyyn
  • Tiedonkeruun alun jälkeen kyselyn sisältö ei enää muutu

Vastausdatan haku:

• Hae halutulla aikavälillä (esim. päivittäin tai viikoittain) tiedonkeruun uudet vastaajatunnukset /vastaajatunnukset-rajapinnasta
  • Yhdistetään kyselyyn kyselyid:n perusteella
• Hae mahdolliset muuttuneet tunnukset /muuttuneet-tunnukset -rajapinnasta
• Hae vastausdata /vastaukset-rajapinnasta
  • Yhdistetään tunnuksiin vastaajatunnusid:n perusteella ja kysymyksiin kysymysid:n perusteella
  • Vastaajaid yksilöi vastaajan (esim. ryhmätunnusten tapauksessa, jolloin vastaajatunnusid ei riitä)
  • Monivalintakysymyksissä jokainen vastaajan valitsema vaihtoehto on oma vastauksensa

Työpaikkaohjaajakysely:

Toimii muuten samoin kuin opiskelijapalaute paitsi että vastaajatunnuksia ei oletuksena palauteta luontihetkellä. 

Tunnukset niputetaan ryhmissä vastattaviksi työpaikkaohjaajille ja työpaikkajaksojen kestot lasketaan vasta niputtamisen yhteydessä. 

• "Keskeneräiset" tunnukset saa tarvittaessa niputtamattomat-parametrilla
• Normaalitapauksissa tunnukset kannattanee hakea pelkästään /muuttuneet-tunnukset rajapinnasta (ellei ole tarvetta saada tunnusten lukumääristä reaaliaikaista tietoa) koska kaikki tullaan joka tapauksessa päivittämään luontihetken jälkeen.

Työpaikkajaksojen yhdistäminen työpaikkakyselyn tunnuksille

Työpaikkajaksot (eli työpaikkaohjaajakyselyn tunnukset) yhdistetään työpaikkakyselyn tunnuksille seuraavasti:

Työpaikkakyselyn tunnukseen liittyvät ne jaksot, joilla:

• tyonantaja ja tyopaikka_normalisoitu taustatiedot ovat samat

• Jaksotunnuksen tyopaikkajakson_loppupvm on työpaikkakyselyn tunnuksen tiedonkeruu_alkupvm ja tiedonkeruu_loppupvm välissä

• Jaksotunnuksen oppisopimuksen_perusta on jotain muuta kuin 02 (yrittäjä)

Tätä kautta liitetyistä jaksotunnuksista voi tarvittaessa laskea työpaikkakyselyn tunnukselle työpaikkajaksojen yhteiskestot, tutkinnot, tutkinnon osat ym.