Suomi.fi-palveluväylä – Käyttöönoton ohje

1. Johdanto

1.1 Käyttöönoton ohje

Tässä dokumentissa kuvataan Suomi.fi-palveluväylän käyttöönoton eri vaiheita ja annetaan ohjeistusta mitä kannattaa ottaa huomioon, kun suunnittelee, toteuttaa, ottaa käyttöön ja ylläpitää oman organisaation palveluväylän liitosta. Tätä dokumenttia lukiessa on hyvä pitää mielessä, että ohjeistus ei ole tarkoitettu noudatettavaksi kirjaimellisesti vaan pikemminkin suuntaa antavaksi ohjeistukseksi.

1.2 Käsitteet

Asiakas tarkoittaa liittyvää organisaatiota tai yritystä. Asiakkaan rooli Suomi.fi-palveluväylässä voi olla palvelujen tarjoaja ja/tai hyödyntäjä.

Palvelu tarkoittaa asiakkaan hallinnoimaa tietovarantoa tai tietojärjestelmää, joka liitetään Suomi.fi-palveluväylään.

REST (en. Representational State Transfer) on HTTP-protokollaan perustuva arkkitehtuurimalli ohjelmointirajapintojen toteuttamiseen. Palveluväylä sisältää oletusarvoisesti SOAP-rajapinnan, mutta sovitinpalvelun avulla myös REST on mahdollinen. Katso sovitinpalvelusta lisää kappaleesta 3 kohdasta ’Sovitinpalvelu’.

SLA (Service Level Agreement) tarkoittaa palvelutasosopimusta. Se on asiakkaan ja palveluntarjoajan välinen sopimus, jossa määritellään palvelulle tietyt vaatimustasot. Sitä mitataan erityyppisillä mittareilla ja palvelutason alittamisesta seuraa yhteisesti sovittu sanktio.

SOAP (en. Simple Object Access Protocol), on XML-kieleen pohjautuva tietoliikenneprotokolla, jota Suomi.fi-palveluväylän rajapintatoteutuksessa käytetään.

Suomi.fi-palveluväylä on standardoitu tiedonsiirtokanava, joka tarjoaa vakioidun tavan tietojen siirtoon organisaatioiden välillä sekä mahdollistaa turvallisten palvelukokonaisuuksien rakentamisen.

Tietojärjestelmä on asiakkaan hallinnoima operatiivinen järjestelmä joka liitetään Suomi.fi-palveluväylään (kts. kohta Palvelu)

Toimittaja tarkoittaa Suomi.fi-palveluväylän omistajaa, Väestörekisterikeskusta.

1.3 Suomi.fi-palveluväylän käyttöönoton edellytykset

Käyttöönotto edellyttää, että Suomi.fi-palveluväylän käyttö oman organisaation kannalta on ennakkoon mietitty ja sitä koskevat vaatimukset selvitetty. Tärkeä on tiedostaa halutaanko hyödyntää jotain palveluväylän kautta tarjottavaa palvelua vai onko tarkoitus tarjota omaa palvelua muille. Palveluväylän käytön perusteet ja liittymisen vaiheet tulisi olla siis selvitetty.

2. Suomi.fi-palveluväylän käyttöönottoprosessi – Aloitus

Käyttöönottoprosessin aluksi kannattaa ainakin seuraavat tarkastuslistan mukaiset asiat käydä läpi:

2.1 Tutustu KaPA lakiin:

Onko oma organisaationi: 1) velvoitettu vai 2) oikeutettu käyttämään Palveluväylää

Lue lisää KaPA laista täältä:

2.2 Sovi vastuuhenkilöistä

Teknisten ja hallinnollisten vastuuhenkilöiden nimeäminen:

Asiakkaan tulee nimetä teknisen yhteyshenkilö ja teknisen varayhteyshenkilö. Käytännössä tekninen yhteyshenkilö vastaa käyttöönoton aikaisista liityntäpalvelimen asennus-, konfigurointi-, ja ylläpitotehtävistä.

Asiakas nimeää hallinnollisen yhteyshenkilön ja varayhteyshenkilön, joita voivat olla esimerkiksi projekti-, hanke-, tai tietohallintopäälliköt. Hallinnollinen yhteyshenkilö voi olla myös sama kuin tekninen yhteyshenkilö.

2.3 Suunnittele ja resursoi

Mitä tarvitaan, jotta saadaan vietyä oma palvelu Suomi.fi-palveluväylään? Tässä kohden on hyvä sopia käyttöönoton aikaisesta budjetista, laatia tarvittavat hankintasopimukset muun muassa palvelimien ja henkilöresurssien osalta.

