Joukkoliikenteen kansallinen ennusterajapinta

Transkriptio

1 ÄLLI-julkaisuja 9/2009 Joukkoliikenteen kansallinen ennusterajapinta Tekninen määrittely v. 1.0

2 ÄLLI-julkaisuja Helsinki 2009

3 SISÄLTÖ KÄSITTEITÄ JOHDANTO YLEISTÄ Työn tavoitteet Suppea ja laaja rajapinta Liitteet Dokumentaation käytöstä Rajapinta toteutuksen testaus Palvelutasovaatimukset Jatkokehitys Yleisiä suosituksia Suomi-tasolla SIRI-STANDARDI SIRI lyhyesti SIRIn palvelut Saatavat hyödyt SIRIn määrittelydokumentti Tietomalli ja viitekehys TEKNISIÄ YLEISOHJEITA Taulukoiden tulkintaohjeet Skeemojen käytöstä WSDL:t XML Schemat Kommunikaatiomallit Vastausviestin eri toimitustavat Sanomien rakenne Kyselyviesti Tilausviesti Vastausviesti Käytettävä viitekehys Päivä- ja aikaformaatit Virhetilanteiden hallinta Palvelimen kyvykkyyksien selvittäminen YHTEISIÄ ELEMENTTEJÄ CapabilityRequest xxxcapabilityrequest CapabilityResponse

4 5.4 xxxcapabilityresponse ServiceDelivery xxxdeliverygroup JourneyPatternInfoGroup VehicleJourneyInfoGroup JourneyProgressInfoGroup ServiceInfoGroup STOP MONITORING SERVICE (SM) Yleistä StopMonitoringCapabilitiesGroup StopMonitoringRequest StopMonitoringSubscriptionRequest StopMonitoringDelivery MonitoredStopVisit MonitoredStopVisitCancellation StopLineNotice StopLineNoticeCancellation MonitoredStopVisit with MonitoredVehicleJourneyAsGroup Esimerkkejä Pysäkille ennustetiedot Ennustetietojen tilaaminen syötteenä LIITE 1: SIRI-MÄÄRITTELYDOKUMENTTI LIITE 2: SIRI WHITE PAPER LIITE 3: SIRI 1.0 SKEEMAT LIITE 4: WSDL-TIEDOSTOJEN RAKENNE LÄHDELUETTELO

5 KÄSITTEITÄ IFOPT Identification of fixed objects in public transport. Joukkoliikenteen käsitteitä ja niiden suhteita määrittelevä standardi (CEN-standardi). XML Extensible Markup Language. Rakenteinen tiedonsiirtoformaatti. SIRI Service Interface for Real Time Information. Reaaliaikarajapintoja standardoiva eurooppalainen organisaatio. WSDL SOAP CEN HKL YTV HSL RHK TRANSMODEL Web Service Description Language. Kuvauskieli, jota käytetään web-palvelujen rajapintojen kuvaamiseen. Web-palveluiden oletusprotokolla, joka toimii HTTPprotokollan päällä. European Committee for Standardization. Eurooppalainen standardointiorganisaatio. Helsingin Kaupungin Liikennelaitos Yhteystyövaltuuskunta Helsingin Seudun Liikenne Ratahallintokeskus Julkisen liikenteen abstrakti tietomalli (CEN-standardi) Kyselytyyppi Tarkoittaa samaa asiaa kuin rajapintafunktio tai rajapintametodi. Toimija Operaattori Liikenneväline Joukkoliikenteen toimija. Esim. HSL (ent. YTV liikenne ja HKL suunnittelu) ja VR ovat toimijoita. Joukkoliikenteen operaattori. Usein epäselvä käsite ja siksi ei ole käytetty tässä dokumentissa. Kulkuneuvo, kulkuväline, ajoneuvo. Voi tarkoittaa bussia, raitiovaunua, junaa tms. 5

6

7 1 JOHDANTO Tässä työssä on tehty tekninen määrittely kansallisen joukkoliikenteen ennustepalvelimen käyttäjärajapinnasta. Ennustepalvelimella tarkoitetaan joukkoliikennetoimijan järjestelmää, joka tuottaa reaaliaikapohjaisia ennusteita joukkoliikennevälineiden liikkeistä toimijan omille tai muiden toimijoiden järjestelmille. Ennustepalvelimen tärkein tunnistettu käyttötapaus on tuottaa saapumisaikaennusteita pysäkeillä ja asemilla oleville näyttötauluille ja niiden ohjausjärjestelmille. Tämä määrittelydokumentti perustuu aiemmin tehtyyn rajapinnan vaatimusmäärittelyyn. Siinä selvitettiin mm. liikenteen toimijoiden tarpeita haastatteluin sekä määriteltiin rajapinnan käyttötapaukset ja toiminnalliset tarpeet. Lisäksi selvitettiin mahdollisuutta hyödyntää kansainvälisiä standardeja rajapinnan määrittelytyössä. Vaatimusmäärittely löytyy dokumentista ennusterajapinta_vaatimusmäärittely.pdf. Tämä työ on tehty Tiehallinnon koordinoiman Älli-ohjelman [1] puitteissa ja liikenne- ja viestintäministeriön toimeksiannosta. Hanketta oli ohjaamassa ministeriön lisäksi YTV, HKL ja Tampereen kaupunki. Työ täydentää osaltaan valmistunutta Kansallinen joukkoliikenteen paikannusarkkitehtuuri -hanketta, jossa määriteltiin ajoneuvon ja paikannuspalvelimen välinen ajoneuvorajapinta sekä paikannuspalvelimen ja ennustepalvelimen välinen paikannusrajapinta. Ennustepalvelintoteutuksista vastaavat joukkoliikennetoimijat, jotka toteuttavat järjestelmät itsenäisesti haluamallaan tavalla, mutta siten että järjestelmät toteuttavat tässä dokumentissa määritellyn rajapinnan. Suomen joukkoliikennetoimijoista ennusterajapinnan tulevat todennäköisesti toteuttamaan ainakin tuleva HSL (YTV liikenne/hkl suunnittelu), RHK ja Tampereen Kaupunki. Suurin osa tästä dokumentista on luonteeltaan teknistä asiaa ja tarkoitettu sovelluskehittäjille ja muille toteutuksesta vastaaville. Dokumentti sisältää yksityiskohtaiset ohjeet miten toteuttaa SIRI-standardin mukainen XML-ennusterajapinta. SIRI-standardi on yhteiseurooppalainen rajapintastandardi reaaliaikapohjaisten joukkoliikennetietojen välitykseen. SIRI-standardi on esitelty tarkemmin tämän dokumentin luvussa 3.

8 2 YLEISTÄ Tässä luvussa on esitelty yleisiä huomioita ennusterajapinnan toteutukseen liittyen. 2.1 Työn tavoitteet Ennusterajapinnan toteutusprojektin tavoitteena on toteuttaa SIRI-standardiin perustuva webpalvelu (XML/SOAP) tyyppinen rajapinta. Rajapinta toteutetaan tämän määrittelydokumentin, annettujen WSDL-palvelukuvausten ja XML Schema sanomakuvasten pohjalta. Toteutuksessa tarvitaan myös SIRIn virallista englanninkielistä määrittelydokumenttia. Tämän työn lähtökohtana on ollut, että määritellyistä käyttötapauksista huomioidaan aluksi vain saapumisaikaennusteiden tuottaminen pysäkkien ja asemien näyttötauluille ja niiden ohjausjärjestelmille. Koska rajapinnan on tarkoitettu olevan julkinen, myös erilaiset www- ja mobiilisovellukset voivat hyödyntää näitä tietoja. Rajapintaa on mahdollista laajentaa myöhemmin tukemaan myös muita käyttötapauksia. Pysäkkinäyttöjen ohjausta varten SIRI-standardissa määritellyistä kahdeksasta eri käyttötapauksesta (kts. kappale 3.2 ) toteutetaan siis aluksi vain tätä käyttötapausta vastaava palvelu: Stop Monitoring Service (SM). Tämän palvelun tarkoitus on mahdollistaa reaaliaikaisten saapumisaikaennusteiden lähettämisen pysäkkinäytöille ja/tai niiden ohjausjärjestelmille. Kuva 1 havainnollistaa, mitä tässä työssä tavoitellaan. Kuvassa vasemmalla puolella on kuvattu nykyinen tilanne, jossa toimijat voivat näyttää pysäkkinäytöillään vain omia ennustetietojaan. Kuvan oikealla puolella on tavoitetila, jossa eri toimijat tarjoavat ennustetietoja julkisten SIRI-rajapintojen kautta, jolloin ennusteita voidaan näyttää muiden toimijoiden näytöillä tai kolmansien osapuolien näytöillä (esim. kokoojannäytöillä kauppakeskuksissa). Ennusterajapintoja voisivat tällöin hyödyntää myös erilaiset www- ja mobiilipalvelut. On huomioitavaa, että ennustepalvelimen tarkoitus on toimia ns. taustajärjestelmänä eli tuottaa raakamuotoista dataa muille järjestelmille. Sen tarkoitus ei ole tuottaa valmiiksi jalostettuja tietoja pysäkkinäytöille sopiviksi, vaan tämä jalostus on syytä suorittaa vasta näyttöjen ohjausjärjestelmässä. Tämä mahdollistaa sen, että data on käyttökelpoista mahdollisimman monelle eri järjestelmälle. 8

