Hämeenlinnan kaupunki Kuntatieto-pilotti

Hämeenlinnan kaupunki 28.01.2019 Hämeenlinnan kaupunki Kuntatieto-pilotti Talousarvion XBRL-sanoman muodostus: Automaattisen tiedonsiirron Versio 0.4 28.01.2019

2 (9) Sisällys Sisällys... 2 Dokumentin versiohistoria... 2 1. Yleistä... 3 1.1. Dokumentin kuvaus... 3 2. Tiedonsiirtotavan valinta... 3 2.1. Yleistä... 3 2.1.1. Suomi.fi -palveluväylä... 3 2.1.2. Pilvipohjaiset integraatiotyökalut... 3 2.1.3. Valtiokonttorin REST-rajapinta... 4 2.2. Vaihtoehtojen arviointikriteerit ja valinta... 4 2.2.1. Suomi.fi palveluväylä ja On-premise ratkaisut... 4 2.2.2. Pilvipohjaiset integraatiotyökalut... 4 3. Tiedoston muodostaminen... 5 4. Tiedoston siirtäminen... 8 5. Tietojen täsmäytys... 9 Dokumentin versiohistoria Versio Päiväys Laatija V0.1 25.10.2018 JS, JS, HK, JP Muutoksen kuvaus Ensimmäinen versio V0.2 18.12.2018 JS, JP Kaikkia osioita päivitetty V0.3 21.12.2018 JS, JP Testauksen tulokset ja huomiot V0.4 28.01.2019 JS, JP Tammikuun huomiot päivitetty

3 (9) 1. Yleistä 1.1. Dokumentin kuvaus Tässä dokumentissa kuvataan pilotissa käytetyt XBRL-sanoman muodostamiseen liittyvät tekniikat ja integraatiot. Lisäksi esitellään vaihtoehtoisia tapoja ja arviointikriteerit, miksi pilotissa on päädytty juuri kyseisiin vaihtoehtoihin. Tiedonsiirtoja ja integraatioita päästiin toteutuksen aikana myös testaamaan aidoissa ympäristöissä. Testausten löydökset on dokumentoitu tähän julkaisuun. 2. Tiedonsiirtotavan valinta 2.1. Yleistä Viestin välittäminen Valtiokonttorin järjestelmiin on mahdollista usealla tavalla. Monella organisaatiolla on jo entuudestaan käytössään täysin riittävät teknologiat, eli ensin kannattaa tutustua niihin. Jos omasta ympäristöstä ei löydy sopivia vaihtoehtoja, niin seuraavassa esitellään muita vaihtoehtoja. 2.1.1. Suomi.fi -palveluväylä Suomi.fi -palveluväylän tavoitteena on tarjota vakioitu tapa tietojen siirtoon eri organisaatioiden välillä. Palveluväylän käyttömahdollisuudet ovat erittäin laajat, eivätkä siis rajoitu pelkästään Kuntatieto-ohjelman alueelle. Lisätietoja palvelusta löytyy osoitteesta: https://esuomi.fi/palveluntarjoajille/palveluvayla/ Palveluntarjoajat lisäävät palveluväylään omia palveluitaan, joihin asiakkaat voivat kytkeytyä. Kytkeytymiseen vaaditaan liityntäpalvelin, jota käyttämällä tiedonsiirto toteutetaan. Liityntäpalvelimen voi asentaa joko omaan palvelinympäristöön tai sitä tarjoavat palveluna myös useat IT-toimittajat. 2.1.2. Pilvipohjaiset integraatiotyökalut Jos omassa ympäristössä ei ole entuudestaan riittäviä integraatiotyökaluja, voi niitä hankkia myös pilvipohjaisina ratkaisuina. Ratkaisuja on tarjolla useita ja myös suuret toimijat kuten Google, Microsoft ja IBM tarjoavat omia ratkaisujaan tälle alueelle. Pilvipohjaisissa työkaluissa etuina verrattuna on-premise tyyppisiin ratkaisuihin on pienemmät alkuinvestoinnit ja nopeampi käyttöönotto. Niiden käyttöä voi myös helpommin skaalata käytön mukaan ajan kuluessa ja tarpeiden muuttuessa. On-premise ratkaisuissa maksetaan yleensä hankintavaiheessa lisenssimaksuja ja asennus tapahtuu omaan tai toimittajan konesaliin. Näiden alkuinvestointien jälkeen kustannusten voi olettaa pysyvän tasaisena, joka tarkoittaa sitä, että monissa tapauksissa kustannukset tasoittuvat pilvipohjaisten ratkaisujen kanssa ajan myötä.

