Projekti

Yleinen

Profile

KSMessaging (Suomi.fi-viestit ja paperikirjeet)

Tässä dokumentissa on kuvattu lyhyesti KSMessagingin käyttöönotto suomi.fi -viestien osalta. Dokumentti täydentyy myöhemmin suomi.fi WSAPI:n ja paperikirjeiden lähetyksen osalta. Viestien käyttöönottamiseksi tarvitaan lisäksi sopimukset Väestörekisterikeskuksen (VRK) kanssa sekä tunnukset Valtion Integraatioalustalle (VIA). Tunnukset ja muut tarvittavat tiedot toimittaa VRK sopimuksen teon yhteydessä.

Tutustu myös VRK:n Suomi.fi -viestien tekniseen aineistoon osoitteessa: https://esuomi.fi/palveluntarjoajille/viestit/tekninen-aineisto/. Käyttöönoton yhteydessä VRK toimittaa erikseen testausohjeet.

Koha-palvelimella

1) Konfiguroi suomi.fi viestintä koha-conf.xml:n "ksmessaging" osassa:

suomifi->branches->default osassa voidaan määritellä oletuskonfiguraatio, jota käytetään jos kirjastoyksikkökohtaisia määrittelyjä ei ole (eli käytännössä useimmiten). Kirjastoyksikkö/default-osan alle määritellään käytettävä rajapinta (ipostpdf tai wsapi), sekä iPostPDF-rajapintaa käytettäessä lisäksi FileTransfer-osa tiedostojen siirtämistä varten. Default-osa on suositeltava paikka määritellä asetukset, kirjastoyksikkökohtaisia määrityksiä tulisi käyttää ainoastaan poikkeustapauksissa. Esimerkiksi jos kimpan ulkopuolinen, mutta kimpan järjestelmässä oleva kirjasto haluaa lähettää suomi.fi -viestejä.

ipostpdf ja filetransfers -osat voidaan määritellä toisistaan riippumatta. Esimerkiksi on mahdollista käyttää tiedostojen siirtoon aina default-osan sisällä olevia määrityksiä ja muihin asetuksiin kirjastoyksikkökohtaisen osan sisällä olevia määrityksiä, tai päinvastoin.

Kirjastoyksikkö/default-osassa määritellään:

  1. Kirjeiden valmisteluhakemisto (stagingdir), paikallinen hakemisto johon kirjeaineistot muodostetaan ennen niiden siirtämistä valtion integraatiopalveluun. Käytä esimerkiksi /home/koha/koha-dev/var/spool/pate-staging, tai muu sopiva hakemisto. Huomaa että lähetettyjä tiedostoja ei automaattisesti siivota pois tästä hakemistosta niiden lähetyksen jälkeen. Hakemistossa olevia vanhoja tiedostoja ei kuitenkaan tästä huolimatta lähetetä uudelleen. Hakemiston siivous kannattanee ajastaa tapahtuvaksi erikseen.
  2. Yhteyshenkilö (contact), sähköpostiosoite, johon VIA/VRK ilmoittaa viestien käsittelyssä tapahtuneista virheistä. Koha-Suomi -kirjastojen osalta on suositeltavaa käyttää tässä Koha-Suomen notifications -sähköpostia.

Kirjastoyksikkö/default-osan sisällä olevassa ipostpdf-osassa määritellään:

  1. kuoritus- ja postituspalvelun käyttäjätunnus ja salasana (customerid, customerpass), jotka suomi.fi-palvelu vaatii, vaikka kirjepostitusta ei käytettäisikään. Tunnus on kuusinumeroinen asiakastunnus. Koska tulostus- ja kuorituspalvelu ei tällä hetkellä ole käytössä, voidaan tunnukseksi asettaa esimerkiksi merkkijono 123456 ja salasana voi olla mitä tahansa.
  2. 12-numeroinen OVT-laskutustunnus (ovtid), joka niinikään on pakollinen, vaikkei kirjeiden lähetystä ja siten myöskään niiden laskutusta tapahtuisikaan. Käytä tässä esimerkiksi kimpan keskuskirjaston OVT-tunnusta.
  3. Kuoritus- ja tulostuspalveluntarjoaja (printprovider), edelleen pakollinen, riippumatta siitä kuoritetaanko ja tulostetaanko. Tässä voi olla vaikkapa esimerkkikonfiguraatiotiedoston mukainen "Edita".
  4. Lähettäjän tunnus/viranomaistunnus (senderid), tämän saa VRK:lta.
  5. Tiedostotunniste (fileprefix), tiedostonimen alkuun liitettävä aineiston lähettäjän tunniste. Jos tämä on määrittelemättä, käytetään lähettäjän tunnusta. Lähettäjän tunnus ei kuitenkaan toimi tapauksissa, joissa tunnus sisältää _ -merkkejä, koska suomi.fi -viestipalvelu on varsin kranttu tiedostonnimien suhteen. Hyvä kandidaatti tähän on esimerkiksi yksinkertaisesti "koha".