9 Toimija A Toimija B Toimija A Toimija B SIRI SIRI Kuva 1: Pysäkkinäyttöjen ohjaus 2.2 Suppea ja laaja rajapinta Ennusterajapinnan määrittelytyöhön sisältyi ehto, että rajapinnasta on toteutettava kaksi eri versiota: laaja ja suppea. Idea oli että pienempien kaupunkien joukkoliikennetoimijat voisivat toteuttaa suppeamman version ja säästää sillä kustannuksissa. Tässä määrittelyssä ei kuitenkaan ole määritelty kahta rajapintaa erikseen vaan ainoastaan yksi. Tässä määrittelyssä suppea ja laaja toteutus on huomioitu siten, että määrittelyssä on (suppea) joukko pakollisia kyselytyyppejä, jotka kaikkien toimijoiden on syytä toteuttaa, sekä joukko valinnaisia kyselytyyppejä, joita voidaan toteuttaa tarvittaessa. Kyselytyyppien lisäksi kaikki rajapinnan viestityypit sisältävät joukon pakollisia ja valinnaisia tietueita. Valinnaisten kyselytyyppien ja tietueiden toteuttamisella voidaan siis säätää rajapinnan toteutuksen laajuutta. Toimijat voivat halutessaan toteuttaa SIRI-rajapinnan huomattavasti laajemmin kuin mitä tässä dokumentissa on suositeltu. Tässä dokumentissa on kerrottu ohjeet miten toteuttaa yksi kahdeksasta eri SIRI-palvelusta. Toimijat voivat kuitenkin SIRI-määrittelydokumentin avulla toteuttaa halutessaan myös muut seitsemän palvelua, jota itse asiassa suositellaan. 2.3 Liitteet Tähän dokumenttiin liittyy useita liitteitä. Liitteessä 1 on SIRI-standardin määrittelydokumentti, jota joudutaan toteutuksen aikana hyödyntämään. Liitteessä 2 on SIRI-standardin lyhyt esittelydokumentti - SIRI White Paper. Liitteessä 3 on toteutusvaiheessa käytettävät skeematiedostot. Liitteessä 4 on havainnollistettu käytettäviä WSDL-skeemoja. 9

10 2.4 Dokumentaation käytöstä Ennusterajapintaa ei voida toteuttaa pelkästään tämän dokumentin ja annettujen skeemojen avulla, vaan apuna on käytettävä myös SIRI-standardin virallista määrittelydokumenttia (liitteessä 1). Tämän dokumentin rooli on toimia ainoastaan tulkintaohjeena ao. määrittelydokumenttiin. Tulkintaohjeen tärkein tarkoitus on pystyä rajaamaan toteutus järkeviin mittoihin ja laatia yhteiset pelisäännöt tietueiden käytöstä rajapinnan viestityypeissä. SIRIn määrittelydokumentti voi tuntua aluksi melko vaikealukuiselta, mutta loppujen lopuksi sen rakenne on melko yksinkertainen. SIRIin tutustuminen on helpointa aloittaa tutustumalla SIRIn www-sivuihin ja sieltä löytyvään standardin yleiskuvaukseen, SIRI White Paperiin (löytyy myös liitteestä 2). Hyödyllistä lukemista voi olla myös SIRI v.1.3a Handbook (draft) [3], joka tarjoaa hieman syvällisemmän johdatuksen standardin rakenteeseen. 2.5 Rajapinta toteutuksen testaus Valmis rajapinta toteutus tulee testata huolellisesti annettuja palvelukuvausdokumentteja (WSDL) ja sanomakuvausdokumentteja (XML Schema) vasten. Testaus on syytä tehdä käyttämällä tähän tarkoitukseen soveltuvia validaattoreita tai muita vastaavia työkaluja. Rajapinnalle on suositeltavaa tehdä myös asianmukaiset kuormitustestaukset ennen käyttöönottoa. Toimijoiden on syytä varautua myös siihen että valmiit toteutukset testataan ulkopuolisen tahon toimesta. Tällä varmistetaan että eri toimijoiden toteutuksista tulee varmasti yhteensopivia. Ulkopuolisen tahon huomatessa toteutuksessa ongelmia, voi tämä suositella toimijaa tekemään korjauksia rajapintaan. 2.6 Palvelutasovaatimukset Seuraavassa on asetettu ennustepalvelintoteutuksille joitain alustavia palvelutasovaatimuksia. Toimijoiden on syytä vielä tarkentaa näitä vaatimuksia vastaamaan paremmin omia tarpeitaan. Viestinvälityksen on tapahduttava rajapinnasta viiveettömästi ja ilman porrastusta, kun viestejä lähetetään asiakassovellukselle syötteenä. Tämä tarkoittaa sitä, kun päivitetyt tiedot ovat saatavilla, ne on lähetettävä asiakkaalle saman tien. Ennusterajapinnasta on pystyttävä välittämään normaalisti vähintään 1000 viestiä sekunnissa. Monesti tarvittava välityskyky voi olla tästä reilusti suurempikin, mutta ei yli viestiä sekunnissa. Rajapinnan on pystyttävä vastaamaan pyyntöihin riittävän lyhyellä viiveellä. Palvelun on oltava saatavilla vähintään 99,5 % kaikesta ajasta mahdollisia huoltokatkoja lukuun ottamatta. Saatavuus sisältää ehdon, että vastausviestien on oltava virheettömiä. Palvelun saatavuutta tullaan mahdollisesti seuraamaan toisen palvelun tai lokitiedostojen avulla. 10

11 2.7 Jatkokehitys Tämän dokumentin ensimmäinen versio on määrittely siitä, miten tarjota ennustetietoa SIRIrajapinnan kautta pysäkkinäytöille. Sitä varten on tässä dokumentissa tehty suosittelu, miten toteuttaa yksi kahdeksasta SIRI-palvelusta (SM - Stop Monitoring Service). SM-palvelun määrittelyä olisi kuitenkin hyvä pitää vain ensimmäisenä vaiheena SIRI-standardin käyttöönotossa Suomessa. Koska SIRI tarjoaa erinomaiset mahdollisuudet joukkoliikennetietojen välitykseen toimijoiden välillä, olisi tätä määrittelyä syytä jatkaa tulevaisuudessa kattamaan myös muita SIRI-palveluja. Seuraavassa vaiheessa olisi suositeltavaa toteuttaa ainakin SIRIn Vehicle Monitoring (VM) palvelutyyppi, joka liittyy läheisesti tässä dokumentissa määriteltyyn SM-palvelutyyppiin. VMpalvelusta olisi selvää hyötyä käytännössä, koska tällöin voitaisiin seurata pysäkkien lisäksi myös liikennevälineiden liikkeitä. VM-palvelun avulla voitaisiin välittää mm. paikkatietoja karttapalveluihin sekä tietoja liikennevälineiden sisänäytöille. Kuva 2 esittää VM-palvelun tarjoamia mahdollisuuksia. VM-palvelun käyttönoton jälkeen voidaan harkita SIRIn käyttämistä myös aikataulutietojen välittämiseen (PT-, ET-, ST-palvelut) ja taattujen vaihtojen hallintaan (CT,CM). SIRI Kuva 2: Jatkokehitysmahdollisuudet 2.8 Yleisiä suosituksia Suomi-tasolla Ennusterajapintaprojekteja varten on suositeltavaa perustaa Suomi-tasoinen koordinointiryhmä, jolta voisi saada tarvittaessa tukea hankaliin tilanteisiin. Työryhmä suosittelee, että koordinointiryhmän puoleen voisi kääntyä ongelmatilanteiden lisäksi myös tilanteissa, joissa määrittelyssä havaitaan korjaus- tai kehitystarpeita. 11