4 (9) 2.1.3. Valtiokonttorin REST-rajapinta Valtiokonttori tarjoaa palveluihinsa myös REST (Representational State Transfer) -rajapinnan. Kyseessä on HTTP-protokollaan perustuva arkkitehtuurimalli, jossa käytetään hyödyksi HTTP:n metodeja, kuten get, post, put ja delete. REST-rajapintaan voi kytkeytyä joko käyttämällä ilmaisia tai kaupallisia työkaluja. 2.2. Vaihtoehtojen arviointikriteerit ja valinta Hämeenlinnan kaupunki asetti pilotin toteutukselle tavoitteita, jotka ohjasivat osaltaan myös teknologisia valintakriteereitä. Yksi tavoitteista oli selvittää, miten jo käytössä olevia työkaluja voitaisiin mahdollisimman hyvin käyttää hyödyksi, että ylimääräisiä kustannuksia ei syntyisi sen vuoksi. Lisäksi ratkaisun tuli tukea nykyisiä prosesseja, mahdollistaa automatisointia ja kyetä mukautumaan mahdollisiin muutoksiin, joita kehitysvaiheessa oleviin rajapintoihin väistämättä tulee. Kuntatieto-ohjelman mukaisen raportoinnin aikataulu muuttui pilotin aikana. Tämän todettiin johtavan siihen, että pilotin toteutuksen ja varsinaisen tuotantokäytön aloittamisen välille syntyisikin pidempi väliaika, kuin alun perin oli ajateltu. Ratkaisun käyttö tällä välillä tulee olemaan rajallista. Tärkeimmiksi kriteereiksi tässä pilotissa valittiin: Ratkaisun investointikustannukset Kyky skaalautua tarpeen muuttumisen myötä (pilotointi vs. tuotantokäyttö) 2.2.1. Suomi.fi palveluväylä ja On-premise ratkaisut Suomi.fi -palveluväylän käyttöönottoa varten tulisi asiakkaalle asennettavaksi liittymäpalvelin tai vaihtoehtoisesti sen hankkiminen palveluna. Näistä molemmista vaihtoehdoista muodostuisi kiinteitä investointikustannuksia ja jälkimmäisessä vaihtoehdossa huomioon tulee ottaa myös sopimuksen muut ehdot, kuten vähimmäiskesto. On-premise ratkaisuissa kustannusmalli olisi ollut samankaltainen, kuin Suomi.fi palveluväylän käyttöönotossa, eli niistä olisi syntynyt lisenssi- ja investointikustannuksia jo projektin alkuvaiheessa. Lisäksi On-premise ratkaisun takaisinmaksuajan todettiin olevan niin pitkä, että tämän pilotoinnin sisällä ratkaisua ei kannata arvioida sen enempää. 2.2.2. Pilvipohjaiset integraatiotyökalut Pilvipohjaisten ratkaisujen käyttö sopi parhaiten asetettuihin valintakriteereihin. Hämeenlinnan kaupungin nykyinen palvelukeskuskumppani KuntaPro on rakentanut nykyisen järjestelmäympäristönsä pääosin Microsoftin ratkaisuja käyttäen, eli suurimmat synergiahyödyt pilotin rajallisessa aikaikkunassa todettiin saavutettavaksi silloin, kun käytetään tähän tuoteperheeseen sopivia ratkaisuja. Samalla pystytään käyttämään hyödyksi nykyisiä toimittajia ja muita kumppaneita.

