Yleistä
Tievelho tarjoaa tiedon tuottajille monipuoliset ja nykyaikaiset työkalut tiedon ylläpitoon. Tievelhossa oleva tieto syntyy pääasiallisesti järjestelmän ulkopuolella. Tietoa syntyy erityisesti Väyläviraston ydintoiminnasta. Tievelhon rooli on tarjota prosesseille tekniset rajapinnat, joihin prosessit voivat kytkeytyä automaation avulla. Tietoa tuotetaan järjestelmään myös muista tiestötietoa tuottavista järjestelmistä, jotka integroituvat Tievelhoon rajapintojen kautta.
Tievelhon rajapinnat validoivat tiedon rakenteellista yhtenäisyyttä ja varmistavat tiedon oikeellisuutta rakenteiden näkökulmasta.
Seuraavat asiat on tärkeä huomioida:
- Kun jo aiemmin luotua, mutta ulkopuolella päivitettyä, tietoa tuodaan Tievelhoon, muutokset kohdistetaan tunnistetietojen avulla oikein aiempaan tietosisältöön (tunnisteita voi olla tieosoitteet tai kohteen yksilöivät OID-tunnukset).
- Kun ulkopuolella uutena luotua tietoa tuodaan, sille luodaan tunnistetiedot perusrekistereissä ja palautetaan luodut tunnisteet ulkopuoliselle järjestelmälle, jotta myöhemmin niissä tehtävät päivitykset kohdistuvat oikein.
- Mikäli ulkopuolisen järjestelmän luoma tieto tuodaan perusrekisteriin sellaisena eräajona, että luodut tunnisteet eivät ole palautettavissa ja kohdistettavissa, kyseisen järjestelmän/toimijan on varmistettava kohteiden oikea tunnistaminen korvaamalla oman järjestelmänsä tietosisältö perusrekisterin uudella tietosisällöllä.
- Tiestötietoa päivitetään Tievelhossa eri tavoin tietokokonaisuudesta ja kohdeluokasta riippuen.
Yleisimmät tavat päivittää tietoa ovat seuraavat:
- ulkoisista järjestelmistä Tievelhon tarjoaminen rajapintojen kautta (APIt)
- eräajoina lähetyspalvelun kautta, joko
- toimijat itse tai
- Operointipalvelun avulla.
Ulkoiset järjestelmät (APIt)
Osaa Tievelhon kohdeluokista ylläpidetään muissa järjestelmissä ja tieto luetaan Tievelhoon rajapintojen kautta.
Rajapinnassa tarjotaan kunkin rekisteripalvelun toteuttamat päivitystoiminnallisuudet REST-toteutuksina:
- uuden kohteen luomiselle
- olemassa olevan kohteen muokkaamiselle
- siten, että kohteen historia säilyy (tilanne, jossa kohteen ominaisuudet ovat muuttuneet maastossa)
- siten, että muokataan kohteen historiaa (tilanne, jossa kohteen tiedot ovat olleet virheelliset)
- kohteen lakkauttamiselle, sen historia kuitenkin säilyttäen
- kohteen poistolle, historia mukaan lukien (ei yleensä sallittu).
Ulkoisten rajapintojen käyttöohje (Väyläpilvi)
Lähetyspalvelu
Tievelhon lähetyspalvelun kautta on tarkoitus päivittää suuria datamassoja sekä aineistoja, joita luonteensa vuoksi päivitetään esimerkiksi muutamia kertoja vuodessa.
Tievelhon lähetyspalvelun toimintaperiaate on seuraava:
- Ulkoinen järjestelmä tekee REST-rajapintaan pyynnön haluavansa tuoda kohteita Velhoon. Se saa vastauksena osoitteen, johon data voidaan lähettää HTTP:llä, sekä eräajotunnisteen.
- Ulkoinen järjestelmä lähettää datan annettuun osoitteeseen NDJSON-muotoisena siirtotiedostona (soveltuvin osin sama kuin Latauspalvelun tarjoama muoto).
- Lähetyspalvelu validoi lähetetyn datan ja vie sen Tievelhon rajapintoja käyttäen oikeisiin rekistereihin.
- Ulkoinen järjestelmä voi 1-kohdassa saamansa eräajotunnisteen avulla tiedustella, miten lähetetyn datan käsittely etenee, ja onko esim. datan validoinnissa ilmennyt virheitä.
Siirtotiedostossa voidaan ilmaista uusien kohteiden luonti (kohteen tiedot ilman OID:ia), kohteen päivitys (kohteen OID ja sen tiedot) sekä kohteiden lakkauttaminen tai poisto (kohteen OID sekä tieto lakkautuksesta/poistosta). Näiden operaatioiden semantiikka on sama kuin REST-rajapintojen kohdalla.
Tarkemmat käyttöohjeet lähetyspalvelun dokumentaatiossa.