Suomi.fi-palvelutietovaranto Kaikki oleellinen julkishallinnon palveluista yhdessä paikassa. PTV-rajapintojen hyödyntäminen

Transkriptio

1 Suomi.fi-palvelutietovaranto Kaikki oleellinen julkishallinnon palveluista yhdessä paikassa PTV-rajapintojen hyödyntäminen

2 Tavoitteet ja sisältö Selventää rajapinnan käyttöön ja parametreihin liittyviä asioita. Laatuasiat Luokitukset Käsittelysäännöt deleteall parametrien käyttö PUT-metodien käsittelysäännöt rakenteita lähetettäessä

3 Havaittuja laatuasioita koskee sekä manuaalisesti että rajapinnan kautta tuotettuja tietoja Palvelut ilman asiointikanavia Asiointikanavat ilman palveluja Pohjakuvauksen tekstiä kopioitu palvelun kuvaukseen Asioinnin yhteystietoja kuvattu palvelun kuvaukseen Tiivistelmään kopioitu palvelun nimi tai sisältö ei vastaa palvelun kuvauksen tietoja Palvelupisteitä on kuvattu palveluna Terveyskeskus (Ohje: Kuvaa terveyskeskuksissa tarjottavia palveluja pohjakuvauksia hyödyntäen) Yhteispalvelupisteet ja asiointipisteet Uimahalli, Liikuntahalli, Uimaranta Pohjakuvausten perusteella on kuvattu palveluja, joita kunta ei todellisuudessa tarjoa. Kaikkia pohjakuvauksia ei ole pakko käyttää. Esimerkkejä: turvakoti, pysäköinninvalvonta Kohderyhmien valinta 3

4 Palvelutietovarannon keskeisiä käsitteitä Käsitteet ja luokitukset Palvelu Vastaa asiakkaan tarpeeseen ratkaista jokin ongelma Ilman asiakasta ja asiointikanavaa palvelu ei konkretisoidu. Palvelu koostuu ennalta määritellyistä prosesseista. Asiointikanava On tapa jolla asiakas saa palvelun tai voi aloittaa prosessin palvelun saamiseksi Sisällöntuotannon perusteet koulutus materiaali esuomi.fissä ASIOINTIKANAVA Verkkoasiointi ORGANISAATIO Vastaa palvelusta ja/tai tuottaa palvelua Vastaa asiointikanavista PALVELU Palvelun kuvaus, ehdot ja kriteerit, toimintaohjeet ASIOINTIKANAVA Tulostettava lomake PTV-tietojen ylläpitäjä ASIOINTIKANAVA Verkkosivu /virasto Tietojen ylläpito ja hallinta ASIOINTIKANAVA Palvelupiste ASIOINTIKANAVA Puhelinasiointi ORGANISAATIO Tuottaa palvelua ja/tai vastaa asiointikanavista PTVpääkäyttäjä PTVpääkäyttäjä PTV-tietojen ylläpitäjä

5 Palvelutietovarannon keskeisiä käsitteitä Käsitteet ja luokitukset Tietojen yhdisteleminen, esittäminen ja hakeminen perustuu metatietoihin Kenelle Kohderyhmä kuvaa kenelle palvelu on tarkoitettu Missä Mitä Asiasanat kuvaavat palvelun sisältöä Metatiedot Asiasanat Luokitukset Luokitukset Kohderyhmäluokat Palveluluokat Tilanneluokat Toimialaluokat Rajaukset Alueellinen kattavuus Metatietokoulutuksen materiaali esuomi.fissä Toimialaluokka rajaa toimialat, joita palvelu koskee Elämäntilanne rajaa ajanjakson milloin palvelua tarvitaan Aluerajaus kuvaa organisaation vastuualuetta. Minkä alueen palvelujen järjestämisestä organisaatio on vastuussa ja missä palvelupisteet sijaitsevat Palvelu Palveluluokka kuvaa palvelun sisältöä

6 PTV-rajapinnan käsittelysäännöt POST ja PUT metodit

