Suomi.fi Viestit. SFTP API Viranomaisille. Versio 1.0 / Hyväksytty. Väestörekisterikeskus

Transkriptio

1 Suomi.fi Viestit SFTP API Viranomaisille / Hyväksytty

2 Sivu: 2 Sisällysluettelo SFTP API Viranomaisille... 3 Rajapinnan kuvaus... 4 Sekvenssikaavio... 7 Viranomaistoimija... 7 Vastaanottaja (kansalainen)... 7 Tee virustarkastus... 8 Käsittele aineisto... 8 VIA FTP-palvelin... 8 Suomi.fi Viestit taustapalvelut... 8 Tulostustoimittajan järjestelmä... 8 Suomi.fi Viestit postilaatikko... 8

3 Sivu: 3 SFTP API Viranomaisille DOKUMENTINHALLINTA Omistaja: Lasse Pynnönen, VRK Laatinut: Suomi.fi-viestit sovelluskehitystiimi Tarkastanut: Lasse Pynnönen, VRK Hyväksynyt Riikka Noponen, VRK VERSION HALLINTA v / Jaakko Muhonen - Luotu ensimmäinen versio. v / Jaakko Muhonen - Tehty korjauksia ja lisäyksiä v / Jaakko Muhonen - Lisätty VIA-palvelun kommentit v / Jaakko Muhonen - Lisätty Viestit arkkitehtuuritiimin kommentit v / Jaakko Muhonen Lisätty VRK:n katselmoinnin tulokset v / Jaakko Muhonen Lisätty PDF-tiedoston kokorajoitus, tehty pieniä korjauksia ulkoasuun v / Jaakko Muhonen Lisätty VIA-palvelun tarkennuksia varmenteen luontiin v / Jaakko Muhonen Tarkennettu lähetettäviä kuittauksia ja paluukanavaa v / Jaakko Muhonen Dokumentti on hyväksytty

4 Sivu: 4 Rajapinnan kuvaus Yleistä Tässä dokumentissa on kuvattu Suomi.fi Viestit -palvelun tarjoama SFTP-rajapinta eli tiedostojen ja dokumenttien (=aineistot) siirtäminen Suomi.fi Viestit -palveluun. SFTP-rajapinnan avulla viranomaiset voivat lähettää aineistoa kansalaisille. Rajapinta mahdollistaa aineiston jakelun paperipostina tai sähköisessä muodossa. Sähköinen posti edellyttää, että kansalaisella on tili Suomi.fi Viestit -palvelussa. Mikäli kansalainen haluaa viestit ja aineistot sähköisesti, pitää hänen myös antaa yleinen suostumus siitä, että kaikki viranomaisviestit aan toimittaa hänelle sähköisesti Suomi.fi Viestien postilaatikkoon. Samalla kyseinen henkilö poistetaan paperitulostuksesta. Suomi.fi Viestit tilin olemassaolo tarkistetaan ohjaustiedoissa (xml- tiedosto) olevista henkilötunnuksista (SSN): <lb:recipient address="recipient1@nnn.nn" customercode="1111" phonenumber=" " SSN=" "> Kirje lähetetään normaalisti paperikirjeenä entiseen tapaan kaikille niille henkilöille, joilla ei ole käytössä Viestit sähköistä palvelua. Viranomaisen järjestelmä saa teknisen kuittauksen SFTP-siirron päätteeksi, että tiedosto on otettu vastaan VIA:n FTP-palveluun. Jotta Suomi.fi Viestit -palvelu voi lähettää kuittauksen sähköisten viestien toimittamisesta, tarvitaan Web Service -paluukanava käyttöön. Paluukanavan rajapinta on kuvattu dokumentissa Viranomaisen Paluukanava WS API, joka on saatavana sivulla Samalta sivulta löytyy myös muita hyödyllisiä dokumentteja Viestit-palveluun liittymiseksi. Aineiston toimitus Viranomainen siirtää aineiston SFTP-siirtona VIA-palveluun (Valtion yhteinen integraatiopalvelu). SFTP-siirtoa varten täytyy olla joka virastolla oma käyttäjätunnus. Viranomainen tekee käyttäjätunnus pyynnön SFTP siirtoa varten VRK:lle, joka koordinoi SFTPliittymisprosessia. Käyttäjätunnuksen lisäksi Viranomaisen ja VIA-palvelun välille pitää avata tietoliikenneyhteys SFTP-protokollalle. Tietoliikenneavauksesta viranomainen täydentää tietoliikenneavauslomakkeen ja toimittaa sen VIA:lle. SFTP-siirtoa varten luodaan aluksi FTP-käyttäjätunnus tunnus/salasana-parilla, joka toimitetaan Viranomaiselle suojatulla sähköpostilla. Viranomainen voi ottaa käyttöön halutessaan myös varmenne perusteisen tunnistautumisen SFTP-yhteydessä (tapa 1 ja 2). Tapa 1: luomalla itse PKI-avainparin ja viemällä omaan SFTP-kotihakemistoon varmenteen salaisen osan. Luotava avainpari tulisi olla RSA/DSA tapauksessa vähintään 2048 bittiä. 1. Viranomainen luo avain parin 2. Viranomainen toimittaa julkisen osan VIA:lle 3. Julkinen osa asennetaan tunnukselle 4. Viranomainen voi aloittaa käyttämään tunnusta

