Päätösdatan tuonti 6Aika-päätösrajapintaan

Tämä opasteksti on tarkoitettu niille, jotka suunnittelevat 6Aika-päätösrajapinnan käyttöönottoa ja tarvitsevat tietoa siitä, mitä tietoja operatiivisesta asianhallintajärjestelmästä täytyy irrottaa päätösrajapinnan tarpeisiin. Tästä dokumentista voi olla hyötyä myös, jos haluaa pääpiirteissään ymmärtää, minkälaista tietoa päätösrajapinnasta voi kysellä ja miten eri tietotyypit liittyvät toisiinsa.

6Aika-päätösrajapinta

6Aika-päätösrajapinta tuo kuntien päätökset avoimen REST-rajapinnan kautta avoimena datana vapaaseen käyttöön. Koska ulkopuolisia ei yleensä haluta päästää kuormittamaan operatiivista asianhallintajärjestelmää, tiedot tuodaan soveltuvin osin asianhallintajärjestelmästä päätösrajapinnan tietokantaan. Yksi tapa on irrottaa (export) päätösdata operatiivisesta järjestelmästä eräajona koneluettavassa muodossa ja tuoda (import) se päätösrajapintaan.

Päätöstietojen irrotus lähdejärjestelmästä ja siirto päätösrajapinnan tietokantaan.

Siirtotiedoston rakenne

Irrotuksen tuloksena syntyy rakenteisessa muodossa oleva ja yleisillä ohjelmointityökaluilla hyödynnettävissä oleva tekstitiedosto. Tieto voi olla esimerkiksi yksinkertaisessa JSON- tai XML-muodossa.

Tiedot voidaan jakaa useampaan tiedostoon esimerkiksi tietotyypeittäin, jos niiden looginen järjestys on selvä. Esimerkiksi kokoukset täytyy tuoda päätösrajapintaan organisaatioiden jälkeen, koska kokous liittyy aina organisaatioon, jonka täytyy tietysti olla olemassa ennen kuin kokoustietue voidaan luoda tietokantaan.

Päätösrajapinnan tietomalli

Tietomallikuvassa näkyy tärkeimmät tietotyypit ja niiden väliset suhteet. Pallo yhteysviivan päässä tarkoittaa ”suhde moneen” -tyyppistä yhteyttä ja pallon puute ”suhde yhteen”. Esimerkiksi Caseen (asia) voi liittyä useampi Action (toimenpide), joista jokainen liittyy vain yhteen Caseen.

Irrotettava data

Kaikkien eri tietotyyppien objekteilla täytyy olla lähdejärjestelmän yksilöllinen tunniste (id), jolla se voidaan tunnistaa ja jolla siihen voidaan tarvittaessa viitata päätösrajapinnasta (origin_id).

Lisäksi hyödyllisiä tietoja ovat objektin luontiaika ja viimeisin muutosaika lähdejärjestelmässä. Näitä käytetään tuotaessa uusia ja muuttuneita tietoja päätösrajapintaan.

Siirtotiedoston kenttien nimeäminen

Alla olevissa listoissa määriteltyjen kenttien nimien sijaan voidaan käyttää SÄHKE2-määrittelyn mukaista nimeämiskäytäntöä, jos sellainen löytyy ja se on siirtotiedoston muodostamisen kannalta yksinkertaisempaa.

Kaikille tietotyypeille yhteiset kentät

  • id: lähdejärjestelmän yksilöllinen tunniste objektille (SÄHKE2: Identifier.NativeId)
  • created_at: objektin luontiaika (SÄHKE2: Date.Created)
  • modified_at: objektin viimeisin muutosaika (SÄHKE2: Date.Modified)

Aikaleimat tuodaan ISO 8601 -standardin mukaisessa muodossa aikavyöhyketietoineen, esimerkiksi ”2016-12-19T18:00:00+02”. Jos aikavyöhyketiedon lisääminen on mahdotonta, oletetaan aikaleiman olevan aikavyöhykkeellä Europe/Helsinki.

https://fi.wikipedia.org/wiki/ISO_8601

Puuttuvat tiedot

Puuttuvat tiedot jätetään pois siirtotiedostosta tai kentän arvoksi kirjataan null tai tyhjä merkkijono.

Ei-rakenteisessa muodossa olevien tietojen osalta voidaan erikseen harkita, kannattaako niitä alkaa muuttaa automaattisesti rakenteiseen muotoon. Hyödyllisiä kohteita automatisoinnille olisi mm. kaavanumeroiden, katuosoitteiden ja paikkojen muuttaminen paikkatiedoksi eli GPS-koordinaateiksi.

Tässä dokumentissa mainitsematta jääneet tiedot

Lähdejärjestelmästä voidaan mahdollisesti irrottaa helposti sellaista hyödyllistä dataa, jota tässä dokumentissa ei ole erikseen mainittu. Yleisesti ottaen tällainen data kannattaa sisällyttää siirrettävään dataan, sillä se voi olla tarpeen päätösrajapinnan kehittyessä eteenpäin.

Irrotettavat tietotyypit

Toimielimet