7 Yleiset käsittelysäännöt - aluerajaus Ei koske organisaatiota organisaation käsittelykäännöt on kuvattu kohdassa Organisaation käsittelysäännöt Aluerajaus/parametrit Koko maa Koko maa pl. Ahvenamaa Rajattu alue areatype WholeCountry WholeCountryExceptAlan dislands AreaType subareatype - - Municipality 418 (kuntakoodi) subareatype - - Province 13 (maakuntakoodi) subareatype - - BusinessRegions (yritysseutualuekoodi) subareatype - - HospitalRegions HUOM! Aluetyyppejä voi valita useita 14 (sairaanhoitopiirikoodi)

8 Yleiset käsittelysäännöt - puhelinnumero Puhelinnumeron kentän käyttö prefixnumber kenttään annetaan maan suuntanumero ja number kenttään puhelinnumero. Puhelinnumero annetaan kansainvälisessä muodossa ilman etu nollaa, kun isfinnishservicenumber on FALSE. Maan suuntanumeroa ei tarvitse antaa, jos isfinnishservicenumber kenttään kirjataan arvo TRUE. Puhelinnumero on kansallisessa muodossa etunollan kanssa. HUOM! prefixnumber tieto jätetään huomioimatta, kun isfinnishservicenumber on TRUE.

9 Yleiset käsittelysäännöt - ordernumber Verkkosivu-kentän järjestyksen määrittäminen Verkkosivujen järjestyksen voi valita antamalla ordernumber kenttään arvoja (N=0, 1, 2,...). Samaa arvoa ei voi antaa kahta kertaa Verkkosivujen järjestyksen voi määritellä kieliversiokohtaisesti HUOM! Arvot annetaan kieliversioittain. Arvo nolla (0) ei tuo käyttöliittymään esijärjestystietoa (vastaa tilannetta, että arvoa ei annettaisi ollenkaan).

10 Yleiset käsittelysäännöt - osoitetiedot Osoitetiedot (organisaatio, tulostettavalomake, palvelupaikka) Käyttäjä voi määrittää yhden taulukon array sisään vain yhden osoite tiedon. Kopioimalla taulukkorakenteen, voidaan kuvata lisää osoitetietoja type ja subtype kenttien arvoilla määritellään mitä osoitetietoa ollaan antamassa. Kenttien riippuvuussuhteet ovat type = Postal, subtype = Street TAI PostOfficeBox TAI Foreign type = Visiting, subtype = Street TAI Foreign

11 Yleiset käsittelysäännöt - publishingstatus Tämä kenttä on (v7 alkaen) aina pakollinen. Sallitut arvot ovat Draft, Published, Modified, Deleted mutta riippuen lähtötilasta, voi sallittuja arvoja olla rajoitetummin käytössä. Esimerkki: tilatietona on Draft, käyttäjä voi antaa vain Draft tai Published arvot

12 Organisaation käsittelysäännöt - aluerajaus organizationtype kentän valinnasta riippuen käytetään joko Kuntanimi ( municipality ) kenttää tai AreaType, subareatype ja areas kenttiä. Aluerajauksien yhdistely ei ole mahdollista. Organisaatio tyyppi/alue rajaus Koko maa Koko maa pl. Ahvenamaa Kunta Munincipality Ei sallittu Ei sallittu Vain yksi sallittu RegionalOrganizat ion Ei sallittu Ei sallittu Useampi sallittu State Sallittu Sallittu Useampi sallittu Organization Sallittu Sallittu Useampi sallittu Company Sallittu Sallittu Useampi sallittu Maakunta Sairaanhoitopiiri Yrityspalvelujen seutualue Ei sallittu Ei sallittu Ei sallittu Useampi sallittu Useampi sallittu Useampi sallittu Useampi sallittu Useampi sallittu Useampi sallittu Useampi sallittu Useampi sallittu Useampi sallittu Useampi sallittu Useampi sallittu Useampi sallittu