12 Tärkeässä osassa ovat yhteisten koodistojen ja muiden uniikkien tunnisteiden sopiminen. Koordinaatioryhmän tärkeimpiä tehtäviä olisi ylläpitää listaa käytettävistä yhteisistä tunnisteista ja koodistoista. Kansallisen rajapinnan toteutumiseksi tulisi myös varmistaa, että toimijoiden toteutukset ovat määrittelyiden mukaisia. Koordinaatioryhmän toimenkuvaan voisi kuulua siis myös valmiiden rajapinta toteutusten testaus. Koordinointiryhmä voisi myös valtuuttaa tukipalvelun perustamisen, mikä tarjoaisi tukea rajapinnan toteuttajille. 12

13 3 SIRI-STANDARDI Tässä luvussa on esitelty rajapinnan toteutustavaksi valittu SIRI-standardi. 3.1 SIRI lyhyesti SIRI (Service Interface for Real Time Information) on yhteiseurooppalainen rajapintastandardi julkisen liikenteen ja ajoneuvojen reaaliaikatietojen välittämiseen joukkoliikennetoimijoiden välillä. SIRI-standardi on käytössä mm. Isossa-Britanniassa, Ruotsissa, Tanskassa, Norjassa, Saksassa, Ranskassa ja Tshekissä. SIRI on kehitetty kansallisten standardien pohjalta ja siitä on pyritty kehittämään mahdollisimman joustava, jotta sitä voidaan käyttää mahdollisimman monissa maissa. Standardi on alun perin kehitetty Ranskassa, Saksassa ja Iso-Britanniassa. SIRI on hyväksytty CEN-standardiksi vuonna 2006 (CEN ). SIRIä voidaan käyttää mm. aikataulujen välittämiseen muille toimijoille, tietojen välitykseen pysäkkinäytöille, liikennevälineiden seurantaan, taattujen vaihtojen hallintaan ja liikennevälinenäyttöjen ohjaukseen. SIRI on modulaarinen ja kevyt arkkitehtuuri, joka voidaan ottaa käyttöön askeleittain. Tämän tekee mahdolliseksi se, että SIRI on jaettu kahdeksaan palveluun (moduuliin), joista voidaan valita vapaasti mitkä halutaan ottaa käyttöön. Nämä kahdeksan palvelua on selitetty tarkemmin seuraavassa kappaleessa. SIRI määrittelee XML-rajapinnan, jossa sanomat lähetetään joko TCP:n tai yli. Rajapinta voidaan toteuttaa myös web-palveluna, jolloin viestit lähetetään käyttämällä SOAPprotokollaa. Web-palvelu -tavan etu on että siinä voidaan hyödyntää SIRIn valmista palvelukuvausdokumenttia (WSDL), joka määrittelee tarkasti rajapinnan toimintatavan. Tässä määrittelyssä on suositeltu toteutustavaksi ao. web-palvelu tapaa. 3.2 SIRIn palvelut Kuva 3 esittää SIRIn arkkitehtuuria ja kahdeksaa perusmoduulia, joista rajapinta koostuu. Näitä moduuleita nimitetään SIRIssä toiminnallisiksi palveluiksi (functional services). Kukin palveluista vastaa jotakin rajapinnan käyttötapausta ja määrittelee siihen liittyvän tiedonvaihdon. Kuten mainittua, SIRIn käyttötapauksiin kuuluivat aikataulujen välitys, taattujen vaihtojen hallinta, pysäkkinäyttöjen ohjaus, ajoneuvonäyttöjen ohjaus ja viestinnän hallinta ohjauskeskusten välillä. 13

14 Kuva 3: SIRIn tarjoamat palvelut Production Timetable Service (PT) palvelu on tarkoitettu suunniteltujen aikataulujen kommunikointiin muille toimijoille. Tyypillisesti aikataulut muuttuvat jatkuvasti ja näitä tietoja halutaan päivittää muille toimijoille, joiden kanssa toimijalla on esim. taattuja vaihtoja. Aikataulujen tai muutosten lisäksi tässä palvelussa tiedot mm. lisätyistä tai poistetuista lähdöistä. Tämän palvelun kautta aikatauluja voi kysellä toimija-, linja- ja aikavälikohtaisesti. Tämä palvelu on suunniteltu erityisesti toimijoiden AVL-järjestelmät silmällä pitäen. Estimated Timetable Service (ET) palvelu on tarkoitettu reaaliaikakorjattujen aikataulutietojen kommunikointiin muille toimijoille. Reaaliaikakorjatuissa aikatauluissa on huomioitu liikennevälineen sen hetkinen poikkeavuus suunnitellusta aikataulusta. Tämän palvelun viestit voivat sisältää myös muuta suunnitellusta toiminnasta eroavuutta ilmaisevaa tietoa, kuten muuttunutta lähtölaituria tai reittimuutosta, jota ei kyseisen päivän suunnitellussa aikataulussa ole mukana. Tämä palvelu tukee erityisesti AVL-järjestelmiä sekä reaaliaikaiseen tietoon perustuvia matkustajainformaatiojärjestelmiä. Stop Timetable Service (ST) -palvelu on tarkoitettu pysäkkiaikataulujen kommunikointiin. Pysäkkikohtaisilla aikatauluilla tarkoitetaan määrätyn pysäkin suunniteltujen aikataulujen mukaisia ajoneuvojen saapumis- ja lähtöaikoja. Tämä palvelu tukee suoraan pysäkkiaikataulutietoja hyödyntäviä järjestelmiä. Lisäksi sitä voidaan hyödyntää myös epäsuorasti reaaliaikaisissa matkustajainformaatiojärjestelmissä, esim. referenssidatana, jota korjataan reaaliaikatiedoilla. 14

