Suomi.fi-verkkopalvelu –
Rekisterin käyttöönoton ohje

Print Friendly, PDF & Email
 


Suomi.fi-verkkopalvelu, rekisteri

Rekisteritiedoissa voit tarkastella vahvasti tunnistautumalla itseäsi koskevia tietoja eri julkishallinnon ja yritysten rekistereissä. Rekisteritiedot sisältävät koosteen rekisterin ylläpitäjän valitsemista tiedoista. Näytettäviä tietoja ei tallenneta verkkopalveluun.

Rekisterin käyttöönoton vaiheet

Tämä käyttöönoton ohje kuvaa, miten asiakasorganisaatio tuo omasta rekisteristään tietoja Suomi.fi-verkkopalveluun kansalaisen nähtäväksi.

  1. Asiakasorganisaatio tutustuu Suomi.fi-palveluihin ja Verkkopalvelun käyttöönoton ohjeisiin,
  2. Ennen käyttöönoton aloitusta asiakasorganisaation on hyväksyttävä Suomi.fi-verkkopalvelun käyttöehdot.
  3. Suomi.fi-palveluväylän käyttöönotto on aloitettu.

Palveluväylän käyttöönoton ohje löytyy täältä: Palveluväylään liittyminen

Suomi.fi-palveluväylä tarjoaa vakioidun tavan tietojen siirtoon organisaatioiden välillä mahdollistaen turvallisten palvelukokonaisuuksien rakentamisen kansalaisille, yrityksille ja viranomaisille.

Suomi.fi-verkkopalvelun rekisterin käyttöönottoprosessi

Määrittely

Määritetään käyttöönottoprosessin vastuuhenkilöt sekä tietovaranto, kuvataan käyttötapaus yleisellä tasolla ja suunnitellaan käyttöönoton aikataulu. Apuna voidaan käyttää seuraavaa lomaketta Suomi.fi-verkkopalvelu käyttöönotto rekisteri perustiedot

Vastuuhenkilöt

Asiakasorganisaation vastuuhenkilö: Asiakasorganisaation nimeämä yhdyshenkilö, joka toimii yhdessä Väestörekisterikeskuksen nimeämän henkilön kanssa.

Tuoteomistaja: Väestörekisterikeskuksen nimeämä henkilö, joka vastaa koko Suomi.fi-verkkopalvelusta.

Käyttöönoton projektipäällikkö: Väestörekisterikeskuksen yhdyshenkilö asiakasorganisaation suuntaan.

Rekisterin määrittely

Liitettävä rekisteri (tietovaranto) on asiakasorganisaation palvelu, jonka tulee olla liitettynä Palveluväylään liityntäpalvelimen kautta. Suomi.fi-verkkopalvelu lähettää rekisteriin pyynnön kansalaisen tietojen saamiseksi ja näyttämiseksi. Pyyntö kohdistuu aina yhteen vahvasti tunnistetun kansalaisen henkilötunnukseen.

Käyttötapauksen yleiskuvaus

Käyttötapauksen yleiskuvauksessa kuvataan lyhyesti, mitä omia tietoja kansalainen voi tarkastella Suomi.fi-verkkopalvelusta. Esimerkiksi kansalainen saa nähtäväksi omat ajoneuvonsa listauksena, jolloin ajoneuvolistaus toimii käyttötapauksen yleiskuvauksena.

Aikataulu

Asiakasorganisaation tulee yhdessä Väestörekisterikeskuksen kanssa sopia seuraavat tavoiteaikataulut ennen teknistä toteutusta, jotta molemmilla osapuolilla on varattuna oikeat resurssit oikeaan aikaan:

  • Suomi.fi-palveluväylään liittyminen: suunniteltu aloitus ja lopetus testi- ja tuotantoympäristöön
  • Suomi.fi-verkkopalveluun liittyminen: suunniteltu aloitus ja lopetus testi- ja tuotantoympäristöön

Käyttöönottoprojekti edellyttää lisäksi aikatauluarvioita, milloin suoritetaan

  • Käyttötapausten kuvaus
  • Perustietojen määritys
  • Kehitys
  • Testaus

Sopimus- ja käyttöehdot