13 Palvelun käsittelysäännöt - pohjakuvaus Kun pohjakuvaus on otettu käyttöön palvelussa Palvelutyyppi ( type ) kentän voi jättää tyhjäksi Kuvaus ( description ) kentän voi jättää tyhjäksi, jos pohjakuvaus sisältä pääkuvaus tietoa ( description ). Palveluluokan ( serviceclasses ) kentän voi jättää tyhjäksi käyttäjä voi kyllä lisätä arvoja. Asiasanat ( ontologyterms ) kentän voi jättää tyhjäksi käyttäjä voi kyllä lisätä arvoja. Kohderyhmä ( targetgroups ) kentän voi jättää tyhjäksi käyttäjä voi kyllä lisätä arvoja. Palveluluokka, asiasanat ja kohderyhmä kentissä tupla-arvojen tarkastus

14 Palveluaikojen kuvaaminen kenttien käyttö Aukioloaika - tyyppi validfrom validto dayfrom dayto boolean Normaalit palveluajat Toistaiseksi voimassa oleva Monday Friday Toistaiseksi voimassa oleva 24/7 validfornow Voimassa ajanjaksolla Monday Friday Voimassa ajanjaksolla 24/ Vuorokauden yli menevät palveluajat Toistaiseksi voimassa oleva Monday Wednesday Voimassa ajanjaksolla Monday Wednesday Poikkeavat palveluajat Päivä Thursday Ajanjakso Thursday Friday Päivä + Suljettu koko päivän isclosed Ajanjakso + Suljettu ajanjaksolla isclosed

15 deleteall kenttien käsittelysäännöt

16 deleteall kenttien käyttö deleteall kenttä poistaa määritellyn kentän kaikki tiedot. Jos käyttäjä yrittää lisätä tai päivittää tietoa ja samanaikaisesti haluaa poistaa kaikki tiedot, käyttäjän omat määritykset jäävät voimaan ja deleteall ei poista mitään tietoa. Poistaakseen määritellyn kentän kaikki tiedot, ei samanaikaisesti saa lisätä tai päivittää kentän tietoja.

17 Esimerkit - deleteall s " addresses": [ { "description": "sähköposti-1", "value": "first1.last1@name.fi", "language": "fi" }, { "description": "sähköposti-2", "value": "first2.last2@name.fi", "language": "fi" } ], "deleteall s": true

18 deleteall s esimerkki 1 " addresses": [ { "description": "sähköposti-1", "value": "first1.last1@name.fi", "language": "fi" }, { "description": "sähköposti-2", "value": "first2.last2@name.fi", "language": "fi" } ], "deleteall s": true Lopputulos - käyttäjän antamat tiedot jäävät voimaan

19 deleteall s esimerkki 2 "deleteall s": true Lopputulos - kaikki sähköpostiosoitetiedot ( s) poistetaan.

20 PUT-metodien käsittelysäännöt rakenteita lähetettäessä

21 Kieliversio Kieliversiot suositellaan lisättäväksi samanaikaisesti mutta ne voidaan syöttää myös erikseen. Kun syöttää kielikohtaiset tiedot samanaikaisesti (esimerkki 1), tulee kaikkiin kieliversiollisiin kenttiin kuvata tiedot kaikilla annetuilla kielillä. Kun nimi-kenttä kuvataan kolmella kielellä, tulee muutkin kentät kuvata kolmikielisesti esimerkiksi displaynametype, organizationdescriptions Jos syöttää kieliversiot erikseen, tulee päivitys vaiheessa huomioida jo olemassa olevan kieliversion tiedot. Niitä ei saa jättää pois (esimerkki 2A ja 2B).

22 Kieliversio esimerkki 1 kolmen kieliversion syöttäminen (organisaation luonti (POST organization)) Kun nimi-kenttä kuvataan kolmella kielellä, tulee muutkin kentät kuvata kolmikielisesti esimerkiksi displaynametype, organizationdescriptions