2.4 Tutustu Palveluväylän materiaaleihin

2.5  Tee käyttölupahakemus

Palveluväylään liitytään täyttämällä käyttölupahakemus liity palveluväylään -sivulla.

Samalla hyväksytään Palveluväylän käyttöehdot.

2.6 Täytä ja lähetä varmennehakemukset

Varmennehakemukset tehdään, jos organisaatio liittyy joko FI-TEST(testiympäristö) tai FI (tuotantoympäristö) ympäristöihin. FI-DEV (kehitys- ja kokeiluympäristö) ympäristöön ei varmenteita tarvita.

Testiympäristöön (FI-TEST) on liityttävä ennen tuotantoympäristöön liittymistä. Kun palveluväylän ylläpito tai hyödyntäjä/tarjoaja-osapuolet ovat todenneet yhteyksien olevan kunnossa, voidaan aloittaa tuotantoympäristöön (FI) liittyminen.

Varmennehakemuksien täyttämiseen on varattava aikaa, koska hakemuksessa kyseltäviä tietoja on paljon ja puutteellisesti täytetyt varmennehakemukset palautuvat asiakkaalle korjattavaksi. Tästä syystä varmennehakemuksien käsittelyyn ja hyväksymiseen on syytä varata 2-3 viikkoa kalenteriaikaa.

Varmennehakemuksien täyttöohjeet ja valmiit, täytetyt esimerkit löytyvät eSuomi.fi sivustolta liity palveluväylään.

2.7 Suunnittele Suomi.fi-palveluväylään liittymisen aikataulu

Suunnittele palveluväylään liittymisen aikataulu – projektin aloitus sekä aiottu valmiiksisaattaminen  – sekä testi- että tuotantoympäristön osalta. Arvioi myös työmäärä, joka tarvitaan tavoitteiden saavuttamiseksi.

Tyypillisesti käyttöönottoprojektin läpiviemiseen kannattaa varata vähintään 3kk-6kk kalenteriaikaa. Aikataulu riippuu hyvin paljon siitä minkälaisesta hankkeesta on kyse: onko tarkoitus vain liittyä palveluväylään esimerkiksi FI-DEV kehitysympäristössä ja vasta sen jälkeen alkaa tutustua väylän käyttöön tarkemmin kokeilemalla asioita? Ja vasta kokeilemisen jälkeen miettiä miten väylää voisi paremmin hyödyntää. Vai onko tarkoitus liittää väylään oma, iso tietojärjestelmä/palvelu ja sovittaa sen käyttö käyttööottoprojektin myötä palveluväylään yhteensopivaksi?

Palveluväylään liittymisprosessiin ja hakemuksien käsittelyihin sekä palvelin ohjelmiston asennuksiin kannattaa varata noin 1kk kalenteriaikaa. Ison tietojärjestelmän/palvelun liittäminen vaatii moninkertaisen ajan suunnitteluineen, sovitustöineen ja testauksineen. Tyypillinen ison tietojärjestelmän/palvelun käyttöönottoaika on kalenteriajassa mitattuna 6kk-12kk.

3. Suomi.fi-palveluväylän käyttöönottoprosessi – Suunnittelu

Käyttöönottoa suunniteltaessa seuraaviin asioihin on syytä kiinnittää huomiota:

3.1 Liitokset muihin palveluihin

Tarvitaanko liitoksia tai integraatioita toisiin palveluihin 1) oman organisaation sisällä ja/tai 2) Suomi.fi-palveluväylässä muiden organisaatioiden tarjoamiin palveluihin (esimerkiksi VRK:n väestötietojärjestelmä VTJ).

3.2 Sovitinpalvelu

Oman palvelun liittäminen Suomi.fi-palveluväylään vaatii todennäköisesti ns. sovitinpalvelun käyttöä. Sovitinpalvelu on palveluväylän liityntäpalvelimen ja organisaation liitettävän tietojärjestelmän väliin sijoittuva komponentti, joka sovittaa liitettävän järjestelmän tarjoamat palvelut palveluväylän tiedonsiirtoprotokollan mukaiseen muotoon.

Palveluväylään käyttöönotto edellyttää, että liitettävä tietojärjestelmä pystyy lähettämään ja vastaanottamaan SOAP-sanomia palveluväylän edellyttämässä muodossa. Käytännössä tämä tarkoittaa sitä, että SOAP-sanomien on sisällettävä tietyt palveluväylän tiedonsiirtoprotokollan määrittelemät otsikkotiedot. Lisäksi kysely- ja vastausparametrit on sisällytettävä SOAP-sanoman body-osaan protokollan määrittelemällä tavalla. Lisäksi sovitinpalvelun on myös tarjottava liitettävien palveluiden rajapintakuvaukset (ns. WSDL kuvaukset).

