WS-rajapinta

Korkeakoulujen valtakunnallisen tietovarannon WS-rajapinta

Osana korkeakoulujen valtakunnallisen tietovarannon toteutusta on syntynyt WS-rajapinta, jonka kautta tietovarannon tietoja voi kysellä. Rajapinta ei ole julkinen ja sen käyttöoikeuksia myöntää opetus- ja kulttuuriministeriö, yhdessä korkeakoulujen kanssa.  Rajapinta palauttaa tiedon järjestettynä CEN\SFS-standardin EUROLMAI-mukaan viranomaiskäyttöön tai korkeakoululle siirrettyjen tietojen tarkistamiseksi tai muuhun käyttöön.

Lisätietoja VIRTA-tietojen hyödyntämisestä:

Käytännössä rajapinta palauttaa korkeakoulujen valtakunnallisen tietovarannon 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.

Rajapinta palvelee 24/7 -periaatteella. Mahdollisten häiriötilanteiden korjaaminen tapahtuu virka-aikana.

Viimeisin versio näistä XML-määrityksistä on aina saatavilla tietovarannon wiki sivulta:
https://confluence.csc.fi/display/VIRTA/Tiedonsiirtomaaritykset+korkeakouluille

Tietosisällön ymmärtämisessä auttaa myös tämä wiki sivusto erityisesti voi mainita Tietovarannon tiedot osion alasivuineen:
https://confluence.csc.fi/display/VIRTA/Tietovarannon+tiedot

Tietovarannon teknisen ylläpidon tavoittaa tarvittaessa sähköpostiosoitteesta virta (at) csc.fi

Testiympäristö

Julkinen testiympäristö joka ei sisällä oikeita henkilö- tai opiskeluun liittyviä tietoja löytyy osoitteesta http://virtawstesti.csc.fi/
Uutta testiaineistoa tuotetaan tilauksesta Virta-tiimin toimesta (virta(a)csc.fi).

Rajapinnan esittely

Rajapinnan yksityiskohtainen tekninen määrittely löytyy WSDL kuvauksesta joka on saatavissa osoitteesta http://virtawstesti.csc.fi/luku/opiskelijatiedot.wsdl

Ohessa lyhyt kuvaus rajapinnan toiminnasta.

Rajapinnasta voidaan hakea tietoa seuraavilla parametreilla

Kutsuja:

Hakuehdot:

Massahakuehdot:

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).

<virta:LukukausiIlmoittautumiset xmlns:virta="urn:mace:funet.fi:virta/2013/01/29">
            <virta:LukukausiIlmoittautuminen opiskelijaAvain="H2">
               <virta:Myontaja>
                  <virta:Koodi>01901</virta:Koodi>
               </virta:Myontaja>
               <virta:Tila>1</virta:Tila>
               <virta:IlmoittautumisPvm>2007-09-07</virta:IlmoittautumisPvm>
               <virta:AlkuPvm>2007-08-01</virta:AlkuPvm>
               <virta:LoppuPvm>2008-07-31</virta:LoppuPvm>
               <virta:YlioppilaskuntaJasen>1</virta:YlioppilaskuntaJasen>
               <virta:YTHSMaksu>1</virta:YTHSMaksu>
            </virta:LukukausiIlmoittautuminen>
            <virta:LukukausiIlmoittautuminen opiskelijaAvain="H2">
               <virta:Myontaja>
                  <virta:Koodi>01901</virta:Koodi>
               </virta:Myontaja>
               <virta:Tila>1</virta:Tila>
               <virta:IlmoittautumisPvm>2008-09-01</virta:IlmoittautumisPvm>
               <virta:AlkuPvm>2008-08-01</virta:AlkuPvm>
               <virta:LoppuPvm>2009-07-31</virta:LoppuPvm>
               <virta:YlioppilaskuntaJasen>1</virta:YlioppilaskuntaJasen>
               <virta:YTHSMaksu>1</virta:YTHSMaksu>
            </virta:LukukausiIlmoittautuminen>
         </virta:LukukausiIlmoittautumiset>