Tekninen käyttöönotto
Tällä sivulla kerrotaan teknisestä näkökulmasta, mitä vaatimuksia Suomi.fi-viestien käytölle on ja mitä toimenpiteitä Suomi.fi-viestien käyttöönotto pitää sisällään. Voitte lukea lisää käyttöönoton hallinnollisista vaiheista Hallinnollinen käyttöönotto -sivulla.
Huomaattehan, että käyttöönottoprosessi koskee pääasiassa Suomi.fi-viestien REST-rajapintaa. Muiden rajapintojen käyttöönoton vaiheet voivat erota alla kuvatusta.
Lukekaa ensin palvelun esittely Palvelukuvaus-sivulta. Palvelun tarjoamia toiminnallisuuksia käsitellään Toiminnallisuudet -osiossa. Tekninen kuvaus -sivulta voitte lukea lisää siitä, miten Suomi.fi-viestit toimii käytännössä ja mitä rajapintavaihtoehtoja Suomi.fi-viestien käytölle on.
Yleisen tutustumisen lisäksi organisaationne tulee varmistaa, että Suomi.fi-viestien käyttämisen tekniset reunaehdot täyttyvät. Huomioikaa vähintään seuraavat seikat:
- Sähköisten viestin lähettämiseksi organisaatiollanne tulee olla tiedossa vastaanottajan henkilö- tai Y-tunnus, jonka avulla viesti kohdennetaan oikeaan sähköiseen postilaatikkoon.
- Paperipostia lähettäessä organisaatiollanne tulee olla tiedossa vastaanottajan osoitetiedot, sillä Suomi.fi-viesteissä ei ole integraatiota väestö- tai yritystietojärjestelmän osoitetietoja sisältävään rekisteriin.
- Suomi.fi-viestit ei sisällä käyttöliittymää organisaatioille. Palveluun tarjotaan käyttöliittymiä vain loppukäyttäjille.
- Organisaatiollanne tai valitsemallanne toimittajalla tulee olla viestien lähetykseen kykenevä järjestelmä.
- Liityntänne tulee olla tietoturvallisesti toteutettu. REST-rajapinnassa käytetään tietoturvallisia TLS-protokollan salausalgoritmeja, joille käyttämistänne järjestelmistä tulee löytyä tuki. Tulevaisuudessa edellytämme järjestelmiltä tukea TLS 1.3 ‑salaukselle. Suosittelemme mahdollistamaan TLS 1.3 ‑tuen järjestelmissänne jo nyt.
- REST-pyyntöjen autentikaatiossa käytetään autentikaatiotokenia mikä voidaan hakea REST-rajapinnasta organisaation tunnuksella ja salasanalla. Organisaationne väliaikainen salasana tulee vaihtaa ennen käyttöä REST-rajapinnan kutsulla. Salasanan vaihtamiseen suosittelemme automatisoitua säännöllistä prosessia. Autentikaatiotoken vanhenee ja pitää päivittää tarvittaessa.
Mahdolliset yhteydenotot Digi- ja väestötietovirastoon hoidetaan osana hallinnollista käyttöönottoprosessia. Osallistukaa tarvittaessa käyttöönottoa käsitteleviin tapaamisiin yhdessä käyttöönoton hallinnosta vastaavien henkilöiden kanssa.
Tunnistakaa järjestelmienne nykytilanne sekä mitä muutoksia tai integraatioita niihin vaaditaan Suomi.fi-viestien käytön aloittamiseksi.
Tukekaa käyttöönoton hallinnosta vastaavia henkilöitä projektin valmistelussa.
Tukekaa hallinnollista käyttöönottoa käyttölupahakemuksen ja palvelutietolomakkeen täytössä. Etenkin palvelutietolomakkeen täytössä tarvitaan teknisen asiantuntijan osaamista. Käyttölupahakemuksen ja palvelutietolomakkeen yksityiskohtia käsitellään Hallinnollinen käyttöönotto -sivulla.
Lomakkeiden palauttamisen jälkeen DVV tekee avaukset toimittamillenne IP-osoitteille testi- ja tuotantoympäristöön. Testiympäristön osoite on api.messages-qa.suomi.fiAvautuu uuteen ikkunaan. ja sen käyttöohjeet on kuvattu Testiympäristön rajapintadokumentaatiossa (api.messages-qa.suomi.fi, englanniksi)Avautuu uuteen ikkunaan.. Tuotantoympäristön osoite on api.messages.suomi.fiAvautuu uuteen ikkunaan. ja sen käyttöohjeet on kuvattu Tuotantoympäristön rajapintadokumentaatiossa (api.messages.suomi.fi, englanniksi)Avautuu uuteen ikkunaan..
Avauksien lisäksi DVV toimittaa salatulla sähköpostilla organisaatiollenne testihenkilötunnukset, järjestelmätunnuksen (systemId), palvelutunnuksen (serviceId) ja testiympäristön väliaikaisen salasanan. Väliaikainen salasana tulee vaihtaa organisaationne valitsemaan salasanaan seuraavasti:
- Autentikoitukaa saamienne tunnusten avulla testiympäristön token-päätepisteessä. Päätepisteen osoite on api.messages-qa.suomi.fi/v1/token. Username on vastaanottamanne järjestelmätunnus (systemId) ja password on vastaanottamanne väliaikainen salasana.
- Päätepiste palauttaa teille autentikaatiotokenin.
- Vaihtakaa väliaikainen salasana haluamaanne salasanaan testiympäristön change-password-päätepisteessä vaiheessa 2. saamanne autentikaatiotokenin avulla. Päätepisteen osoite on api.messages-qa.suomi.fi/v1/change-password.
- Säilökää valitsemanne salasana tietoturvallisesti.
Voitte testata asettamanne salasanan toimivuutta näin:
- Autentikoitukaa QA-ympäristön token-päätepisteessä. Päätepisteen osoite on api.messages-qa.suomi.fi/v1/token. Username on vastaanottamanne järjestelmätunnus (systemId) ja password on valitsemanne salasana.
- Päätepiste palauttaa teille autentikaatiotokenin.
- Käyttäkää saamaanne autentikaatiotokenia jonkin toisen QA-ympäristön päätepisteen kutsumiseen. Esimerkiksi päätepiste events palauttaa koodin 200, jos tunnukset toimivat.
Nyt pääsette rakentamaan liityntää ja testaamaan sitä testiympäristössä. Huomaattehan, että kaikkien rajapinnan päätepisteiden käyttö vaatii yllä kuvatulla tavalla saadun autentikaatiotokenin, sekä testiympäristössä että tuotantoympäristössä.
Jos organisaationne haluaa ottaa tulostus-, kuoritus- ja jakelupalvelun (TKJ-palvelu) käyttöön, tutustukaa Hallinnollinen käyttöönotto -sivun kohtaan 3 sekä Tulostus-, kuoritus- ja jakelupalvelun käyttöönotto -sivuun. TKJ-palvelun toimittaja Posti Messaging Oy toimittaa paperipostitukseen tarvittavat tunnukset organisaatiollenne kirjeitse.
Tässä vaiheessa tapahtuu itse tekninen kehitys.
Toteuttakaa mahdolliset integraatiot tai muutokset omaan asiointijärjestelmäänne organisaationne tekemien määrittelyjen mukaisesti. Jos liitytte valmisohjelmiston välityksellä, huolehtikaa implementaatiosta yhdessä kyseisen ohjelmiston tuottajan kanssa. Tutustukaa teknisiin kuvauksiin Testiympäristön rajapintadokumentaatiossa (api.messages-qa.suomi.fi, englanniksi)Avautuu uuteen ikkunaan..
Suosittelemme, että toteutatte muutokset yksi rajapinta kerrallaan ja testaatte toteutusta jo kehityksen yhteydessä. Lisäksi toteutuksessa kannattaa ottaa huomioon mahdolliset verkkovirheet ja hetkelliset katkot niin, että lähetätte viestin riittävän monta kertaa ja riittävän pitkään uudestaan.
Testausvaiheessa varmistetaan, että Suomi.fi-viestit toimii kokonaisuutena käytössänne kuten pitääkin. Organisaationne tulee testata kaikki liitynnälleen olennaiset testitapaukset ja niiden vaiheet.
Ohjeet erilaisille testitapauksille on koottu Testausohjeet -sivulle. Testaus tehdään käyttämällä Digi- ja väestötietoviraston organisaatiollenne toimittamia testihenkilötunnuksia.
Huomaattehan, että testiympäristöön ei tule lähettää aineistoja, jotka sisältävät henkilötietoja tai salaista tietoa. Testiympäristö on kaikkien yhteisessä käytössä.
Jos teette suorituskykytestausta isolla volyymilla ja teillä on tarvetta suuremmalle määrälle testihenkilötunnuksia tai Y-tunnuksia, tutustukaa suorituskyvyn ohjeisiin ja olkaa tarvittaessa yhteydessä osoitteeseen viestit-kayttoonotot@dvv.fi.
Valmisratkaisuja käytettäessä keskustelkaa toimittajanne kanssa tarvittavasta testauksen laajuudesta. Organisaationne vastuulla on varmistaa liitynnän asianmukainen testaus.
Varmistakaa, että olette huomioineet kaikki käyttöönoton oleelliset seikat täyttämällä Käyttöönoton tarkistuslista (ks. Hallinnollinen käyttöönotto kohta 7. Palauttakaa tarkistuslista ja siirtykää tuotantokäyttöön).
Kun käyttölupanne on hyväksytty, toimittakaa täyttämänne tarkistuslista DVV:lle ja ilmoittakaa tarkka päivämäärä, jolloin aiotte siirtyä tuotantokäyttöön. Tarkistettuaan täyttämänne tarkistuslistan, DVV toimittaa teille tuotantoympäristön salasanan. Vaihtakaa salasana change-password päätepisteellä.
- Aikaisemmin vastaanottamanne järjestelmätunnus (systemId) ja palvelutunnus (serviceId) toimivat edelleen myös tuotantoympäristössä.
Tuotantoympäristön osoite on api.messages.suomi.fiAvautuu uuteen ikkunaan.. Sen kuvaukset on koottu Tuotantoympäristön rajapintadokumentaatioon (api.messages.suomi.fi, englanniksi)Avautuu uuteen ikkunaan..
Varmistakaa koko palveluputken toimivuus myös tuotantoympäristössä aidolla datalla. Tuotantoympäristössä ette voi enää käyttää testihenkilötunnuksia testien tekemiseen, joten rajoittakaa tuotannon toimivuuden todentaminen välttämättömiin testeihin.
Suomi.fi-viestien tekninen käyttöönotto on nyt valmis, ja voitte siirtyä käyttämään Suomi.fi-viestejä.
Suomi.fi-viestien käyttöön vaadittu tekninen työ ei pääty käyttöönottoon. Organisaationne tulee myös huolehtia liitynnän teknisestä ylläpidosta koko sen elinkaaren ajan. Suosittelemme vaihtamaan REST-rajapinnan salasanan vähintään puolen vuoden välein, mieluiten useamminkin. Tutustukaa tarkempiin ohjeisiin Tekninen ylläpito -sivulla.