Toimielin (organization) on kunnassa päätöksiä tekevä organisaatio, esimerkiksi Kaupunginvaltuusto, Kaupunginhallitus sekä lautakunnat.

  • classification: toimielimen tyyppi (esim. virasto, lautakunta, viranhaltija, toimiala, jaosto, valtuusto, kaupunki, toimikunta, hallitus, yksikkö, osasto)
  • name: virallinen nimi
  • founding_date: perustamispäivämäärä
  • dissolution_date: lopettamispäivämäärä
  • parent: ylemmän toimielimen id, jos toimielin jonkin toisen toimielimen alaisuudessa

https://github.com/6aika/paatos/blob/master/decisions/models/organization.py

Virat

Virka (Post)

  • label: viran nimi
  • organization: toimielimen tunniste, johon virka liittyy
  • start_date: viran perustamispäivä
  • end_date: viran lopetuspäivämäärä

Kokoukset

Kokouksen (Event) pitää aina jokin toimielin.

  • name: kokouksen nimi, jos sellainen on
  • organization: kokouksen pitäneen toimielimen tunniste
  • start_date: kokouksen alkuaika tai päivämäärä
  • end_date: kokouksen loppuaika tai päivämäärä

https://github.com/6aika/paatos/blob/master/decisions/models/meeting.py

Tehtäväluokka

Tehtäväluokka (Function) on (esimerkiksi SÄHKE2-määrityksen mukainen) hierarkia ”00 02 00” Valtuuston päätöksenteko

  • name: tehtäväluokan nimi, esim. ”Valtuuston päätöksenteko”
  • function_id: esimerkiksi ”00 02 00”
  • parent: tehtäväluokan mahdollinen yläluokka

https://github.com/6aika/paatos/blob/master/decisions/models/case.py

Asiat

Asia (Case) sitoo yhteen kaikki siihen kohdistuneet toimenpiteet (Action), eikä se itse sisällä asian nimen ja diaarinumeron lisäksi välttämättä muuta tietoa.

  • title: asian otsikko
  • register_id: diaarinumero
  • function: tehtäväluokka
  • geometries: lista asiaan liittyviä paikkatieto-objekteja (esim. pisteet, alueet) GeoJSON-muodossa (nämä voivat olla myös erillisessä listassa)

Toimenpide

Toimenpide (Action) on asian käsittelykerta toimielimen kokouksessa. (Tulevaisuudessa mahdollisesti myös muu käsittely (vireilletulo, valmistelu) avataan.)

  • title: toimenpiteen otsikko
  • case: asian tunniste (Case id)
  • ordering: toimenpiteen järjestysnumero kokouksen esityslistassa
  • article_number: pykälänumero lähdejärjestelmässä
  • resolution: päätöksen tyyppi (pöydätty, päätetty…)
  • post: viranhaltijapäätöksissä viran tunniste (ks. virka / Post)
  • event: kokouksen tunniste lähdejärjestelmässä

Toimenpiteen sisältöteksti

Toimenpiteen sisältö on yleensä jaettu kappaleisiin (Content), joiden tyyppi (type) voi olla esimerkiksi tiivistelmä, käsittely, perustelut, päätösehdotus, päätös jne. Jos kappaleet ovat lähdejärjestelmässä valmiiksi eri tietueissa tai ne on jaettavissa erillisiin kappaleisiin ne tuodaan myös siirtotiedostoon osissa.

  • ordering: kappaleen järjestysnumero toimenpiteen sisältötekstissä
  • title: kappaleen otsikko
  • type: kappaleen tyyppi
  • hypertext: sisältöteksti, joka voi sisältää muotoiluja (rajoitettu joukko HTML-elementtejä)
  • action: toimenpiteen tunniste (action id)

Liitteet

Toimenpiteeseen liittyvät tiedostoliitteet tuodaan siirtotiedoston mukana tai ne voivat sijaita julkisessa internet-verkossa, johon voidaan viitata päätösrajapinnasta tai josta ne voidaan hakea päätösrajapinnan tiedostojärjestelmään.

  • name: tiedoston lyhyt kuvaus
  • filename: alkuperäinen tiedostonimi
  • url: tiedoston sijainti tiedostojärjestelmässä tai verkossa
  • action: toimenpiteen tunniste, johon liite liittyy
  • number: liitteen järjestysnumero
  • public: tiedoston julkisuus (true tai false)
  • confidentiality_reason: salauksen syy (jos liite ei ole julkinen)

Lisäksi voidaan tuoda tiedostomuoto (Content type, esim. application/pdf), mahdolliset eheystunnisteet (MD5, SHA jne) sekä muut metatiedot.

Jatkokehitys

Tällä hetkellä (lokakuu 2017) Helsingin Ahjo-järjestelmästä on tuotu päätösdataa 6Aika-päätösrajapintaan OpenAhjo-rajapinnan tietokannan kautta. Suoraan Ahjo-dokumenteista tiedot hakeva importteri odottaa käyttöönottoa. Oulun ja Vantaan TWeb-järjestelmien verkkosivuilta on skreipattu päätöstietoja päätösrajapintaan. Tampereen CaseM:ista tiedot haetaan OData-rajapinnasta. Espoon Dynasty 360°:stä data on toistaiseksi skreipattu, mutta eräajona tiedot suoraan tietokannasta irrottava työkalu on valmis ja se odottaa importterin käyttöönottoa.

Kaikkia päätösdatan irrotusta suunnittelevia rohkaistaan olemaan ennen työn aloittamista yhteydessä Aapo Ristaan (aapo.rista@forumvirium.fi) päällekkäisen ja mahdollisen turhan työn minimoimiseksi.