Examin vaatimat integraatiot: ohjeet

Transkriptio

1 Examin vaatimat integraatiot: ohjeet Opintojaksoilta haettava tieto Tuonti JSON-rajapinnan yli Esimerkkejä Tuonti CSV-muodossa Kuinka tuonti tehdään? Suoritukselle kirjattavat tiedot JSON-rajapinta Apache-konfiguraatiot Live-testirajapinta CSV-tiedostot Tälle sivulle kootaan ajantasainen ohjeistus Examin vaatiminen integraatioiden tekemisestä korkeakouluissa. Ohjesivun muutosten ylläpito: Muutospäivämäärä Muutoksen tekijä Muutoksen kohde Matti Lupari Poistettu väärä tieto, jonka mukaan intojaksotietokentän nimi on vapaaehtoinen Matti Lupari Lisätty uusi suoritustieto "institutionname" Matti Lupari Lisätty uusi intojakson arvosanatieto "isfailed" Kristiina Uolia Lisätty ajantasaiset excelit integraatiossa liikkuvista tiedoista. Koottu tiedot tälle yhdelle sivulle Mikko Katajamäki Lisätty intojakson tuontiin liittyvät JSON / CSV -tiedostot Mikko Katajamäki Lisätty ohjeita intojaksotiedon tuontiin CSV-tiedostosta Matti Lupari Päivitetty intojaksotiedon JSON-tiedosto Matti Lupari Päivitetty intojaksotiedon Excel-tiedosto Matti Lupari Siirretty yleiskuvauksen ohjeiden sisältöä tänne, jotta yleiskuvaus pysyisi yleisluontoisena Matti Lupari Päivitetty tietomallia puuttuvilla tiedoilla. Kirjoitettu auki CSV-formaatti taulukkomuotoon Kristiina Uolia Korjattu termi "eppn" oikeaan muotoon edupersonprincipalname Taustatietoa Exam-palvelu vaatii toimiakseen tenttien taustalle oman organisaation intojaksotietoja. Näin voidaan varmistaa että suorituksille kirjataan oikeita pohjatietoja sekä säästetään ettajan kirjaustyötä. Kirjautuminen on suunniteltu tapahtuvaksi HAKA-federaation kautta. Tarvittavista attribuuteista ja niiden käytöstä on tietoa asennusohjeissa. Integraatioiden toteutustavat Vaatimusmäärittelyn mukaisesti tietointegraatioissa tuetaan kahta toteutustapaa: reaaliaikaista integraatiota REST-rajapinnoilla (JSON) sekä tiedostosiirtoa (CSV). Opintojaksoilta haettava tieto Tuonti JSON-rajapinnan yli Allaolevissa taulukoissa on kuvattu tiedot, jotka intojaksoilta voidaan lukea sisään Examiin JSON-muodossa verkkorajapinnan yli. Vastauksen sisällössä tulee olla seuraavat tiedot: Nimi JSON-kenttä Määrä Muoto Käyttö Pyynnön tila status 1 "OK" jos pyynnön käsittelyssä ei ongelmia, muuten vapaavalintainen. Jos arvona muu kuin "OK", ei vastausta käsitellä sen enempää Opintojaksotieto CourseUnitInfo 1 (useamman tiedon tuonti kerralla ei toistaiseksi ole virallisesti tuettu) katso alla JSON-objekti joka sisältää intojakson tiedot