Palveluväylään liitettyjen palveluiden rajapintakuvausten (WSDL) tarjoaminen liityntäpalvelimelle.

Sovitinpalvelu ei ole liityntäpalvelinohjelmiston mukana tuleva valmiskomponentti, vaan se on toteutettava jokaiselle liitettävälle järjestelmälle erikseen. Asiakaan vastuulle jää sovitinpalvelun sunnittelu ja toteutus

Lisätietoja sovitinpalvelusta löytyy eSuomi.fi sivustolta Sovitinpalvelu -dokumentista.

3.3 Palvelun tukimalli

Miten oman Suomi.fi-palveluväylään liitettävän palvelun käytössä tarvittava tuki hoidetaan? Kuka hoitaa esimerkiksi mahdolliset käyttäjätukiasiat ja ratkaisee järjestelmässä ilmaantuvat käyttäjien ongelmat?

Tukimalli on sovittava joko oman organisaation sisällä (esim. oman organisaation IT-osasto hoitaa tuen), tai tuki voidaan ulkoistaa (esim. sopivalle IT-toimittajalle).

3.4 Palvelutasosopimus eli SLA

Suomi.fi-palveluväylään tarjottavan palvelun asennukseen, ylläpitoon ja tukipalveluita varten voidaan tehdä palvelusopimus. Sopimus voidaan tehdä joko oman organisaation sisäisesti, tai palvelu voidaan ulkoistaa esimerkiksi jollekin IT-toimittajalle. Tällöin tehdään sopimus palvelun hoitamisesta palvelutasosta. Sopimuksessa määritellään palvelulle tietyt vaatimustasot ja sen alittamisesta seuraa yhteisesti sovittu sanktio.

3.5 Tarkennettu aikataulu ja työmääräarvio

Laadi projektisuunnitelma tai vastaava suunnitelma, jossa on suunniteltu aikataulu ja työmääräarvio palveluväylän käyttöönotosta.

3.6 Testi- ja tuotantoympäristöjen ominaisuudet

On olennaista ymmärtää kehitys-, testi- ja tuotantoympäristöjen erot ja milloin voidaan siirtyä  tuotantoympäristöön.

Lue lisää eri ympäristöistä täältä:

4. Suomi.fi-palveluväylän käyttöönottoprosessi – Toteutus

Toteutuksen aikana tehdään seuraavat asiat:

4.1 Testiympäristöön liittyminen

Suomi.fi-palveluväylä – Liity palveluväylään

4.2 Varmennetilaus (viimeistään tässä vaiheessa, mieluummin jo edeltävässä vaiheessa)

Varmenteiden hakemiseen löytyvät ohjeet Liity palveluväylään sivulta. Sivun oikeassa reunassa löytyvät tarvittavat hakemuspohjat ja esimerkit hakemuksien täyttämisestä.

4.3 Liityntäpalvelimen asennus (FI-TEST)

Ohjeet liityntäpalvelimen asennukseen löydät täältä:

RHEL7 liityntäpalvelimen asennusohjeet FI-TEST ympäristössä

Ubuntu liityntäpalvelimen asennusohjeet FI-TEST ympäristössä

4.4. Konfiguraatioankkurin asennus

Palveluväylän ylläpito lähettää ympäristökohtaisen (FI-TEST) Suomi.fi-palveluväylän konfiguraatiotiedoston eli ns. konfiguraatioankkurin

4.5 Yhteyksien avaus (palomuurit jne.)

Oman organisaation liityntäpalvelimen tiettyjen porttien avaaminen muille Suomi.fi-palveluväylään liittyneille.

Palveluväylän ylläpito lähettää ohjeet näiden tekemisestä.

4.7 Rekisteröintipyyntö

Palveluväylän ylläpito viimeistelee palvelimen liittämisen palveluväylään.

4.8 Liityntäpalvelimen konfigurointi omien palveluiden tarjoamiseksi tai muiden palvelujen hyödyntämiseksi

Jokaisen palveluväylää käyttävän organisaation on lisättävä vähintään yksi alijärjestelmä käyttämänsä liityntäpalvelimen oman organisaation alle.

Alijärjestelmän lisääminen (ja poistaminen) on ohjeistettu eSuomi.fi sivustolla Alijärjestelmän lisääminen ja poistaminen.

4.9 Omien, palveluväylään tarjottavien, palveluiden konfigurointi

