Suomi.fi Viestit ‐integraatio - espoon-voltti/evaka GitHub Wiki

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 käyttää REST-pohjaista Viestit-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. Suomi.fi viestien tapahtuma-integraatio

Suomi.fi -viestit palvelu tarjoaa lähetetyn viestin tapahtumatiedot /v2/events -rajapinnan kautta. Yhteen lähetettyyn viestiin voi liittyä yksi tai useampi tapahtuma, kuten tieto siitä lähetettiinkö viesti sähköisesti vai paperisena. Listaus evakaan talletettavista tapahtumien arvoista, suluissa rajapinnan kautta tulevat arvot:

  • ELECTRONIC_MESSAGE_CREATED("Electronic message created")
  • ELECTRONIC_MESSAGE_READ("Electronic message read")
  • ELECTRONIC_MESSAGE_FROM_END_USER("Electronic message from end user")
  • RECEIPT_CONFIRMED("Receipt confirmed")
  • PAPER_MAIL_CREATED("Paper mail created")
  • SENT_FOR_PRINTING_AND_ENVELOPING("Sent for printing and enveloping")
  • POSTI_RECEIPT_CONFIRMED("Posti: receipt confirmed")
  • POSTI_RETURNED_TO_SENDER("Posti: returned to sender")
  • POSTI_UNRESOLVED("Posti: unresolved")

Lisäksi jokaisella kutsulla rajapinta palauttaa continuationToken-arvon. Kun tämä arvo annetaan seuraavalla kutsukerralla, palauttaa rajapinta ainoastaan edellisen kutsukerran jälkeen syntyneet tapahtumat. Ensimmäisellä kutsukerralla eVaka lähettää tyhjän tokenin jolloin rajapinnasta palautuu kaikki sieltä löytyvät tapahtumat. Dokumentaation mukaan näitä on tallessa joidenkin kuukausien ajalta.

Tapahtumat talletetaan eVakan sfi_message_event -tauluun josta on viittaukset päätöksiin joihin liittyen suomi.fi -viesti lähetettiin.

Tapahtumien haku tapahtuu ajastetusti joka yö.

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.