5 Sivu: 5 Tapa 2: Pyytämällä VIA-palvelua luomaan varmenne. 1. VIA-palvelu luo avainparin ja asettaa siihen salasanan (passphrase) 2. VIA-palvelu toimittaa varmenteen privaattiosan ja salasanan (passphrase) turvapostilla asiakkaille 3. Julkinen osa asennetaan VIA tunnukselle ja asiakas asentaa varmenteen siirtävään ohjelmaan 4. Viranomainen voi aloittaa käyttämään tunnusta Tiedostonsiirrossa tuetaan SFTP:put operaatiota, jossa viranomainen siirtää aineiston VIA-palvelulle. Virastolle tehty SFTP-tunnus ja hakemisto ovat Virastokohtaiset, joten hakemiston sisältö ei näy muille viranomaisille. Siirrettävän aineiston nimeämisessä saa käyttää vain isoja ja pieniä kirjaimia; ei skandinaavisia aakkosia, erikoismerkkejä eikä välilyöntejä. Viranomaisen toimittama aineisto siirretään eteenpäin Suomi.fi Viestit -palveluun. VIA:n hakemistossa oleva aineisto siirtyy siirron yhteydessä arkisto-hakemistoon, josta VIA-palvelu automaattisesti poistaa aineiston 30 vuorokauden kuluttua. Aineisto Aineiston lähettäjä on vastuussa siirron onnistumisesta ja mm. siitä ettei samaa tiedostoa siirretä kahteen kertaan. Aineisto on siirrettävä (SFTP:put operaatiolla) annettuun hakemistoon ensin väliaikaisella nimellä. Lähettäjä nimeää tiedoston (rename) uudelleen onnistuneen siirron merkiksi. PDF-tiedoston suositeltu enimmäiskoko on 100 Mt ja sivukohtainen enimmäiskoko on 100 kt. Mustavalkotulostuksessa ei ole yksittäiseen kirjeeseen liittyviä rajoitteita sivumäärän suhteen, mutta väritulostuksessa (color ipost PDF) yksittänen kirje voi olla enintään 60 sivua sivuinen PDF-tiedosto/erä on mahdollinen, mutta käytännössä huomattavasti pienemmät tiedostot/erät ovat suositeltavia, eli korkeintaan 2000 sivua. Tiedoston nimeämisen perusteella ohjataan aineisto paperitulostukseen oikealle tulostustoimittajalle. Lähettäjällä on oltava voimassa oleva sopimus tulostustoimittajan kanssa. Aineiston nimeäminen tehdään seuraavasti: <alkutarkenne>_<päivämäärä muodossa vvvvkkppttmmss>_tulostustoimittajan nimi>.zip Esimerkki: Vaka_ _Edita.zip Jos viranomainen haluaa käyttää olemassa olevaa sopimustaan esim. OpusCapitan kanssa, täytyy tulostusaineistotiedosto nimetä niin, että nimen lopussa on OpusCapita, esimerkiksi Vaka_ _OpusCapita.zip. Jos tulostustoimittajan nimeä ei ole tiedostossa, ohjataan tiedosto VRK:n sopimuksen mukaiselle tulostustoimittajalle, joka on Edita. Virheellisesti nimettyjä aineistoja ei toimiteta eteenpäin. VRK:n tulostustoimittajat ovat Edita ja OpusCapita. Tulostuspalvelu Paperikirjeiden tulostus hoidetaan tulostuspalvelun kautta. Jos on aiemmin käyttänyt Opus Capitan ipost palvelua, tämä rajapinta on yhteensopiva sen kanssa. Opus Capitan ipost-dokumentaatio ( Suunnitteluohje kirjeiden lähettämiseen ) löytyy osoitteesta: Tärkeimmät huomiot edellä mainitusta dokumentaatiosta: Toimitettavat aineistot ovat ZIP-pakattuja paketteja, jotka sisältävät yhden PDF + XML tiedostoparin.

