Oppijanumeropalvelun testaus (suppeat tiedot)

Käyttöoikeudet

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

Vaihekohtainen testausohje

1. Kirjaudu sisään ja mene Swaggeriin

• Kirjaudu sisään valittuun ympäristöön (https://virkailija.testiopintopolku.fi/) palvelukäyttäjällä, jolla on vaadittu käyttöoikeus
  
  • varmista, että cas-autentikaatio onnistuu
• 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 Testioppijanumerot 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

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