5 (9) Näin ollen valinta osui Microsoftin työkaluihin ja tarkemmin sanottuna Azure Logic Appsiin sekä SSIS-työkaluihin, jotka kuuluvat nykyisin käytössä olevaan Sql Server -pakettiin. SSIS-työkalut linkittyvät vahvasti Sql-tietovarastoon, jonne Kuntatieto-data ja muukin tiedolla johtamisen data kerätään jo tällä hetkellä. Tämän vuoksi työkalun kokeileminen oli hyvin luontevaa, eikä siitä aiheutunut ylimääräisiä kustannuksia. Logic Appsin monipuolisten ominaisuuksien vuoksi se pystyisi olemaan myös pidempiaikainen ratkaisu tässä kyseissä ympäristössä, myös tuotantokäytön alkaessa. Logic Appsin hinnoittelu on käyttöön perustuvaa, mikä tekee siitä edullisen valinnan pilotoinnin ajaksi. Merkittävin kustannuselementti muodostuu integration accounteista, joskin niissä on tuntipohjainen hinta, jolloin voi olla mahdollista pitää niitä käytössä vain osan aikaa. Tuotantokäytön alkaessa käyttökustannukset nousevat käyttöasteen noustessa. Nämä vaikutukset tulee arvioida erikseen. 3. Tiedoston muodostaminen XBRL-muotoisen xml-aineiston luominen ei sinällään eroa muista xml-aineistojen luomisista. Tässä tapauksessa aineisto on vain tietyllä tavalla parametrisoitu. Tarvittavat parametrit kerättiin JHS_KUNTA_DPM_Taulukkomallit_edit_2018_07_04 excelistä (Valitettavasti tämä aineisto ei ollut pilotin aikana yksiselitteinen, vaan valkotaustaisista soluista piti toimittaa ne, jotka olivat näkyvillä, eivätkä plussan takana piilossa excelissä. Jos plussan takana excelissä oli piilossa valkoisia soluja, piti toimittaa niiden yläpuolelta harmaalla taustalla oleva solu.) sekä mallitiedostoista ja sähköposteilla kyselemällä. Aineiston muodostamiseen tarvittavat komponentit ovat itse eurojen lisäksi seuraavat Reference date or period (REF) Actual, estimated, planned (AEP) Main Catetory (MC) Source reporting code Period Metrics Precision UnitRef Tämä on kommentoitu eli ei tarpeellinen, mutta helpottaa aineiston lukemista ja täsmäyttämistä. Tämä on johdettavissa edellisen kolmen perusteella tai toisinpäin. Uusimmassa taksonomiaversiossa tätä ei ollut enää näkyvillä, mutta tätä versiota ei saanut vielä käyttää pilotin aikana. Tilikauden vuoden viimeinen päivä desimaalit valuutta/yksikkö