6 Sivu: 6 Aineiston kuvaus noudattaa Opus Capitan tekemää skeemaa: LetterBundle_V1x0.xsd. Myös liitetyn PDF-tiedoston tulee noudattaa määritettyä rakennetta, jotta aineiston käsittely on mahdollista. Tulostusaineiston PDF:ään liittyvät rajoitteet löytyvät dokumentista: ipost Technical specification FiSeNo EN.pdf (sivu 15, luku 5). Lähettäjällä tulee olla voimassaoleva sopimus tulostustoimittajan kanssa. Ohjaustiedoissa (xml- tiedosto) tulee olla asiakastunnus (customerid) ja salasana (password), jotta aineisto aan lähettää eteenpäin: <lb:stdbundleprocessing customerid="pnnnnn" password="mmmm"./> Aineiston siirron käyttötapaukset Käyttötapaus 1: Aineiston siirtäminen SFTP API rajapinnan kautta ja aineiston toimitus sähköisesti 1. Viranomaisen siirtää SFTP-siirtona aineiston VIA:n FTP-palveluun 2. VIA siirtää edelleen aineiston Suomi.fi Viestit taustapalveluille (ipost-purkajalle) 3. Viestit taustapalveluissa aineisto käydään läpi jokaisen vastaanottajan (kansalainen) osalta 4. Vastaanottajalle lähetetään ilmoitus viestin saapumisesta sähköpostitse (ja/tai mobiii push-viestillä), jos vastaanottajalla on aktiivinen tili Suomi.fi Viestit -palvelussa 5. Vastaanottaja käy lukemassa viestin ja siihen liittyvät tiedostot omasta Suomi.fi Viestit sähköisestä postilaatikosta Käyttötapaus 2: Aineiston siirtäminen SFTP API rajapinnan kautta ja kirjeen toimitus paperipostituksella 1. Viranomaisen siirtää SFTP-siirtona aineiston VIA:n FTP-palveluun 2. VIA siirtää edelleen aineiston Suomi.fi Viestit taustapalveluille (ipost-purkajalle) 3. Viestit taustapalveluissa aineisto käydään läpi jokaisen vastaanottajan (kansalainen) osalta 4. Vastaanottajalle lähetetään viestin sisältö paperipostitse, jos vastaanottajalla ei ole aktiivista tiliä Suomi.fi Viestit -palvelussa 5. Vastaanottaja noutaa paperikirjeen postitoimipaikasta tai omasta fyysisestä postilaatikosta Yhteyden testaus Viranomainen voi testata tietoliikenneyhteyttä ottamalla SFTP-Client:llä yhteyden VIA-palvelun QA- tai Tuotanto-ympäristöön. Onnistuneen tunnistautumisen jälkeen tulee näkyville aineistohakemisto. Tämän jälkeen voi kokeilla aineiston SFTP-siirtoa (SFTP:put) <kotihakemisto>/to_viestit/ipost/ hakemistoon. VIA palvelun sftp-osoite integraatiotestausympäristössä (QA): qat.integraatiopalvelu.fi (internetistä) qat.integraatiopalvelu.vyv.fi (vy-verkosta) VIA palvelun sftp-osoite tuotantoympäristössä (PROD): pr0.integraatiopalvelu.fi (internetistä) pr0.integraatiopalvelu.vyv.fi (vy- verkosta)

