Suomi.fi Viestit ‐integraatio

eVaka lähettää mm. varhaiskasvatuksen paikkapäätöksistä viralliset dokumentit Suomi.fi Viestit -palvelun kautta kuntalaisille. Jos kuntalaisella on sähköinen palvelu käytössä, viesti kulkee sinne ja Suomi.fi lähettää siitä sähköpostinotifikaation. Jos sähköistä palvelua ei ole, Suomi.fi lähettää viestin postituspalveluun ja dokumentti kulkee paperipostina.

eVaka tukee sekä uutta REST-pohjaista Viestit-rajapintaa, että vanhaa poistuvaa SOAP-pohjaista rajapintaa. Kuukausittainen yöllinen ja vikasietoinen ajo eVakassa hoitaa REST-rajapinnan salasanan rotatoimisen automaattisesti.

Suomi.fi REST-rajapinnan käyttöönotto

1. Hallinnollinen käyttöönotto ja sopimus DVV:n kanssa

Käyttöönotto lähtee DVV:n kanssa keskustelusta ja hallinnollisesta puolesta, joista löytyy tarkemmat ohjeet DVV:n omista käyttöönotto-ohjeista: https://kehittajille.suomi.fi/palvelut/viestit/kayttoonotto Kun käyttöönotosta on sovittu DVV:n kanssa, DVV lähettää rajapinnan käyttöön tarvittavan salasanan, joka tarvitaan teknistä käyttöönottoa varten

2. Rajapintasalasanan konfigurointi ja AWS-käyttöoikeudet

Rajapintasalasana laitetaan AWS SSM-palveluun johonkin polkuun SecureString-tyyppisenä arvona, ja eVakan Viestit REST-integraatio tarvitsee luku-ja kirjoitusoikeudet siihen. Polun nimi, esim. /prod/evaka/sfi-viestit-password voidaan valita vapaasti, ja se kerrotaan evaka-servicelle ympäristömuuttujan kautta.

SSM-parametrin ensimmäiselle arvolle pitää antaa CURRENT-niminen label (ei sama asia kuin tagi), esim. AWS:n käyttöliittymän kautta tai AWS CLI:n avulla (esim. aws ssm label-parameter-version --name /prod/evaka/sfi-viestit-password --labels CURRENT).

evaka-servicelle tulee antaa AWS IAMin avulla oikeudet tehdä nämä operaatiot kyseiselle SSM-parametrille:

• ssm:GetParameter
• ssm:PutParameter
• ssm:LabelParameterVersion

Jos jokin AWS-oikeus puuttuu, salasanan lukeminen ja/tai rotatointi epäonnistuu.

3. evaka-service:n konfigurointi

REST-rajapinta konfiguroidaan evaka-serviceen seuraavilla muuttujilla, jotka voidaan konfiguroida ympäristömuuttujina (ISOT_KIRJAIMET_JA_PISTEET_ALAVIIVOINA, esim. EVAKA_INTEGRATION_SFI_REST_ADDRESS), tai yaml-konfiguraation kautta:

• evaka.integration.sfi.enabled=true
• evaka.integration.sfi.rest_enabled=true
• evaka.integration.sfi.rest_address: joko https://api.messages.suomi.fi (Suomi.fi tuotantoympäristö) https://api.messages-qa.suomi.fi (Suomi.fi testiympäristö)
• evaka.integration.sfi.rest_username: DVV:n kertoma REST-rajapinnan palvelutunnus/käyttäjätunnus
• evaka.integration.sfi.rest_password_ssm_name: polku (ei ARN) AWS SSM-parametriin josta löytyy DVV:n kertoma REST-rajapinnan salasana, esim /prod/evaka/sfi-viestit-password
• evaka.integration.sfi.service_identifier: DVV:n kertoma lähettävän organisaation palvelutunnus

Paperipostin lähetyksen tiedot:

• evaka.integration.sfi.contact_person.email: lähettävän organisaation yhteyshenkilön sähköpostiosoite
• evaka.integration.sfi.printing.billing.id: postituspalvelun käyttäjätunnus
• evaka.integration.sfi.printing.billing.password: postituspalvelun salasana

Paperipostin lähettävän organisaation tiedot:

• evaka.integration.sfi.contact_organization.name: organisaation nimi
• evaka.integration.sfi.contact_organization.street_address: osoite
• evaka.integration.sfi.contact_organization.postal_code: postinumero
• evaka.integration.sfi.contact_organization.post_office: postitoimipaikka

4. Ensimmäinen salasanan rotatoinnin käynnistys manuaalisesti

Kun DVV:ltä saatu ensimmäinen salasana on SSM:ssä ja evaka-servicen konfiguraatio paikallaan, rotaatio kannattaa testata käynnistämällä se manuaalisesti. Manuaalinen käynnistys tapahtuu lisäämällä tausta-ajo käsin tietokantaan kyselyllä:

INSERT INTO async_job (type, retry_count, retry_interval, payload)
VALUES ('RunScheduledJob', 1, '5 minutes', '{"job": "RotateSfiMessagesPassword"}');

Jos konfiguraatiossa ja/tai AWS-käyttöoikeuksissa on virhe, tausta-ajo epäonnistuu ja ongelma tulee korjata virheen perusteella. Jos tausta-ajo menee läpi, SSM:ään pitäisi ilmestyä uusi versio parametrista (esim. versio 2), ja tälle versiolle pitäisi tulla CURRENT ja PENDING -labelit.

5. Valmis

REST-rajapinta on nyt käytössä. Jos kyse on testiympäristöstä ja käyttöönoton testausvaiheesta, DVV:n omista testausohjeista löytyy tarkemmat tiedot miten sähköinen kanava ja paperipostitus testataan. eVakan puolella lähetyksen saa helpoiten testattua tekemällä esim. paikkapäätös jollekin lapselle yksikköön.