Siirry suoraan sisältöön.
Suomi.fi-palveluväylä

1. Tutustu ja suunnittele

Käytyäsi läpi tämän osion olet

  • tutustunut Palveluväylän materiaaleihin
  • tutustunut Palveluväylän ja Liityntäkatalogin ympäristöihin
  • sopinut teknisistä ja hallinnollisista yhteyshenkilöistä
  • tutustunut liityntäpalvelinratkaisuihin
  • valinnut tiedonsiirron teknisen lähtökohdan palveluillesi (SOAP tai REST)
  • tutustunut sovitinpalvelun toteutukseen

Tutustu ja suunnittele -vaihe

Tämän osion avulla pääset alkuun Suomi.fi-palveluväylän käyttöönotossa. Voit myös halutessasi ulkoistaa Palveluväylän käyttöönottoprosessin. Lue lisää käyttöönottoprosessin ulkoistamisesta.

Käyttöönoton kesto

Palveluväylän käyttöönottoprosessissa kuluu yleensä noin 1–3 kuukautta, mutta prosessin kesto voi olla myös lyhyempi. Varsinainen asennusprosessi itsessään ei ole kovin pitkä, erityisesti jos prosessi on jo tuttu. Jos organisaatio liittyy Palveluväylään vain hyödyntäjänä tai jos organisaatiolla on jo olemassa Palveluväylään liitetty liityntäpalvelin, on käyttöönottoprosessi nopeampi. Palomuuriavauksiin ja varmenteiden myöntämiseen on hyvä varata muutamia viikkoja.

Käyttöönoton suunnittelu

Suunnittele käyttöönotto huolella, jotta se onnistuu mahdollisimman sujuvasti. Muista, että organisaatiosi tarpeet ja resurssit vaikuttavat prosessiin, ja ne on hyvä huomioida jo suunnitteluvaiheessa. Käyttöönoton suunnittelu jakautuu hallinnolliseen sekä tekniseen suunnitteluun. Huomioi, että tästä huolimatta suunnittelu täytyy tehdä tiiviissä yhteistyössä kaikkien käyttöönottoprosessiin osallistuvien henkilöiden ja tahojen kanssa.

Käyttöönoton hallinnollisen suunnittelun vaiheet.

Tässä osiossa ohjeistetaan seuraavat käyttöönoton suunnittelun vaiheet:

  1. Tutustu Palveluväylän materiaaleihin
  2. Tutustu Palveluväylän ja Liityntäkatalogin ympäristöihin
  3. Sovi yhteyshenkilöistä
  4. Tutustu liityntäpalvelinratkaisuihin
  5. Suunnittele palveluidesi tekninen lähtökohta: SOAP tai REST
  6. Suunnittele mahdollinen sovitinpalvelu

1. Tutustu Palveluväylän materiaaleihin

Tutustu ennen Palveluväylään liittymistä ainakin seuraaviin materiaaleihin:

Lisätietoa löydät seuraavista:

2. Palveluväylän ja Liityntäkatalogin ympäristöt

Palveluväylän ympäristöt

Suomi.fi-palveluväylä toimii kolmessa eri ympäristössä:

  • Kehitysympäristö (FI-DEV): Kehitysympäristössä käytetään keksittyjä organisaatioita ja dataa. Voit kokeilla Palveluväylän toimintaa ilman velvoitteita liittyä testi- tai tuotantoympäristöön. Kehitysympäristöön voivat liittyä myös yksityishenkilöt. Jos haluat liittyä Palveluväylän kehitysympäristöön yksityishenkilönä, saat Palveluväylän tuelta kehitysympäristöön tarvittavat liittymistiedot. Kehitysympäristössä käytetään ympäristöä ylläpitävän operaattorin omia varmenteita, joiden hankkiminen onnistuu sähköpostitse. Saat varmenteet lähettämällä vapaamuotoisen hakemuksen osoitteeseen palveluvayla@palveluvayla.fiAvautuu uuteen ikkunaan.. Lue lisää kehitysympäristöstä ja kehitysympäristöön liittymisestä.
  • Testiympäristö (FI-TEST): Sinun on aina liityttävä testiympäristöön ennen tuotantoympäristöön liittymistä. Testiympäristö vastaa toiminnaltaan tuotantoympäristöä, joten voit testiympäristössä kokeilla Palveluväylän toimintaa ja siihen liittymistä. Testiympäristöön voivat liittyä suomalaisen Y-tunnuksen omaavat organisaatiot tai organisaatiot, joilla ei Suomen lainsäädännön mukaisesti ole rekisteröitymisvelvollisuutta, esimerkiksi yksityiset yritykset, tai joille ei muutoin anneta suomalaista Y-tunnusta, eli esimerkiksi säätiöt tai vastaavat. Liittymisehdot on kuvattu tarkemmin Palveluväylän käyttöehdoissa. Testiympäristössä käytetään oikeita organisaatioita, mutta keksittyä dataa.
  • Tuotantoympäristö (FI): Tuotantoympäristö on Palveluväylän virallinen toimintaympäristö. Sinun tulee liittyä testiympäristöön ennen tuotantoympäristöön siirtymistä. Tuotantoympäristössä noudatetaan samoja ehtoja liittymisen osalta kuin testiympäristössäkin. Tuotantoympäristössä on oikeat organisaatiot ja oikea data.