7 Sivu: 7 Sekvenssikaavio SFTP API Viranomaisille - (Interaction diagram) VIA FTP-palvelin Suomi.fi Viestit taustapalvelut Tulostustoimittajan järjestelmä Suomi.fi Viestit postilaatikko Viranomaistoimija Vastaanottaja (kansalainen) Siirrä aineisto (zip-tiedosto) Siirrä aineisto (zip-tiedosto) Tee virustarkastus Käsittele aineisto Kuittaus sähköisten viestien vastaanottamisesta (paluukanava) Sähköinen toimitus Lähetä viesti() Lue viesti() Nouda viesti ja aineisto() Nouda aineisto() Paperipostitus Toimita kirje() Kuva: 1 SEKVENSSIKAAVION TOIMIJAT Viranomaistoimija Viranomaistoimija on käytännössä sama kuin viranomaisjärjestelmä. Viranomainen lähettää viestejä ja aineistoja kansalaisille. Vastaanottaja (kansalainen) Kansalainen, joka saa viestit ja/tai paperipostit.

8 Sivu: 8 Tee virustarkastus Viestit taustapalvelut tekevät aineistolle virustarkastuksen. Käsittele aineisto Viestit taustapalveluissa aineisto käydään läpi jokaisen vastaanottajan (kansalainen) osalta. VIA FTP-palvelin VIA:n (Valtion yhteinen integraatiopalvelu) FTP-palvelin, jonne viranomaiset siirtävät aineistot. Suomi.fi Viestit taustapalvelut Suomi.fi Viestit taustapalvelut, joihin kuuluvat mm. Viestit Postituspalvelu ja Viestit Tallennuspalvelu sekä kansalaisten postilaatikon käsittelyn logiikka. Kansalaisen postilaatikko näkyy Suomi.fi Viestit Verkkopalveluissa. Tulostustoimittajan järjestelmä Tulostustoimittaja, joka vastaa tulostuksesta eli paperipostituksesta. Suomi.fi Viestit postilaatikko Kansalainen ottaa omalla tietokoneella yhteyttä Suomi.fi Viestit postilaatikkoon ( jonka käyttöliittymästä käytetään nimitystä Suomi.fi Verkkopalvelut. Suomi.fi Verkkopalvelun Viestit-osiossa kansalainen voi lukea itselleen tulleet viestit sen jälkeen, kun on kirjautunut verkkopalveluun. Kansalaisen viestit haetaan Suomi.fi Viestit taustapalveluilta. SEKVENSSIKAAVION VIESTIT Siirrä aineisto Viranomaisen siirtää SFTP-siirtona aineiston VIA:n FTP-palveluun. Siirrä aineisto VIA siirtää edelleen aineiston Suomi.fi Viestit taustapalveluille. Kuittaus sähköisten viestien vastaanottamisesta Suomi.fi Viestit voi lähettää viranomaisjärjestelmälle kaikista yksittäisistä sähköisistä viesteistä toimituskuittaukset paluukanavan kautta, jos paluukanava on otettu käyttöön. Paluukanavan rajapinta on kuvattu dokumentissa Viranomaisen Paluukanava WS API, joka on saatavana sivulla: Lähetä viesti

9 Sivu: 9 Vastaanottajalle (kansalainen) lähetetään ilmoitus viestin saapumisesta sähköpostitse (ja/tai mobiii push-viestillä), jos vastaanottajalla on aktiivinen tili Suomi.fi Viestit -palvelussa. Lue viesti Vastaanottaja käy lukemassa viestin ja siihen liittyvät tiedostot omasta Suomi.fi Viestit sähköisestä postilaatikosta. Nouda viesti ja aineisto Viesti ja siihen liittyvät liitetiedostot noudetaan Suomi.fi Verkkopalvelut postilaatikkoon Viestit taustapalveluilta. Nouda aineisto Tulostustoimittaja noutaa kaikkien niiden vastaanottajien aineistot paperipostitukseen, joilla ei ole aktiivista tiliä Suomi.fi Viestit -palvelussa. Toimita kirje Vastaanottajalle lähetetään viestin sisältö paperipostitse, jos vastaanottajalla ei ole aktiivista tiliä Suomi.fi Viestit -palvelussa.