Tälle sivulle kootaan ajantasainen ohjeistus Examin vaatiminen integraatioiden tekemisestä korkeakouluissa.
Taustatietoa
Exam-palvelu vaatii toimiakseen tenttien taustalle oman organisaation opintojaksotietoja. Näin voidaan varmistaa että suorituksille kirjataan oikeita pohjatietoja sekä säästetään opettajan 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 opintojaksoilta 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-n | katso alla | JSON-objekti TAI -lista, joka sisältää opintojakson/opintojaksojen tiedot |
Opintojaksotiedon sisältävän JSON-objektin määrittely on alla olevassa taulukossa
| Nimi | JSON-kenttä | Määrä | Selite | Muoto | Pakollinen | Käyttö Examissa | Siirtyy opintosuoritukseen |
|---|---|---|---|---|---|---|---|
| Järjestelmätunniste | identifier | 1 | opintojakson tunniste perusjärjestelmässä | vapaavalintainen | |||
| Opintojakson koodi | courseUnitCode | 1 | vapaavalintainen | ||||
| Opintojakson nimi | courseUnitTitle | 1 | vapaavalintainen | ||||
| Toteutustieto | courseImplementation | 0-1 | opintojakson toteutuksen tunniste | vapaavalintainen | |||
| Laajuus | credits | 0-1 | opintojakson opintopistemäärä | kokonais- tai desimaaliluku | |||
| Kieli | creditsLanguage | 0-1 | suorituskieli | ISO-639-1-kielikoodi "creditsLanguage": {
"name": "fi"
}
"creditsLanguage": [
{
"name": "fi"
}
]
"creditsLanguage": "fi"
| |||
| Taso | courseUnitLevel | 0-1 | opinnon 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" : {
"10979859" : {
"grade" : 10979859,
"description" : "HYV",
"scale" : 0,
"isFailed" : "false"
},
"10979861" : {
"grade" : 10979861,
"description" : "HYL",
"scale" : 0,
"isFailed" : "true"
}
}
}
]
Tämä esimerkki ja sen mukainen toteutus on tehty EXAMiin aikoinaan Oodi-järjestelmän tarjoaman datan perusteella. Nykyisin kun tietoja tuodaan Peppi, Sisu tms. järjestelmistä, niin niiden tietomallit/sisällöt saattavat erota aiemmasta Oodi-järjestelmästä. EXAM tallentaa tietokantaansa tietyn korkeakoulun opintohallinnon järjestelmästä tuodun arvosana-asteikon (OTHER-tyypin asteikko) vain kerran eikä päivitä asteikon tietoja vaikka myöhemmin rajapinnan kautta tulisi saman asteikon (=sama code) tietoja kuten arvosanoja eri muodossa. (Toisaalta arvosana-asteikkoja ja näiden arvosanoja voidaan lisätä/muokata EXAMiin/EXAMin tietokantaan myös manuaalisesti.) Tarkennuksena mitä tietoja EXAM em. esimerkin OTHER-tyypin asteikon datasta tarvitsee: Arvosana-asteikon eli gradeScalen tiedoista ovat pakollisia name, type ja code. grades ei ole pakollinen mutta ilman sitä ei arvosana-asteikolle tule EXAMissa arvosanoja jolloin sitä ei voi käyttää tenttisuoritusten arvioinnissa. (EXAMiin/EXAMin tietokantaan voidaan lisätä asteikon arvosanat myös erikseen/manuaalisesti jolloin sitä voi taas käyttää.). Asteikon arvosanojen (grades) tiedoissa ei ole väliä mitä noissa id-kentissä (grades ja grade) on, kunhan ovat yksilöiviä." EXAM ei käytä/tallenna näitä id-tietoja. EXAM käsittelee ja tallentaa ainoastaan description ja isFailed tietoja. Grade tai scale tietoja ei ole pakko olla JSONissa. Description kentän sisältöä voi esimerkiksi tarvittaessa käyttää id ja grade kentissä (kunhan ne ovat yksilöiviä mitä varmastikin ovat kun ei samassa asteikossa eri arvosanat kai koskaan ole samoja). Jos opintojaksolla/toteutuksella ei ole arvosana-asteikkoa tai sitä ei haluta lähettää ollenkaan EXAMille, niin gradeScale-tietoa ei saa laittaa ollankaan JSON-dataan. Esimerkiksi ei saa laittaa "gradeScale": null, koska EXAM ei osaa käsitellä tuossa olevaa null-arvoa oikein. EXAMin 6.3.3 versiosta alkaen on opintojaksotiedoissa arvosana-asteikkona mahdollista käyttää myös EXAMin sisäisiä/oletusarvosana-asteikkoja jotka ovat 0-5, Hyväksytty / Hylätty ja Improbatur-Laudatur. Näissä käytetään arvosana-asteikon tyyppitietoa. 0-5 -asteikolla: "gradeScale": [
{
"type" : "ZERO_TO_FIVE"
}
],
Hyväksytty / Hylätty -asteikolla: "gradeScale": [
{
"type" : "APPROVED_REJECTED"
}
],
Improbatur-Laudatur -asteikolla: "gradeScale": [
{
"type" : "LATIN"
}
],
|
Toistaiseksi EXAM tukee vain yhtä asteikkoa. Jos rajapinta tarjoaa useampaa, otetaan niistä ensimmäinen. |
EXAMin sisäisillä/oletusasteikoilla käytetään asteikon nimeä ZERO_TO_FIVE, APPROVED_REJECTED tai LATIN. | |
| Tyyppi | courseUnitType | 0-1 | opinnon tyyppi | vapaavalintainen | |||
| Vastuuopettaja | lecturerResponsible | 0-N | vapaavalintainen. Toistaiseksi EXAM tukee vain yhtä opettajaa. Jos rajapinta tarjoaa useampaa, otetaan niistä ensimmäinen. JSON-muodoissa (valitse yksi) "lecturerResponsible": {
"name": "??"
}
"lecturerResponsible": [
{
"name": "??"
}
]
"lecturerResponsible": "??"
| ||||
| Opettaja | lecturer | 0-N | vapaavalintainen. Toistaiseksi EXAM tukee vain yhtä opettajaa. Jos rajapinta tarjoaa useampaa, otetaan niistä ensimmäinen. JSON-muodoissa (valitse yksi) "lecturer": {
"name": "??"
}
"lecturer": [
{
"name": "??"
}
]
"lecturer": "??"
| ||||
| Oppilaitos | institutionName | 1 | oppilaitoksen nimi | vapaavalintainen | |||
| Osasto | department | 0-N | osaston/tiedekunnan/yksikön/tms nimi | vapaavalintainen. Toistaiseksi EXAM tukee vain yhtä osastoa. Jos rajapinta tarjoaa useampaa, otetaan niistä ensimmäinen. JSON-muodoissa (valitse yksi) "department": {
"name": "??"
}
"department": [
{
"name": "??"
}
]
"department": "??"
| |||
| Oppiaine | degreeProgramme | 0-N | oppiaineen/ohjelman/tms nimi | vapaavalintainen. Toistaiseksi EXAM tukee vain yhtä oppiainetta. Jos rajapinta tarjoaa useampaa, otetaan niistä ensimmäinen. JSON-muodoissa (valitse yksi) "degreeProgramme": {
"name": "??"
}
"degreeProgramme": [
{
"name": "??"
}
]
"degreeProgramme": "??"
| |||
| Kampus | campus | 0-N | vapaavalintainen. Toistaiseksi EXAM tukee vain yhtä kampusta. Jos rajapinta tarjoaa useampaa, otetaan niistä ensimmäinen. JSON-muodoissa (valitse yksi) "campus": {
"name": "??"
}
"campus": [
{
"name": "??"
}
]
"campus": "??"
| ||||
| Voimassa alkaen | startDate | 0-1 | opintojakso astuu voimaan tällä päivämäärällä | Päiväys muotoa "yyyyMMdd". | |||
| Voimassa asti | endDate | 0-1 | opintojakso astuu pois voimasta tällä päivämäärällä | Päiväys muotoa "yyyyMMdd". |
= Tiedolle ei mitään varsinaista käyttöä ainakaan toistaiseksi
Esimerkkejä
{
CourseUnitInfo: {
identifier: "abc1",
courseUnitCode: "ABC1",
...
},
status: "OK"
}
Tuonti CSV-muodossa
Opintojaksotiedot voi tuoda suoraan tietokantaan kopiomalla ne CSV-muodossa. Seuraavassa taulukossa on esitetty tiedot, jotka voidaan määritellä tuotaville opintojaksoille.
| Tietokantakolumni | Tyyppi | Arvo | Kuvaus | Pakollinen | Käyttö examissa | Kirjataan opintosuoritukselle |
|---|---|---|---|---|---|---|
| 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 | oppilaitoksen/organisaation tunniste | Esiintyy käyttöliittymässä | ||
| code | varchar | uniikki | opintojakson koodi | Käytetään opintojakson tunnisteena examin sisällä. Esiintyy käyttöliittymässä. | ||
| name | varchar | vapaavalintainen | opintojakson nimi | Esiintyy käyttöliittymässä | ||
| level | varchar | vapaavalintainen | opintojakson taso | Ei käyttöä | ||
| credits | double | vapaavalintainen | opintopisteiden määrä | Käytetään oletusarvoisesti opintojaksoon liitetyn tenttisuorituksen opintopistemääränä. Esiintyy käyttöliittymässä. | ||
| identifier | varchar | vapaavalintainen | opintojakson järjestelmätunniste | Ei käyttöä | ||
| start_date | timestamptz | vapaavalintainen | opintojakson voimassaolon alkamispäivämäärä | Opintojakso ei valittavissa tentille, jos se ei sillä hetkellä ole voimassa | ||
| course_implementation | varchar | vapaavalintainen | opintojakson toteutustieto | Ei käyttöä | ||
| credits_language | varchar | ISO-639-1-kielikoodi | opintojakson suorituskieli | Käytetään oletusarvoisesti opintojaksoon liitetyn tenttisuorituksen kielenä. Esiintyy käyttöliittymässä. | ||
| lecturer | varchar | vapaavalintainen | opettaja | Ei käyttöä | ||
| lecturer_responsible | varchar | vapaavalintainen | vastuuopettaja | Ei käyttöä | ||
| department | varchar | vapaavalintainen | osaston nimi | Ei käyttöä | ||
| degree_programme | varchar | vapaavalintainen | oppiaineen/ohjelman/tms nimi | Ei käyttöä | ||
| campus | varchar | vapaavalintainen | kampuksen nimi | Ei käyttöä | ||
| course_material | varchar | vapaavalintainen | opintojakson materiaalikuvaus | Ei käyttöä | ||
| course_unit_type | varchar | vapaavalintainen | opinnon tyyppi | Ei käyttöä | ||
| grade_scale_id | integer | Viiteavain. Joku grade_scale-relaation id-kolumnin arvoista | arvosana-asteikko | Käytetään asetuksista riippuen opintojaksoon liitetyn tentin arvosana-asteikkona. Jos asetuksissa on sallittu, voi opettaja ylikirjoittaa kyseisen asteikon. | ||
| object_version | bigint | 1 | tietueen versiotieto, sisäinen. | Versiotieto, sisäiseen käyttöön | ||
| end_date | timestamptz | vapaavalintainen | opintojakson voimassaolon päättymispäivämäärä | 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 kopioida tietokantaan näin:
$ 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-optio määrittelee erottimen, joka voi olla muukin merkki kuin pilkku. Jos csv-tiedoston ensimmäinen rivi on otsikkorivi, täytyy komennon lopussa olla optio 'HEADER'.
Vastaavasti tietokannasta voidaan kopioida opintojaksoja CSV-tiedostoon:
sitnet => \COPY course TO 'courses.csv' WITH (DELIMITER ';', FORMAT CSV, HEADER);
Lopuksi 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 opiskelijan tenttisuoritukselle ulkopuolisen järjestelmän luettavaksi.
| Nimi | JSON-kenttä | Selite | Muoto | HAKA-attribuutti | Opintojaksorajapinnan vastaava tietue | Muuta |
|---|---|---|---|---|---|---|
| Suorituksen ID | id | yksilöivä tunniste | kokonaisluku | |||
| Opiskelija | student | opiskelijan tunnus | vapaavalintainen | eduPersonPrincipalName | ||
| Opiskelijanumero | studentId | opiskelijanumero | vapaavalintainen | schacPersonalUniqueCode | ||
| Opintojakson tunniste | identifier | opintojakson tunniste perusjärjestelmässä | vapaavalintainen | identifier | ||
| Opintojakson koodi | courseUnitCode | opintojakson koodi perusjärjestelmässä | vapaavalintainen | courseUnitCode | ||
| Suorituspäivä | examDate | tenttisuorituksen päivämäärä, päivämäärä jona opiskelija on tehnyt tentin | yyyy-MM-dd | |||
| Laajuus | credits | suoritukselle kirjattu opintopistemäärä | desimaaliluku | credits | Ei välttämättä ole sama kuin opintojaksotiedon mukana tuleva arvo. Opettaja voi ylikirjoittaa arvon. | |
| Suorituskieli | creditLanguage | suorituskieli | ISO-639-1-kielikoodi | creditLanguage | Ei välttämättä ole sama kuin opintojaksotiedon mukana tuleva arvo. Opettaja voi ylikirjoittaa arvon. | |
| Arvosana | studentGrade | suorituksen kokonaisarvosana | vapaavalintainen | gradeScale > grades > description | Tämä voi olla myös EXAMin sisäisessä formaatissa riippuen siitä onko opintojaksojen arvosana-asteikot tuotu perusjärjestelmästä vai ovatko ne suoraan konfiguroitu EXAMin tietojärjestelmään. | |
| Arvosana-asteikko | gradeScale | Suorituksen arvostelussa käytetty asteikko | vapaavalintainen | gradeScale > code | Tämä voi olla myös EXAMin sisäisessä formaatissa riippuen siitä onko opintojaksojen arvosana-asteikot tuotu perusjärjestelmästä vai ovatko ne suoraan konfiguroitu EXAMin tietojärjestelmään. | |
| Pistemäärä | examScore | Suorituksen pistemäärä | vapaavalintainen | Suorituksen vastausten laskennallinen kokonaispistemäärä. Summaan laskettu mukaan ainoastaan kysymykset, joiden arvosteluasteikko on numeerinen. | ||
| Taso | courseUnitLevel | Suorituksen taso | vapaavalintainen | courseUnitLevel | ||
| Oppilaitoksen nimi | institutionName | Opintojaksolle liitetyn organisaation nimi | vapaavalintainen | institutionName | ||
| Suoritustyyppi | creditType | Suoritystyyppi |
| |||
| 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äivämäärä jolloin opettaja on merkannut suorituksen loppuunkäsitellyksi / valmiiksi rekisteriin vietäväksi. | ||
| Opintojakson toteutustieto | courseImplementation | Opintojakson toteutustieto | vapaavalintainen | courseImplementation | ||
| Lisätieto | additionalInfo | Lisätieto rekisteriin vientiä varten | vapaavalintainen | Opettaja voi syöttää tähän haluamansa lisätiedon jatkokäsittelyn tarpeita varten. |
JSON-rajapinta
Kysyvä järjestelmä ottaa yhteyttä Examin polkuun /integration/record/{suorituksen rekisteröintipäivämäärä} missä suorituksen rekisteröintipäivämäärä on ISO-8601-formaatissa (esim: 2014-08-20T22:19:17+03:00). Paluuviestinä saadaan JSON-muodossa kaikki suoritukset kyseisestä rekisteröintiajankohdasta alkaen.
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 https://exam.fi ProxyPass /excluded ! ProxyPass /Shibboleth.sso ! ProxyPass / http://127.0.0.1:9000/ ProxyPassReverse / http://127.0.0.1:9000/ # 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
Demopalvelimella on nyt käytössä suoritusrajapinta joka palauttaa kyseisellä palvelimella tehdyt suoritukset:
https://dev.csc.fi/integration/record/2020-08-20T22:19:17+03:00
Rajauskriteeriksi voi antaa rekisteröintipäivämäärän. Haku palauttaa kaikki suoritukset, jotka on rekisteröity kyseisestä ajankohdasta alkaen.
Esimerkkejä Examin tuottamista suoritustiedoista. Luotu Oodi-instanssista saadun opintojaksotiedon pohjalta, henkilötietoja muutettu yksityisyydensuojan vuoksi:
[
{
"id":121,
"studentId":"0123456789",
"student":"opiskelija@some.org",
"identifier":"9876543210",
"courseUnitCode":"6000009",
"examDate":"2015-09-30",
"credits":"3.0",
"creditLanguage":"fi",
"studentGrade":"Hyv.",
"gradeScale":"101",
"examScore":"1.0",
"courseUnitLevel":null,
"courseUnitType":"1",
"creditType":"FINAL",
"lecturer":"teacher@some.org",
"lecturerId":"33333333",
"date":"2015-09-30",
"courseImplementation":null,
"additionalInfo":null,
"lecturerEmployeeNumber":"123455",
"institutionName": "Itä-Suomen yliopisto"
},{
"id":141,
"studentId":"01234567890",
"student":"opiskelija@some.org",
"identifier":"9876543210",
"courseUnitCode":"6000010",
"examDate":"2015-08-06",
"credits":"3.0",
"creditLanguage":"fi",
"studentGrade":"Hyv.",
"gradeScale":"101",
"examScore":"10.0",
"courseUnitLevel":null,
"courseUnitType":"1",
"creditType":"FINAL",
"lecturer":"teacher2@some.org",
"lecturerId":"44444444",
"date":"2015-10-05",
"courseImplementation":null,
"additionalInfo":null,
"lecturerEmployeeNumber":"123456",
"institutionName": "Itä-Suomen yliopisto"
}
]
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ä.