15 Stop Monitoring (SM) palvelu on tarkoitettu pysäkkien infonäyttöjen tarvitsemien tietojen kommunikointiin. Välitettävät tiedot pitävät sisältään mm. liikenneväineiden ennustetut saapumis- ja lähtöajat pysäkille. Palvelua voivat hyödyntää bussipysäkkien näyttötaulujen ohjausjärjestelmien lisäksi muut reaaliaikaiset pysäkkikohtaisia tapahtumia näyttävät järjestelmät kuten kokoojannäytöt tai www- ja mobiilipalvelut. Connection Timetable (CT) ja Connection Monitoring (CM) -palvelut ovat tarkoitettu taattuihin vaihtoihin liittyvien reaaliaikatietojen kommunikointiin toimijoiden kesken. Nämä palvelut mahdollistavat taattujen vaihtojen reaaliaikaisen hallinnan ja suunnittelun. Lisäksi näitä palveluja voidaan käyttää matkustajainformaatiojärjestelmissä, esim. myöhässä olevan junan matkustajia voidaan tiedottaa jatkoyhteyksiin liittyvistä yksityiskohdista. Vehicle Monitoring Service (VM) palvelu on tarkoitettu liikennevälineiden paikkatietojen ja pysäkkikohtaisten ohitusaikojen kommunikointiin niiden reiteillä. Ohitusaikoihin kuuluvat sekä suunnitellut että arvioidut saapumis- ja lähtöajat reitin pysäkeillä. Tämä palvelu on tarkoitettu erityisesti liikennevälineissä olevien infonäyttöjen ja paikkatietoja visualisoivien (karttapohjaisten) järjestelmien tarpeisiin. Koska tämä palvelu mahdollistaa myös historiatietojen keräämisen liikennevälineiden käyttäytymisestä, voidaan palvelua hyödyntää myös liikennesuunnittelussa. General Messaging Service (GM) palvelu on tarkoitettu yleisluontoisten tietojen kommunikointiin toimijoiden ja muiden virallisten osapuolten välillä. Palvelun avulla voidaan kommunikoida mm. liikennetiedotteita, poikkeustilanteita ja ajo-ohjeita toimijoiden ohjauskeskusten välillä. Palvelu on ikään kuin sähköposti, mutta luotettavampi ja määrämuotoisempi tapa viestiä. 3.3 Saatavat hyödyt SIRI-standardin hyödyntäminen määrittelyssä tarjoaa lukuisia etuja verrattuna siihen, jos suunniteltaisiin Suomea varten kokonaan omanlaisensa määrittely. SIRI on EU-standardi ja sen ovat suunnitelleet ammattilaiset, joilla on laaja asiantuntemus joukkoliikennejärjestelmistä ja rajapintojen suunnittelusta. SIRI on myös luotu avoimeksi standardiksi, joka perustuu avoimiin ja nykyaikaisiin XML ja Web Service perusteknologioihin. SIRI-standardia kehitetään myös jatkuvasti eteenpäin ja siihen on saatavissa tukipalveluita. Koska SIRI-standardi on otettu käyttöön monessa maassa, voidaan sen olettaa olevan melko toimiva ja luotettava ratkaisu myös käytännössä. Koska standardi on otettu käyttöön muissa maissa, voidaan siihen olettaa myös löytyvän valmiita ohjelmistokomponentteja ja käyttöönottoon liittyvää osaamista. Tämä mahdollistaa kustannussäästöt. SIRI on modulaarinen arkkitehtuuri, joka voidaan ottaa käyttöön askeleittain. Tämä on siksi, koska SIRIn määrittelemistä palveluista voidaan toteuttaa omaan rajapintaan vain ne, joita oikeasti tarvitaan. Tämä säästää myös kustannuksissa, kun ei tarvitse toteuttaa koko SIRIrajapintaa. Lisäksi mainittakoon, että SIRI-rajapintaa voi helposti laajentaa omilla laajennuksilla. 15

16 SIRIssä on huomioitu hyvin myös sellaisia asioita kuten tietoturva, versiointi, käyttäjien autentikointi, pääsyoikeuksien hallinta, eri kommunikaatiomallit ja virhetilanteiden käsittely. Rajapinnan on kerrottu olevan lisäksi tehokas ja suunniteltu kestävään kovaa kuormitusta. Edellä mainitut asiat pitäisi pystyä huomioimaan myös itse suunnitellussa rajapinnassa, jos ei käytetä SIRIä. Tämä voi osoittautua vaikeaksi ja kalliiksi. SIRIn etuihin kuuluu myös se, että on jo olemassa laite/järjestelmätoimittajia, joilla on valmiita ohjelmistokomponentteja, jotka hyödyntävät SIRIä. Myös erilaisissa järjestelmäkilpailutuksissa voidaan hyödyntää SIRIä, kun määritellään, että tietyt tiedot on välitettävä SIRI-muotoisesti. Näin säästytään vaativilta määrittelytöiltä. 3.4 SIRIn määrittelydokumentti Seuraavassa on esitetty mitä osia SIRIn määrittelydokumentti sisältää ja miltä osin niitä kannattaa lukea. Määrittelydokumentti löytyy liitteestä 1. Osassa 1 (Context and framework) on kuvattu konteksti ja viitekehys sekä standardin taustatiedot, rooli ja käyttötarkoitus. Lisäksi osassa 1 selvitetään käytetyt termit, lyhenteet ja määritelmät. Osan 1 loppuosassa esitetään mahdollisia käyttötapauksia. Tästä osasta kannatta perehtyä käsitteisiin ja SIRIn käyttämään tietomalliin. Osassa 2 (Communications infrastructure) määritellään kommunikointiympäristö sisältäen tiedot XML-viestien eri kuljetustavoista sekä pyyntö/vastaus, julkaise/tilaa ja jakelu kommunikaatiomalleista. Tämä osa sisältää paljon hyödyllistä asiaa ja se kannattaa silmäillä läpi kokonaan. Osassa 3 (Functional service interfaces) on esitelty toiminnalliset palvelut. Kussakin luvussa on kuvattu yksityiskohtaisesti jokaisen palvelun toimintatapa. Tästä osasta kannattaa lukea ainoastaan luku 8 Stop Monitoring Service. Huom. SIRIn määrittelydokumenttia ei löydy suoraan SIRIn www-sivuilla, vaan se löytyy erilliseltä UkGovTalk sivustolla [2], jossa hallitaan Iso-Britannian sähköisen asioinnin standardeja. 3.5 Tietomalli ja viitekehys SIRIn tietomalli perustuu Euroopassa käytettyyn julkisen liikenteen tietomalliin, TRANSMODELiin (CEN TC, 278 ENV 12896), ja viitekehys puolestaan perustuu Iso- Britannialaiseen IFOPT-viitekehykseen (CEN/TS ). Viitekehyksellä tarkoitetaan tässä yhteydessä sitä miten eri toimijoiden linjat, pysäkit, ym. yksilöidään ja voidaan tunnistaa toisistaan. On huomioitavaa, että SIRIn viitekehysjärjestelmä on joustava ja se pystyy huomioimaan myös maakohtaiset piirteet. Ennusterajapintamäärittelyä varten voidaan laatia kokonaan oma Suomi-kohtainen viitekehys, jossa linjat, pysäkit ym. yksilöidään aivan omalla tavallaan. Tämä ajatus sopii hyvin kansallisen joukkoliikennerajapinnan määrittelyyn. 16

17 4 TEKNISIÄ YLEISOHJEITA 4.1 Taulukoiden tulkintaohjeet Myöhemmin kappaleissa on monessa kohdin käytetty seuraavanlaisia taulukoita kuvaamaan XML-elementtejä ja niiden sisältämiä tietueita. Taulukoissa on esitetty samoja tietoja kuin SIRImäärittelyn vastaavissa taulukoissa. Kunkin toteutettavan elementin kohdalta on taulukoissa selitetty jokaisen tietueen nimi, tarkoitus ja suositus kannattaako ao. tietuetta toteuttaa. Merkintä pakollinen tarkoittaa, että tietue on määritelty pakolliseksi SIRImäärittelydokumentissa. Jos pakollinen-merkintä puuttuu, niin tietueet ovat aina valinnaisia. Merkintä (R) tarkoittaa että tietuetta käytetään vain raideliikennettä kuvattaessa. Huom. Taulukoiden suositukset ovat vain suosituksia, ne eivät edellytä toimijoita toteuttamaan ennusterajapintojaan juuri näin. Toimijat ovat vapaita toteutuksissaan tukemaan tietueita myös aivan erilailla kuin tässä on ehdotettu. Toimijoiden suositellaan tukevan mm. sellaisia ylimääräisiä tietueita, joihin niillä on saatavilla helposti dataa. Tietue Selite Suositus Tietueen nimi Tietueen tarkoitus ja tulkinta (suomeksi) Pakollinen Jos tarvitaan (R) 4.2 Skeemojen käytöstä Seuraavassa on esitetty, miten käyttää rajapinnan määrittäviä skeematiedostoja, jotka löytyvät liitteestä WSDL:t Koska rajapinta toteutetaan web-palveluna, niin toteutus tulisi tehdä annettujen WSDLskeemojen pohjalta. Palvelukuvausdokumenteissa (WSDL) on määritelty Web Service - rajapintojen toimintatapa ja tarjottavat rajapintafunktiot. Palvelukuvausdokumenttiin liittyy sanomakuvausdokumentteja (XML Schema), joissa on määritelty välitettävät sanomat. Toteutettavaan rajapintaan liittyy kaksi WSDL-skeemaa: wsproducer.wsdl ja wsconsumer.wsdl. Näistä ensimmäisessä on kuvattu palvelinpään tarjoamat rajapintafunktiot. Jälkimmäisessä on kuvattu notify-tyyppiset rajapintafunktiot, joita asiakassovelluksen täytyy tukea, kun tietoja lähetetään syötteenä. Jälkimmäinen toteutetaan vain silloin, kun halutaan lähettää ennustetietoja asiakassovellukselle syötteenä (kun käytetään julkaise/tilaa-tapaa). Liitteessä 4 on havainnollistettu näiden kahden skeeman rakennetta. 17