Ennen käyttöönoton aloitusta asiakasorganisaation on hyväksyttävä Suomi.fi-verkkopalvelun käyttöehdot.

Rekisterin tietomalli

Asiakasorganisaatio toimittaa erillisessä dokumentissa seuraavat tiedot:tietokentät, tietolähteen perustiedot sekä metaluokittelun (myöhemmässä vaiheessa), linkit ja kuvailutiedot.

Käyttötapaukset

Käyttötapaus täytyy kirjata sellaisella tarkkuudella, että sitä voidaan hyödyntää:

  • Suomi.fi-verkkopalvelun kehityksessä
  • testauksessa
  • integraatiotyössä
  • palvelun tuessa

Tietolähteen kuvailutiedot

Jokainen Suomi-fi-verkkopalvelun Rekisterit-osiossa näytettävä yksittäinen rekisteritietolähde kuvaillaan palvelun admin-käyttöliittymässä. Näitä yleisiä kuvailutietoja näytetään Suomi-fi-verkkopalvelussa myös tunnistautumattomalle loppukäyttäjälle. Kuvailutiedot tulee aina kirjoittaa loppukäyttäjän näkökulmasta.

Tietolähteen perustiedot:
Tietolähteen otsikko

Esimerkiksi henkilötietoni

Tietolähteen/rekisterin virallinen nimi

Esimerkiksi väestötietojärjestelmä

Tuottajaorganisaatio/rekisterinpitäjä

Esimerkiksi Väestörekisterikeskus

Tietolähteen kuvaus

Kuvataan tietolähteen sisältö lyhyesti ja loppukäyttäjälähtöisesti

Visuaalinen kuva, ikoni, logo tai vastaava

Tietolähteen yhteydessä näytettävä mahdollinen kuvatiedosto

Mallidata

Tietolähteessä tulevien tietojen mallidatasetti, esim. xml-muodossa

Linkit:
Rekisteriseloste

Linkki tietolähteen/rekisterin henkilötietolain mukaiseen rekisteriselosteeseen

Optio: linkitys ulkopuoliseen tietolähteeseen

Linkki tietolähteeseen, jota ei ole kytketty Palveluväylään ja josta ei tuoda tietoja suoraan Suomi-fi-verkkopalveluun, mutta jonne käyttäjä siirretään kertakirtautumisen kautta tunnistautuneena käyttäjänä

[myöhemmin]
Tietolähteeseen liittyvät palvelut

Linkit sähköisiin asiointipalveluihin, jotka liittyvät keskeisesti tässä tietolähteessä näytettäviin tietoihin. Esimerkiksi henkilötietoihin voisi keskeisesti liittyä muuttoilmoitus, johon pääsy voitaisiin tarjota käyttäjälle rekisteritietojen vieressä

Toimintaohjeet/yhteystiedot virhetilanteessa

Tekstimuotoinen kuvaus, miten käyttäjän tulisi toimia, jos huomaa virheitä rekisteritiedoissa, mahdolliset yhteystiedot

Linkki virhetilanteessa

Mahdollinen linkki sähköiseen palveluun tai vastaavaan, jolla käyttäjä voi tehdä ilmoituksen virheestä

Määrämuotoiset kuvailutiedot:
Palvelun tuottajatyyppi

Luokitellaan annetun luokittelun mukaisesti, sama luokittelu kuin Suomi.fi-palvelutietovarannon palveluissa

Palveluluokka

luokitellaan tietolähde kaksitasoisen palveluluokituksen mukaisesti, sama luokittelu kuin Suomi.fi-palvelutietovarannon palveluissa

Kohderyhmä
Määritellään kohderyhmä, sama luokittelu kuin Suomi.fi-palvelutietovarannon palveluissa
Ontologiasanat

Määritellään datalähdettä kuvaavat ontologiasanat

Vapaat asiasanat

Määritellään mahdolliset vapaat asiasanat

Metaluokittelu, linkit ja kuvailutiedot

Yhteiset rekisteritiedot (R1), jotka tarvitaan jokaisesta liitetystä tietovarannosta. Tunnusluokan tiedot ovat Suomi.fi-palvelutietovarannon mukaiset.

Otsikko

1

teksti

Tiedon tuottajaorganisaatio

teksti / tunnus

