1(12) Timo Lampola (0400 612 215) 15.11.2010 Sisällysluettelo 1 2 1.1 HRIS lyhyesti 2 1.2 HRIS-palvelun rakenne 3 2 Sijaintitiedot 4 3 Ajosuoritetiedot 6 3.1 Helpten ajosuoritteet 6 3.1.1 Ajosuoritteen elinkaari 6 3.2 Ajosuoritetiedon kuvaus (matkalasku) 7 3.3 Ajosuoritetiedon kuvaus (ERP) 8 4 Kuukausittaiset ajokilometrit 9 5 Tiedonsiirtoasetukset 10 5.1 FTP-haku 10 5.2 HTTP GET -palvelu sijaintitiedon integrointiin 11 6 Integraatioiden toteutusmalli 12
2(12) 1 1.1 HRIS lyhyesti Helpten tarjoaa integrointirajapinnan (HRIS, Helpten Remote Integration System) tietojen siirtämiseksi Helptenin ja Asiakkaan järjestelmien välillä. HRIS sisältää rajapintatoteutuksen seuraaviin ajotietoihin: 1. Viimeisin sijaintitieto 2. Ajosuoritetiedot matkalaskutusta varten 3. Ajosuoritetiedot laskutusta ja kustannusten kohdistamista varten (ERP) 4. Kuukausittaiset ajokilometrit Helpten kehittää a jatkuvasti. Uusia tietokokonaisuuksia lisätään ja vakioituja tiedonsiirtototeutuksia kehitetään yhdessä yhteistyökumppanien ja Helptenin asiakkaiden kanssa.
3(12) 1.2 HRIS-palvelun rakenne Kuva 1: HRIS-palvelun rakenne Tieto ohjataan HRIS-palvelimella sijaitsevaan FTP-hakemistoon, josta se voidaan noutaa tiedostoina (CSV tai TAB) asiakkaan järjestelmään. Sijaintitieto- ja ajosuoritetieto voidaan myös päivittää vastaanottavaan järjestelmään URL:n (HTTP GET) avulla. HRIS-ohjaustiedoilla voidaan hallita: - Tiedostojen rakennetta ja tietosisältöä - Tiedostojen luomisen ajastusta - Asiakaskohtaisten FTP-hakemistojen ominaisuuksia Tietojen käyttöoikeudet perustuvat Helptenin käyttöoikeusasetuksiin ja FTP-tunnusten hallintaan.
4(12) 2 Sijaintitiedot HRIS voidaan määrittää siirtämään sijaintitiedot vastaanottavaan järjestelmään tapauskohtaisesti määritettävän URL:n avulla siten, että HRIS toimii aktiivisena osapuolena. Rajapinta tarjoaa seuraavat tiedot: Identifiointitiedot - Laitetunnus (identifioi ajoneuvon) - Helptenin sisäinen tietuenumero - Helpten sopimustunnus (identifioi ajoneuvon) - Ajoneuvon rekisteritunnus - Ajoneuvon kuvaustieto - Ajoneuvon yksilöllinen lisäkoodi (esim. ERP-järjestelmässä käytettävä tunnistekoodi) Sijaintipisteen GPS-pohjaiset tiedot - GPS-aikaleima (sekunnin tarkkuus) - Pituusaste (max. 6 desimaalia) - Leveysaste (max. 6 desimaalia) - Suuntatieto (asteina, kokonaisluku) - Korkeustieto (metreinä merenpinnan tasosta) - Nopeustieto (km/h, kokonaisluku) - Sijaintipistevälin aikana vallinnut maksiminopeus (km/h, kokonaisluku) - GPS-trippimittarin lukema (metreinä, kokonaisluku, trippimittari nollautuu mikäli laite resetoituu) - Satelliittien lukumäärä
5(12) - Fix-tieto (liittyykö havaintopisteeseen ajantasainen GPSinformaatio) Sijaintipisteen osoitetiedot - Katuosoite (Suomessa katu ja kunta, muissa maissa vaihteleva tieto, esim. katu, postinumero, kaupunki, mahdollisesti myös katunumero ja muita tietoja) - Kohdetieto (Helptenin sisäinen id) Tapahtumatiedot (syykoodi sijaintipisteen rekisteröimiselle, esim. ajastettu sijaintipiste tai esimerkiksi tietyn kynnysarvon ylittäminen) - Tapahtumatyyppi (koodattu kokonaislukuna) - Tapahtumakentän lisätieto/mittausarvo (kokonaisluku) Sijaintipisteen tilatiedot - Digitaalianturien välittämä tilatieto (max. 6 anturia, tieto päällä/pois) - Analogiantureiden välittämä mittasarvo (millivoltteina, max. 4 analogianturia) - Valintapainikelaitteen tila (mahdolliset arvot 0, 1, 2, 3) - Palvelimen päässä määritetyt tilatiedot (max. 3 tilatietoa) Sijaintipisteen kuljettajatiedot (edellyttää ibutton-lukijaa) - Kuljettajatunnisteen koodi (ibutton id) Kuljettajan id-numero (Helptenin sisäinen id) - Kuljettajan nimi Sijaintipisteen ajosuoritekoodit - Viitekoodi Ajopäiväkirjan ajosuoritteeseen - Viitekoodi Tuotantoajopäiväkirjan ajosuoritteeseen
6(12) 3 Ajosuoritetiedot 3.1 Helpten ajosuoritteet 3.1.1 Ajosuoritteen elinkaari Ajosuoritteet syntyvät Helpteniin, kun ajosuorite päättyy. Ajosuorite voi päättyä kun - ajoneuvo on ollut kokonaan pysähtyneenä vähintään 5 minuuttia - kuljettaja vaihtaa ajotyyppiä painamalla valintapainiketta - toinen kuljettaja kirjautuu ibutton-tunnisteella saman ajosuoritteen aikana Ajosuoritteet tallentuvat erikseen Helpten Ajopäiväkirjaan (suunniteltu matkalaskukäyttöön) ja Helpten Tuotantoajopäiväkirjaan (suunniteltu tuotantoajoneuvojen seurantaan ja raportointiin). HRIS voi käsitellä (siirtää eteenpäin) ajosuoritteita heti, kun ne ovat syntyneet. Tavallisempaa on kuitenkin ajastaa ajosuoritteiden haku esimerkiksi kerran vuorokaudessa tapahtuvaksi. Helptenin käyttäjät voivat päivittää ja täydentää ajosuoritteiden tietoja. Muokkaukset olisi syytä tehdä ennen ajastettua siirtotiedostojen luomista. Joitakin Tuotantoajopäiväkirjan tietokenttiä (asiakastunnus ja laskutustunnus) voi päivittää ajon aikana kuljettajan Garminkäyttöliittymästä. Ajosuoritteen tietoihin voidaan liittää ajoneuvokohtaisia parametritietoja. Näin siirrettäviin ajosuoritteisiin saadaan mukaan ERP-järjestelmän vaatimia ajoneuvokohtaisia koodituksia. Ajosuoritteet voidaan hakea asiakaskohtaisesta FTP-outboxista, jonne HRIS tallentaa ne sovitun aikataulun mukaisesti.
7(12) 3.2 Ajosuoritetiedon kuvaus (matkalasku) Rajapinta tarjoaa seuraavat tiedot: Identifiointitiedot - Ajosuoritteen Helpten-tunnus - Laitetunnus (identifioi ajoneuvon) - Helpten sopimustunnus (identifioi ajoneuvon) - Ajoneuvon rekisteritunnus - Ajoneuvon kuvaustieto - Ajoneuvon lisäkoodi ERP1 (esim. matkalaskujärjestelmän henkilönumero) - Ajoneuvon aikavyöhyketieto Ajosuoritteen perustiedot - Aloituspvm. ja kellonaika, koordinaatit (lat/lon) - Lopetuspvm. ja kellonaika, koordinaatit (lat/lon) - Aloituspaikan osoite ja lopetuspaikan osoite - Ajomatka (metrin tarkkuus) - Matkan tyyppitieto (työajo 1/ työajo 2 / yksityisajo) Ajosuoritteen lisätiedot (edellyttää ajosuoritteiden muokkausta ennen siirtoa) - Käyttäjän korjaama kilometritieto - Kuvaus matkan tarkoituksesta - Lisähenkilöiden määrä - Lisäkustannuksen määrä - Perävaunutieto
8(12) 3.3 Ajosuoritetiedon kuvaus (ERP) Rajapinta tarjoaa seuraavat tiedot: Identifiointitiedot - Ajosuoritteen Helpten-tunnus - Laitetunnus(identifioi ajoneuvon) - Helpten sopimustunnus (identifioi ajoneuvon) - Ajoneuvon rekisteritunnus - Ajoneuvon kuvaustieto - Ajoneuvon lisäkoodi ERP1 (esim. henkilö/ajoneuvonumero) - ERP-koodi 2 (ajoneuvokohtainen tunnus, käyttötarkoitus valinnainen) - ERP-koodi 3a (ajoneuvokohtainen tunnus, joka saadaan mukaan kaikille laskutettaviksi merkityille ajosuoritteille) - ERP-koodi 3b (ajoneuvokohtainen tunnus, joka saadaan mukaan kaikille ei-laskutettaviksi merkityille ajosuoritteille) - Ajoneuvon aikavyöhyketieto Ajosuoritteen perustiedot - Aloituspvm. ja kellonaika, koordinaatit (lat/lon) - Lopetuspvm. ja kellonaika, koordinaatit (lat/lon) - Aloituspaikan osoite ja lopetuspaikan osoite - Ajomatka (metrin tarkkuus) - Pysähdysaika (minuutteina) - Matkan tyyppitieto (laskutettava / ei-laskutettava / yksityisajo)
9(12) Ajosuoritteen kuljettajatiedot (edellyttää ibutton-lukijaa) - Kuljettajan id (Helptenin sisäinen id) - Kuljettajan nimi Ajosuoritteen lisätiedot (edellyttää ajosuoritteiden muokkausta ennen siirtoa) - Käyttäjän korjaama kilometritieto - Kuvaus matkan tarkoituksesta - Lisähenkilöiden määrä - Lisäkustannuksen määrä - Laskutusohje - Asiakastunnus (voidaan asettaa navigaattorilla ajon aikana) - Laskutustunnus (voidaan asettaa navigaattorilla ajon aikana) 4 Kuukausittaiset ajokilometrit Ajoneuvojen kuukausittaiset ajokilometrit voidaan noutaa FTPhakemistosta. Kuukauden tiedot ovat saatavissa kuukauden päättymisen jälkeen. Rajapinta tarjoaa seuraavat tiedot: Identifiointitiedot - Laitetunnus (identifioi ajoneuvon) - Helpten sopimustunnus (identifioi ajoneuvon) - Ajoneuvon rekisteritunnus - Ajoneuvon kuvaustieto - Ajoneuvon yksilöllinen lisäkoodi (esim. ERP-järjestelmässä käytettävä tunnistekoodi)
10(12) Kilometritiedot - Kalenterivuosi ja -kuukausi - Ajokilometrien määrä/kk (metrin tarkkuus) o o o Kokonaiskilometrit Työajot Yksityisajot 5 Tiedonsiirtoasetukset 5.1 FTP-haku Helptenin ja HRIS-palvelun asetukset määrittävät, mitä tietoa asiakkaalle voidaan siirtää. Helptenin ja asiakkaan välillä tehdään palvelusopimus, jonka pohjalta määritetään tiedonsiirtoon liittyvät käyttöoikeusasetukset. Siirtotiedostojen muoto ja tietosisältö sovitaan tapauskohtaisesti. Käytettävissä on myös vakioituja tiedostomalleja yleisesti käytössä oleviin ERP-, matkalasku- ja muihin ajo- tai sijaintitietoa käyttäviin ohjelmistoihin. HRIS-palvelun FTP-toimintojen avulla jokaista tiedonsiirtotapausta varten luodaan FTP-hakemisto. FTP-siirroissa käytetään FTPS-protokollaa, joka sisältää SSL/TLSsalausta. Asiakas voi käyttää esimerkiksi WinSCP-ohjelmaa, joka tarjoaa helpon käyttöliittymän tiedostojen siirtämiseen. Myös muut FTPS- tai SFTP-pohjaiset tiedonsiirtototeutukset ovat mahdollisia. Tiedonsiirtojen suunnitteluvaiheessa valitaan käytettävä protokolla, ja Helpten toimittaa asiakkaalle ohjeistuksen yhteyden muodostamisesta.
11(12) Tiedostojen siirto Käyttäjän FTP-hakemistoon luodaan alihakemistot. - Outbox-hakemisto sisältää tiedostot, jotka HRIS on generoinut. - Inbox-hakemisto on käyttäjän lähettämiä tiedostoja varten. - Archive-kansioon sijoitetaan Inbox-hakemistosta käsitellyt tiedostot. Komentotiedostojen käyttö Komentotiedostojen avulla voidaan määrittää toimintoja, joilla asiakas voi itse ohjata haettavien tiedostojen luomista ja tietosisältöä. HRIS FTP -haku tukee CSV-muodossa annettuja komentotiedostoja. Komentotiedosto on muotoa: # command [command parameters] Command on palvelimella ajettava komento. Komennolla voi olla tarvittaessa parametreja. Komennot ja niiiden parametrit määritetään tapauskohtaisesti. Komentotiedosto siirretään Inbox-kansioon, josta palvelin suorittaa komentotiedoston. Tämän jälkeen HRIS-palvelin poistaa komentotiedoston Inbox-kansiosta ja siirtää sen Archivekansioon. 5.2 HTTP GET -palvelu sijaintitiedon integrointiin Asiakkaan ajoneuvojen viimeisin sijaintitieto voidaan siirtää kohdejärjestelmään HTTP GET palvelun avulla. Tässä integraatiovaihtoehdossa HRIS monitoroi ajoneuvosta Helptenpalvelimelle saapuvaa dataa ja lähettää datan kohdepalvelimelle. Datan lähetyksessä käytetään URL-templatea, jolla on seuraava rakenne: http://server:port/path?[parameter=value[¶meter=value]]
12(12) Parametrit voivat olla mitä tahansa tekstiparametrejä, jotka vastaanottava järjestelmä tunnistaa. HTTP GET palvelun avulla voidaan tehdä toteutuksia myös ajosuoritetiedon siirtämiseen. HTTP GET palvelun käyttö edellyttää luonnollisesti, että vastaanottavaan järjestelmään on toteutettu toiminnot tällä menetelmällä saapuvan datan käsittelyyn. 6 Integraatioiden toteutusmalli Helpten integraatiot toteutetaan määrittely- ja toteutusprojektina, jossa kartoitetaan tiedonsiirtotarpeet ja valitaan sopiva toteutustapa. Projektissa ovat osapuolina Asiakas ja Helpten, sekä tarvittaessa Asiakkaan käyttämä ohjelmistotoimittaja tai integraatiokumppani.