18 Huom! Liitteestä 3 löytyy kahdet versiot skeemoista: SIRIn alkuperäiset wsproducer.wsdl ja wsconsumer.wsdl tiedostot että Logican tekemät versiot (wsproducer-riisuttu.wsdl ja wsconsumer-riisuttu.wsdl). Jälkimmäisistä on poistettu SM-palvelutyyppiin liittymättömät tai muuten epäolennaisiksi nähdyt rajapintafunktiot, joita ei ole tässä vaiheessa syytä toteuttaa. Suosittelemme käyttämään Logican tekemiä riisuttuja skeemoja XML Schemat Käytettäviin WSDL-tiedostoihin liityy myös joukko XML Schema tiedostoja. Skeemojen avulla on määritelty WSDL:issä lähetettävien sanomien rakenteet. Käytettävistä XML skeemoista tärkein on siri.xsd, jonka roolina on toimia kaikkien skeemojen pääskeemana. Se linkittää itseensä kaikki muut skeematiedostot (kts. include-lauseet). Kuva 4 näyttää SIRIn XML skeemojen väliset suhteet. Kuva 4: XML Schema tiedostot ja niiden väliset suhteet 4.3 Kommunikaatiomallit SIRI tarjoaa kaksi erilaista peruskommunikointimallia, joilla ennustepalvelin voi kommunikoida asiakassovelluksen kanssa. Näistä molemmat tavat suositellaan toteutettavaksi. SIRIn määrittelydokumentissa on kommunikaatiomalleista kerrottu osassa 2 luvuissa 5-8. Pyyntö/vastaus on perustapa, jossa asiakassovellus lähettää kyselyviestin ja palvelin vastaa siihen vastausviestillä. Tämä tapa tunnetaan myös request/response tapana. Pyyntöviesti on määritelty aina ServiceRequest-elementissä. Julkaise/tilaa on tapa, jossa asiakassovellus tilaa palvelimelta ennustetiedot jatkuva-aikaisena syötteenä. Tämä tapa tunnetaan myös publish/subscribe tapana. Syötteen tilaus tapahtuu siten, että asiakassovellus lähettää palvelimelle tilausviestin, josta tämä saa kuittauksen. 18

19 Tämän jälkeen palvelin alkaa lähettää ennustetietoa asiakassovellukselle ja jatkaa niin kauan kunnes tilaus raukeaa tai asiakassovellus lähettää peruutusviestin. Syötteen tilausviesti on määritelty aina SubscriptionRequest-elementissä. 4.4 Vastausviestin eri toimitustavat Eri kommunikaatiomallien lisäksi SIRI tarjoaa eri tapoja, millä ennusterajapinnasta vastausviesti voidaan toimittaa asiakassovellukselle. Vastausviesti voidaan toimittaa suorana toimituksena, noudettuna toimituksena tai osatoimituksena. Tässä määrittelyssä suositellaan toteutettavaksi vain suora toimitustapa. Kehittyneempiä toimitustapoja (noudettu toimitus, osatoimitus) ei suositella toteuttavaksi vielä tässä vaiheessa. Kaikki vastausviestit on määritelty aina Delivery-elementissä riippumatta onko kyseessä suora toimitus, noudettu toimitus vai osatoimitus. SIRI-määrittelyssä vastausviestien toimitustavoista on keskusteltu osassa 2 luvussa Sanomien rakenne Tässä kappaleessa on kuvattu lyhyesti käytettävien sanomien perusrakenne. Huom. Sanomien ympärille tulisi normaalisti lisäksi SOAP-protokollan mukainen kääre, mutta sitä ei ole tässä kuvattu Kyselyviesti Kaikki SIRI-sanomat, mukaan lukien kyselyviestit, käyttävät juurielementtinään Siriä. Ensimmäisenä sisempänä elementtinä on kyselyviesteissä aina ServiceRequest, joka sisältää jotain yleisiä tietueita ja yhden tai useamman xxxrequest-alielementin. Näissä on määritelty tarkemmin tiettyyn SIRI-palveluun kohdistuvat kyselyt. Esim. Jos kyselyviesti sisältää StopMonitoringRequest-alielementin, niin tällöin sanoma sisältää SM-palvelua koskevan kyselyn. ServiceRequest-elementti on dokumentoitu määrittelydokumentin osassa 2 kappaleessa Toteutettavassa rajapinnassa suositellaan tuettavan tästä elementistä vain pakollisia tietueita (RequestTimestamp, RequestorRef, xxxrequest). <Siri xmlns=" xmlns:xsi=" xsi:schemalocation=" version= 1.0 > <ServiceRequest> <RequestTimestamp> T09:30:47-05:00</RequestTimestamp> <RequestorRef>TRE-INFOSYSTEM</RequestorRef> <! ======= KYSELY 1 ======== > <xxxrequest version= 1.0 > </xxxrequest> 19

20 <! ======= KYSELY 2 ======== > <xxxrequest version= 1.0 > </xxxrequest> </ServiceRequest> </Siri> Tilausviesti Seuraavassa on esitetty SIRI-tilausviestien perusrakenne. Tätä viestiä käytetään, kun halutaan tilata rajapinnasta tietoja syötteenä. Tilausviestien rakenne on sama kuin em. kyselyviestienkin sillä erolla, että ServiceRequestin sijasta käytetään SubscriptionRequest-elementtiä. Elementin sisällä rajapinnalta pyydettävät tiedot määritellään samaisella xxxservicerequestelementillä. SubscriptionRequest-elementti on dokumentoitu SIRIssä kappaleessa Elementistä suositellaan tuettavan vain sen pakollisia tietueita (RequestTimestamp, RequestorRef, xxxsubscriptionrequest). <Siri xmlns=" xmlns:xsi=" xsi:schemalocation=" version= 1.0 > <SubscriptionRequest> <RequestTimestamp> T09:30:47-05:00</RequestTimestamp> <RequestorRef>HSL-SYSTEM</RequestorRef> <! ======= TILAUS 1 ======== > <xxxsubscriptionrequest> </xxxsubscriptionrequest> <! ======= TILAUS 2 ======== > <xxxsubscriptionrequest> </xxxsubscriptionrequest> </SubscriptionRequest> </Siri> Vastausviesti Seuraavassa on esitetty SIRI-vastausviestin rakenne. Samaa vastausviestiä käytetään sekä kysely- että tilausviesteillekin. Vastausviestissä tiettyjä SIRI-palveluja koskevat vastaukset ovat xxxdelivery-elementeissä (voi olla useita). ServiceDelivery on dokumentoitu määrittelydokumentissa osassa 2 kappaleessa ServiceDelivery-elementin tietueiden käytöstä on esitetty suositus tämän dokumentin kohdassa 5.5. <Siri xmlns=" xmlns:xsi=" xsi:schemalocation=" 20

21 version= 1.0 > <ServiceDelivery> <ResponseTimestamp> T09:30:46-05:00</ResponseTimestamp> <ProducerRef>HSL-PREDICTIONSERVICE</ProducerRef> <Status>true</Status> <! ======= VASTAUS 1 ======== > <xxxdelivery version= 1.0"> </xxxdelivery> <! ======= VASTAUS 2 ======== > <xxxdelivery version= 1.0"> </xxxdelivery> </ServiceDelivery> </Siri> 4.6 Käytettävä viitekehys Viitekehyksellä tarkoitetaan rajapinnassa käytettäviä tunnistekäytäntöjä, ts. minkälaisia yksilöiviä tunnisteita ja koodeja (viitteitä) käytetään joistain tärkeistä asioista kuten linjoista, pysäkeistä, reiteistä, ajosuunnista ym. Näitä tunnisteita käytetään välitettävissä viesteissä tietueiden arvoina. Seuraavassa on esitetty alustava ja ohjeellinen suositus tunnisteiden käytöstä ennusterajapinnassa. Esitettyä suositusta voidaan täydentää myöhemmin mahdollisen referenssitoteutuksen yhteydessä, kun tunnetaan tarkemmin tarpeelliset tunnisteet. Viitekehyksen ylläpidosta tulisi vastata perustettava Suomi-tasoinen koordinointiryhmä, jonka puoleen voisi kääntyä epäselvissä tilanteissa. Toimijat ja muut osapuolet Tässä suositellaan, että toimijat tunnistetaan niiden 2-3-kirjaimisten lyhenteiden avulla. Kirjoitetaan lyhenteet isoilla kirjaimilla. Esimerkiksi: HSL, VR, MH. Kaupungit SIRI suosittelee käyttämään kaupungeista helposti ymmärrettäviä lyhenteitä. Tässä suositellaan, että käytetään kaupungeista niiden vakiintuneita lyhenteitä: HKI, TRE, TUR, ESP jne. Suomessa tässä voidaan käyttää myös Kelan virallisempaa kuntakoodiluokittelua, josta löytyy kaikkien kuntien lyhenteet ja numeeriset koodit. 21