Tiedon tuottajakuvaus

1

teksti

Lyhyt kuvaus

1

teksti

Linkki tietolähteeseen

1

url

Logo, ikoni, kuva

1

kuva

Metatiedot (elämäntilanne, teema)

1…n

tunnus

Palvelun tuottajatyyppi

1

tunnus

Palveluluokka

1…n

tunnus

Kohderyhmä

1…n

tunnus

Ontologiasanat

1…n

tunnus

Vapaat asiasanat

0…n

teksti

Liittyvät palvelut

0…n

palvelu (B)

Ohje virheellisen tiedon korjaamiseen

0…n

teksti / url

Kieliversiot

Kuvailu ja ohjetekstit tulee toimittaa kaikilla Suomi.fi palvelun tukemilla kielillä, jotka ovat suomi, ruotsi ja englanti.

Toteutus

Toteutusvaiheessa liityntäpalvelimet kytketään Suomi.fi-palveluväylään. Samalla liitetään tarvittavat rajapinnat sekä avataan pääsy rajapintojen sisältämään tietoon Suomi.fi-verkkopalveluun.

Toteutusvaiheessa syntyvät seuraavat tuotokset:

  • Palveluväylän liityntäpalvelin (jos ei toteutettu muussa yhteydessä)
  • Palveluväyläliitos (testiympäristö)
  • SOAP/REST-rajapinnan luominen liitettävään palveluun
  • JSON-tiedoston määritys tiedon tuontiin
  • Handlebars (mustache yhteensopiva) templaten luonti Suomi.fi-verkkopalvelun nostoa varten

Rajapintakyselyt

Suomi.fi-verkkopalvelu tekee oman liityntäpalvelimensa kautta Palveluväylään kyselyn asiakasorganisaation rajapintaan. Tämä kysely on muotoa:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xrd="http://x-road.eu/xsd/xroad.xsd" xmlns:id="http://x-road.eu/xsd/identifiers">
   <SOAP-ENV:Header>
       <xrd:client id:objectType="SUBSYSTEM">
           <id:xRoadInstance>FI</id:xRoadInstance>
           <id:memberClass>GOV</id:memberClass>
           <id:memberCode>0245437-2</id:memberCode>
           <id:subsystemCode>ServiceViewClient</id:subsystemCode>
       </xrd:client>
       <xrd:service id:objectType="SERVICE">
          <id:xRoadInstance>FI</id:xRoadInstance>
          <id:memberClass>GOV</id:memberClass>
          <id:memberCode>000000-1</id:memberCode>
          <id:subsystemCode>TestSystem</id:subsystemCode>
          <id:serviceCode>testService</id:serviceCode>
       </xrd:service>
       <xrd:protocolVersion>4.0</xrd:protocolVersion>
       <xrd:id></xrd:id>
       <xrd:userId></xrd:userId>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
       <ns1:testService xmlns:ns1="http://x-road.fi/producer">
          <request>
             <ssn>123456-2111</ssn>
          </request>
       </ns1:testService>
    </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

Tähän täydennetään kunkin Palveluväylään dataa tarjoavan tahon tiedot <xrd:service id:objectType=”SERVICE”>-tagien sisään.

Suomi.fi-verkkopalveluun voi liittyä, mikäli vastauksena henkilötunnuksella tehtyyn kyselyyn saadaan Palveluväylän hyväksymä xml-sanoma, jossa luettava data löytyy <response></response>-tagien sisältä. Suomi.fi-verkkopalvelussa näytetään haettu vastaus yksinkertaisesti tyyliteltynä handlebars-templaten mukaisesti. On tärkeää huomioda, että kaiken näytettävän datan tulisi olla mukana vastauksen response-tagien sisällä. Suomi-fi-verkkopalvelun päässä ei siis ole tarkoitus yhdistellä eri datalähteistä tullutta tietoa, vaan se jää tiedon tarjoajan sovitinpalvelun (tai sisäisen tietojärjestelmän) tehtäväksi. Tieto ei myöskään saa olla esimerkiksi sanoman liitteenä (attachment) tai koodistona, joka tulisi avata Suomi.fi-verkkopalvelun päässä.

Esimerkki vastaussanomasta:


<?xml version="1.0" encoding="utf-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:id="http://x-road.eu/xsd/identifiers" xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">
    <SOAP-ENV:Header>
       <xrd:client id:objectType="SUBSYSTEM">
          <id:xRoadInstance>FI</id:xRoadInstance>
          <id:memberClass>GOV</id:memberClass>
          <id:memberCode>0245437-2</id:memberCode>
          <id:subsystemCode>ServiceViewClient</id:subsystemCode>
       </xrd:client>
       <xrd:service id:objectType="SERVICE">
       <id:xRoadInstance>FI</id:xRoadInstance>
       <id:memberClass>GOV</id:memberClass>
       <id:memberCode>000000-1</id:memberCode>
       <id:subsystemCode>TestSystem</id:subsystemCode>
       <id:serviceCode>testService</id:serviceCode>
       </xrd:service>
       <xrd:userId>test</xrd:userId>
       <xrd:id>ID11234</xrd:id>
       <xrd:protocolVersion>4.0</xrd:protocolVersion>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
       <ts1:testServiceResponse xmlns:ts1="http://test.x-road.fi/producer">
       <request>
          <ssn>123456-2111</ssn>
       </request>
       <response>
          <nimi>Mallidata</nimi>
          <aika>TI 31.2.2016 15:00</aika>
          <lisatieto>malliksi</lisatieto>
          </response>
       </ts1:testServiceResponse>
    </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

Tässä esimerkissä näkyvät html-elementtien tyylittelyt tulevat Suomi.fi-verkkopalvelun tyylioppaasta, mutta asiakasorganisaatio saa esittää rakenteeseen toiveita.

Handlebars template

Asiakasorganisaation palvelusta haettavan xml:stä muunnetun JSON-tiedoston sisällä olevat tietoalkiot näytetään omana nostona Suomi.fi-verkkopalvelussa. Noston sisältö koodataan handlebars templaten mukaisesti, jolloin tietoalkioon viitataan {{ }} sulkeilla alla olevan esimerkin mukaisesti. Asiakasorganisaatio voi vaikuttaa esitysmuotoon luomalla mallitiedoston, mutta lopullisen version tekee kehitystiimi. Nosto ei saa sisältää aktiivista sisältöä, mutta linkit asiakasorganisaation palveluun ovat sallittuja. Noston täytyy noudattaa Suomi.fi-tyyliohjeita.

Suomi.fi-verkkopalvelussa xml:stä jsoniksi muutettu edellisen kohdan esimerkkivastaus muuntuu seuraavaksi:

{
”nimi”:”Mallidata”,
”aika”:”TI 31.2.2016 15:00″,
”lisatieto”:”malliksi”
}

Tämä puolestaan näytetään itse Suomi.fi-verkkopalvelussa käyttäen handlebars-templatointia esimerkiksi seuraavasti:

Tietosi järjestelmässä

  • Nimi: {{nimi}}
  • Aika: {{aika}}
  • Lisätietoa palvelusta: {{lisatieto}}

Esimerkki:

Handlebars template esimerkki

Testaus ja hyväksyntä

Testausvaihe koostuu seuraavista aktiviteeteista:

  • Testitapaukset: poikkeustilanteiden hallinta, tietojen oikeellisuuden tarkistus, testihetujen määrittely Palvelun testaus testitapauksia vasten
  • Virhekorjaukset
  • Beta-versio

Liitettävän palvelun testaus tehdään aina testiympäristössä. Hyväksytty testaus on edellytys ennen kuin tietovaranto voidaan siirtää tuotantoympäristöön.

Hyväksyntävaihe koostuu seuraavista aktiviteeteista:

  • Dokumentoinnin viimeistely
  • Ohjausryhmähyväksyntä
  • Sopimus

Asiakasorganisaatio

Asiakasorganisaation vastuulla on suorittaa liitetyn palvelun toiminnallinen testaus ja validoida, että siirretty tieto on oikeaa ja esitysmuoto on oikein. Lisäksi asiakasorganisaatio luo testitapaukset käyttötapauksista yhdessä Väestörekisterikeskuksen kanssa. Asiakasorganisaation tulee myös toimittaa palvelusta mallidataa, jonka avulla testausta voidaan tehdä. Todellisen tiedon käyttö testauksessa on kiellettyä.