6 (9) Context id Identifier HUOM! Tämä oltava tuloveroprosentin ja henkilöstön määrän kanssa upure. Muissa kentissä euroarvot ja kentässä EUR. järjestysnumero y-tunnus Koska komponentteja on niin paljon ja talousarviossa toimitettavia rivejäkin on paljon, niin haluttiin toteutustapa, joka olisi mahdollisimman automaattinen. Talousarvion lisäksi jatkossa tulee olemaan muitakin kokonaisuuksia, joita pitää toimittaa ja toimitettavan aineiston vaatimukset voivat muuttua, joten systeemistä haluttiin joustava. Tässä ensisijaisena apuna olisi skeema, jonka avulla xml-aineiston saa automaattisemmin muodostettua. Valitettavasti pilotin aikana käytössä ollut taksonomiaversio sisälsi bugeja, eikä skeemaa pystynyt hyödyntämään. Näin ollen xml-aineiston muodostamiseen tarvittavasta scriptistä tuli vähän pidempi. Aineistoa varten tileillä olevat budjettieurot piti saada linkitettyä yllä listattuihin komponentteihin. Tätä ja näitä komponentteja varten hyödynnettiin SQLpakettiin kuuluvaa Master Data Servicea (MDS). MDS:ssä on helppo selaimessa tai excelin kautta luoda ja ylläpitää tunnisteita. Muutosten tekeminen on nopeaa, eikä vaadi koodaamista. Kuntatietoaineistoista poimittiin Kuntatietotilit/Main Category (esim. MC:x62 Muut toimintatuotot) ja niiden hierarkia muodostettiin MDS:ään omaksi tauluksi. Hierarkian avulla myöhemmin tuleviin muutoksiin on helpompi varautua verrattuna siihen, että kukin oma tili linkitettäisiin suoraan johonkin tiettyyn Kuntatietotiliin. Nykyisellä menetelmällä saadaan kaikki eurot alimmalle tasolle Kuntatietotilihierarkiassa ja erillisen scriptin avulla ne saadaan nostettua sille tasolle, mitä vaaditaan kussakin tapauksessa. Tämä voi olla esimerkiksi eri taso talousarviossa kuin toteumatietojen toimituksessa. Tätäkään scriptiä ei tosin tarvittaisi, jos tiedot toimitettaisiin aina alimmalla tasolla ja summaus tehtäisiin kohdepäässä. Kuntatietotilit linkitettiin kunnan tileihin omassa taulussa. Tätä taulua ja budjettidatataulua vasten tehtiin proseduuri, mikä siirsi eurot Kuntatietokoodeille. Pääosa muistakin komponenteista linkitettiin MDS:ään, jolloin ne nousivat tarvittavaan näkymään kuntatietotilien mukana. Toimintamallin tehokkuus tuli esille, kun taksonomia-excelistä paljastui myös virheitä, minkä vuoksi miltei puolet toimitettavista tiedoista pitikin toimittaa eri tasolla. Tämän muutoksen tekemiseen meni arviolta tunti aikaa, mikä olisi helposti voinut olla päivien urakka. Oman haasteensa näkymään tarvittavan aineiston muodostamiseen tuli siitä, että tietoja piti tulla eri vuosilta. Budjettiluvuista talousarvio ja suunnitelmavuodet ovat samalle vuodelle tallennettuja lukuja, mutta tilikauden talousarvio kuluvalle vuodelle. Kaikissa kentissä tulee kuitenkin period-arvona käyttää kuluvan vuoden viimeistä päivää. Tämä ongelma ratkaistiin sillä, että tilikauden talousarvioluvut kopioitiin samalle vuodelle muiden lukujen kanssa.

7 (9) Alla olevassa kuvassa on kuvattu aineiston muodostamisen prosessia. Kaksi ensimmäistä saraketta on tehty sen takia, että toteutus on tehty ensin kehitysympäristössä ja vasta sitten tuotannossa. Kehitysympäristössä ei ole budjettidataa, joten tätä varten muodostettiin näkymästä erillinen tiedosto, joka siirrettiin kehitysympäristöön. Kolmas sarake haarautuu puolestaan kahteen sen vuoksi, että haluttiin erikseen xml-aineistolle aineisto ja täsmäytystä varten aineisto. Xml-aineistoa varten ei haluttu ylimääräisiä elementtejä, mitä taas kuutiossa tarvittiin täsmäytystä helpottamaan. Myöhemmin on myös tarkoitus, että kuutiossa on muissakin aineistossa käytettävää dataa ja mahdollisesti myös dataa avoimen rajapinnan kautta muilta kunnilta. Kuva: XBRL-aineiston muodostaminen SSIS:llä. Logic Appsillä tehtävä siirto on muuten sama, mutta Logic Apps ottaa yhteyden oikeassa yläkulmassa laatikossa olevaan näkymään ja muodostaa tiedoston itse sen sijaan, että se noutaisi SSIS:n muodostaman tiedoston laatikon alapuolelta. SSIS-työkalulla muodostettava xml-tiedosto tehtiin niin, että kullekin vuodelle, organisaatiolle ja raportointikokonaisuudelle muodostuu joka yö oma tiedosto. Power Appsin Kuntatieto-painikkeella valittavilla parametreilla (vuosi, organisaatio ja raportointikokonaisuus) välitetään Logic Appsilla tieto, mikä tiedostoista noudetaan ja siirretään Valtiokonttorin palveluun. Ajot laitettiin päivittymään joka yö, jolloin ajo ei häiritse tuotantokäyttöä. Näin ollen budjettiluvut ja niiden linkittyminen Kuntatietotileihin tapahtuu aina öisin. Mikäli kuluvan päivän muutokset haluttaisiin saada toimitettua, pitäisi ajo ajaa erikseen manuaalisesti SQL management studiolla.

