Testaussivu on tarkoitettu järjestelmätoimittajille, jotka ovat toteuttamassa integraation oppijanumerorekisteriin oppijanumeron (yleistunnisteen) hakua/luontia varten

Käyttöoikeudet

  • Testauksessa tarvittavat käyttöoikeudet
    • Palvelukäyttäjän käyttäjärooli: Oppijanumeron haku (vain palvelukäyttäjälle)
    • Virkailijan käyttäjärooli: Oppijanumeropalvelun pääkäyttäjä 
  • Testaaminen edellyttää palvelukäyttäjätunnusta ja virkailijan tunnusta testiympäristössä (QA).
  • Tunnusten tilaus testaukseen: yhteisetpalvelut@opintopolku.fi 

Rajapintojen autentikaatio

Opintopolun palveluiden autentikaatio pohjautuu CAS:iin. Ulkoiset järjestelmät voivat tunnistautua käyttäen CAS:n rest-rajapintaa (https://apereo.github.io/cas/6.0.x/protocol/REST-Protocol.html). 

CAS protokolla on varsin monimutkainen ja kannattaa sisäistää ennen varsinaisen integraation rakentamista. Valmiiksi tehdyn asiakasohjelmiston käyttäminen on suositeltavaa. Ohessa löytyy shelliskripti joka yksinkertaistetusti esittää haluttuun palveluun kirjautumisen CAS:in avulla. Tutustu myös CAS-integraatiota koskevaan ohjeeseen Githubissa.

Tarkempi kuvaus löytyy täältä.

Rajapintojen kuvaus


Tutustu dokumentaatioon Swaggerissa:

  • Oppijanumeron käyttö yleistunnisteena sisältää seuraavat endpointit:
  • PUT /yleistunniste, useamman oppijan luonti: Käynnistää oppijoiden/henkilöiden luonnin tausta-ajona, jonka tilaa voi seurata palautettavan tuonnin id:n avulla. Lisää automaattisesti oppijat/henkilöt palvelukäyttäjän organisaatioihin. Organisaation palvelukäyttäjän tulee ensin luoda oppijat (= luoda organisaatiolinkitys henkilöihin) ennen kuin oppijanumeron voi hakea
  • POST / oppijanumerorekisteri-service​/yleistunniste​/hae, oppijanumeron haku yksittäiselle henkilölle. Hakee tai luo oppijanumeron yksittäiselle henkilölle annetun syötteen pohjalta. 
  • GET / yleistunniste/tuonti={id}, oppijoiden tuonnin kaikki tiedot: Perustietojen lisäksi palauttaa tuontiin liittyvät oppijat/henkilöt
  • POST / yleistunniste/tuonti={id}, käynnistä oppijoiden tiedon käsittely: Tarvitaan vain, jos oppijoiden/henkilöiden tuonnin automaattinen käsittely on keskeytynyt syystä tai toisesta.
  • GET / yleistunniste/tuonti={id}/perustiedot, oppijoiden tuonnin perustiedot: Tämän avulla voi seurata oppijoiden/henkilöiden tuonnin edistymistä.


Vaihekohtainen testausohje

1. Kirjaudu sisään ja mene Swaggeriin

2. Syötä vaaditut tiedot

  • vaadittuja tietoja ovat etunimi, kutsumanimi, sukunimi, henkilötunnus, organisaation oma tunniste ja organisaation sähköpostiosoite
  • käytä testauksessa OPH:n Testioppijanumeroita tai omia testihetuja
    • huomaa, että rajapinta palauttaa oppijanumeron vain sellaisille hetuille, jotka löytyvät rekisteristä ja ovat VTJ-yksilöityjä
  • rajapinnassa on validointeja
    • henkilötunnuksen muoto
    • henkilötunnuksen loppuosa ei saa alkaa 9:llä tuotantoympäristössä
    • kutsumanimen pitää olla yksi etunimistä

{ "sahkoposti": "oph@testaa.fi", "henkilot": [ { "tunniste": "foo123", "henkilo": { "hetu": "060517-7737", "etunimet": "Olli Matti", "kutsumanimi": "Olli", "sukunimi": "Testaaja", } ] } } ] }

Useamman henkilön samanaikainen syöttäminen:

{
  "henkilot": [
    {
      "henkilo": {
        "etunimet": "string",
        "hetu": "string",
        "kutsumanimi": "string",
        "sukunimi": "string"
      },
      "tunniste": "string"
    },
    {
      "henkilo": {
        "etunimet": "string",
        "hetu": "string",
        "kutsumanimi": "string",
        "sukunimi": "string"
      },
      "tunniste": "string"
    },
    ...
  ],
  "sahkoposti": "string"
}


Esimerkki

3. Poimi vastauksesta batch id talteen

  • Tarvitset batch-id:tä, kun haet vastauksen.
  • Batch-id vastauksen muoto on seuraavanlainen:

{   "id": 164087967,   "kasiteltavia": 1,   "kasiteltyja": 0,   "kasitelty": false }

Esimerkki


4. Syötä batch id sille varattuun kenttään

  • Syötä batch id ja paina Execute


Esimerkki


5. Ota talteen oppijanumero 

  • Pysyvä yksilöivä tunniste löytyy henkilön "oppijanumero" attribuutista
  • Väliaikainen henkilö-oid löytyy henkilön "oid" attribuutista. Jos oppijanumero on tyhjä (null), tarkista virkailijan Opintopolun käyttöliittymästä, miksi oppijanumero ei palaudu. Mikäli tiedot ovat oikein, tee oppijan luonti myöhemmin uudelleen ja varmista, että oppijanumero palautuu. Ole tarvittaessa yhteydessä asiakaspalveluun (yhteisetpalvelut(a)opintopolku.fi)
  • Lue lisää oppijanumerosta: Mikä on oppijanumero?
  • Vastaus on muotoa:

{   "id": 164087967,   "kasiteltavia": 1,   "kasiteltyja": 1,   "kasitelty": true,   "henkilot": [     {       "tunniste": "foo123",       "henkilo": {         "oid": "1.2.246.562.24.87306153182",         "oppijanumero": null,       }     }   ] }


Esimerkki oppijanumerosta

  • oid: löytyy mutta ei ole relevantti
  • oppijanumero: löytyy ja otetaan talteen
  • esimerkkitapaukseen on myös linkitetty toinen identiteetti, jolla on toinen oid, joka ei palaudu rajapinnan kautta


Esimerkki oppijanumeron puuttumisesta

  • oid: löytyy mutta ei ole relevantti
  • oppijanumero: puuttuu, joten henkilöä ei ole yksilöity. Edellyttää toimenpiteitä. Ks. kohta Virhetilanteet.

Esimerkki passivoidusta henkilöstä, joka on VTJ-yksilöity

  • passivoitu: true, oppijanumero: säilyy, koska se on pysyvä. Passivointi voi johtua esimerkiksi henkilön menehtymisestä.


Esimerkki oppijanumeron ja oid:n välisestä erosta sekä linkitetystä henkilöstä käyttöliittymässä

1. Oppijanumero löytyy, henkilö on yksilöity

2. Oppijanumero löytyy, mutta se on eri kuin henkilön oid.

Pollaa halutessasi oppijan luonnin prosessia

  • Oppijoiden luontiprosessia voi pollata seuraavalla komennolla:
curl -H 'Caller-Id: testi' -H 'Content-Type: application/json' -H 'Cookie: JSESSIONID=<kohdassa 1. haettu JSESSIONID>' -i 
'https://virkailija.testiopintopolku.fi/oppijanumerorekisteri-service/yleistunniste/tuonti=<kohdassa 4. haettu batch id>'

Oppijanumerorajapinnan kutsumisen esimerkki

Javalla koodattu pelkistetty esimerkki Oppijanumerorekisterin CAS-autentikoidun rajapinnan kutsumisesta löytyy GitHubista:

github.com/Opetushallitus/oppijanumerorekisteri/.../example/Main.java