Kirjastoyksikkö/default-osan sisällä olevassa filetransfer-osassa määritellään:

  1. Valtion integraatioalustan palvelinosoite (host), testiympäristön osoite on qat.integraatiopalvelu.fi (192.49.232.194) ja tuotantoympäristön pr0.integraatiopalvelu.fi (192.49.232.195). Käytä joko nimeä tai IP-osoitetta.
  2. Palvelimen portti (port), määritys ei ole pakollinen. Käytettävän tiedonsiirtoprotokollan oletusportti valitaan automaattisesti mikäli muuta ei ole määritelty.
  3. Kohdehakemisto palvelimella (remotedir), oletus on käyttäjän kotihakemisto, integraatioalusta haluaa viestit hakemistoon to_viestit/ipost, joten oikea asetus tähän on "to_viestit/ipost".
  4. Käyttäjätunnus ja salasana integraatiopalvelimella (user, password), nämä saa VRK:lta
  5. Käytettävä tiedonsiirtoprotokolla (protocol), joko sftp tai ftp. FTP-protokollan kanssa pitää erikseen huolehtia tiedonsiirtoväylän suojaamisesta, koska protokolla sinänsä on suojaamaton ja viesteissä liikkuu luottamuksellisia tietoja. Älä käytä FTP:tä.

WSAPI dokumentaatio täydentyy tähän myöhemmin

2) Määrittele yhteys sotu-siiloon koha-conf.xml:n "ssnProvider"-osassa

Henkilötunnusten hakemiseen siilosta voi käyttää joko suoraa tietokantayhteyttä (directDB) tai sotu-siilon web-liittymää (findSSN). Henkilötunnusten noutamiseen käytetään KohaSuomi::SSN::Access -modulia. Modulin ja henkilötunnusten käsittelyn tulevaisuus on kuitenkin hieman auki, koska yksittäisten Koha-installaatioiden siilot on ajatus korvata Koha-Suomen laajuisella Hetulalla.

directDB:

  1. Määritä koha-conf.xml:n ssnProvider-osan interface-kohtaan "directDB".
  2. Lisää siilon tietokantaan MariaDB-käyttäjä ja anna select-oikeus tietokannan ssn-tauluun.
  3. Varmista että lisäämäsi käyttäjä pääsee käsiksi tietokantaan Koha-kontista.
  4. Lisää koha-conf.xml:n ssnProvider-osan alle directDB-osa ja määrittele sen alle siilon tietokannan palvelinosoite (host), portti (port), sekä lisäämäsi MariaDB-käyttäjän käyttäjätunnus (user) ja salasana (password).

Huomaa: directDB soveltuu käytettäväksi ainoastaan jos sekä Koha-palvelin että Sotu-siilo ovat samassa suojatussa verkossa, esimerkiksi kontainerisoituna samalla palvelimella tai fyysisesti samassa konesalissa sijaitsevilla palvelimilla! Se ei missään tapauksessa sovellu käytettäväksi esimerkiksi julkisen internetin yli.

findSSN:

  1. Määritä koha-conf.xml:n ssnProvider-osan url-kohtaan sotu-siilon www-osoite, mikäli se ei ole määritettynä.
  2. Määritä koha-conf.xml:n ssnProvider-osan interface-kohtaan "findSSN".
  3. Lisää sotu-siiloon user-tauluun käyttäjä, jolla on oikeus hakea sotuja siilosta.
  4. Lisää koha-conf.xml:n ssnProvider-osan alle findSSN-osa ja määrittele sen alle siiloon lisäämäsi käyttäjätunnus (user) ja salasana (password).

3) Ajasta suomi.fi -viestien lähetys.

Suosittelen pate.pl -skriptin symlinkkaamista cronjobs-hakemistoon:

ln -s /home/koha/Koha/C4/KohaSuomi/Pate/pate.pl /home/koha/Koha/misc/cronjobs/

Sen jälkeen crontabiin sopiva rivi viestien käsittelemistä varten, esimerkiksi:

*/5 07-22 * * *   $KOHA_CRONJOB_TRIGGER cronjobs/pate.pl --suomifi

Lisäksi on hyvä ajastaa vanhojen kirjepakettien siivous valmisteluhakemistosta vaikkapa siten, että yli kaksi viikkoa vanhat kirjepaketit hävitetään:

00 23 * * *       find /home/koha/koha-dev/var/spool/pate-staging -name *.zip -mtime +14 -exec rm -v {} \; >> /home/koha/koha-dev/var/log/cronjobs/clean_pate_staging.log 2>&1

pate.pl osaa käsitellä samaan tapaan myös Kohan kirjeviestit --letters vivulla. Viestit voidaan lähettää konfiguraation mukaisesti esimerkiksi RopoCapitalille, Editalle tai OpusCapitalle joko iPostPDF+XML tai EPL -formaatissa. Tätä toiminnallisuutta ei kuitenkaan ole vielä testattu.

