Tämä dokumentaatio tarkentaa Työmarkkinatorin työnhakuprofiilien tuontirajapinnan teknisiä vaatimuksia ja kuvaa tarkemmin varsinaisen rajapinnan käytön. Rajapinnan käyttöönoton prosessi on kuvattu tarkemmin Työmarkkinatorin sivulla. Samasta paikasta löytyvät myös työnhakuprofiilien tuontirajapintaan liittyvien rajapintojen (P51 ja P64) OpenApi-kuvaukset.
Rajapinnan avulla käyttäjään liittyviä työkokemus ja osaamistietoja voidaan tuoda ulkoisista palveluista osaksi Työmarkkinatorin työnhakuprofiilia. Tällaisia ulkoisia palveluita ovat esimerkiksi erilaiset osaamistietopankit ja toimialakohtaiset rekrytointipalvelut.
Työkokemus ja osaamistietojen siirto ulkoisista järjestelmistä Työmarkkinatorille vaatii aina käyttäjän antaman valtuutuksen. Tämä valtuutus annetaan Työmarkkinatorilla, jossa tarkennetaan myös mitä tietoja ollaan siirtämässä. Valtuutuksen jälkeen halutut tiedot siirretään osaksi käyttäjän Työmarkkinatorin työnhakuprofiilia.
Rajapinta käyttäjän työkokemus ja osaamistietojen tuontiin osaksi Työmarkkinatorin Työnhakuprofiilia tarjotaan KEHA-keskuksen integraatioalustan (Kipa) kautta. Tunnukset integraatioalustan käyttöön sekä siihen liittyvät IP-avaukset tehdään KEHA-keskuksen toimesta osana rajapinnan käyttöönoton prosessia. Rajapinnan käytössä tarvittavat tunnukset toimitetaan rajapinnan käyttäjälle tietoturvallisesti. Tarkempia tietoja käyttöönotosta löytyy Työmarkkinatorin sivuilta.
Tarkempi tietojen siirron prosessi on kuvattu alla olevassa kaaviossa. Eri vaiheisiin liittyvät kutsut ja niiden parametrit on avattu seuraavissa kappaleissa.
Käyttäjän työkokemus- ja osaamistietojen siirto Työmarkkinatorille alkaa sillä, että käyttäjä siirtyy ulkoisen järjestelmän toiminnosta valtuuttamaan tietojen siirron Työmarkkinatorille. Toiminto ohjaa käyttäjän Työmarkkinatorin tietojen siirron valtuutusprosessiin. Käyttäjä tunnistautuu Työmarkkinatorille ja valtuuttaa haluamansa tiedot tuotatavaksi ulkoisesta järjestelmästä osaksi Työmarkkinatorin työnhakuprofiilia. Näille tiedoille muodostetaan kertakäyttöinen ja väliaikainen valtuuskoodi, jota hyödynnetään varsinaisessa tietojen siirrossa.
Osana käyttäjän tekemää valtuutusprosessia muodostetaan myös tekninen access-token, jonka avulla järjestelmä pyytää
varsinaista valtuuskoodia tietojen siirtoa varten.
Alla kuvattu tuotantoympäristön osoitteet, joiden kautta käyttäjän valtuutus tietojen siirtoon tehdään.
Testiympäristössä urlin alkuosa on muotoa https://tmt-qa.tyomarkkinatori.fi. Testiympäristön käyttö on rajattu, joten
testaus pitää tehdä yhdessä KEHA-keskuksen kanssa. Endpoint ei versioidu.
https://tyomarkkinatori.fi/henkiloasiakkaat/oma-tyopolku/profiilitietojen-tuonnin-luvitushttps://tyomarkkinatori.fi/sv/personkunder/min-karriarstig/autentisering-for-import-av-profildatahttps://tyomarkkinatori.fi/en/personal-customers/my-job-path/permission-to-import-profile-dataUlkoisen järjestelmän on välitettävä valtuutus-kutsussa seuraavat tiedot. Kutsu lähtee käyttäjän selaimesta ulkoisen järjestelmän sivulta.
| Parametri | Formaatti | Kuvaus |
|---|---|---|
| response_type | String | Paluuviestin tyyppi, arvo täytyy olla code. |
| client_id | UUID | Työmarkkinatorin rajapinnan käyttöönoton yhteydessä luoma yksilöivä tunniste ulkoiselle järjestelmälle |
| redirect_uri | Prosentti-koodattu URL | URL, jonne Työmarkkinatori ohjaa käyttäjän profiilitietojen tuonnin valtuutuksen jälkeen. Urin on vastattava tietoa, joka ilmoitettiin rajapinnan käyttöönotton yhteydessä. |
| state | Base64URL | Ulkoisen järjestelmän määrittämä arvo, jonka avulla se voi säilyttää tilaa rajapinnan kutsun ja redirect-kutsun välillä |
curl -X GET https://tyomarkkinatori.fi/henkiloasiakkaat/oma-tyopolku/profiilitietojen-tuonnin-luvitus?
response_type=code&client_id=f47ac10b-58cc-4372-a567-0e02b2c3d479&
redirect_uri=https%3A%2F%2Fexampledomain.fi%2Fexamplepath&state=abcXYZ123
Onnistuneen käyttäjän valtuutuksen jälkeen valtuutuskutsu uudelleenohjataan osoitteeseen, jonka ulkoinen järjestelmä
välitti valtuutus-kutsun redirect_url query-parametrina.
| Parametri | Formaatti | Maksimikoko | Kuvaus |
|---|---|---|---|
| code | Base64URL | 100 merkkiä | Autorisointikoodi, Työmarkkinatorin generoima lyhytkestoinen (max 10min) ja kertakäyttöinen tunniste työnhakuprofiilin tuonnissa tarvittavan access_tokenin hakuun |
| state | Base64URL | - | Ulkoisen järjestelmän määrittämä arvo, jonka avulla se voi säilyttää tilaa rajapinnan kutsun ja redirect-kutsun välillä. Työmarkkinatori palauttaa parametrin arvon muuttamattomana takaisin ulkoiselle järjestelmälle. |
Valtuutuksen jälkeen palataan annettuun osoitteeseen
https://exampledomain.fi/exmaplepath?state=abcXYZ123
Jos pyynnössä välitetty redirect_uri on kelvollinen, mutta kutsun tiedot muuten puutteelliset, välitetään kutsujalle
seuraavat tiedot. Tiedot välitetään query-parametreina applcation/x-www-form-urlencoded formaatissa.
| Parametri | Kuvaus |
|---|---|
| error | Virhettä kuvaava koodi, arvot RFC 6749 kappaleesta 4.1.2.1 |
| error_description | Selväkielinen virheen tarkempi kuvaus |
| state | Jos asiakasjärjestelmä on välittänyt state-parametrin, se välitetään takaisin sellaisenaan |
https://exampledomain.fi/exmaplepath?error=access_denied&state=abcXYZ123
Jos kutsussa ei ole redirect_uri-parametria tai välitetty uri ei ole validi tai jos kutsussa ei ole client_id-parametria
tai välitetty client-id ei ole validi, kutsua EI uudelleenohjata redirect_uri osoitteeseen, vaan
Työmarkkinatorille kirjautuneelle käyttäjälle esitetään virheilmoitus.
Tässä kohdassa prosessia ulkoinen järjestelmä hakee käyttäjälle luodun kertakäyttöisen valtuuskoodin Kipa-integraatioalustan
palvelun P64 kautta Työmarkkinatorin taustapalvelusta. Tällä varmistetaan se, että siirtoa yrittää sama järjestelmä,
jonka kautta käyttäjä on valtuuden antanut. Kutsussa tarvittava KIPA-SubscriptionIdon sama kaikille palveluille.
Rajapinta on versioituva ja versionumero on osa rajapinnan URIa. Käyttävän järjestelmän tunnistautumisessa käytetään HTTP Basic Authenticationia (RFC2617). Ulkoisen järjestelmän on valitettävä valtuuskoodin haun kutsussa seuraavat tiedot.
https://api-qa.ahtp.fi/kipa/p64/v1/request-tokenhttps://api.ahtp.fi/kipa/p64/v1/request-token| Header | Formaatti | Kuvaus |
|---|---|---|
| Authorization | <client-id>:<client-secret> Base64-koodattuna | Clientin tunnistautumiseen tarvittavat tiedot HTTP Basic Authenticationin mukaisesti |
| KIPA-SubscriptionId | Kipa API key | Kipa-integraatioalustan käyttöön tarvittava tilausavain, jonka KEHA-keskus toimittaa |
| Content-type | application/x-www-form-urlencoded | Sisällön tyyppi |
| Parametri | Formaatti | Kuvaus |
|---|---|---|
| grant_type | string | Paluuviestin tyyppi, arvon täytyy olla authorization_code |
| code | Base64URL | Työmarkkinatorin luoma lyhytkestoinen ja kertakäyttöinen tunniste valtuutuskoodin hakuun |
| redirect_uri | Prosentti-koodattu URL | Työmarkkinatorin profiilin tuonnin valtuutuksessa käyttämä ulkoisen järjestelmän osoite, johon kutsu uudelleenohjataan |
curl -X POST https://api.ahtp.fi/kipa/p64/v1/request-token \
-H "Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW" \
-H "KIPA-SubscriptionId: <KIPA API key>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=1SnMFAfrkhrM0V_U9PlZf6ZfgxdjSgjEOz5Y4uxkuXxN3ZSeT84" \
-d "redirect_uri=https%3A%2F%2Fexampledomain.fi%2Fexamplepath"
Onnistuneessa kutsussa (http-status 200) tiedot välitetään vastauksen bodyssä (content-type: application/json)
| Parametri | Formaatti | Kuvaus |
|---|---|---|
| access_token | JWS Compact Serialization (RFC 7515) | Työmarkkinatorin allekirjoittama valtuuskoodi, jonka avulla ulkoinen järjestelmä voi tuoda valtuutetut työkokemus ja osaamistiedot osaksi Työmarkkinatorin työnhakuprofiilia |
| token_type | string | Tokenin tyyppi, arvo on bearer |
| expires_in | integer | Tokenin voimassaoloaika sekunneissa. Katso myös tunnisteessa välitettävä iat-claim |
| Claim | Kuvaus | Formaatti |
|---|---|---|
| typ | Tokenin media tyyppi (Type), arvo on JWT | String |
| alg | JWS:n allekirjoituksessa käytetty algoritmi, arvo on ES256 | String |
| Claim | Kuvaus | Formaatti | Esimerkki | Huomiot |
|---|---|---|---|---|
| jti | Tokenin tunniste (JWT ID) | UUID | 1c39e89b-7408-4368-a00b-90f1bbad7a05 | Tunniste on uniikki kaikkien tokenin myöntäjän (iss) luomien tokenien joukossa |
| client_id | Työmarkkinatorille rekisteröityneen ulkoisen järjestelmän tunniste (client-id) | UUID | 550e8400-e29b-41d4-a716-446655440000 | Työmarkkinatori luo tunnisteen rekisteröitymisen yhteydessä |
| exp | Tokenin vanhenemisen ajanhetki, jonka jälkeen token ei ole enää käytettävissä. Aika ilmaistaan sekunneissa ajanhetkestä 1970-01-01T00:00:00Z UTC tokenin vanhenemisen ajanhetkeen. | NumericDate | 1550668186 | |
| iat | Tokenin luontihetki, aika ilmaistaan sekunneissa ajanhetkestä 1970-01-01T00:00:00Z UTC tokenin luontihetkeen | NumericDate | 1550667586 | Luontihetkeä käytetään kun varmistetaan tokenin voimassaolo rajapinnassa välitettävää expires_in-parametrin arvoa vasten |
| iss | Tokenin myöntäjä | string | integraatiot.tyomarkkinatori.fi | |
| aud | Tokenin kohdeyleisö | string | integraatiot.tyomarkkinatori.fi/api/v1/import-profile | Tuontirajapinnan toteutus validoi aud-tiedon ja käsittelee kutsun kokonaisuudessaan vain, jos se kuuluu aud-tiedossa määritettyyn kohdeyleisöön |
| sub | Tokenin kohdehenkilö, Työmarkkinatorin työnhakuprofiilin omistavan käyttäjän yksilöivä tunniste | UUID | b7fa721e-07c4-4f17-8a82-75d7bb3f33e4 | |
| operation | Operaatio, johon tokenin omaava kutsuja on valtuutettu | string | profile_import | Profiilin tuonti |
| data | Työnhakuprofiilin data | json | Rajapinnan YAML-kuvauksen mukainen rakenne |
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIERvZSIsImlhdCI6MTY5MzAwMDAwMH0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"token_type": "bearer",
"expires_in": 600
}
Epäonnistuneessa kutsussa (http-status 400) tiedot välitetään responsen bodyssä (content-type: application/json)
| Parametri | Kuvaus | Sallitut arvot |
|---|---|---|
| error | Virheettä kuvaava koodi | Katso arvot RFC 6749 kappaleesta 5.2 |
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_request"
}
Varsinainen tietojen siirto tapahtuu valtuuskoodin haun jälkeen Kipa-integraatioalustan palvelun P51 kautta
Työmarkkinatorin taustapalvelusta. Työnhakuprofiiliin siirrettävät datat ovat kutsun payloadissa
rajapinnan YAML-kuvauksen
mukaisessa json-formaatissa. Kutsussa olevien tietojen on myös vastattava tietoja, jotka käyttäjä siirtoon valtuutti.
https://api-qa.ahtp.fi/kipa/p51/v1/profilehttps://api.ahtp.fi/kipa/p51/v1/profile| Header | Formaatti | Kuvaus |
|---|---|---|
| Authorization | JWT Bearer tokenina | Työnhakuprofiilin siirron valtuuskoodista saatu access-token |
| KIPA-SubscriptionId | Kipa API key | Kipan käyttöön tarvittava tilausavain, jonka KEHA-keskus toimittaa |
| content-type | JSON | Sisällön tyyppi |
| Parametri | Formaatti | Kuvaus |
|---|---|---|
| profile | JSON | Työnhakuprofiilin tiedot, P51-tmt-profile-tuonti-V1.yaml tietomallin mukaisesti |
Vastauksessa ei välitetä responsen bodya.
| Koodi | Kuvaus | Tilanne | Esimerkkejä / lisätietoja |
|---|---|---|---|
| 204 | Ok | Tiedot tallennettu onnistuneesti Työmarkkinatorin työnhakuprofiiliin | |
| 400 | Bad request | Kutsusta puuttuu pakollisia tietoja tai tiedot sisältävät rajapintamäärityksen vastaisia tietoja tai merkkejä | Esimerkiksi profiilin tiedoissa on ei-sallittuja merkkejä |
| 401 | Unauthorized | Access tokenin tai sen allekirjoituksen validointi epäonnistuu | Token on vanhentunut, jo käytetty tai muulla tavalla epävalidi. JWS:n on allekirjoittanut, joku muu kuin odotettu taho tai allekirjoitukseen käytetty avain ei ole yhteensopiva Työmarkkinatorilla olevan vastaavan julkisen avaimen kanssa. |
| 403 | Forbidden | Käyttäjä yrittää suorittaa operaatiota, johon hänellä ei ole valtuuksia | Käyttäjä tuo muita profiilitietoja kuin mihin hän on antanut valtuutuksen |
| 404 | Not Found | Access tokenin sub-claimissa yksilöityä käyttäjää ei ole Työmarkkinatorilla | |
| 405 | Method Not Allowed | Kutsuja käyttää http-metodia, joka ei ole sallittu pyydetylle resurssille | Esimerkiksi kutsuja käyttää GET, POST tai DELETE-metodia |
| 406 | Not Acceptable | Kutsujan välittämä viestin sisällön tietotyyppi ei ole rajapintamääritysten mukainen | Kutsuja välittää esimerkiksi kuvia tai muuta kuin application/json -muotoista tietoa |
| 500 | Internal Server Error | Palvelun toteutus päätyy vikatilaan, josta se ei osaa toipua | Ohjelmointivirhe |
| 501 | Not Implemented | Kutsuja käyttää http-metodia, jota palvelimella ei tueta ollenkaan | Käyttäjä kutsuu rajapintaa esimerkiksi metodilla PATCH tai OPTIONS |
Työnhakuprofiiliin liittyvät erilaiset koodistoarvot ovat saatavilla Työmarkkinatorin koodistopalvelusta. Alla on kuvattu eri tietojen koodistot. Myös OpenApi-kuvauksessa on tieto attribuuttiin liittyvästä koodistosta.
Koodiston json-rakennetta luetaan siten, että koodiarvot löytyvät tunnus-elementistä ja tunnukseen liittyvä kuvaus
lokalisoituna selite-elementistä. Jokaiseen koodiarvoon liittyy myös voimassaoloaika. Koodistossa saattaa olla siis
koodiarvoja, jotka on jo poistettu käytöstä. Tälloin koodeilla on loppupaiva-tieto. Joillain koodistoilla voi olla
laajennuksia, joilla koodiston hyödyntämistä voidaan tarkentaa. Esimerkiksi osajoukko-laajennuksella halutaan rajata
vain tietyt kooditunnukset tiettyyn tarkoitukseen. Järjestysnumero-laajennus kertoo koodien halutun järjestyksen
esimerkiksi valintalistoissa. Lisäksi joitain koodiarvoja hyödynnetään myös muissa järjestelmissä ja erityisesti
asiakkaalle Työmarkkinatorilla näytettävät tekstit on tarkennettu AsiakkaalleNaytettavaSelite-laajennuksella.