23 Kieliversio esimerkki 1 "organizationnames": [ { "language": "fi", "value": "Kirkonkylä", "type": "name" }, { "language": "sv", "value": "Kyrkby", "type": "name" }, { "language": "en", "value": "Village", "type": "name" } ], >>> "organizationdescriptions": [ { "value": "Kirkonkylän Kuvaus", "language": "fi" "type": "description }, { "value": "Kyrkby beskrivning ", "language": "sv" "type": "description }, { "value": "Village description ", "language": "en" "type": "description } ],

24 Kieliversio esimerkki 2A yhden kieliversion syöttäminen (organisaation luonti (POST organization)) "organizationnames": [ { "language": "fi", "value": "Kirkonkylä", "type": "name" } ], >>> "organizationdescriptions": [ { "value": "Kirkonkylän Kuvaus", "language": "fi" "type": "description } ],

25 Kieliversio esimerkki 2B toisen kieliversion lisääminen (organisaation päivitys (PUT organization)) "organizationnames": [ { "language": "fi", "value": "Kirkonkylä", "type": "name" }, { "language": sv", "value": "Kyrkby", "type": "name" } ], >>> "organizationdescriptions": [ { "value": "Kirkonkylän Kuvaus", "language": "fi" "type": "description }, { "value": Kyrkby beskrivning", "language": sv" "type": "description } ],

26 Kieliversio esimerkki 3 toisen kieliversion lisääminen (organisaation päivitys (PUT organization)) Jos käyttäjä syöttää vain uuden kielen (esimerkki 3) eikä jo olemassa olevaa kieliversiota, poistetaan olemassa olevat kielitiedot tietokannasta Pohjalla on esimerkin 2B mukainen toteutus/rakenne

27 Kieliversio esimerkki 3 "organizationnames": [ { "language": sv", "value": "Kyrkby", "type": "name" } ], >>> "organizationdescriptions": [ { "value": Kyrkby beskrivning", "language": sv" "type": "description } ], Lopputuloksena tietokantaan tallentuu ruotsinkielinen versio ja suomenkielinen poistuu kannasta.

28 Tietojen päivittäminen taulukoissa Taulukkorakenteissa tietoja käsitellään kokonaisuutena (vastaava kuin kieliversiot). Säilytettävät tiedot on kuvattava tai ne poistetaan. Katso esimerkit Lähtötilanne - Verkkoasiointi sisältää neljä puhelinnumeroa Esimerkki 1 päivitetään kaksi puhelinnumeroa Kirjataan uudet puhelinnumerot sekä säilytettävät kaksi puhelinnumeroa Esimerkki 2 poistetaan yksi numero ja päivitetään yksi numero Kirjataan uusi numero sekä säilytettävä puhelinnumeroa. HUOM! Numero jota ei kuvata, poistetaan Esimerkki 3 poistetaan yksi numero Kirjataan olemassa olevat kolme numeroa. HUOM! Numero jota ei kuvata, poistetaan Vastaavia kenttiä ovat esimerkiksi addresses, phonenumbers, webpages, serviceclasses, ontologyterms, targetgroups, language versions jne. Käyttäjä voi jättää koko taulukon pois tämä ei tarkoita, että tiedot poistetaan vaan tietoja ei muuteta ja ne säilyvät ennallaan.

29 Liitosten päivittäminen (connections) Liitoksien muutoksia käsitellään samalla tavalla kuin taulukkoja (katso dia 20). Käyttäjän tulee kuvata kaikki ne liitokset ja niiden tiedot, jotka hän haluaa säilyttää. Tieto mitä ei anneta, poistetaan tietojen päivittämisen yhteydessä.

30 Liitemateriaalia -sisällöntuotanto

31 Asiakasnäkökulma Asiakas voi olla kansalainen, yritys tai viranomainen Asetu asiakkaan asemaan Käytä selkeää yleiskieltä, vältä hallinnollisia termejä Jos mahdollista, niin pyydä palautetta asiakasnäkökulman toimivuudesta oikeilta käyttäjiltä Laadi palvelukuvaukset asiakkaan näkökulmasta. Kuvaa asiakkaan saamaa palvelua, älä palvelua järjestävää organisaatiota tai sen tehtäviä. Mitä tietoja asiakas tarvitsee saadakseen kokonaiskuvan palvelusta? Miten osaisit itse toimia palvelukuvauksen perusteella? Pohdi palvelukuvauksen hyötyjä kuvaatko palvelun niin hyvin, ettei asiakkaan tarvitse kysyä lisätietoja? Tekstien tulee toimia eri yhteyksissä Kunkin kuvauksen on oltava itsenäinen kokonaisuus. Älä viittaa palvelukuvauksesta toiseen, vaikka ne koskisivat samaa aihepiiriä. Katso esuomi.fistä kohta Kirjoitus- ja tyyliohjeet 36

32 Palvelu on erotettava asiointikanavista Palvelu Liitos Asiointikanava Palvelun kuvaus kertoo mihin asiakkaan tarpeeseen palvelu vastaa kenelle palvelu on suunnattu miten asiakas voi palvelun saada. Asiointikanavan kuvaus kertoo miten asiakas voi asioida kyseisessä asiointikanavassa ratkaistakseen tilanteensa ja täyttääkseen jonkin velvollisuutensa mitä erityispiirteitä asiointikanavaan liittyy. Perheneuvola palvelut Hammashoidon päivystys Lastensuojelun palvelut Työterveys palvelut Perhe- ja ryhmäterapia Ma, ti, to 10:00-14:00 Sisäänkäynti 3 kerros Hammashoitola Ma-pe 8:00 16:00 Lastensuojelu Ma-pe 9:00 15:30 Vain ajanvarauksella Työterveyden hoitaja Ma-pe 8:00 16:00 Ilmoittautuminen 1 kerros Terveyskeskus Normaalit aukioloajat: Ma-pe 8:00 18:00 Vahtimestari:

33 Useita palveluja - yksi palvelupiste Palvelupisteen kuvaustekstissä ei kuvata palveluja. Palvelupisteen puhelinnumeroihin ei laiteta palvelujen puhelinnumeroita Palvelun puhelinnumerot lisätään omana puhelinasiointikanavana Palvelupisteestä annetaan se tieto, johon asiakas voi ensimmäisellä kerralla omatoimisesti kävellä sisään. Organisaatio voi itse päättää, kumman tavan valitsee: kuvaako palvelupisteen yhtenä ja antaa yksityiskohtaiset palvelun ja palvelupisteen väliset tiedot liitoksissa, vai kuvaako useita samassa osoitteessa sijaitsevia toimipaikkoja kokonaan erillisinä palvelupisteinä. Suosituksemme on, että esim. sote-puolen palvelupisteet kuvattaisiin yhtenä palvelupisteenä ja palvelun ja palvelupisteen liitostiedossa annettaisiin yksityiskohtaiset tiedot. Näin ei kuitenkaan ole pakko tehdä, jos käyttäjän näkökulmasta on selkeämpää, että kukin palvelupiste kuvataan erikseen. Tähän vaikuttaa esimerkiksi rakennuksen koko, onko sisäänkäyntejä useita vai yksi/muutama, millä nimellä rakennus tai sen osat yleisesti tunnetaan jne. Paikallistuntemus on tässä avuksi. Samaan osoitteeseen voi tehdä useita palvelupisteitä, mikäli se palvelee asiakasta.

34 Liitemateriaalia - rajapinta

35 Tuetut versiot Julkaisun numero Julkaisun päivä Tuetut rajapintaversiot V5, V4, V3, V2 Lisätieto V6, V5, V4, V V6, V5, V * V7, V6, V5, V4 Rajapintaversiota V4 ei tueta - voi käyttää V7, V6, V5 Ei uutta raja-pintaversiota (alustava) (alustava) V8, V7, V6, V5 Rajapintaversiota V5 ei tueta - voi käyttää Ei uutta raja-pintaversiota (alustava suunnitelma)

36 Tiedon tilan ja versionhallinta Tiedot tallentuvat ensin luonnostilaan, josta ne voi julkaista. Julkaistuja tietoja voi muokata ilman, että jo julkaistut tiedot muuttuvat. Käyttäjä voi julkaista uudelleen muokattuja tietoja. Käyttäjä voi myös arkistoida julkaistuja tietoja. Arkistoidut tiedot voidaan käyttöliittymän kautta palauttaa luonnostilaisiksi, jonka jälkeen ne voidaan julkaista. Rajapinnan kautta arkistoidut tiedot voidaan siirtää suoraan julkaistutilaan, mikäli tiedosta ei ole olemassa muokkauksessa olevaa versiota. POST metodilla voi lähettää ensimmäisen luonnos- ja/tai julkaistutilaisen tiedon. PUT metodilla voi päivittää luonnosversiota (0.1 tai suurempi on olemassa) päivittää julkaistua versiota (1.0 tai suurempi on olemassa) arkistoida luonnos- tai julkaistutilaisen version julkaista arkistoidun version uudelleen. Rajapinnan kautta EI voi päivittää muokkaustilassa olevaa versiota

37 Palvelujen hakeminen GET service/{id} metodi tuo pohjakuvaukselta vain ne tiedot näkyviin, jotka ovat pakollisia ja joita käyttäjä ei ole itse syöttänyt: Palvelutyyppi Kohderyhmä Palveluluokka Asiasanat Pohjakuvauksen tiedot haetaan metodilla GET GeneralDescription/{id} Yhden organisaation palvelujen ja asiointikanavien hakeminen Hae organisaation palvelut (id, y- tunnus, oid) Palvelun tiedot, pohjakuvaus id, listaus kanavista: id, nimi Listaus palveluista: Id, nimi Hae jokaisen palvelun tiedot (id) Hae pohjakuvauksen tiedot (id) Hae jokaisen kanavan tiedot (id)

38 IN API rajapinnassa 1/2 Järjestelmäpääkäyttäjä PTV pääkäyttäjä PTV ylläpitäjä API käyttäjä Lisätietoa Pääorganisaation luonti Ei sallittu Ei sallittu Ei sallittu Ei sallittu Vain Palvelunhallinnan kautta (tulossa) Pääorganisaation arkistointi* Sallittu Ei sallittu Ei sallittu Ei sallittu * Arkistointi poistaa organisaation suomi.fi verkkopalvelusta Pääorganisaation tietojen muokkaus (lisäys/muutos/poisto) Organisaatiorakenteen (puun) muutokset Sallittu Sallittu Ei sallittu Sallittu Ei sallittu Ei sallittu Ei sallittu Ei sallittu Alaorganisaation luonti Sallittu Sallittu Ei sallittu Sallittu Alaorganisaation arkistointi Sallittu Sallittu Ei sallittu Sallittu Alaorganisaation tietojen muokkaus (lisäys/muutos/poisto) Palvelujen tai asiointikanavien luonti Palvelujen tai asiointikanavien arkistointi Sallittu Sallittu Ei sallittu Sallittu Sallittu Sallittu Ei sallittu Sallittu Sallittu Sallittu Ei sallittu Sallittu

39 IN API rajapinnassa 2/2 Palvelu tai asiointikanavien tietojen muokkaus (lisäys/muutos/poisto) Järjestemä pääkäyttäjä PTV pääkäyttäjä PTV ylläpitäjä API käyttäjä Lisätietoa Sallittu Sallittu Ei sallittu Sallittu Liitosten luonti Sallittu Sallittu Ei sallittu Sallittu Liitosten poisto Sallittu Sallittu Ei sallittu Sallittu Liitosten lisätietojen muokkaus (lisäys/muutos/poisto) Sallittu Sallittu Ei sallittu Sallittu Pohjakuvausten luonti Sallittu Ei sallittu Ei sallittu Ei sallittu Pohjakuvausten poisto Sallittu * Ei sallittu Ei sallittu Ei sallittu Pohjakuvausten tietojen muutokset Sallittu * Ei Sallittu Ei sallittu Ei sallittu Pohjakuvausten käyttö palveluissa Sallittu Sallittu Ei sallittu Sallittu

40 Lisätietoja esuomi.fi ja PTV-in rajapinta materiaalia löytyy esuomi.fistä PTV:n versiotiedotteet: Esimerkkejä IN-rajapinnan kutsusanomista: IN-rajapinta Apin kuvaukset löytyvät osoitteesta PTV-rajapintojen skeemat ovat saatavilla swaggerissa osoitteessa HUOM! Swaggerissa on valittava haluttu versio erikseen. Pohjakuvausten tiedot ja tuotantoympäristön ID:t löytyvät: 45

41 Kiitos! Yhteydenotot: Lisätietoja: PTV-video: 46