VIRTA-opintotietopalvelun WS-rajapinta
VIRTA-opintotietopalvelun tietoja on mahdollista hyödyntää teknisellä käyttöyhteydellä WS-rajapinnan kautta. Rajapinta ei ole julkinen ja sen käyttöoikeuksia myöntää opetus- ja kulttuuriministeriö, yhdessä korkeakoulujen kanssa. Tiedonluovutuksesta säädetään laissa 884/2017. Rajapintakysely on mahdollista tehdä joko henkilötunnuksella tai kansallisella oppijanumerolla. Rajapinta palauttaa tiedon järjestettynä CEN\SFS-standardin EUROLMAI-mukaan.
Käytännössä rajapinta palauttaa VIRTA-opintotietopalvelun XML-määristysten mukaisesti tietoa loppukäyttäjille. Dataa haetaan rajapinnasta yhden henkilön tiedot kerrallaan, tietyt tai kaikki tiedot. Tietoja voi hakea kansallisella oppijanumerolla tai henkilötunnuksella. Kansallinen oppijanumero yksilöi ja yhdistää saman henkilön tiedot kaikkien korkeakoulujen kesken tietovarannossa. Massahaussa käytetään listaa henkilötunnuksia tai oppijanumeroita.
Rajapinta palvelee 24/7 -periaatteella. Mahdollisten häiriötilanteiden korjaaminen tapahtuu virka-aikana. VIRTA-tietojen hyödyntäminen on maksutonta.
VIRTA-opintotietopalvelun tietosisältö on kuvattu tämän wiki-sivuston sivulla Tietovarannon tiedot. CSC:n VIRTA-tiimi auttaa tarvittaessa tietosisältöön ja tietojen hyödyntämiseen liittyvissä kysymyksissä. Yhteydenotot palvelusoitteen kautta: virta (at) csc.fi
Lisätietoja
Rajapinnan esittely
Rajapinnan yksityiskohtainen tekninen määrittely löytyy WSDL-kuvauksesta joka on saatavissa osoitteesta https://github.com/CSCfi/VIRTA-Opintotietopalvelu/blob/master/WSDL/opiskelijatiedot.wsdl
Rajapinnasta voidaan hakea tietoa seuraavilla parametreilla:
Kutsuja:
| parametri | tyyppi | kuvaus | huom |
|---|---|---|---|
| jarjestelma | string | Lukurajapintaa käyttävän eli kutsuvan järjestelmän nimi (esim. TIPTOP) | |
| tunnus | string | Kutsuja/käyttäjä eli kutsuvan järjestelmän käyttäjän käyttäjätunnus. | |
| avain | string | Lukurajapinnan salasana |
Hakuehdot:
| parametri | tyyppi | kuvaus | huom |
|---|---|---|---|
| henkilotunnus | virta:HenkilotunnusTyyppi | Suomalainen henkilötunnus | |
| kansallinenOppijanumero | string | Kansallinen oppijanumero | haetaan joko oppijanumerolla tai henkilötunnuksella |
| organisaatio | virta:OrganisaatioKoodiTyyppi | organisaation koodi, josta tiedot halutaan hakea | organisaation koodi EILOYDY |
Massahakuehdot:
| parametri | tyyppi | kuvaus | huom |
|---|---|---|---|
| henkilotunnusLista | virta:HenkilotunnusTyyppi | Suomalaisia henkilötunnuksia | Max. 200 kpl. Listassa saa olla vain joko henkilötunnuksia tai oppijanumeriota. Ei molempia. |
| kansallinenOppijanumeroLista | string | Kansallisia oppijanumeroita | Max. 200 kpl. Listassa saa olla vain joko henkilötunnuksia tai oppijanumeriota. Ei molempia. |
| organisaatio | virta:OrganisaatioKoodiTyyppi | organisaation koodi, josta tiedot halutaan hakea | organisaation koodi EILOYDY |
Haettavat tiedot:
Rajapinta palauttaa seuraavat tietojoukot. Huomion arvoista on, että kaikkia määriteltyjä tietoja ei välttämättä palauteta vaan tietojen kattavuus riippuu tiedon toimittaneesta korkeakoulusta.
Erityisesti tämä korostuu silloin, mitä vanhempia tietoja haetaan.
OpiskelijanTiedot:
Opiskelijatiedoissa palautetaan henkilön perustiedot mm. nimi, asuinkunta, kansallisuus. Tekninen määritys: Opiskelijatiedot.xsd
Opintosuoritukset:
Opintosuorituksen tiedoissa palautetaan suorituksen tyyppi, arvosana, suorituspäivämäärä jne. Opintosuorituksena ilmoitetaan myös saavutettu tutkinto ja mahdollinen pätevyys. Tekninen määritys: Opintosuoritukset.xsd
Tutkinnot:
Palautetaan vain ne opintosuoritukset, jotka ovat tyyppiä tutkinto. Tekninen määritys: Opintosuoritukset.xsd
Opiskeluoikeudet:
Opiskeluoikeuden tiedoissa luetellaan henkilön jo poistuneet ja vielä aktiiviset opiskeluoikeudet. Tällaisia tietoja ovat mm. opiskeluoikeuden tyyppi, tila, alkupvm, loppupvm, koulutusluokitus, koulutusmoduuli ja suoritettava op määrä.
Tekninen määritys: Opiskeluoikeudet.xsd
LukukausiIlmoittautumiset:
Henkilön lukukausi-ilmoittautumiset. Tiedot läsnä- tai poissaoloilmoittautumisista opiskeluoikeuksiin Tekninen määritys: Lukukausiilmoittutumiset.xsd
Liikkuvuusjaksot
Opiskelijatiedoissa palautetaan opiskelijan liikkuvuusjakso tiedot. Esim. alkupvm, loppupvm, lähtevä/saapuva, kohdemaa, liikkuvuusohjelma. Tekninen määritys: Liikkuvuusjaksot.xsd
OpiskelijanKaikkiTiedot:
OpiskelijanKaikkiTiedot tuo yhdellä kyselyllä kaikki neljä edellistä tietojoukkoa. Tekninen määritys: Virta.xsd
Koodistot:
Rajapinnan palauttamissa dokumenteissa käytetään yhteisiä koodistoja: Tietovarannon koodistot
Massahakuvaihtoehto
OpiskelijanKaikkiTiedotLista
OpiskelijanKaikkiTiedotLista tuo yhdellä kyselyllä hetu- tai oppijanumerolistan (max 200) mukaan kaikkia neljän edellisen (OpiskelijanKaikkiTiedot) tietojoukkoa. Tekninen määritys: Virta.xsd
Virhekäsittely:
Tyhjä vastaus
Rajapinta ei palauta mitään, jos haettua henkilöä ei löydy annetusta organisaatiosta tai henkilöä ei ole olemassa tietovarannossa.
Validation error
Kyseinen virheilmoitus kertoo siitä että kyselyn parametri on väärin. Syötteen oikeellisuutta tutkitaan Organisaatiotunnisteen (sallitut arvot löytyvät XSD määrityksistä) ja henkilötunnuksen (pitää olla oikein muodostettu) yhteydessä. Tämä virhe palautetaan myös, jos jokin pakollinen parametri on jäänyt tyhjäksi, tai muuten väärin määritelty.
Access denied
Ongelma käyttäjän tunnistuksessa. Ota yhteyttä Tietovarannon ylläpitoon (virta(a)csc.fi).