Ohjeet järjestelmätoimittajalle
Järjestelmätoimittaja kehittää tai toimittaa organisaation käyttämää tietojärjestelmää, johon on toteutettu integraatio Suomi.fi-viesteihin. Järjestelmätoimittajana teillä onkin keskeinen rooli siinä, millaisia mahdollisuuksia julkishallinnon organisaatiolla on hyödyntää Suomi.fi-viestejä käyttämässään järjestelmässä. Lisäksi voitte tukea asiakasorganisaatiota käyttöönoton eri vaiheissa.
Integraation toteutustapa vaikuttaa esimerkiksi siihen
- kuinka helposti viestejä voidaan lähettää järjestelmästä
- voidaanko viesteihin vastata
- miten viestien tilatietoja hyödynnetään
- miten sähköposti-ilmoituksia hallitaan
- miten viestisisältöjä luodaan
- kuinka hyvin toteutus tukee organisaation arjen prosesseja.
Hyvin toteutettu integraatio auttaa organisaatiota sekä täyttämään lakisääteiset velvoitteensa että hyödyntämään Suomi.fi-viestien ominaisuuksia mahdollisimman tehokkaasti.
Alta löydätte tarkemmat ohjeet järjestelmätoimittajan kehitystyön tueksi.
Suomi.fi-viestien integraation toteutusta suunniteltaessa kannattaa ensin tutustua organisaatioiden käyttötapoihin ja tarpeisiin. Organisaatiot kannattaa ottaa mukaan kehitystyöhön alusta lähtien.
DVV suosittelee tutustumaan organisaatioille tuotettuihin ohjesivuihin sekä tukimateriaaleihin. Ne auttavat hahmottamaan, millaisissa palveluprosesseissa ja käyttötapauksissa Suomi.fi-viestejä voidaan hyödyntää.
Yksittäiseen palvelupolkuun voi liittyä useita viestityyppejä, kuten vastaanottokuittauksia, täydennyspyyntöjä, ajanvarauksia, päätöksiä ja maksumuistutuksia. Eri viesteillä voi olla erilaiset tarpeet esimerkiksi ilmoituksille, viestisisällöille ja lähetystavoille. Organisaation ammattilaisilla voi olla erilaisia tarpeita viestien seurantaan, postilaatikon tilan tarkistamiseen tai kaksisuuntaiseen viestintään.
Jos samaa järjestelmää käytetään useissa palveluissa, kannattaa mahdollistaa useiden palvelutunnusten luominen yhden järjestelmätunnuksen alle. Näin viestit voidaan lähettää kunkin palvelun omissa nimissä. Vastaanottaja näkee heti, mistä palvelusta viesti on tullut. Samalla organisaatio välttyy tarpeelta keksiä kaikille palveluille sopiva yhteinen nimi.
Tärkeitä ohjesivuja:
- Organisaation liittyminen Suomi.fi-viesteihin
- Käyttökohteet organisaatiossa
- Viestien vastaanottajat
- Sähköisen viestin ja ilmoituksen muotoilu
- Suomi.fi-viestien ja asiointipalvelun yhteiskäyttö
Yhteistyössä organisaatioiden kanssa tuotettuja materiaaleja:
- Suomi.fi-viestien asiakastarinatAvautuu uuteen ikkunaan.
- Hyvinvointialueiden toimintamallikuvaukset (erikoissairaanhoito, sosiaalihuolto, laskut, asiakasmaksu- ja päätösasiakirjat)
- Kuntien toimintamallikuvaukset – tulossa! (asianhallinta, varhaiskasvatus, rakennusvalvonta, kaavoitus, pysäköinninvalvonta)
Blogitekstejä, jotka kannattaa lukea:
Toiminnallisuuksien ja niiden ominaisuuksien suunnittelun lähtökohtana tulisi olla asiakkaan palvelupolku sekä ammattilaisten palveluun liittyvä arjen työskentely.
Ratkaisu voisi mahdollistaa esimerkiksi viesti- tai asiakirjatyypeittäin määritellyt toiminnallisuudet, kuten:
- ilmoitukset
- tilatiedot
- lähetystavat
- viestin muotoilu
- kaksisuuntainen viestintä
- postilaatikon tilan tarkistaminen
- muut lisäautomaatiot
Näin esimerkiksi päätöksille, lisätietopyynnöille ja laskuille voitaisiin määrittää omat käytännöt, mikä tekee ratkaisusta joustavan ja erilaisiin tarpeisiin skaalautuvan.
Organisaation ammattilaiset voivat haluta mahdollisuuden muokata viesteihin liittyviä asetuksia itse. Kannattaa arvioida, mitä ominaisuuksia organisaation ammattilaiset voisivat hallita. Esimerkiksi:
- sähköposti-ilmoitusten muokkaaminen
- sähköisen viestin tekstisisältöjen muokkaaminen
- lukematon viesti -sähköposti-ilmoituksien määrittely
- vastaus mahdollisuuden määrittely viestikohtaisesti
Kaikkiin REST-rajapinnan toiminnallisuuksiin voi perehtyä Toiminnallisuudet -sivukokonaisuuden alta.
Suunnitteluvaiheessa voitte olla yhteydessä myös DVV:n asiantuntijoihin, joilla on monipuolisesti tietoa asiakastarpeista, viestien käyttötapauksista ja teknisistä toteutusvaihtoehdoista.
Voitte hakea kehitystyön tueksi omaan käyttöönne testitunnukset. REST-rajapinnan testitunnusten avulla saatte pääsyn Suomi.fi-viestien testiympäristöön. Järjestelmätoimittajille ei luoda tunnuksia ollenkaan tuotantoympäristöön.
Täyttäkää Palvelutietolomake (DOCX, 218,34 kt)Avautuu uuteen ikkunaan.ja palauttakaa se Digi- ja väestötietovirastolle (DVV) osoitteeseen viestit-kayttoonotot@dvv.fi. Voitte saatteessa tarkentaa, että kyse on järjestelmätoimittajan testitunnuksista ja lyhyesti kuvata, millaisesta järjestelmäintegraatiosta on kyse.
Palvelutietolomakkeen tietojen perusteella teille lisätään käyttöoikeudet Suomi.fi-viestien testiympäristöön ja saatte REST-rajapinnan testitunnukset.
TKJ-palvelun testitunnukset
Tulostus-, kuoritus- ja jakelupalvelun (TKJ) kehittämistä ja testaamista varten on myös mahdollista tilata TKJ-tunnus.
TKJ-tunnus on järjestelmätoimittajille maksullinen. TKJ-tunnuksen voi tilata täyttämällä TKJ-tilauslomakkeen. Lomakkeen lopusta löytyy järjestelmätoimittajille erikseen tarkoitettu osio sekä TKJ-tunnuksen hinta.
Testausohjeet -sivulta löytyy lisätietoa testaamisesta. Huomioittehan, että testiympäristöön ei tule lähettää aineistoja, jotka sisältävät henkilötietoja tai salaista tietoa. Testiympäristö on kaikille yhteinen, joten testiympäristössä on samanaikaisesti useiden organisaatioiden testiaineistoja.
REST-rajapinnan kaikki tekniset kuvaukset on koottu Rajapintadokumentaatioon (api.messages.suomi.fi, englanniksi)Avautuu uuteen ikkunaan..
Kun integraatio on valmis ja olette valmiita ottamaan asiakkaita tuotantoon, ilmoittakaa asiasta DVV:lle. Ilmoittakaa samalla järjestelmätoimittaja listausta varten kuvaus ratkaisustanne sekä linkki haluamallanne verkkosivulle.
Lisäättehän myös omille verkkosivuillenne sekä asiakasmateriaaleihin tiedon, että järjestelmään on mahdollista saada integraatio Suomi.fi-viesteihin ja mitä toiminnallisuuksia ratkaisu tukee.
Tutustukaa myös Ylläpito -sivulta löytyviin ohjeisiin.
Käyttöönottoprosessiin voi tutustua Käyttöönotto organisaatiossa -sivulla. Jokaisen Suomi.fi-viestejä käyttöönottavan organisaation tulee käydä läpi Hallinnollinen käyttöönotto -sivulla kuvattu prosessi.
Käyttöönoton etenemiseksi organisaation on huolehdittava, että
- käyttölupa on voimassa,
- organisaatio täyttää ja palauttaa palvelutietolomakkeen saadakseen testitunnukset,
- organisaatio täyttää ja palauttaa käyttöönoton tarkistuslistan saadakseen tuotantotunnukset.
Käyttöönoton yhteydessä DVV:lle palautettavien dokumenttien tiedot ovat organisaatiota sitovia. Järjestelmätoimittaja ei voi täyttää eikä palauttaa palvelutietolomaketta tai käyttöönoton tarkistuslistaa organisaation puolesta.
Käyttöönoton aikana järjestelmätoimittaja rooli on tukea organisaatiota lomakkeiden täyttämisessä esimerkiksi kertomalla järjestelmän toiminnallisuuksista. Organisaatio käy kuitenkin itse dokumentit huolellisesti läpi ja varmistaa, että niissä ilmoitetut tiedot ovat oikein.
Testaaminen organisaatiossa
Organisaatiolle kannattaa korostaa testaamisen tärkeyttä osana käyttöönottoprosessia. Testaamisen ansiosta organisaatio hahmottaa paremmin, millaiselta ilmoitukset, viestit, palvelun nimi, linkit ja liitteet näyttävät loppukäyttäjän silmin.
Näin saadaan varmistettua, että asiointipalvelu on sujuva, viestisisällöt ymmärrettäviä ja että kokonaisuus tukee asiakkaan asiointia.
Suomi.fi-viestien vanhat rajapinnat (WS, SFTP ja SMTP) ovat ylläpitotilassa, eikä niihin enää tuoteta uusia toiminnallisuuksia. Kaikki vanhat rajapinnat suljetaan 1.1.2027.
Kaikkien Suomi.fi-viestejä vanhoilla rajapinnoilla olevien palvelujen pitää siirtyä käyttämään uutta REST-rajapintaa ennen vuotta 2027.
Huolehdittehan, että asiakasorganisaationne ovat siirtyneet käyttämään REST-rajapintaa hyvissä ajoin ennen vuoden vaihdetta.
Lisätiedot ja tarkennukset REST-siirtymästä, sen aikataulusta tai organisaatioita koskevista toimenpiteistä: viestit-kayttoonotot@dvv.fi