Kun uusi alijärjestelmä on lisätty, sen alle voidaan lisätä uusi tarjottava palvelu. Tässä kohtaa puhutaan siis siitä, että palveluntarjoaja haluaa tuoda palveluväylään oman tietojärjestelmänsä palvelun jota muut voivat käyttää. Uuden palvelun lisääminen tapahtuu liityntäpalvelimen ylläpitoliittymän kautta. Ohjeistus aiheeseen löytyy eSuomi.fi sivustolta Uuden palvelun lisääminen

4.10 Asiakasjärjestelmän liittäminen liityntäpalvelimelle

Muiden tarjoamia palveluita palveluväylässä voi käyttää liittämällä toisen organisaation asiakasjärjestelmän omaan liityntäpalvelimeen. Huomioitavaa on, että asiakasjärjestelmän tarjoavan organisaation on ensin annettava lupa järjestelmän käyttöön ennen kuin se voidaan lisätä omalle liityntäpalvelimelle.

Ohjeistus asiakasjärjestelmän liittämiseksi löytyy eSuomi.fi-sivulta Asiakasjärjestelmän lisääminen

4.11 Sovitinpalvelun käyttöönotto

Sovitinpalvelun asennus, konfigurointi ja testaaminen

Käyttöönottoprosessia kokonaisuudessaan on kuvattu seuraavassa kaaviossa:

palveluvaylan-kayttoonottoprosessi-9-12-2016 Palveluväylän käyttöönottoprosessi

5. Suomi.fi-palveluväylän käyttöönottoprosessi – Testaaminen ja viimeistely

5.1 Testaaminen testiympäristössä (FI-TEST)

Laadi testitapaukset omalle palvelu(i)lle.

Tällä hetkellä testaaminen tapahtuu niin, että testiympäristöön liitetään kaksi liityntäpalvelinta: sekä palvelun tuottajan että palvelun kuluttajan liityntäpalvelimet. Nämä kaksi sitten viestivät keskenään ja tarjottavien palveluiden toiminta voidaan tällä tavalla testata. Liityntäpalvelimet voivat olla joko kummatkin oman organisaation liityntäpalvelimia tai niin, että toinen liityntäpalvelin on organisaation oma (esimerkiksi palvelua tarjottaessa palvelun tuottajan liityntäpalvelin) ja toinen liityntäpalvelin jonkin toisen organisaation omistama (esimerkiksi palvelua hyödynnettäessä palvelun kuluttajan liityntäpalvelin). Tarkoituksena on testata koko viestiketjun toimivuus niin, että viestit kulkevat palvelun tuottajan ja palvelun kuluttajan välillä ja takaisin.

Palveluväylässä on myös olemassa muutamia yksinkertaisia testipalveluita, joiden avulla oman liityntäpalvelimen perus SOAP-viestien toiminta voidaan testata.

5.2 Bugikorjaukset

Testauksen aikana havaitut virheet kirjataan ja korjataan ennen tuotantoon siirtymistä.

5.3 Varmennetilaus tuotantoympäristöä varten (jos ei ole jo tehty)

Tuotantoympäristön varmennetilauksen voi tehdä valmiiksi jo testiympäristön varmennetilausten yhteydessä.

5.4 Tuotantoympäristön asennus kun testaus on ok.

Kun on todettu, että palveluväyläliitos ja tulevat rajapinnat toimivat oikein, palveluväylän ylläpito antaa luvan siirtyä tuotantoympäristöön.

5.5 Dokumentoinnin viimeistely

Asennus-ja/tai ylläpitodokumenttien sekä muun mahdollisen dokumentaation täydentäminen ja korjaukset.

5.6 Sopimusten vahvistus

Mahdollisesti vielä auki olevien sopimusten vahvistaminen. Esimerkiksi tuotantoympäristön palvelimien vuokraus, asennus- ja konfigurointipalvelut, ylläpitopalvelut jne.

6. Suomi.fi-palveluväylän käyttöönottoprosessi – Tuotantokäyttö

6.1 Hyväksyntä tuotantoympäristöön siirtymisestä

Lupa siirtyä tuotantoympäristöön saadaan kun FI-TEST ympäristössä oleva oma palvelu täyttää tuotantoympäristön vaatimukset

Palveluväylän ylläpito vahvistaa hyväksynnän (hyväksymispyyntö osoitteeseen: palveluvayla@palveluvayla.fi)

6.2 Tuotantoympäristöön liittyminen (FI-tuotantoympäristö)

6.3 Liityntäpalvelimen asennus (FI-tuotantoympäristö)

Ympäristöjen yleissivun, josta löytyy kaikki ohjeet:

FI-tuotantoympäristö palveluväyläohjelmiston asennusohjeet:

