Ohjeita tiedonsiirtoihin koulutuksen järjestäjän järjestelmästä eHOKSiin

HOKSin luonnilla tarkoitetaan opiskelijan HOKSin ensimmäistä tallennusta eHOKSiin. eHOKS muodostaa HOKSille eHOKS id:n. Kun tietoja tallennetaan tiedonsiirtona rajapinnan kautta, eHOKS lähettää eHOKS id:n koulutuksen järjestäjän järjestelmään.

HOKSin luonnissa eHOKSiin täytyy tallentaa vähintään seuraavat tiedot:

• opiskeluoikeuden oid
• oppijanumeron oid
• HOKSin ensikertaisen hyväksymisen päivämäärä
• opiskelijan ajantasainen sähköpostiosoite
• tieto osaamisen hankkimisen tarpeesta

Katso tarkemmin Usein kysytyissä kysymyksissä: Vastauksia usein kysyttyihin kysymyksiin

Opintohallintojärjestelmästä tehtäviä tiedonsiirtoja varten koulutuksen järjestäjä tarvitsee eHOKS-palvelukäyttäjätunnuksen. Koulutuksen järjestäjä (Opintopolun vastuukäyttäjä) luo tunnuksen virkailijan Opintopolussa. Tunnus (käyttäjätunnus ja salasana) tallennetaan omaan opintohallintojärjestelmään. Salasanan pitää olla vähintään 10 merkkiä. Sen pitää sisältää isoja ja pieniä kirjaimia, numero ja erikoismerkki.

Jos tiedonsiirto ei ollenkaan onnistu (yksikään siirto ei mene läpi), tarkista, että käyttäjätunnus ja salasana on varmasti tallennettu opintohallintojärjestelmään täsmälleen siinä muodossa kuin se on luotu virkailijan Opintopolkuun. Huom. Käyttäjätunnus on koulutuksen järjestäjän antama käyttäjätunnus, ei OID-numero.

Varmista myös, että palvelukäyttäjätunnukseen on lisätty käyttöoikeus "eHOKS-palvelukäyttäjä (järjestelmän oikeus, ei henkilölle)" ja se on voimassa.

Ohje palvelukäyttäjätunnuksen tekemiseen: eHOKS-käyttöoikeudet (integraatiolla tietoa siirtävät)

Jos nämä toimenpiteet eivät auta, ota yhteyttä eHOKSin asiakaspalveluun ehoks@opintopolku.fi.

Kuvaa mahdollisimman tarkasti, mitä teit, mihin aikaan ja millaisen virheilmoituksen sait.

Tietoa virhekoodeista löytyy myös sivulta Vastauksia usein kysyttyihin kysymyksiin.

400 - "HOKS with the same opiskeluoikeus-oid already exists"

eHOKSiin on jo luotu opiskeluoikeus kyseiselle opiskeluoikeudelle. Sen jälkeen, kun HOKS on luotu eli siirretty ensimmäisen kerran eHOKSiin, tietoja päivitetään eHOKSiin eHOKS-id:n avulla.

Vaihtoehto 1: Yritetään päivittää jo olemassa olevaa eHOKSia, mutta eHOKS ID -kenttä lähtevissä tiedoissa on jäänyt tyhjäksi tai siinä on virheellinen eHOKS ID. Jos eHOKS palauttaa tiedonsiirrossa otsikossa mainitun virheilmoituksen, syy voi olla se, että opintohallintojärjestelmä yrittää lähettää tiedonsiirtoa HOKSin luontina eikä päivityksenä. Joissain tapauksissa on käynyt ilmi, että HOKSin luonnin yhteydessä syntyvä eHOKS id ei ole palautunut tai tallentunut koulutuksen järjestäjän järjestelmään, vaikka id on tallentunut eHOKSin tietokantaan HOKSin luonnin eli ensimmäisen tiedonsiirron yhteydessä. Kun tällaisessa tapauksessa HOKS-tietoja päivitetään opintohallintojärjestelmästä eHOKSiin, opintohallintojärjestelmä katsoo, että kyseessä on HOKSin luonti (koska opintohallintojärjestelmässä ei ole eHOKS id:tä), mutta eHOKS katsoo, että HOKS on jo luotu (koska kyseiseen opiskeluoikeuteen jo löytyy id eHOKSin kannasta). 

Toimintaohjeena: tarkista, löytyykö opiskelijan HOKS jo eHOKSista ja löytyykö opintohallintojärjestelmästä eHOKS id. Jos opintohallintojärjestelmässä on eHOKS id, varmista vielä, että se on sama kuin eHOKSissa. eHOKS id näkyy opiskelijan HOKSin tiedoissa. eHOKS id:stä löydät tietoa alempana olevan kysymyksen kohdalta (otsikko Mikä on eHOKS id ja mihin sitä tarvitaan?). Tarkemmin tiedonsiirtovirheen selvittämiseksi kannattaa ottaa ensin yhteyttä järjestelmätoimittajan asiakastukeen.

Vaihtoehto 2: Yritetään luoda uutta eHOKSia, mutta eHOKS ID-kenttään on jäänyt opiskelijan jonkin toisen opiskeluoikeuden eHOKS ID.