2 Opintojaksotiedon sisältävän JSON-objektin määrittely on alla olevassa taulukossa Nimi JSON-kenttä Määrä Selite Muoto Pakollinen Käyttö Examissa Järjestelmätunniste identifier 1 intojakson tunniste perusjärjestelmässä vapaavalintainen Opintojakson koodi courseunitcode 1 vapaavalintainen Opintojakson nimi courseunittitle 1 vapaavalintainen Käytetään intojakson tunnisteena exami sisällä. Esiintyy Esiintyy käyttöliittymässä Toteutustieto courseimplementation 0-1 intojakson toteutuksen tunniste vapaavalintainen Laajuus credits 0-1 intojakson intistemäärä kokonais- tai desimaaliluku Kieli creditslanguage 0-1 suorituskieli ISO kielikoodi Käytetään oletusarvoisesti intojaksoon liitet tenttisuorituksen intistemäärän Esiintyy Käytetään oletusarvoisesti intojaksoon liitet tenttisuorituksen kielenä. Esiintyy Taso courseunitlevel 0-1 innon taso vapaavalintainen (perus, yleis, aine, syventävä tms.) Arvosana-asteikko gradescale 0-N arvosana-asteikko ja sen sisältämät arvosanat "gradescale" : [ { "name" : "HYL-HYV", "type" : "OTHER", "code" : 11, "grades" : { " " : { "grade" : , "description" : "HYV", "scale" : 0, "isfailed" : "false", " " : { "grade" : , "description" : "HYL", "scale" : 0, "isfailed" : "true" ] Käytetään asetuksista riippue intojaksoon liitet tentin arvosana-asteikko Jos asetuksissa on sallittu, voi ettaja ylikirjoittaa kyseise asteikon. Exam 2.0: OTHER-tyypin asteikot ja sisältyv arvosanat tuodaan osaksi järjestelmää Toistaiseksi EXAM tukee vain yhtä asteikkoa. Jos rajapinta tarjoaa useampaa, otetaa niistä ensimmäine Tyyppi courseunittype 0-1 innon tyyppi vapaavalintainen

3 Vastuuettaja lecturerresponsible 0-N vapaavalintainen. Toistaiseksi EXAM tukee vain yhtä ettajaa. Jos rajapinta tarjoaa useampaa, otetaan Opettaja lecturer 0-N vapaavalintainen. Toistaiseksi EXAM tukee vain yhtä ettajaa. Jos rajapinta tarjoaa useampaa, otetaan Oppilaitos institutionname 1 pilaitoksen nimi vapaavalintainen Näkyy käyttöliittymässä Osasto Oppiaine Kampus department 0-N osaston/tiedekunnan/yksikön/tms nimi vapaavalintainen. Toistaiseksi EXAM tukee vain yhtä osastoa. Jos rajapinta tarjoaa useampaa, otetaan degreeprogramme 0-N piaineen/ohjelman/tms nimi vapaavalintainen. Toistaiseksi EXAM tukee vain yhtä piainetta. Jos rajapinta tarjoaa useampaa, otetaan campus 0-N vapaavalintainen. Toistaiseksi EXAM tukee vain yhtä kampusta. Jos rajapinta tarjoaa useampaa, otetaan Voimassa alkaen startdate 0-1 intojakso astuu voimaan tällä päivämäärällä Voimassa asti enddate 0-1 intojakso astuu pois voimasta tällä päivämäärällä Päiväys muotoa "yyyymmdd". Päiväys muotoa "yyyymmdd". Opintojakso e valittavissa tentille jos se ei sillä hetke ole voimassa Opintojakso e valittavissa tentille jos se ei sillä hetke ole voimassa. = Tiedolle ei mitään varsinaista käyttöä ainakaan toistaiseksi Esimerkkejä { CourseUnitInfo: { identifier: "abc1", courseunitcode: "ABC1",..., status: "OK" courseinfo.json Tuonti CSV-muodossa Opintojaksotiedot voi tuoda suoraan tietokantaan kiomalla ne CSV-muodossa. Seuraavassa taulukossa on esitetty tiedot, jotka voidaan määritellä tuotaville intojaksoille. Tietokantakolumni Tyyppi Arvo Kuvaus Pakollinen Käyttö examissa Kirjataan intosuoritukselle id bigint uniikki course-relaation sisällä yksilöivä tunniste, sisäinen Opintojakson PK, sisäinen organisation_id bigint Viiteavain. Joku organisation-relaation id-kolumnin arvoista pilaitoksen/organisaation tunniste Esiintyy käyttöliittymässä code varchar uniikki intojakson koodi Käytetään intojakson tunnisteena examin sisällä. Esiintyy name varchar vapaavalintainen intojakson nimi Esiintyy käyttöliittymässä

4 level varchar vapaavalintainen intojakson taso Ei käyttöä credits double vapaavalintainen intisteiden määrä Käytetään oletusarvoisesti intojaksoon liitetyn tenttisuorituksen intistemääränä. Esiintyy (ettaja voi ylikirjoittaa pistemäärän halutessaan) identifier varchar vapaavalintainen intojakson järjestelmätunniste start_date timestamptz vapaavalintainen intojakson voimassaolon alkamispäivämäärä Ei käyttöä Opintojakso ei valittavissa tentille, jos se ei sillä hetkellä ole voimassa course_implementation varchar vapaavalintainen intojakson toteutustieto Ei käyttöä credits_language varchar ISO kielikoodi intojakson suorituskieli Käytetään oletusarvoisesti intojaksoon liitetyn tenttisuorituksen kielenä. Esiintyy (ettaja voi ylikirjoittaa kielen halutessaan) lecturer varchar vapaavalintainen ettaja Ei käyttöä lecturer_responsible varchar vapaavalintainen vastuuettaja Ei käyttöä institution_name department varchar vapaavalintainen pilaitoksen nimi Näkyy käyttöliittymässä varchar vapaavalintainen osaston nimi Ei käyttöä degree_programme varchar vapaavalintainen piaineen/ohjelman/tms nimi Ei käyttöä campus varchar vapaavalintainen kampuksen nimi Ei käyttöä course_material varchar vapaavalintainen intojakson materiaalikuvaus Ei käyttöä course_unit_type varchar vapaavalintainen innon tyyppi Ei käyttöä grade_scale_id integer Viiteavain. Joku grade_scale-relaation id-kolumnin arvoista arvosana-asteikko Käytetään asetuksista riippuen intojaksoon liitetyn tentin arvosana-asteikkona. Jos asetuksissa on sallittu, voi ettaja ylikirjoittaa kyseisen asteikon. OTHER-tyypin asteikon attribuutti "code" annetaan suoritukselle. Muilla asteikoilla käytetään asteikon nimeä, joka ei ole perusjärjestelmästä saatu arvo. object_version bigint 1 tietueen versiotieto, sisäinen. end_date timestamptz vapaavalintainen intojakson voimassaolon päättymispäivämäärä Versiotieto, sisäiseen käyttöön Opintojakso ei valittavissa tentille, jos se ei sillä hetkellä ole voimassa. = Tiedolle ei mitään varsinaista käyttöä ainakaan toistaiseksi Kuinka tuonti tehdään? Kun yllä olevan formaatin mukainen CSV-tiedosto on luotu, voidaan se kioida tietokantaan näin:

5 $ psql -Usitnet sitnet psql (9.3.5) Type "help" for help. sitnet=> \COPY course (id, organisation_id,... <tähän kaikki kolumnit mitä CSV toteuttaa>) FROM 'courses.csv' WITH (DELIMITER ';', FORMAT CSV, HEADER); On huomioitavaa, että komennossa tulee olla listattuna suluissa samat kolumnit, jotka on määritelty csv-tiedostossa. DELIMITER-tio määrittelee erottimen, joka voi olla muukin merkki kuin pilkku. Jos csv-tiedoston ensimmäinen rivi on otsikkorivi, täytyy komennon lussa olla tio 'HEADER'. Vastaavasti tietokannasta voidaan kioida intojaksoja CSV-tiedostoon: sitnet => \COPY course TO 'courses.csv' WITH (DELIMITER ';', FORMAT CSV, HEADER); Luksi korjataan sekvenssit: sitnet => select setval('course_seq', (select max(id) from course)); Suoritukselle kirjattavat tiedot Tässä listauksessa on kuvattu tiedot, jotka Exam kirjaa yksittäisen iskelijan tenttisuoritukselle ulkuolisen järjestelmän luettavaksi. Nimi JSON-kenttä Selite Muoto HAKA-attribuutti Opintojaksorajapinnan vastaava tietue M Suorituksen ID id yksilöivä tunniste kokonaisluku Opiskelija student iskelijan tunnus vapaavalintainen edupersonprincipalname Opiskelijanumero studentid iskelijanumero vapaavalintainen schacpersonaluniquecode Opintojakson tunniste identifier intojakson tunniste perusjärjestelmässä Opintojakson koodi courseunitcode intojakson koodi perusjärjestelmässä Suorituspäivä examdate tenttisuorituksen päivämäärä, päivämäärä jona iskelija on tehnyt tentin Laajuus credits suoritukselle kirjattu intistemäärä vapaavalintainen identifier vapaavalintainen courseunitcode yyyy-mm-dd desimaaliluku credits E sa m O yl Suorituskieli creditlanguage suorituskieli ISO kielikoodi creditlanguage E sa m O yl

6 Arvosana studentgrade suorituksen kokonaisarvosana vapaavalintainen gradescale > grades > description Tä E fo si ar tu pe va su E tie Arvosana-asteikko gradescale Suorituksen arvostelussa käytetty asteikko vapaavalintainen gradescale > code Tä E fo si ar tu pe va su E tie Pistemäärä examscore Suorituksen pistemäärä vapaavalintainen S va la ko S m ky ar nu Taso courseunitlevel Suorituksen taso vapaavalintainen courseunitlevel Oppilaitoksen nimi institutionname Opintojaksolle liitetyn organisaation nimi vapaavalintainen institutionname Suoritustyyppi credittype Suoritystyyppi FINAL = kokonaissuoritus PARTIAL = osasuoritus Opettaja lecturer Opettaja, joka on antanut suoritukselle kokonaisarvosanan vapaavalintainen edupersonprincipalname Opettajan numero lecturerid Opettajan tunnus vapaavalintainen schacpersonaluniquecode Opettajan henkilökuntatunnus lectureremployeenumber Opettajan henkilökuntatunnus vapaavalintainen employeenumber Rekisteröintipäivämäärä date Rekisteröinnin päivämäärä yyyy-mm-dd P m su lo va vi Opintojakson toteutustieto courseimplementation Opintojakson toteutustieto vapaavalintainen courseimplementation Lisätieto additionalinfo Lisätieto rekisteriin vientiä varten vapaavalintainen O tä lis ja ta JSON-rajapinta Kysyvä järjestelmä ottaa yhteyttä Examin polkuun missä päivämäärä on (esim: /integration/record/{päivämäärä ISO-8601-formaatissa T22:19:17+02:00). Paluuviestinä saadaan JSON-muodossa kaikki suoritukset kyseisestä hetkestä alkaen.

7 Apache-konfiguraatiot HUOM rajapinta ei ole suojattu, vastuu jätetään korkeakouluille. Pääsyä polkuun voidaan rajoittaa esim IP-rajauksella Apachen konfiguraatiossa polku tulee poistaa Shibboleth-autentikaation piiristi, muuten kysyvältä järjestelmältä vaaditaan HAKA-kirjautumista. esim: <VirtualHost XXX.XXX.XXX.XXX:443> ProxyPreserveHost On ServerName ProxyPass /excluded! ProxyPass /Shibboleth.sso! ProxyPass / ProxyPassReverse / # application root, require HAKA login <Location /> AuthType shibboleth ShibUseHeaders On ShibRequestSetting requiresession 1 require valid-user </Location> # exam records, exclude from HAKA <Location /integration/record> Satisfy Any Allow from all </Location>... </VirtualHost> Live-testirajapinta Demalvelimella on nyt käytössä suoritusrajapinta joka palauttaa kyseisellä palvelimella tehdyt suoritukset: Rajauskriteeriksi voi antaa nyt vain päivämäärän. Haku palauttaa kaikki suoritukset tuosta päivämäärästä alkaen. Esimerkkejä Examin tuottamista suoritustiedoista. Luotu Oodi-instanssista saadun intojaksotiedon pohjalle, henkilötietoja muutettu yksityisyydensuojan vuoksi:

8 [ { "id":121, "studentid":" ", "student":"iskelija@some.org", "identifier":" ", "courseunitcode":" ", "examdate":" ", "credits":"3.0", "creditlanguage":"fi", "studentgrade":"hyv.", "gradescale":"101", "examscore":"1.0", "courseunitlevel":null, "courseunittype":"1", "credittype":"final", "lecturer":"teacher@some.org", "lecturerid":" ", "date":" ", "courseimplementation":null, "additionalinfo":null, "lectureremployeenumber":"123455", "institutionname": "Itä-Suomen yliisto",{ "id":141, "studentid":" ", "student":"iskelija@some.org", "identifier":" ", "courseunitcode":" ", "examdate":" ", "credits":"3.0", "creditlanguage":"fi", "studentgrade":"hyv.", "gradescale":"101", "examscore":"10.0", "courseunitlevel":null, "courseunittype":"1", "credittype":"final", "lecturer":"teacher2@some.org", "lecturerid":" ", "date":" ", "courseimplementation":null, "additionalinfo":null, "lectureremployeenumber":"123456", "institutionname": "Itä-Suomen yliisto" ] CSV-tiedostot Opettajalla tai ylläpitäjällä on käyttöliittymässä mahdollisuus tulostaa samat tiedot myös CSV-tiedostoon. CSV-formaatissa on mukana myös joitakin informatiivisiä lisäkenttiä.