22 Pysäkit Tässä suositellaan, että pysäkit tunnistetaan toimijoiden omien tunnistekäytäntöjen mukaisesti. Mikäli rajapinnasta halutaan tarjota tietoja useamman toimijan pysäkeistä, tällöin joudutaan mahdollisesti käyttämään tunnisteissa toimijakohtaisia etuliitteitä esim. HKL-123, YTV-123. Pysäkkitunnuksina olisi mahdollista käyttää myös yhtenäisiä maanlaajuisia Digistop tunnuksia, mutta tätä ei suositella, koska vain harvat toimijat ovat ottaneet näitä tunnuksia käyttöönsä. Toistaiseksi lähes kaikki toimijat käyttää pysäkkikatoksissaan omia (lyhyitä) pysäkkitunnuksiaan. Linjat Käytetään tässä toimijoiden vakiintuneita tapoja tunnistaa linjat. On huomattavaa, että linjatunnisteessa voidaan joutua välittämään tarvittaessa myös tieto linjan tyypistä (metro, juna, raitiovaunu, paikallisbussi, vakio, pika), lähdön tunnisteesta (esim. autokierron tunniste, junanumero) tai reittivariantista, jotta linja voidaan yksilöidä riittävän hyvin. Ajosuunnat SIRI suosittelee, että käytetään liikennevälineiden ajosuunnista (linjoilla) lyhenteillä in (keskustaan päin), out (keskustasta poispäin), cw (myötäpäivään ympyrälinjalla) ja ccw (vastapäivään ympyrälinjalla). Epäselvissä tapauksissa, esim. poikittaislinjoilla, voidaan valita vapaasti kumpi suunta on in ja kumpi out. On huomattavaa, että Suomessa ei kuitenkaan käytetä normaalisti näitä lyhenteitä, vaan suunnat on useimmiten numeroitu. Liikennemuodot SIRI suosittelee, että liikennemuodoista käytetään seuraavia tunnisteita: air, bus, coach, ferry, metro, rail, tram. Rajapinnan käyttäjät Tässä rajapinnan käyttäjillä tarkoitetaan asiakassovelluksia, jotka hyödyntävät rajapintaa. Käyttäjätunnisteita tarvitaan mm. rajapinnan käytön valvonnassa ja virhetilanteiden selvittämisessä. Tässä suositellaan, että käyttäjistä käytettäisiin tunnisteita TOIMIJA- SOVELLUS (kaikki yhteen kirjoitettuna), jossa sovelluksella tarkoitetaan tietoja hyödyntävää järjestelmää. Esim. TRE-Reittiopas, TKU-StopDisplaySystem. Lähdöt ja vuorot Tässä suositellaan, että lähdöt ja vuorot tunnistetaan toimijoiden omien tunnistekäytäntöjen mukaisesti.. Esim. VR:llä tämä perustuu junanumeroon ja Tampereella autokierron numeroon. 22

23 4.7 Päivä- ja aikaformaatit SIRI määrittelee että kaikki päivämäärät ja ajat kyselyviesteissä ja vastausviesteissä esitetään ISO 8601 aikaleimoina. Esimerkki tämmöisestä aikaleimasta on T18:39:00+01:00. Aikaleimoissa ajat ovat siis aina UTC-aikoja. Kts. SIRI-määrittely Virhetilanteiden hallinta Toteutuksessa on tärkeää noudattaa SIRI-määrittelyn mukaista virhetilanteiden hallintaa, joka parantaa palvelun palvelutasoa. Virhekoodi tai muu virhekuvaus on käyttäjän ja ylläpitäjän kannalta tärkeää saada, jos tämä on esim. lähettänyt virheellisen kyselyn tai palvelin on virhetilassa. Virhetilanteessa käyttäjälle on annettava taulukon 3 (SIRI 2-5.7) mukainen virhekoodi. Taulukossa 3 virhekoodit on jaettu kahteen luokkaan: järjestelmätason virheisiin ja sovellustason virheisiin. Järjestelmätason virhe on, jos esim. palvelimelle lähetetty viesti on syntaktisesti virheellinen. Järjestelmävirheistä pitää käyttäjälle antaa virhekoodi aina HTTP-vastauksen otsakkeen vastauskoodissa. Lisäksi käyttäjälle voidaan antaa sanallinen kuvaus virhetilanteesta. Järjestelmävirheinä käytetään 400-alkuisia HTTP-virhekoodeja. Sovellusvirhe on esim. jos käyttäjä lähettää sellaisen SIRI-palvelun kyselyviestin, jota palvelin ei tue. Sovellustason virheitä ei anneta HTTP-vastauksen virhekoodina, vaan SIRI-vastauksen sisällä ServiceDelivery tai xxxservicedelivery-elementeissä. Tällöin käytetään elementtien määrittelyissä määriteltyjä virheitä kuvaavia elementtejä. Taulukon 3 sovellusvirheiden koodeja ei (ilmesesti) tarvitse käyttää missään. Huom! SOAP-viestien fault-elementtejä ei tarvitse käyttää SIRI-virheiden ilmaisuun, koska virheet ilmaistaan edellä mainitusti kuljetettavassa XML-rakenteessa. 4.9 Palvelimen kyvykkyyksien selvittäminen Rajapinnan käyttäjän kannalta on varsin hyödyllistä, jos tämä voi kysyä rajapinnalta mitä SIRIpalveluja se tukee ja mitä tietoja vastausviesteissä voidaan välittää. Tästä käytetään SIRImäärittelyssä nimitystä palvelimen kyvykkyyksien selvittäminen. SIRIssä on palvelimen kyvykkyyksien selvittämistä varten oma CapabilityRequest-niminen viestityyppi. Tällä viestityypillä rajapinnan käyttäjä voi monipuolisesti selvittää mitä palveluja on tarjolla ja mitä tietueita kysely- ja vastausviestit tukee. Tämän viestityypin toteuttaminen on hyvin suositeltavaa. CapabilityRequest-viestityyppiin liittyvät elementit ovat kuvattu tämän dokumentin kappaleissa 5.1, 5.2, 5.3 ja 5.4 Kyvykkyyksien selvittämisestä on kerrottu lisää SIRI-määrittelydokumentin osassa 2 kappaleessa 5.10 sekä luvussa

24 5 YHTEISIÄ ELEMENTTEJÄ Tässä luvussa on kuvattu joitain SIRIn elementtejä tai elementtiryhmiä, joita käytetään kysely/vastausviestien perusosissa tai jotka ovat yhteisiä eri SIRI-palveluille. Nämä elementit ovat kuvattu tässä siksi, että niihin voidaan viitata muualta tästä dokumentista. 5.1 CapabilityRequest Tämä viesti lähetetään palvelimelle, kun halutaan tietoja sen kyvykkyyksistä. Tämä elementti on kokoojaelementti, joka sisältää yleisiä tietoja sekä yhden tai useamman xxxcapabilityrequest-elementin. Näillä elementeillä kysytään tarkemmin yksittäisten SIRIpalveluiden kyvykkyyksistä. Seuraavassa on esitetty miten SIRIn osan 2 taulukkoa 37 on syytä tulkita. Tietue Selite Suositus RequestTimestamp Kyselyn lähetysaika Pakollinen Address Verkko-osoite, johon vastaus halutaan lähetettävän, jos ei sama RequestorRef Asiakassovelluksen tunniste Pakollinen MessageIdentifier Asiakassovelluksen tälle viestille antama tunniste xxxcapabilityrequest Johonkin tiettyyn SIRI-palveluun liittyvä kyvykkyyspyyntö. Tähän voi tulla (toistaiseksi) vain StopMonitoringCapabilityRequest-elementtejä. 5.2 xxxcapabilityrequest Tämä elementti on aina CapabilityRequestin alielementti ja sillä kysytään kyvykkyystiedot tarkemmin tietystä SIRI-palvelusta. Seuraavassa on esitetty miten SIRIn osan 2 taulukkoa 38 on syytä tulkita. Tietue Selite Suositus Version (attrib.) SIRI-palvelun versio, jota käytetään (pitäisi olla aina 1.0) Pakollinen RequestTimestamp Kyselyn lähetysaika Pakollinen MessageIdentifier ParticipantPermissions Asiakassovelluksen tästä kyselystä käyttämä tunniste Halutaanko vastaukseen tiedot kyvykkyyksien lisäksi palvelun käyttöoikeuksista 24