Palveluväylän ympäristöt

Huomioi, että tarvitset kaikkiin ympäristöihin erilliset liityntäpalvelimet, eli fyysiset tai virtuaaliset palvelimet, joiden kautta viestit kulkevat Palveluväylässä. Lue lisää liityntäpalvelinohjelmiston asentamisesta kehitysympäristöön liityttäessä.

Liityntäkatalogin ympäristöt

Liityntäkatalogi esittelee tuotantoympäristöön liittyneet organisaatiot ja palvelut sekä testiliityntäkatalogi testiympäristöön liittyneet organisaatiot ja palvelut. Kun liityt Palveluväylän testiympäristöön, kuvaa organisaatiosi ja palvelusi Testiliityntäkatalogiin. Kun siirryt Palveluväylän tuotantoympäristöön, kuvaa organisaatiosi ja palvelusi Liityntäkatalogiin.

Liityntäkatalogin ympäristöt.

Lue lisää Palveluväylän ja Liityntäkatalogin ympäristöistä.

3. Sovi yhteyshenkilöistä

Sovi käyttöönoton yhteyshenkilöistä oman organisaation sisällä yhdessä käyttöönoton hallinnollisesta puolesta vastaavan kanssa jo ennen Suomi.fi-palveluväylän varsinaista käyttöönottoa. Hallinnollinen ja tekninen yhteyshenkilö voivat olla sama henkilö. Nimeä organisaatiostasi:

  • Hallinnollinen yhteyshenkilö
  • Hallinnollinen varayhteyshenkilö
  • Tekninen yhteyshenkilö
  • Tekninen varayhteyshenkilö.

Hallinnolliset yhteyshenkilöt voivat olla esimerkiksi projekti-, hanke- tai tietohallintopäälliköitä. Hallinnollisella yhteyshenkilöllä olisi hyvä olla nimenkirjoitusoikeus organisaatiossa. Hallinnollinen yhteyshenkilö vastaa yleensä esimerkiksi käyttöönottoprosessin yleisestä koordinoinnista, käyttölupahakemuksista ja resursoinnista.

Tekniset yhteyshenkilöt voivat olla esimerkiksi sellaisia henkilöitä, jotka ovat vastuussa organisaatiosi tietojärjestelmien ylläpidosta. Tekninen yhteyshenkilö vastaa esimerkiksi liityntäpalvelimen asennus-, konfigurointi- ja ylläpitotehtävistä.

Suosittelemme, että tekniset yhteyshenkilöt ovat henkilöitä, jotka ovat vastuussa organisaatiosi tietojärjestelmien ylläpidosta. Tekniseen suunnitteluun ja käyttöönoton tekniseen toteutukseen osallistuvilla henkilöillä olisi myös hyvä olla perustaidot Ubuntu- tai RHEL-käyttöjärjestelmästä, jotta liityntäpalvelinohjelmiston asentaminen sujuu ongelmitta. Jos organisaatiosi aikoo käyttää kontitettua liityntäpalvelinta, henkilön tulisi tuntea Docker-teknologia.

Ilmoitettujen yhteyshenkilöiden rooli

Huomioi, että tarvitset yhteyshenkilöiden ja varayhteyshenkilöiden nimet ja yhteystiedot Palveluväylän käyttölupahakemusta varten.

Järjestelmän muutospyynnöt (esim. alijärjestelmien lisääminen, palomuurien porttiavaukset) on tehtävä Palveluväylän käyttölupahakemuksessa ilmoitettujen yhteyshenkilöiden välityksellä. Muutospyyntöjen tekemisen voi siirtää kolmannelle osapuolelle ja vastaavan yhteyshenkilön tulee ilmoittaa tästä Palveluväylän ylläpidolle.

4. Tutustu liityntäpalvelinratkaisuihin

Ennen kuin voit aloittaa Palveluväylän käyttöönoton, organisaatiollasi pitää olla erillinen fyysinen tai virtuaalinen palvelin (liityntäpalvelin), jonka avulla Palveluväylään liitytään. Mieti suunnitteluvaiheessa, mikä ratkaisu sopii organisaatiollesi parhaiten:

  • Oman liityntäpalvelimen käyttäminen: Organisaatiosi asentaa liityntäpalvelinohjelmiston sekä huolehtii liityntäpalvelimen ylläpidosta itse.
  • Liityntäpalvelinratkaisun ostaminen ulkopuoliselta palveluntarjoajalta: Organisaatiosi ulkoistaa liityntäpalvelinohjelmiston asentamisen sekä liityntäpalvelimeen liittyvät ylläpitotyöt jollekin ulkoiselle palveluntarjoajalle.
  • Toisen organisaation liityntäpalvelimen käyttäminen: Sovitte jonkin Palveluväylään liittyneen organisaation kanssa, että käytätte heidän kanssaan samaa liityntäpalvelinta sen sijaan, että asentaisitte oman palvelimen.