Kohan liittymässä

  1. Määrittele viestipohjat. Kielikohtaisissa viestipohjissa on uusi kohta 'suomifi', jonka alle suomi.fi viestipohjat määritetään. Suomi.fi viestipohjien tulee olla puhdasta tekstiä. HTML-muotoiluja ei tueta, mutta rivinvaihdot säilytetään tekstiä ladottaessa. Kohan listailmaisimia (----) ei tarvita, ne tulevat turhaan näkyviin viestiin jos niitä käyttää. Katso ohje viestipohjien määrittelyyn: Ilmoitukset ja kuitit.
  2. Käy kliksauttamassa Kohan järjestelmäasetuksissa "SuomiFiMessaging" asentoon "Enable".
  3. Kun SuomiFiMessaging on käytössä, on asiakkaan viestiasetuksissa uusi kohta 'suomifi'. Aseta asiakaskohtaisesti suomi.fi -viestitäpät asiakkaan haluamille viestityypeille. Katso ohje viestiasetusten tekoon: Asiakkaan viestiasetukset. Suomi.fi viestipalvelu tunnistaa asiakkaat henkilötunnuksen perusteella, joten varmista, että asiakkaan henkilötunnus on sotu-siilossa.

Huomioitavia asioita

  1. Asiakkaalla tulee olla tili suomi.fi -viestipalvelussa. Tilin voi ottaa käyttöön osoitteessa: https://www.suomi.fi/viestit.
  2. Asiakkaan henkilötunnuksen on oltava sotusiilossa ja sen on oltava oikein. Jos asiakkaalla on väärä hetu, päätyvät viestit pahimmassa tapauksessa väärälle henkilölle. Yhteisöille tai hetuttomille viestiminen ei suomi.fi:n kautta onnistu, ja jos tämmöisille asiakkaille kliksii suomi.fi -viestitäppiä, niin tuloksena on "failed" tilaisia viestejä viestijonossa. Tilannetta voisi hieman parantaa tallentamalla Y-tunnukset sellaisille yhteisöasiakkaille, joilla sellainen on. Toistaiseksi Koha-Suomessa ei kuitenkaan ole yhtenäistä käytäntöä tai päätöstä Y-tunnusten tallentamisesta.
  3. Suomi.fi viestissä ei näy viestin sisältöä. Viestissä näkyy ainoastaan otsikko "Kirjaston nimi, kirjastojen viestit". Viestin sisältönä on "Olet saanut dokumentin suomi.fi -viestipalveluun". Varsinainen viestin sisältö on viestin liitteenä olevassa PDF:ssä. Tämä on suomi.fi ipost-viestipalvelun rajoite, eikä sille ikävä kyllä oikein voi mitään Kohan päässä. WSAPI-rajapintaa käytettässä tätä ongelmaa ei ole.
  4. Selaimissa PDF-lukuohjelma tulee mukana, mutta mobiililaitteissa pitää olla suomi.fi -sovelluksen lisäksi asennettuna myös PDF-lukuohjelma. Kaikki lukuohjelmat eivät suomi.fi -sovelluksen kanssa tunnu toimivan. Lisäksi avaamisongelmia voi aiheuttaa esimerkiksi mobiililaitteessa käytössä oleva sisällönsuodatus tai VPN-ohjelmisto. Ongelmista on raportoitu VRK:lle.
  5. PDF-dokumenttia on varsin hankala lukea kännykän pieneltä näytöltä. Viesti on taitettu suomi.fi palvelun vaatimusten mukaisesti SFS-2487 standardin kuvaamaa asettelumallia seuraten A4-paperille, jotta kirje voitaisiin toimittaa tarvittaessa eteenpäin paperikirjeenä. Paperikirjeiden toimitus suomi.fi:n kautta ei kuitenkaan tällä hetkellä (1.10.2019) ole käytettävissä, koska VRK:n kirjeviestinnän kilpailutus on markkinaoikeudessa.
  6. Suomi.fi:ssä ei ainakaan toistaiseksi ole viestien poistotoimintoa, joten asiakas ei voi poistaa suomi.fi -viestilaatikosta saamiaan viestejä. Kahden vuoden kuluttua viestin saapumisesta VRK siivoaa viesteistä liitteet pois, jolloin asiakkaalle jää näkyviin ainoastaan viestin otsikkotiedot. Tästä kannattaa tiedottaa asiakkaita, koska kirjastojen viestejä kertyy helposti aktiivisille lainaajille melkoiset määrät, eikä mitään keinoa päästä niistä eroon hallitusti tai edes kansioida niitä mielekkäästi ole näköpiirissä.
  7. Kohasta voidaan lähettää suomi.fi-viesteinä Kohan normaalia viestikanavaa pitkin kulkevat viestit, eli noutoilmoitukset, laina- ja palautuskuitit ja eräpäivämuistutukset. Laskuja tai palautuskehotuksia ei voi lähettää, koska niiden lähetys toimii Kohassa eri tavalla. Ainakin palautuskehotusten lähetyksen yhdenmukaistaminen muiden Kohan viestityyppien kanssa olisi hyvä seuraava askel ja mahdollistaisi myös palautuskehotusten toimittamisen asiakkaan valitsemalla tavalla.