6.4 Konfiguraatioankkurin asennus

Palveluväylän ylläpito lähettää Suomi.fi-palveluväylän konfiguraatiotiedoston eli ns. konfiguraatioankkurin

6.5 Yhteyksien avaus (palomuurit jne.)

Oman organisaation liityntäpalvelimen tiettyjen porttien avaaminen muille palveluväylän tuotantoympäristöön liittyneille.

Palveluväylän ylläpito lähettää ohjeet näiden tekemisestä.

6.6 Rekisteröintipyyntö

Palveluväylän ylläpito viimeistelee palvelimen liittämisen palveluväylään.

6.7 Liityntäkatalogin päivitys mikäli tietoja tarjolla

Liityntäkatalogi on ajantasainen hakemisto kansallisen palveluväylän liitynnöistä. Liityntäkatalogin tarkoituksena on auttaa palvelun tuottajia ja toteuttajia kehittämään tehokkaampia sähköisiä palveluita ja tukea tietojen uudelleenkäyttöä. Liityntäkatalogiin kuvataan sähköiset palvelut, joissa käsiteltävät tiedot ovat muiden tietojärjestelmien hyödynnettävissä.

6.8 Tuotantoon siirto

Jatkuvan palvelun aloitus ja ylläpito vaiheeseen siirtyminen

7. Suomi.fi-palveluväylän käyttöönottoprosessi – Ylläpito

Jatkuvan palvelun ylläpitovaiheessa väylään liittyjän on ylläpidettävä ja huollettava liityntäpalvelintaan.

7.1 Väylään liittyjän vastuut:

  • Vastaa omien tietojensa ja palveluidensa ylläpidosta
  • Liittyjä vastaa omasta liityntäpalvelimestaan, sen asennuksesta, konfiguroinnista ja valvonnasta
  • Liityntäpalvelimen omistaja ja/tai palvelun tarjoaja päättää siitä kuka saa kutsua organisaation liityntäpalvelinta ja siihen liitettyjä palveluja. Toisin sanoen: kuka saa käyttää väylään tarjottavaa palvelua (tietoluvitus, kahden osapuolen keskinäinen sopimus)
  • Liittyjä vastaa siitä, että kytkettävät palvelut täyttävät määritellyt tekniset rajapintavaatimukset

Jos palveluun tulee uusia versioita saataville, niin tällöin palveluväylä yhteensopivuus on varmistettava

7.2 Liityntäpalvelimen ylläpidon vastuut:

  • Versiopäivitykset (käyttöjärjestelmä + uudet liityntäpalvelimien versiot)
  • Lokien arkistoinnit, levytilan vapauttaminen
  • Käyttöoikeudet, varmuuskopiot, jne.

7.3 Ylläpidossa huomioitavia asioita:

  • Ylläpito ja admin toiminnot vaativat resursseja
  • Liityntäpalvelimen valvonta on suositeltavaa, jotta järjestelmä pysyy stabiilina ja käyttökunnossa
  • Päivityksiä tulee jatkuvasti, niiden tekeminen hyvin suositeltavaa
  • OS tason päivitykset (turvapäivitykset, batchit, uudet versiot jne.)
  • Liityntäpalvelimista julkaistaan uusia versioita 2-3 kpl/vuosi
  • Levytilan valvonta on tärkeää
  • Testiympäristö tarjoaa hyvän vaiheen kokeilla palvelinkapasiteetin riittävyyttä tuotantoympäristön viesti- ja käyttäjämääriä silmällä pitäen.
  • Levytila täyttyy, jos arkistoituja tietoja ei siirretä talteen (tai poisteta).
  • Kannattaa myös huomioida, että esimerkiksi lait tai asetukset saattavat asettaa vaatimuksille sille miten pitkään tietoja on säilöttävä => tämä pitää ottaa huomioon levytilan käyttöä arvioitaessa.
  • Käyttäjämäärät ratkaisevia mm. levytilan ja alustakoneen valinnassa.
  • (Yhtäaikaisten) käyttäjien määrän kasvaessa tulee enemmän viestejä ja kuormitusta järjestelmään => vaatii enemmän kapasiteettia alustalta.
  • Suositeltavaa on, että liityntäpalvelimet olisivat kahdennettuja, jotta vikatilanteessa vara-liityntäpalvelin voidaan ottaa käyttöön.

Print Friendly, PDF & Email

VersioMitä tehty / muutettuPvm/
henkilö
1.0Dokumentti julkaistu.22.12.16 / NP & HH
1.1’Liity palveluväylään’ -linkki korjauttu.30.10.17 / HH

Yksilöintitunnus: 12345