Vastausvirheet

  • HTTP 302
    Rajapinta vastaa HTTP 302 Found -uudelleenohjauksella opintopolun virkailijan login sivulle, jos rajapintaa kutsuu ilman autentikoitumista.
    Esimerkki: github.com/Opetushallitus/oppijanumerorekisteri/.../example/CasAuthenticatedServiceClient.java
  • HTTP 400
    Rajapinta vastaa HTTP 400 Bad Request -virhekoodilla kun rajapintaan antamasi syöte on virheellinen.
    Esim. yleistunnisterajapinta vastaa virheellisen henkilötunnuksen vastaanottaessaan seuraavasti

    Request:
    POST /oppijanumerorekisteri-service/yleistunniste/hae
    {"etunimet":"Magdalena Testi","hetu":"virheellinen hetu","kutsumanimi":"Magdalena","sukunimi":"Sallinen-Testi"}
    
    Response:
    {
      "timestamp": 1698845664893,
      "status": 400,
      "error": "Bad Request",
      "exception": "org.springframework.web.bind.MethodArgumentNotValidException",
      "message": "Validation failed for argument [0] in public fi.vm.sade.oppijanumerorekisteri.dto.YleistunnisteDto fi.vm.sade.oppijanumerorekisteri.controllers.YleistunnisteController.yleistunnisteenHaku(fi.vm.sade.oppijanumerorekisteri.dto.HenkiloExistenceCheckDto): [Field error in object 'henkiloExistenceCheckDto' on field 'hetu': rejected value [virheellinen hetu]; codes [ValidateHetu.henkiloExistenceCheckDto.hetu,ValidateHetu.hetu,ValidateHetu.java.lang.String,ValidateHetu]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [henkiloExistenceCheckDto.hetu,hetu]; arguments []; default message [hetu]]; default message [invalid.hetu]] ",
      "path": "/oppijanumerorekisteri-service/yleistunniste/hae"
    }
  • HTTP 401
    Rajapinta vastaa HTTP 401 Unauthorized kahdessa eri tilanteessa ellei toisin muutoin mainita:
    1. Sessio oppijanumerorekisteriin on vanhentunut. Autentikoidu uudelleen CAS:n kautta.
    2. Käyttöoikeudet ovat puutteelliset. Varmista että palvelukäyttäjälle on myönnetty riittävät käyttöoikeudet ja autentikoidu uudelleen CAS:n kautta.
    Esimerkki: github.com/Opetushallitus/oppijanumerorekisteri/.../example/CasAuthenticatedServiceClient.java

Vaihtoehtoinen hakutapa


Vaihtoehtoinen hakutapa

  1. hae tarvittava sessio-avain
    1. kirjaudu sisään kohdeympäristöön ja etsi selaimen kekseistä onr:n JSESSIONID)
  2. luo luonti.json
  3. käynnistä oppijoiden/henkilöiden luonti
    1. luonti tapahtuu oheisen mukaisella skriptillä: curl -X PUT -H 'Caller-Id: testi' -H 'CSRF: testi' -H 'Content-Type: application/json' -H 'Cookie: CSRF=testi;JSESSIONID=<kohdassa 1. haettu JSESSIONID>' -i
      'https://virkailija.testiopintopolku.fi/oppijanumerorekisteri-service/yleistunniste' --data-binary '@<kohdassa 2. luotu tiedosto>'

Virhetilanteet

Yleistunniste -rajapinnan kautta ei ole mahdollista siirtää henkilöitä oppijanumerorekisteriin virheellisillä tiedoilla. 

Rajapinnassa olevat virheviestit on kuvattu ylempänä.

Miten yleistunniste -rajapinta eroaa oppijan controller -rajapinnasta?

Erot suhteessa korkeakoulujen oppija controller -rajapintaan:

  • vaaditaan henkilötunnus pakollisena tietona, jos oppija/henkilön luodaan rajapinnan kautta
  • henkilötunnuksettomat oppijat/henkilöt luodaan manuaalisesti käyttöliittymän kautta (https://virkailija.testiopintopolku.fi/henkilo-ui/oppija/luonti
  • piilotetaan paluusanomasta ylimääräiset tiedot (muut kuin oppijanumero ja henkilö-oid:t) 
  • eri käyttöoikeudet 
  • POST-kutsulla on mahdollista hakea/luoda oppijanumero ilman että siitä tulee merkintää Opintopolun käyttöliittymäraporteille
  • muutostietorajapintaa ei ole toteutettu yleistunnisteen käyttötapauksiin


Sisällys

Yhteystiedot

Yleiskäyttöisten palvelujen palveluosoite:

yhteisetpalvelut(at)opintopolku.fi 

  • No labels