Toimintaohjeena: Jos haluat luoda uuden eHOKSin, tarkista, että opintohallintojärjestelmässä eHOKS ID -kenttä on tyhjä. Varmista lisäksi, että opiskeluoikeuden oid on oikea.

400 - "Opiskeluoikeus sisältyy toiseen opiskeluoikeuteen"

HOKS-tietoja yritetään tallentaa opiskeluoikeuteen, joka on linkitetty toisen koulutuksen järjestäjän opiskeluoikeuteen. Virhekoodin viestinä on tällöin "Opiskeluoikeus sisältyy toiseen opiskeluoikeuteen". Opiskeluoikeuksien linkityksen tarkistamisella estetään hankintakoulutuksen toteuttajan tekemä tietojen tallentaminen. HOKS-tiedot tallentaa eHOKSiin päävastuullinen koulutuksen järjestäjä, joka on hankintakoulutuksessa koulutusta hankkiva (ostava) osapuoli.

400 - Bad Request "Opiskeluoikeus update not allowed!"

Virheilmoitus tulee, jos päivitystiedoissa on eri opiskeluoikeus-oid kun alkuperäisessä HOKSissa. Virhe voi syntyä myös, jos opiskelijan oppijanumero on vaihtunut.

Toimintaohje: Jos eHOKSissa näkyvä opiskeluoikeus on mitätöity Koskesta tai eHOKSissa näkyvä oppijanumero on vaihtunut Koskessa, tulee eHOKS poistaa ja laatia uusi eHOKS oikeilla tiedoilla.

400 - Yhteysvirhe 400 Bad Request
{"aiemmin-hankitut-ammat-tutkinnon-osat":[{"tutkinnon-osa-koodi-uri":"(not (re-find #\"^tutkinnonosat_\\d+$\" \"\"))"}]}

{"aiemmin-hankitut-ammat-tutkinnon-osat":[null,{"tutkinnon-osa-koodi-uri":"(not (re-find #\"^tutkinnonosat_\\d+$\" \"\"))"}]}

Koodi on syötetty väärässä muodossa, eli siihen on tullut esim. ylimääräinen merkki tai välilyönti.

Koodin tilalla on syötetty tyhjä merkkijono.

401

Tarvittava palvelukäyttäjätunnus puuttuu tai kyseisellä tunnuksella ei ole oikeutta tallentaa tietoa kyseiseen opiskeluoikeuteen.

403

Tiedonsiirrossa käytetty tunnistautuminen on väärän tyyppinen.

404 - "HOKS not found"

Sellaista HOKSia tai opiskeluoikeutta, johon tietoja yritetään siirtää, ei löydy eHOKSista. Syynä voi olla esimerkiksi se, että opiskeluoikeus on mitätöity tai aiemmin luotu HOKS on jostain muusta syystä poistettu eHOKSista.

423

Käyttäjätunnus on lukkiutunut. Käyttäjätunnus lukkiutuu määräajaksi, jos tiedonsiirtoa yritetään tehdä virheellisellä palvelukäyttäjätunnuksella liian monta kertaa. Yleisimmin syynä on se, että opintohallintojärjestelmässä oleva palvelukäyttäjän käyttäjätunnus ja/tai salasana eivät täsmää Opintopolussa oleviin tietoihin. Tarkista, että opintohallintojärjestelmässä on sama käyttäjätunnus kuin Opintopolussa. Vaihda palvelukäyttäjätunnuksen salasana Opintopolussa ja tallenna uusi salasana opintohallintojärjestelmään. Odota, että palvelukäyttäjätunnuksen lukkiutuminen on avautunut. Lukkiutumisaikaa ei valitettavasti ole mahdollista tarkistaa, mutta se on sitä pidempi, mitä useammin ja mitä isommalla tiedonsiirtomassalla tiedonsiirtoa on yritetty tehdä sen jälkeen, kun eHOKSista on tullut virheilmoitus 423. Lukkiutuminen voi kestää muutamasta tunnista muutamaan päivään.

500 - "Yhteysvirhe 500 Server Error"

Tämä virheilmoitus voi johtua useista syistä. Joissain tapauksissa kyse saattaa olla satunnaisesta ja hetkellisestä yhteyskatkoksesta. Voit kokeilla tiedonsiirtoa hetken kuluttua uudestaan. Olemme viime aikoina kuitenkin huomanneet myös toistuvampaa 500-virheen esiintymistä joidenkin opiskelijoiden HOKS-siirtojen kohdalla. Ongelma on selvityksessä ja korjattavana. Tiedotamme eHOKS-käyttäjiä, kun ongelma on korjattu. Jos yritit tiedonsiirtoa uudelleen ja saat edelleen 500-virheen, kyse on todennäköisesti selvityksessä olevasta ongelmasta. Tee tiedonsiirto uudestaan sen jälkeen, kun olemme tiedottaneet ongelman korjaantumisesta. Yksittäisistä 500-virheistä ei tarvitse erikseen ilmoittaa eHOKSin asiakaspalveluun.

(päivitetty 8.12.2020)

Muita virhetilanteita:

Virheilmoitus "Koodistoa osaamisentodentamisenprosessi ei löytynyt Opintopolun koodisto-palvelusta" palautetaan, jos eHOKSiin on yritetty tuoda jokin muu osaamisen todentamisen koodi kuin mikä eHOKSissa on käytössä. eHOKSissa vaihtoehdot ovat Suoraan, Arvioijien kautta tai Ohjattu näyttöön. Jos opintohallintojärjestelmässä on käytettävissä muita vaihtoehtoja, niiden tuominen eHOKSiin ei onnistu, koska eHOKS vaatii tiedon osaamisen todentamisen tavasta niillä vaihtoehdoilla, jotka löytyvät Opintopolun koodistosta. Opintohallintojärjestelmät käyttävät Opintopolun koodistoa.

(vastausta päivitetty edellisen kerran 29.9.2020)

1. Varmista, että palvelun käyttöönotto on tehty järjestelmätoimittajan ohjeistamalla tavalla.
2. Tarkista palvelukäyttäjätunnus. Katso tarkemmin yllä oleva kohta palvelukäyttäjätunnuksesta.
3. Jos kohta 1 näyttäisi olevan ok, mutta siirto ei mene läpi, kokeile vaihtaa palvelukäyttäjätunnuksen salasana. Tallenna uusi salasana opintohallintojärjestelmään. Sulje ja avaa opintohallintojärjestelmä. Kokeile siirtää. Jos virheellisellä salasanalla tehdään tiedonsiirtoyritys liian monta kertaa, palvelukäyttäjätunnus lukkiutuu määräajaksi (virhekoodi 423). Kts. alla erillinen kohta tästä asiasta.
4. Jos tiedonsiirto ei edelleenkään onnistu, ota yhteyttä Opetushallituksen asiakaspalveluun ehoks@opintopolku.fi

Virhekoodi 423 tarkoittaa sitä, että palvelukäyttäjätunnus on lukkiutunut. Jos tiedonsiirtoa yritetään liian monta kertaa esim. virheellisellä salasanalla, käyttäjätunnus lukkiutuu määräajaksi.

Toimi näin, jos saat virheilmoituksen 423:

1. Lopeta siirtoyritykset. Jokainen uusi siirtoyritys lukkiutumisen jälkeen pidentää lukitusaikaa.
2. Vaihda palvelukäyttäjätunnuksen salasana virkailijan Opintopolussa. Salasanan oppilaitoksen palvelukäyttäjätunnukseen voi vaihtaa koulutustoimijan vastuukäyttäjä. Pyydä tarvittaessa neuvoa eHOKSin asiakaspalvelusta ehoks@opintopolku.fi.
3. Tallenna uusi salasana opintohallintojärjestelmään järjestelmätoimittajan ohjeiden mukaisesti.
4. Odota, että lukituksen määräaika kuluu umpeen. Valitettavasti tarkka määräaika ei ole tarkistettavissa. Jos yritit siirtoa kerran pienellä määrällä opiskelijoita vielä sen jälkeen, kun olit jo saanut ensimmäisen kerran virhekoodin 423, odota 2-3 h ennen uutta siirtoyritystä. Jos yritit siirtää isoa määrää opiskelijoita lukittumisen jälkeen, määräaika voi olla melko pitkä, jopa 1-2 vrk.
5. Yritä siirtoa uudestaan. Kokeile ensin yhden HOKSin siirtämisellä. Jos se onnistuu, siirrä loput.

Jos eHOKS ilmoittaa virheestä yksittäisen opiskelijan tietojen siirtymisessä (osalla opiskelijoista tiedot siirtyy, osalla ei) , syy saattaa olla jokin näistä:

• jokin pakollinen tieto puuttuu (esimerkiksi HOKSin ensikertaisen hyväksymisen päivämäärä)
• kyseiselle opiskeluoikeudelle on jo luotu eHOKS (tehty ensimmäinen tiedonsiirto)
• oppijanumero tai opiskeluoikeuden oid on virheellinen (ei vastaa Koskessa olevaa tietoa)
• opiskeluoikeutta (opiskeluoikeuden oid-numeroa, johon tietoja yritetään siirtää) ei löydy Koskesta. Syy voi olla esimerkiksi se, että opiskeluoikeus on mitätöity Koskesta.
• opiskeluoikeus on päättynyt. Päättyneeseen opiskeluoikeuteen liittyvään HOKSiin ei voi tuoda enää uutta tietoa.
• oppilaitoksella ei ole oikeutta päivittää tietoja kyseiseen opiskeluoikeuteen (opiskeluoikeus on jonkin muun oppilaitoksen antama).

Jos ongelman syy ei selviä virheilmoituksen pohjalta, ota yhteyttä asiakaspalveluun ehoks@opintopolku.fi. Ilmoita viestissäsi seuraavat asian tarkempaa tutkimista varten tarvittavat tiedot:

• tiedonsiirtoyrityksen kellonaika

• oppijanumero ja opiskeluoikeuden oid, joihin liittyviä tietoja yritettiin siirtää

• palvelukäyttäjätunnus, jolla tiedonsiirtoyritys tehtiin.