25 5.3 CapabilityResponse Tällä elementti toimii vastausviestinä lähetettyyn CapabilityRequest-kyvykkyyspyyntöön. Elementti on kokoojaelementti, joka sisältää yleistietoja sekä yhden tai useamman xxxcapabilityresponse-elementin. Näissä elementeissä on tarkemmin tiedot tiettyjen SIRIpalveluiden kyvykkyyksistä. Seuraavassa on esitetty miten SIRIn osan 2 taulukkoa 37 on syytä tulkita. Tietue Selite Suositus ResponseTimestamp Vastauksen aikaleima Pakollinen ProducerRef Tämän ennustepalvelimen tunniste Address Verkko-osoite, johon vastaus lähetettään, jos ei sama kuin kyselyn lähetysosoite ResponseMessageIdentifier Tämän viestin tunniste RequestMessageRef Kyselyviestin tunniste, johon tämä viesti vastaa xxxcapabilityresponse Tiedot tarkemmin jonkin tietyn SIRI-palvelun kyvykkyyksistä. Tähän voi tulla toistaiseksi vain StopMonitoringCapabilityResponse-elementtejä. 5.4 xxxcapabilityresponse Tämä elementti on CapabilityResponsen alielementti ja se pitää sisällään kyvykkyystiedot tarkemmin tietystä SIRI-palvelusta. Seuraavassa on esitetty miten SIRIn osan 2 taulukkoa 40 on syytä tulkita. Suositus-sarakkeissa (-> xx) merkintä tarkoittaa, että tietueen arvona on syytä käyttää ao. arvoa. Tietue Selite Suositus Version (attrib.) SIRI-palvelun versio, jota käytetään (pitäisi olla aina 1.0) Pakollinen (-> 1.0) ResponseTimestamp Tämän elementin luontiaika Pakollinen RequestMessageRef Kyselyviestin xxxcapabilityrequest-elementin tunniste, johon tässä vastataan. Status Onko vastaus ehjä, ts.se ei sisällä virheitä ErrorCondition Virheen tiedot (jos virheellinen vastaus) Jos tarvitaan xxxservicecapabilities Tiedot tarkemmin jonkin tietyn SIRI-palvelun kyvykkyyksistä. Tähän voi tulla toistaiseksi vain StopMonitoringCapabilities-elementtejä. Pakollinen GeneralInteraction Kokoojaelementti, yleinen kommunikaatio Interaction Kokoojaelementti, kommunikaatiomallit Pakollinen 25

26 RequestResponse PublishSubscribe Tuetaanko pyyntö/vastaus kommunikaatiomallia Tuetaanko julkaise/tilaa kommunikaatiomallia Pakollinen (-> true) Pakollinen (-> true) Delivery Kokoojaelementti, viestien mahdolliset toimitustavat Pakollinen DirectDelivery FetchedDelivery MultipleSubscriberFilter HasConfirmDelivery HasHeartBeat VisitNumberIsOrder Tuetaanko suora toimitus -tapaa Tuetaanko noudettu toimitus tapaa Tuetaanko MultipleSubscriberFilter -suodatustapaa Tuetaanko taattuja viestien toimituksia Lähettää palvelin elossaolosignaalia Kuvaako MonitoredCall-elementin visitnumber tietue pysäkin järjestysnumeroa reitillä Pakollinen (-> true) Pakollinen (-> false) Pakollinen (-> false) Pakollinen (-> false) Pakollinen (-> false) (-> true) TransportDescription Kokoojaelementti, kuljetuskerrostason palvelut Communications TransportMethod CompressionMethod xxxcapabilitiesgroup xxxpermissions Käytettävä kuljetustapa Pakkaustapa viestien kuljetuksessa Tämä elementtiryhmä on yksilöllinen jokaiselle SIRI-palvelulle. Tähän voi tulla toistaiseksi vain StopMonitoringCapabilitiesGroup (kts. kappale 6.4) Tässä elementissä voidaan kertoa palveluun liittyvistä käyttöoikeuksista (vain jos pääsyoikeuksia käytetään) Pakollinen (-> wsdlsoap Rpc) Pakollinen (-> none) 5.5 ServiceDelivery Tämä elementti on kaikkien vastausviestien perusosa. Elementin tarkoitus on toimia kokoojaelementtinä, joka sisältää yleisiä viestin toimitukseen liittyviä tietoja sekä xxxservicedelivery-rakenteen, jossa on itse tiettyä SIRI-palvelua koskeva vastaus. Seuraavassa on esitetty miten määrittelydokumentin osan 2 kappaleen taulukkoa 12 on suositeltavaa tulkita. Tietue Selite Suositus srsname Käytettävän koordinaatistojärjestelmän nimi, jos vastauksessa mukana paikkatietoja 26

27 ResponseTimestamp Tämän elementin luontiaika Pakollinen ProducerRef Tämän ennustepalvelimen käyttämä tunniste Address Kuittausviestien lähetysosoite, jos taatut toimitukset ovat käytössä ResponseMessageIdentifier Tämän vastausviestin yksilöivä tunniste RequestMessageRef Kyselyviestin tunniste (johon tässä vastataan) Jos tarvitaan Status ErrorCondition CapabilityNotSupported Error OtherError Description MoreData xxxdelivery Onko vastaus ehjä, ts.missään alielementissä ei virheitä (true false) Tähän elementtiin tulee tiedot koko kyselyviestiä koskevasta virheestä (jos sellaista on) Tätä virhetyyppiä tulee käyttää jos palvelimelle lähtetetään sellaisen SIRI-palvelun kyselyviesti, jota ei tueta Tätä virhetyyppiä käytetään, jos kyseessä on jokin muu (sovellustason) virhe kuin edellä mainittu Tässä voidaan halutessa kuvata tapahtunutta virhettä. Tätä kannatta käyttää etenkin OtherErrorin tapauksessa Jos käytetään moniosaista lähetystapaa, tässä voidaan ilmoittaa että palvelimella on vielä dataa Tähän tulee yksi tai useampi palvelukohtainen delivery-rakenne (esim. StopMonitoringDelivery) Pakollinen 5.6 xxxdeliverygroup Tätä yhteistä elementtiryhmää käyttävät kaikki xxxdelivery-elementit (mm. StopMonitoringDelivery). Seuraavassa on esitetty, miten määrittelydokumentin osan 2 kappaleen taulukkoa 13 on suositeltavaa tulkita. Tietue Selite Suositus ResponseTimestamp Tämän elementin luontiaika Pakollinen RequestMessageRef SubscriberRef SubscriptionRef Kyselyviestissä olevan xxxservicerequest-elementin tunniste (johon tässä vastataan) Tilaajan tunniste. Tämä vaaditaan kun tilataan tietoja syötteenä. Tilaajan tekemän tilauksen tunniste. Tämä vaaditaan kun tilataan tietoja syötteenä. Status Onnistuiko kyselyn prosessointi ilman virheitä 27