Testitapaukset ja palvelun testaus testitapauksia vasten

Palvelun testitiimi hoitaa liitettävän palvelun teknisen testauksen ja mahdolliset kuormitustestaukset Suomi.fi-verkkopalvelussa. Testauksesta on sovittava hyvissä ajoin etukäteen ja testauksen kesto on noin 1 viikko. Testitapausten tarkoituksena on testata tietojen oikeellisuus Suomi.fi-verkkopalvelussa.

Virheiden korjaus

Testauksen aikana havaitut virheet kirjataan. Kriittiset virheet on korjattava ennen tuotantoon siirtymistä.

Hyväksyntä

Ennen tuotantoympäristöön siirtymistä validoidaan, että kaikki vaadittava dokumentointi on tehty. Testiraportti osoittaa, että liitettävässä palvelussa ei esiinny kriittisiä virheitä.

Tuotantoympäristö

Palvelun kehitystiimi (tekninen tukihenkilöstö) koordinoi yhdessä asiakasorganisaation teknisen asiantuntijan kanssa palvelun käyttöönoton tuotantoympäristössä.

Jatkuva palvelu

Palvelu siirtyy jatkuvan palvelun tilaan.

Käsitteet

  • Asiakasorganisaatio tarkoittaa liittyvää organisaatiota tai yritystä.
  • De facto –standardi tarkoittaa Suomi.fi-verkkopalvelun käyttöönoton yhteydessä sitä, kun jokin taho on luonut Suomi.fi-verkkopalveluun noston, seuraavien samantyyppistä tietoa tuovien tahojen tulisi noudattaa tämän aikaisemman liittyjän tietomallia ja esitystapaa. Tällöin saavutetaan kansalaisen näkökulmasta tietyn tyyppiselle tiedolle yhtenäinen esitystapa.
  • Loppukäyttäjä tarkoittaa kansalaista, joka saa Suomi.fi-verkkopalvelun kautta nähtäväkseen itseään koskevat asiakasorganisaation palvelu- ja rekisteritiedot.
  • REST (en. Representational State Transfer) on HTTP-protokollaan perustuva arkkitehtuurimalli ohjelmointirajapintojen toteuttamiseen. X-Road sisältää oletusarvoisesti SOAP-rajapinnan, mutta adapterin avulla myös REST on mahdollinen. Käytännössä tämä tarkoittaa, että liittyvä organisaatio ohjelmoi omaan tietovarantoonsa ws-rajapinnan (web services).
  • SOAP (en. Simple Object Access Protocol), on XML-kieleen pohjautuva tietoliikenneprotokolla, jota käytetään X-Road-ratkaisun liityntäpalvelimen rajapintatoteutuksessa.
  • Suomi.fi-palvelutietovaranto on keskitetty tietovaranto, jossa on kuvattuna julkishallinnon palveluntarjoajien palvelut ja julkishallintoon liitoksissa olevien yksityisten palveluntarjoajien palvelut.
  • Suomi.fi-palveluväylä on standardoitu tiedonsiirtokanava, joka tarjoaa vakioidun tavan tietojen siirtoon organisaatioiden välillä sekä mahdollistaa turvallisten palvelukokonaisuuksien rakentamisen.
  • Tietovaranto, rekisteri tarkoittaa asiakasorganisaation hallinnoimaa tietovarantoa, joka on liitetty Suomi.fi-palveluväylän kautta Suomi.fi-verkkopalveluun. Se on tarkoitettu julkisen hallinnon palveluja ja palvelupisteitä kuvailevien tietojen tallentamiseen, säilyttämiseen ja käyttöön rajapintojen kautta. Tietovarannosta loppukäyttäjille voidaan näyttää Suomi.fi-verkkopalvelusta häntä itseään koskevia rekisteritietoja.

 

 


 Dokumentin tiedot

Versionro Mitä tehty Pvm/henkilö
 1.0 Dokumentti luotu 20.01.16/NP
 1.1 Dokumenttia päivitetty  08.06.16 / NP
 1.2  Dokumenttia päivitetty  25.1.18 /TR
1.3 Dokumenttia päivitetty 19.8.18 /TM

Yksilöintitunnus: JTO21