8 (9) 4. Tiedoston siirtäminen Tiedoston siirtämistä kokeiltiin testiä varten sekä web-käyttöliittymän kautta että REST-rajapinnalla. Tässä Logic Apps noutaa (ja muokkaa aineistoa) ja siirtää tiedoston REST-rajapinnalla Valtiokonttorille. Web-käyttöliittymää käytettiin puhtaasti testaamiseen, kun REST-rajapinta ei ollut valmis. Suurimpana haasteena siirron onnistumisessa oli rivinvaihdot, joiden suhteen pitää olla hyvin tarkkana, jotta aineisto menee sisään siirtopalvelussa. Aineiston lähettämistä varten tehtiin Power Appsillä (myöskin Microsoftin tuoteperheeseen kuuluva työkalu) painike, jolla aineiston voi lähettää eteenpäin. Lisäksi sinne saa kuittauksen, että tiedot siirtyivät tietopalveluun onnistuneesti. Kuva: Aineiston lähettäminen Onnistuneesta siirrosta tulee ilmoitus sähköpostiin, että aineisto on nähtävissä hyväksyntäpalvelussa. Virheellisestä siirrosta tulee myös sähköpostiviesti. Jos tässä viestissä on paljon rivejä, niin se saattaa tehdä sähköpostijärjestelmästä hyvin hitaan, minkä vuoksi olisi hyvä, että virhesisältö olisi esim. txt-liitetiedostona. Hyväksyntäpalvelussa näkee omien organisaatioiden aineistot, jotka ovat hyväksyttävissä tai hyväksytty. Olisi kätevää, jos jatkossa näkisi, mihin kaikkiin organisaatioihin on oikeus ja toisaalta voisi hakea oikeuksia uusiin organisaatioihin suoraan palvelussa. Toistaiseksi pitää olla sähköpostitse yhteydessä Valtiokonttoriin. Valtiokonttori työstää myös Rekisteripalvelua, josta voi noutaa aineistoja omasta tai muista kunnista. Tämä on vielä työn alla. Kuten analysointi- ja raportointipalvelu. Myös tukitietopalvelua (yhteentoimiva.suomi.fi) yritettiin hyödyntää projektissa, mutta palvelusta oli vaikea löytää tarvittavia tietoja, jos niitä siellä oli olemassa. Pilotin yhteydessä ei pystytty myöskään muodostamaan ollenkaan taseyksiköiden tai liikelaitoksien aineistoja (Hämeenlinnalla vain taseyksikkö), koska pilotin aikana näihin tarvittavat määritykset olivat vielä järjestävällä taholla työn alla.

9 (9) 5. Tietojen täsmäytys Tietojen täsmäytystä tarvitsee tehdä useammassa kohtaa, jotta voi olla varmempi tiedon oikeellisuudesta. Käytännössä tietoa tulee verrata budjettijärjestelmän, xbrl-aineiston, oman raportointiaineiston ja hyväksyntäpalvelun raportin välillä. Budjettijärjestelmässä eurot ovat vain kaupungin tileillä, joten tässä on suurena apuna, jos omassa raportointijärjestelmässä voi lukuja tarkastella sekä omien että Kuntatietotilien kanssa. Näitä Kuntatietotilieuroja voi puolestaan verrata xbrl-aineistossa oleviin sekä molempia Hyväksyntäpalvelussa oleviin. Myöhemmässä vaiheessa tietojen täsmäytystä voi vähentää, kun eri osasten toimivuus on taattu. Lisäksi olisi järkevää automatisoida tietojen täsmäytystä tekoälyn, robotiikan tai makrojen avulla.