28 ErrorCondition Jos kysely on virheellinen, on tässä elementissä annettava käyttäjälle oikea virhekoodi. Kts. käyttö SIRI taulukko 13. Virheiden käsittelystä kerrottiin aikaisemmin kappaleessa 4.8 Pakollinen ValidUntil Mihin asti tämän elementin tiedot ovat voimassa Jos tarvitaan ShortestPossibleCycle Lyhin aikaväli, jolla palvelin voi lähettää päivityksiä asiakkaalle (kun lähetetään syötteenä) 5.7 JourneyPatternInfoGroup Tällä elementtiryhmällä voidaan antaa lisätietoja liikennevälineen ajamasta linjasta. Tätä elementtiryhmää käytetään mm. SM-palvelutyypin MonitoredVehicleJourney-elementissä. Seuraavassa on esitetty, miten määrittelydokumentin osan 2 kappaleen 12.4 taulukkoa 51 suositellaan tulkittavan. Tietue Selite Suositus JourneyPatternRef VehicleMode Normaalisti ajettavan reittityypin koodi, jos sellaista on Liikennemuoto (air bus coach ferry metro rail tram) (jos toimijalla useita liikennemuotoja RouteRef Nyt ajettavan reitin koodi, jos sellaista on PublishedLineName Matkustajalle esitettävän linjan nimi (jos linjan nimi eri kuin LineRef) DirectionName Suunnasta käytettävä tekstimuotoinen kuvaus ExternalLineRef Vaihtoehtoinen linjakoodi (esim. toimijan sisäisesti käyttämä koodi) 5.8 VehicleJourneyInfoGroup Tällä elementtiryhmällä kuvataan liikennevälineen (tällä hetkellä) ajaman reitin tietoja. Tällaisia tietoja ovat mm. liikennevälineen lähtöpaikkaan, määränpäähän ja via-pisteisiin liittyvät tiedot. Tätä elementtiryhmää käytetään mm. SM-palvelutyypin MonitoredVehicleJourney-elementissä. Seuraavassa on esitetty, miten määrittelydokumentin osan 2 kappaleen 12.3 taulukkoa 50 suositellaan tulkittavan. Tietue Selite Suositus ServiceInfoGroup -> kts. kappale 5.10 Tällä elementtiryhmällä voidaan kuvata tarjottavaan liikennepalveluun liittyviä ominaisuuksia OriginRef Lähtöpysäkin koodi Jos tarvitaan 28

29 OriginName Lähtöpysäkin nimi Jos tarvitaan OriginShortName Lähtöpysäkin lyhyt nimi Via Kokoojaelementti, via-piste Jos tarvitaan PlaceRef Via-pysäkin koodi Jos tarvitaan PlaceName Via-pysäkin nimi Jos tarvitaan PlaceShortName Via-pysäkin lyhyt nimi DestinationRef Määränpään koodi Jos tarvitaan DestinationName Määränpään nimi Jos tarvitaan DestinationShortName Määränpään lyhyt nimi VehicleJourneyName Reitin kuvaus Jos tarvitaan JourneyNote Reittiin liittyvä huomautus HeadwayService Onko kyseessä kiinteillä väleillä ajettava linja OriginAimedDepartureTime DestinationAimedArrivalTime Aikataulun mukainen lähtöaika päätepysäkiltä Aikataulun mukainen saapumisaika päätepysäkille 5.9 JourneyProgressInfoGroup Tällä elementtiryhmällä voidaan kuvata liikennevälineen status-tietoja ja edistymistä sen ajamalla reitillä. Tätä elementtiryhmää käytetään mm. SM-palvelutyypin MonitoredVehicleJourney-elementissä. Seuraavassa on esitetty, miten määrittelydokumentin osan 2 kappaleen 12.6 taulukkoa 53 suositellaan tulkittavaksi. Tietue Selite Suositus Monitored MonitoringError Onko liikennevälineestä käytettävissä reaaliaikatietoa (true false) Tähän voidaan käyttää selitettä jos edellisen kohdan arvo on false InCongestion Onko liikenneväline ruuhkassa InPanic Onko liikennevälineen hälytys (?) kytketty päälle PredictionInaccurate Onko ennustetiedot epätarkkoja DataSource Reaaliaikadatalähteen nimi ConfidenceLevel Toimitettavan datan luottamuksellisuustaso VehicleLocation Liikennevälineen paikkatiedot (sijainti) Bearing Liikennevälineen tämän hetkinen ajosuunta 29

30 ProgressRate Liikennevälineen edistymistaso sen reitillä Occupancy Liikennevälineen täyttöaste Delay Liikennevälineen viive ProgressStatus Vapaamuotoinen teksti liikennevälineen edistymisestä reitillä, ei näytettävä tieto 5.10 ServiceInfoGroup Tällä elementtiryhmällä voidaan kuvata tarjottavaan liikennepalveluun liittyviä ominaisuuksia. Tätä elementtiryhmää käytetään mm. VehicleJourneyInfoGroup-elementissä. Seuraavassa on esitetty, miten SIRIn osan 2 kappaleen 12.2 taulukkoa 49 suositellaan tulkittavan. Tietue Selite Suositus OperatorRef Tämän palvelun tarjoavan toimijan tunniste ProductCategoryRef ServiceFeatureRef VehicleFeatureRef Mihin tuotekategoriaan liikennepalvelu kuuluu (pikavuoro, paikallisvuoro tms.) Tässä voidaan listata liikennepalveluun liittyviä ominaisuuksia (koulubussi tms.) Tässä voidaan listata liikennevälineen ominaisuuksia (onko matalalattiabussi tms.) Vain jos halutaan Vain jos halutaan Vain jos halutaan 30

31 6 STOP MONITORING SERVICE (SM) Tämä luku on ohje siitä, miten SIRIn Stop Monitoring (SM) -palvelu suositellaan toteutettavan. SM-palvelussa määritellään yksinkertainen rajapinta, jonka kautta pysäkkien/asemien näyttötauluille voidaan välittää niiden tarvitsemiaan tietoja. 6.1 Yleistä Tämän palvelutyypin mukaisen rajapinnan toteuttaminen edellyttää perehtymistä SIRIn määrittelydokumenttiin. Yleisiä ohjeita toteutuksen kannalta löytyy osista 1 ja 2, joihin kannattaa perehtyä. SM-palvelutyypin tarkka toteutusohje löytyy osasta 3 luvussa 8 Stop Monitoring Service. Seuraavissa kappaleissa on esitetty tämän palvelutyypin sisältämät viestityypit SIRImäärittelydokumentin mukaisesti. Kappaleissa jokainen viestityyppi on esitelty lyhyesti sekä kuvattu sen sisältämät tietueet. Taulukoissa suositussarakkeissa on kerrottu suositellaanko ao. tietueen tukemista toteutusvaiheessa. Suositukset vastaavat perustason toteutusta, johon kuuluvat vain kaikista olennaisimmat tiedot. Tähän perustasoon on arveltu suurimman osan toimijoista pystyvän kohtuullisella vaivalla. On tärkeää huomata että tässä kappaleessa annetaan vain suosituksia, se ei siis määrää että juuri näin tulee toimia. Toimijat voivat halutessaan tukea myös suurempaa tai pienempää joukkoa tietueita. Esim. jos toimijalla on paljon valmista dataa saatavilla, sen suositellaan tukevan SIRIn niitä vastaavia tietueita, vaikka niitä ei olekaan tässä suositeltu. 6.2 StopMonitoringCapabilitiesGroup Tätä elementtiryhmää käytetään kuvaamaan tämän SIRI-palvelun kyvykkyydet. Tietojen avulla rajapinnan käyttäjä saa selville mitä tietoja rajapinta tarjoaa tämän palvelutyypin osalta. Tämä elementtiryhmä palautetaan xxxcapabilityresponse-elementissä (kts. kappale 5.4 ). Seuraavassa on esitetty, miten määrittelydokumentin osan 2 taulukon 31 tietoja on suositeltavaa tulkita. Tietue Selite Suositus TopicFiltering Kokoojaelementti, tietojen suodatusmahdollisuudet DefaultPreviewInterval FilterByMonitoringRef FilterByLineRef Oletusseurantaväli, ts. kuinka pitkälle (minuutteina) ennusteita palautetaan oletusarvoisesti Voidaanko kyselytuloksia suodattaa pysäkkikoodien perusteella Voidaanko tuloksia suodattaa linjakoodien perusteella Pakollinen (-> P30M) Pakollinen (-> true) Pakollinen (-> true) 31