Näin otan IN-rajapinnan käyttöön
Integraation tekeminen jostakin toisesta järjestelmästä PTV:hen edellyttää käyttöluvan hakemista.
Jos olet tekemässä kokonaan uutta IN-integraatiota PTV:hen, noudata Perusohjetta IN-integraation käyttöön ottamiseksi.
Jos olet ottamassa käyttöön jonkun IT-toimittajan toteuttamaa valmista IN-integraatiota PTV:hen (esim. Pinmeto tai Fonecta Connect), noudata ohjetta IN-integraatio IT-toimittajan järjestelmästä PTV:hen.
Jos ylläpidät organisaatiosi liikuntapaikkatietoa LIPAS-järjestelmästä ja haluat tuoda tiedot PTV:hen, noudata ohjetta IN-integraatio LIPAS.fistä PTV:hen.
Jos et tiedä, mitä ohjetta sinun pitäisi noudattaa, ota yhteyttä ptv-tuki@dvv.fi.
Varmista edellytykset IN-rajapinnan käyttöönotolle
Organisaatiosi voi toteuttaa IN-integraation PTV:hen vain, jos sillä on jokin oma järjestelmä, jossa tieto on
- ajantasaista
- asiakaslähtöisesti kuvattua
- ja PTV-tietomallin kanssa rakenteisesti yhteensopivaa.
Jos järjestelmät ovat hyvin erilaiset tai lähdejärjestelmän dataa ei ylläpidetä säännöllisesti, IN-integraatiota ei tule toteuttaa. Tällaiset integraatiot ovat kalliita, vaikeasti ylläpidettäviä ja niistä aiheutuu huomattava määrä teknisiä virheselvittelyjä, jotka työllistävät sekä asiakasta että DVV:tä.
Tee tietomallimäppäys
Integraatiototeutuksen aluksi organisaatiosi tulee tehdä lähdejärjestelmän ja PTV:n välinen tietomallimäppäys, jossa varmistetaan tietojen yhteismitallisuus. Lue tietomallista lisää sivulta Palvelutietovarannon tietomalli.
Tähän vaiheeseen on syytä käyttää riittävästi aikaa ja resursseja, jotta integraatiosta tulee toimiva ja vältytään turhilta tuotantovaiheen häiriötilanteilta sekä huonolaatuiselta datalta, jota ei voi jatkohyödyntää. Otattehan organisaationne PTV-datan laadusta ja asiakaslähtöisyydestä vastaavat henkilöt mukaan mäppäyksen tekoon.
Varaudu kehittämään lähdejärjestelmää
Jos organisaatiosi lähdejärjestelmän data ei vastaa kaikilta osin PTV:n tietomallia tai laatuvaatimuksia, mutta IN-integraatio halutaan silti toteuttaa, organisaatiosi tulee varautua kehittämään järjestelmäänsä tai parantamaan datansa laatua PTV-yhteensopivaksi ennen integraation toteuttamista. Järjestelmään täytyy esimerkiksi lisätä puuttuvat pakolliset tietokentät ja tietueet pitää muuttaa samaan muotoon kuin PTV:ssä.
Toinen vaihtoehto on tuottaa joidenkin puuttuvien tekstikenttien tiedot koneellisesti. Jos näin toimitaan, organisaatiosi on huolehdittava, että tuotettu data on asiakaslähtöistä.
Hae käyttölupaa
Hae käyttölupaa tämän sivuston sivun Näin teen käyttölupahakemuksen ohjeiden mukaisesti.
Jos organisaatiosi on jo ottanut Palvelutietovarannon käyttöönsä ja tarvitset pelkän IN-integraation käyttöluvan, pääset tekemään käyttölupahakemuksen vahvasti tunnistautuneena Suomi.fi-palveluhallinta-sivuston kirjautuneen käyttäjän etusivulta (dashboard) Palvelutietovaranto-kohdasta Hae käyttölupaa-painikkeen takaa.
Varmista ajantasaisten tietojen siirtyminen
Integraatio tulee toteuttaa siten, että lähdejärjestelmässä dataan tehtävät muutokset tuodaan säännöllisesti PTV:hen. Lisäksi kaikkien palveluiden ja asiointikanavien laatu ja ajantasaisuus tulee tarkistaa lähdejärjestelmässä säännöllisesti, kuitenkin vähintään kerran vuodessa.
Perehdytä tiedon ylläpitäjät
Lähdejärjestelmän sisällöntuottajien on tärkeää ymmärtää, että integraation valmistuttua heidän kuvaamansa sisällöt siirtyvät myös PTV:hen ja niiden täytyy olla PTV-yhteensopivia. Organisaatiosi käyttäjät tulee kouluttaa ja sisäiset ohjeenne tulee päivittää.
Toteuta ja testaa integraatio
IN-integraation toteuttamisessa ja testaamisessa ohjeistetaan sivulla Tekninen dokumentaatio integraation toteuttajalle.
Kun integraatio on toteutettu, tulee sen tekninen valmius testata ja DVV:lle toimittaa testausraportti.
Tarkista tietojen asiasisältö ja laatu
Organisaation PTV-pääkäyttäjän tulee tarkistaa rajapinnan kautta lähetettyjen tietojen asiasisältö, korjata mahdolliset virheet lähdejärjestelmään ja toimittaa DVV:lle testausraportti.
Lue lisää sivuston sivulta Sisällöntuotanto IN-rajapinnan kautta
Tee mahdolliset korjaukset ja tuotantoasennus
DVV arvioi testausraporttien perusteella, voidaanko organisaatiollesi myöntää IN-rajapinnan tuotantotunnukset. Tämä voi vaatia useita iteraatiokierroksia.
Kun testiraportit on hyväksytty, DVV toimittaa erikseen sovitusti organisaatiollesi tai sovellustoimittajallenne käyttölupahakemuksessa yksilöityyn osoitteeseen API-käyttäjäoikeudet PTV:n tuotantoympäristöön. Tämän jälkeen voitte tehdä tuotantoasennuksen.
Tämä ohje on kirjoitettu organisaatiolle, joka ottaa käyttöön IN-rajapinnan kautta PTV:hen valmiiksi integroidun järjestelmän, esimerkiksi yhteystietojen hallintajärjestelmän (esim. Fonectan Kontakti Pro tai PinMeTo).
Siirry tekemään IN-rajapinnan käyttölupahakemus
Jos organisaatiosi ei ole vielä ottanut Palvelutietovarantoa käyttöön, hae käyttölupaa sivun Näin teen PTV-käyttölupahakemuksen ohjeistuksen mukaisesti.
Jos organisaatiosi on jo ottanut Palvelutietovarannon käyttöönsä ja tarvitset pelkän IN-integraation käyttöluvan, pääset tekemään käyttölupahakemuksen vahvasti tunnistautuneena Suomi.fi-palveluhallinta-sivuston kirjautuneen käyttäjän etusivulta (dashboard) Palvelutietovaranto-kohdasta Hae käyttölupaa-painikkeen takaa.
Täytä käyttölupahakemus
Käyttölupahakemuksessa on viisi vaihetta:
- Organisaation perustiedot (nimi, Y-tunnus ja osoite)
- Organisaation yhteyshenkilöiden tiedot
- PTV:n IN-rajapintaan liittyvät tiedot ja liitettävän tietojärjestelmän tiedot
Kerro kohdassa liitettävän tietojärjestelmän tiedot, minkä järjestelmän kautta tehdyn IN-integraation organisaatiosi ottaa käyttöön ja alihankkija (IT-toimittaja), jonka integraatio on kyseessä.
Kerro lisäksi alihankkijan API-tunnus ja Anna API-tunnuksen haltijan yhteystiedot.
4. Käyttöehtojen hyväksyminen
5. Käyttölupahakemuksen esikatselu ja lähettäminen
Käyttöluvan myöntäminen ja käyttöluvasta tiedottaminen
Käyttölupahakemuksen käsittely kestää jonotilanteesta riippuen 1-2 viikkoa. Kun käyttölupa on myönnetty, käyttölupa tulee näkyviin organisaationne tilille Palveluhallinnassa ja DVV:n käyttölupatiimi lähettää hakemuksessa mainituille yhteyshenkilöille sekä organisaationne mahdollisille vanhoille PTV-pääkäyttäjille viestin, jossa annetaan ohjeita integraatiossa PTV:hen tuotavan datan laadun tarkistamisessa. Varsinaiset IN-rajapinnan tuotantotunnukset saatte, kun integraation kautta tuotavat sisällöt on hyväksyttävästi katselmoitu.
PTV-pääkäyttäjäoikeuksien myöntäminen
Käyttöluvan myöntämisen jälkeen PTV-tuki lisää yhteyshenkilöllenne PTV-pääkäyttäjäoikeudet ja tiedottaa asiasta yhteyshenkilöä sähköpostitse.
Sisältöjen tarkistaminen ja korjaaminen lähdejärjestelmässä
Sopikaa IT-toimittajan kanssa, miten organisaationne sisällöt tuotetaan PTV:hen integroitavaan järjestelmään. Jos organisaationne on kuvannut sisältöjä PTV:n käyttöliittymään, yksi vaihtoehto on hakea nykyiset sisällöt pohjaksi PTV:n OUT-rajapinnasta ja päivittää ne ajan tasalle.
Kun sisällöt on tuotettu PTV:hen integroitavaan järjestelmään, PTV-pääkäyttäjän ja tai IT-toimittajan edustajan tulee käydä ne läpi ja tarkistaa, että ne vastaavat PTV:n tietomallia ja sisältöohjeita. Virheelliset tiedot tulee korjata lähdejärjestelmään.
Kaikki PTV:hen integroitavaan järjestelmään tietoja ylläpitävät tulee myös perehdyttää siihen, että he osaavat tuottaa ja ylläpitää tietoja PTV:n tietomallin ja sisältöohjeiden vaatimassa muodossa.
Sisältöraportin toimittaminen katselmoitavaksi
Kun sisällöt ovat kattavat ja ajantasaiset, IT-toimittajanne tulee tuoda data PTV:n asiakastestiympäristöön ottaa siitä Excel-raportti sekä toimittaa se katselmoitavaksi Digi- ja väestötietovirastoon osoitteeseen ptv-tuki@dvv.fi.
Sisällön katselmointi
DVV katselmoi, että data on laadukasta ja noudattaa tietomallia. Varautukaa myös tekemään mahdolliset sisältökorjaukset katselmoinnin jälkeen.
API-avaimen toimittaminen
Kun tarvittavat sisältökorjaukset on tehty, Digi- ja väestötietovirasto tekee organisaatiollenne tuotannon API-avaimen tietojen tuomiseksi PTV:hen ja toimittaa sen IT-toimittajallenne. Tämän jälkeen voitte tehdä tuotantoasennuksen.
PTV:hen tuotavien asiointikanavien ja palveluiden liittäminen
Palvelutietovarannossa jokaisen asiointikanavan tulee olla liitetty palveluihin, joita asiointikanavassa tarjotaan. PTV:n integroitavasta järjestelmästä tuotaviin asiointikanaviin liittyvät palvelut tulee hyvissä ajoin kuvata PTV:n käyttöliittymässä, mikäli niitä ei aiemmin ole kuvattu. Kun integraatio on tuotannossa, teidän tulee tehdä käyttöliittymässä liitokset palveluiden ja asiointikanavien välille. Jokaisella asiointikanavalla tulee olla liitos vähintään yhteen palveluun.
LIPAS–PTV-integraatio on tekninen ratkaisu, jonka avulla voitte siirtää tietoja LIPAS-liikuntapaikkatietojärjestelmästä Palvelutietovarantoon.
Lue lisää LIPAS–PTV-integraatiosta
Jos haluat ottaa käyttöön LIPAS-liikuntapaikkarekisterin ja PTV:n välisen integraation, hae PTV:n IN-rajapinnan käyttölupaa Palveluhallinta-sivustollaAvautuu uuteen ikkunaan..
Jos organisaatiosi on jo ottanut Palvelutietovarannon käyttöön, pääset hakemaan IN-rajapinnan käyttölupaa Palveluhallinta-sivuston kirjautuneen käyttäjän etusivulta Hae käyttölupaa -painikkeen kautta.
Käyttölupahakemuksen täyttäminen
Käyttölupahakemuksessa on kolme osiota:
- Tiedot organisaatiosta ja yhteyshenkilöistä.
- Tiedot PTV:hen IN-rajapinnan kautta integroitavasta tietojärjestelmästä ja selvitys tietojen suojauksesta.
- Organisaation antamat sitoumukset (mm. Käyttöehtojen hyväksyminen).
Täytä tekninen yhteyshenkilö -kohtaan Jyväskylän yliopiston yhteyshenkilön tiedot (tapani.j.laakso@jyu.fi sekä lipasinfo@jyu.fi). Ilmoita hakemuksessa kohdassa Alihankkija myös, että käytätte Jyväskylän yliopiston API-avainta API@jyu.fi ja kirjaa Jyväskylän yliopiston Y-tunnus 0245894-7.
Käyttöluvan myöntäminen ja käyttöluvasta tiedottaminen
Käyttölupahakemuksen käsittely kestää jonotilanteen mukaan 1-2 viikkoa. Kun käyttölupa on myönnetty, se tulee näkyviin organisaationne tilille Palveluhallinnassa.
Käyttöoikeuksien myöntäminen
Kun käyttölupa on myönnetty, PTV-tuki tarkistaa, ketkä ovat organisaationne PTV-pääkäyttäjiä, lisää hakemuksessa mainitulle hallinnolliselle yhteyshenkilölle PTV-pääkäyttäjän oikeudet sekä kytkee organisaationne Jyväskylän yliopiston API-avaimeen.
Kun PTV-tuki on tehnyt nämä toimenpiteet, se tiedottaa asiasta sähköpostitse hakemuksessa mainituille yhteyshenkilöille ja organisaationne PTV-pääkäyttäjille.
Tämän lisäksi PTV-tuki toimittaa Jyväskylän yliopistolle Palveluhallinta-sivustolle muodostuneen organisaationne organisaatiotunnisteen (organisaatio-ID), jota Jyväskylän yliopisto tarvitsee tietojen tuomiseksi Palvelutietovarantoon.
Sisältöjen tarkistaminen ja julkaiseminen Palvelutietovarantoon
Aloittakaa organisaationne kuvausten tarkistaminen ja täydentäminen LIPAS-järjestelmässä heti kun mahdollista, vaikka käyttölupaa ei olisi vielä myönnetty. Tähän liittyvät kysymykset pyydämme ohjaamaan osoitteeseen lipasinfo@jyu.fi.
Kun olette päivittäneet tiedot LIPAS-järjestelmässä, voitte julkaista palvelut ja palvelupaikat Palvelutietovarantoon Vie Palvelutietovarantoon –toiminnon avulla. Asia on ohjeistettu tarkemmin Jyväskylän yliopiston tuottamassa LIPAS-PTV-integraation käyttöönotto -ohjeessa.
Ohje LIPAS-PTV-integraation käyttöön | Jyväskylän yliopisto (linkki tulossa)
Datan laadun katselmointi
Kun olette julkaisseet LIPAS-palvelut ja palvelupaikat ja ne ovat siirtyneet Palvelutietovarantoon, ilmoittakaa asiasta Digi- ja väestötietovirastoon osoitteeseen ptv-tuki@dvv.fi. DVV katselmoi, että data on laadukasta ja noudattaa tietomallia. Varautukaa myös tekemään mahdolliset sisältökorjaukset katselmoinnin jälkeen.