Jos organisaatiosi toteuttaa liityntäpalvelimen itse, organisaatiosi tulee valita:

  • Liityntäpalvelimen tekninen toteutustapa: Organisaatiosi tulee valita joko RHEL- tai Ubuntu-liityntäpalvelin tai kontitettu liityntäpalvelin.
  • Liityntäpalvelimen käyttöympäristö: Organisaatiosi tulee valita käyttöympäristöksi joko pilviympäristö tai konesali.

Liityntäpalvelinratkaisuista kerrotaan tarkemmin seuraavassa vaiheessa.

5. Suunnittele palveluidesi tekninen lähtökohta: SOAP tai REST

Palveluväylän kautta tarjottavat palvelut voivat perustua joko SOAP-protokollan mukaiseen tiedonsiirtoon tai tiedon esitysmuodosta riippumattomaan REST-arkkitehtuurimalliin. Jos organisaatiosi liittyy Palveluväylään palveluntarjoajana, mieti, tuleeko organisaatiosi käyttämään SOAP- vai REST-rajapintoja tietojen välittämiseen. Myös molempien käyttäminen on mahdollista. Rajapinnan muoto vaikuttaa jonkin verran käyttöönottoprosessin kulkuun.

  • SOAP (Simple Object Access Protocol) on XML-kieleen pohjautuva tietoliikenneprotokolla. SOAP toimii useiden eri protokollien yli, mutta Palveluväylässä sitä käytetään vain HTTP-protokollan yli. SOAP on tietoturvallinen, mutta REST-mallia raskaampi ratkaisu.
  • REST (Representational State Transfer) on HTTP-protokollaan perustuva arkkitehtuurimalli ohjelmointirajapintojen toteuttamiseen. REST ei rajaa rajapinnoissa käytettyä teknologiaa tai tiedon esitysmuotoa. Yleisin REST-sovelluksissa käytetty tiedonesitysmuoto on tällä hetkellä JavaScript Object Notation (JSON), mutta myös muun muotoisia REST-palveluita on mahdollista lisätä Palveluväylään. REST on SOAPia kevyempi ratkaisu, koska se on kevyemmin standardisoitu.

Palveluväylään liittymisen kannalta suurin ero SOAP- ja REST-palveluiden välillä on se, että SOAP-palvelut tarvitsevat pääsääntöisesti erillisen sovitinpalvelun, mutta REST-palvelut eivät. Lisätietoja sovitinpalvelun toteutuksesta ja suunnittelusta löydät myöhemmin tästä osiosta.

6. Suunnittele mahdollinen sovitinpalvelu

Sovitinpalvelu on liityntäpalvelimen ja tietojärjestelmän väliin sijoittuva komponentti, joka sovittaa organisaatiosi järjestelmän palvelut Palveluväylän käyttämän X-Road-tiedonsiirtoprotokollan mukaiseen muotoon. Huomaa, että et tarvitse sovitinpalvelua, kun:

  • SOAP-palvelu on suunniteltu ja toteutettu nimenomaan Palveluväylää varten ja Palveluväylän asettamia vaatimuksia noudattaen.
  • Organisaatiosi käyttää REST-rajapintoja tiedonsiirtoon.

Jos organisaatiosi käyttää olemassa olevia SOAP-rajapintoja tiedon tarjoamiseen Palveluväylän kautta, on sovitinpalvelu tarpeen. Palveluväylän käyttöönotto edellyttää, että siihen liitettävä tietojärjestelmä pystyy lähettämään ja vastaanottamaan SOAP-sanomia Palveluväylän käyttämän X-Road-tiedonsiirtoprotokollan edellyttämässä muodossa. SOAP-sanomiin on sisällytettävä tietyt tiedonsiirtoprotokollan määrittelemät otsikkotiedot. Lisäksi kysely- ja vastausparametrit on sisällytettävä SOAP-sanoman body-osaan protokollan määrittelemällä tavalla.

Sovitinpalvelu ei ole liityntäpalvelinohjelmiston mukana tuleva valmiskomponentti, vaan se on toteutettava jokaiselle liitettävälle järjestelmälle erikseen. Sovitinpalvelun suunnittelu ja toteutus on siis organisaatiosi vastuulla. Sovitinpalvelu voidaan toteuttaa:

  • Suoraan osana liitettävää järjestelmää
  • Järjestelmän ja liityntäpalvelimen väliin sijoitettavana erillisenä ohjelmistokomponenttina

Lue lisää Palveluväylän sovitinpalvelusta.


Siirry seuraavaan vaiheeseen

Päivitetty: 10.10.2024

Oletko tyytyväinen tämän sivun sisältöön?