Page tree
Skip to end of metadata
Go to start of metadata


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:

parametrityyppikuvaushuom
jarjestelmastringLukurajapintaa käyttävän eli kutsuvan järjestelmän nimi (esim. TIPTOP) 
tunnusstringKutsuja/käyttäjä eli kutsuvan järjestelmän käyttäjän käyttäjätunnus. 
avainstringLukurajapinnan salasana 



Hakuehdot:

parametrityyppikuvaushuom
henkilotunnusvirta:HenkilotunnusTyyppiSuomalainen henkilötunnus 
kansallinenOppijanumerostringKansallinen oppijanumerohaetaan joko oppijanumerolla tai henkilötunnuksella
organisaatiovirta:OrganisaatioKoodiTyyppiorganisaation koodi, josta tiedot halutaan hakeaorganisaation koodi


Massahakuehdot:

parametrityyppikuvaushuom
henkilotunnusListavirta:HenkilotunnusTyyppiSuomalaisia henkilötunnuksiaMax. 200 kpl. Listassa saa olla vain joko henkilötunnuksia tai oppijanumeriota. Ei molempia.
kansallinenOppijanumeroListastringKansallisia oppijanumeroitaMax. 200 kpl. Listassa saa olla vain joko henkilötunnuksia tai oppijanumeriota. Ei molempia.
organisaatiovirta:OrganisaatioKoodiTyyppiorganisaation koodi, josta tiedot halutaan hakeaorganisaation koodi

 

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

 

Esimerkki keksityn henkilön lukukausi-ilmoittautumisista
<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>

 



  • No labels