Avtale om Digitale Tjenester v. 2.1

Beskrivelse av den tilbudte tjenesten 👁‍🗨

Denne avtalen regulerer utvekslingen av data mellom en Tjenesteyter, som regel et operatørselskap for mobilitetstjenester, og Ruter As (heretter kalt Tjenestemottaker), som er administrasjonsselskap for mobilitetstjenester i Oslo-regionen.

Tjenestemottaker har en Digital Plattform (RDP), hvor det produseres aggregerte tjenester for brukerne av mobilitetstilbudet. Disse tjenestene baserer seg på data fra kjøretøy/fartøy og mobilitetskunder. Tjenesteyter har ved inngåelse av en Transporttjenestekontrakt (TTK) forpliktet seg til å levere data i henhold til Avtale om Digitale Tjenester. For at Tjenesteyter og Tjenestemottaker i samarbeid skal kunne produsere best mulig tjenester, regulerer denne avtalen kvalitetskrav til dataproduksjonen/-utvekslingen mellom Tjenesteyter og Tjenestemottaker.

Ruters Avtale om Digitale Tjenester er gjenstand for oppgraderinger i henhold til et versjonerings regime. Tjenestemottaker ønsker å motivere Tjenesteytere til å oppgradere til nyere versjoner i takt med Ruters egne versjonslanseringer.

Tjenesteyter forplikter seg til å kople seg til Ruters digitale tjenester slik som de er beskrevet her på enten siste eller nest siste major versjon, men står selv fritt til å bestemme migrasjonstakten. For eksempel kan flåten migreres til nyere avtale-versjon kjøretøy for kjøretøy, depot for depot, eller alt på én gang. Avtaleforpliktelsene gjelder per kjøretøy ut fra den avtale-versjonen som kjøretøyet til enhver tid har jobbet mot.

Tjenestemottaker kan velge å gi ut nye minor versjoner av avtalen og tilhørende dokumentasjon for å ivareta nye leveranseavtaler som inkluderer f.eks. nye kjøretøy klasser eller funksjoner. Minor versjoner forplikter ikke Tjenesteytere som leverer på tidligere versjoner av ADT. Tjenesteyter kan selv velge å implementere en minor versjon hvis ønskelig. Hvis ikke annet er oppgitt er det rimelig å anta at ny funksjonalitet i en minor versjon vil bli inkludert i en major versjon på et senere tidspunkt.

Versjonshåndtering ved oppstart og versjonsoppgraderinger er nærmere beskrevet i egne avsnitt.

Inneværende avtale dekker API v2.1

Kontaktpunkter

Alle feilmeldinger og annen teknisk kontakt skal rettes til rdp-support@ruter.no.

Alle Tjenesteytere må, som del av utført SIT-test, innrapportere en tilsvarende kontaktadresse til Tjenestemottaker.

Tjenesteyter forplikter seg til enhver tid å sørge for at Tjenestemottaker har korrekt kontaktinformasjon både for tekniske henvendelser og henvendelser relatert til oppfølging av denne avtalen.

Løsningsarkitektur

Open

Tjenesteyter og Tjenestemottaker

Datakommunikasjon

Sanntidsdata mellom Tjenesteyter og -mottaker bruker i hovedsak en felles infrastruktur for utveksling av sanntidsdata til og fra kjøretøy/fartøy. MQTT-data passerer gjennom Tjenestemottakers MQTT-server, og tjenestekvaliteten måles umiddelbart bak denne. For å holde forsinkelse av dataleveranse og feil i datatransport lav ønsker og anbefaler Tjenestemottaker færrest mulig ledd mellom kjøretøyets/fartøyets og Tjenestemottakers MQTT-broker.

Tjenestemottakers applikasjon RuterSalg gjør i tillegg et antall REST-kall mot baksystem hos Tjenestemottaker og dennes underleverandører.

Tjenestemottakers DPI-applikasjon skal ha tilgang til nedlasting av statiske filer fra Tjenestemottakers CDN. Se nærmere beskrivelse under «Spesielle krav til DPI».

Maskinvare

All maskinvare, installasjoner og tjenesteproduksjon ombord i kjøretøy/fartøy, skal være i henhold til spesifikasjonene i ITxPT. Utstyr og tjenester skal ha bestått godkjenning og være utstyrt med ITxPT-merking i henhold til prosessen beskrevet under https://itxpt.org/technology/itxpt-labeling/.

For noe utstyr som ikke er helt eller delvis omfattet av ITxPT standarden kan spesielle krav til maskinvare være beskrevet i denne avtalen under egne punkter.

Dataelementer

Sanntidsdata 👁‍🗨

De aller fleste dataemnene som ønskes overført i sanntid over MQTT, er hentet fra ITxPT sin emnestruktur. Enkelte emner er imidlertid Ruter-spesifikke. Dokumentasjon av API-et er beskrevet i eget versjonert dokument.

API v2.1

Plandata for turer og vognløp

Det er svært viktig at dataintegriteten mellom Tjenesteyter og Tjenestemottaker er så høy som mulig. Begge parter skal derfor synkronisere rute- og vognløpsdata til sine operative systemer fra Tjenestemottakers operative ruteplandatabase hver gang det er publisert en endring. Data publiseres på NeTEx (planlagte data) og SIRI ET (akutte endringer)-format. Identifikatorer for vognløp, tur og turmønster skal ikke manipuleres.

Merk at dette ikke er det samme datasettet som er brukt i forbindelse med planlegning av rutetilbudet mellom Tjenesteyter og Tjenestemottaker. Utenom Vognløpsnummer kan ingen referanser brukt i planleggingsfasen regnes som korrekte.

SIRI-ET i henhold til norsk SIRI profil: Nordic SIRI Profile

NeTEx i henhold til nordisk NeTEx profil: Nordic NeTEx Profile

Spesielle krav til Salg/billettering 👁‍🗨

Tjenestemottaker kjører sitt eget system for billettsalg og validering av reiserett ombord. Hvilke krav som gjelder den enkelte funksjonskategori beskrives i følgende tabeller:

Tekniske krav - RuterSalg Standard

• Salgsenheten skal benytte Android operativsystem, versjon 7.0 eller nyere

• Oppgradering til nyere versjon av operativsystem skal utføres når oppdragsgiver har behov for dette, senest innen tretti (30) virkedager fra dato oppdragsgiver melder slikt behov

• Salgsenheten skal ha innbygd støtte for å kjøre applikasjoner

• Salgsenheten skal ikke kjøre andre applikasjoner enn RuterSalg

• Salgsenheten skal kunne kommunisere med 4G-ytelse eller bedre

• Når oppdragsgiver produksjonssetter nye versjoner av RuterSalg-applikasjonen, skal enheten oppdateres med den nye versjonen innen ti (10) virkedager fra dato oppdragsgiver gir melding om at ny versjon er tilgjengelig

• Salgsenheten skal ha en ytelse tilsvarende AndroidPassmark score 2000 eller bedre

• I kjøretøyet/fartøyets kommunikasjonsgateway må det åpnes for kommunikasjon over internett fra RuterSalg-appen til Ruters baksystem

• Salgsenheten må ha en skjermstørrelse i området fra 7” til 10”

• NFC-enhet skal ha NFC-lese og -skrivekapabilitet, og må være kompatibel med ISO/IEC18092 standarden og ha support for MIFARE Desfire/Ultralight og ISO 14443 A/B kort

• Eksterne NFC enheter skal støtte konfigurerbar tilbakemelding til kunde

• Kvitteringsskriver må ha støtte for tilkobling av salgsenhet, og skal ha en utskriftshastighet på minimum 50 mm/sek og ha en papirstørrelse mellom 58 og 80 mm bredde

• Kvitteringsskriver skal støtte utskrifter av QR koder, Model 2 med Error correction level M

• Kvitteringsskriver skal ha støtte for Bluetooth 3.0 eller høyere

• Kvitteringsskriver skal støtte kansellering av utskrift

• Salgsenheten skal være dimensjonert for å minimum støtte tilkobling for ytterlige to periferienheter, som betalingsterminal eller liknende

Tekniske krav - RuterSalg Håndholdt

• Salgsenheten skal benytte Android operativsystem, versjon 7.0 eller nyere

• Oppgradering til nyere versjon av operativsystem skal utføres når oppdragsgiver har behov for dette, senest innen tretti (30) virkedager fra dato oppdragsgiver melder slikt behov

• Salgsenheten skal ha innbygd støtte for å kjøre applikasjoner

• Salgsenheten skal ikke kjøre andre applikasjoner enn RuterSalg

• Salgsenheten skal kunne kommunisere med 4G-ytelse eller bedre

• Når oppdragsgiver produksjonssetter nye versjoner av RuterSalg-applikasjonen, skal enheten oppdateres med den nye versjonen innen ti (10) virkedager fra dato oppdragsgiver gir melding om at ny versjon er tilgjengelig

• Salgsenheten skal ha en ytelse tilsvarende AndroidPassmark score 2000 eller bedre

• Hvis enheten benytter kjøretøyet/fartøyets kommunikasjonsgateway for kommunikasjon over internett fra RuterSalg-appen til Ruters baksystem

• Salgsenheten må ha en skjermstørrelse i området fra 5.5” til 7”

• NFC-enhet skal ha NFC-lese og -skrivekapabilitet, og må være kompatibel med ISO/IEC18092 standarden og ha support for MIFARE Desfire/Ultralight og ISO 14443 A/B kort

• Kvitteringsskriver må ha støtte for tilkobling av salgsenhet, og skal ha en utskriftshastighet på minimum 50 mm/sek og ha en papirstørrelse mellom 58 og 80 mm bredde

• Kvitteringsskriver skal støtte utskrifter av QR koder, Model 2 med Error correction level M

• Kvitteringsskriver skal ha støtte for Bluetooth 3.0 eller høyere

• Kvitteringsskriver skal støtte kansellering av utskrift

• Salgsenheten skal være dimensjonert for å minimum støtte tilkobling for ytterlige to periferienheter, som betalingsterminal eller liknende

Funksjonstest RuterSalg

Før innfasing av nye enheter for RuterSalg skal Tjenesteyter stille til rådighet for Tjenestemottaker en komplett fysisk testrigg av hver implementasjon, inkludert salgsenhet, skriver og kortleser.

Minumum 4 måneder før driftssetting skal testriggen ha gjennomgått en fullstendig funksjonstest med Tjenestemottaker. Funksjonstesten innebærer kontroll av at alle enheter fungerer i henhold til kravene. Hvis kravene ikke oppfylles, skal Tjenestetilbyder finne alternative enheter for godkjenning.

Spesielle krav til Dynamisk Passasjerinformasjon (DPI) 👁‍🗨

Tjenestemottaker kjører sitt eget system for DPI ombord. Følgende krav til kapabiliteter stilles:

Krav til skjermer

• Skjermen skal ha automatisk lysjustering ut fra omgivelsene

• Skjermen skal være ikke-reflekterende

• Skjermen skal ha en synsvinkel på 178 grader både horisontalt og vertikalt.

• Skjermen skal ha minimum oppløsning på 1920 piksler i bredden ved plassering i landskapsmodus, og minimum 1920 piksler i høyden ved plassering i portrettmodus.

• Alle skjermer må laste inn DPIs webapplikasjon og kjøre den i en nettleser, anbefalt av type Chrome/Chromium.

• Skjermplayeren må støtte følgende tekniske kapabiliteter:

  • HTML 5

  • CSS 3

  • ECMAScript 6

  • Websockets

  • Webworkers / Serviceworkers

  • HTML video i H.264-format opp til 1080P

  • Canvas / SVG

  • WebGL

  • IndexedDB

  • Local storage

• Alle data lagret av DPI-applikasjonen skal vedvare mellom restart og skal aldri slettes av en operatørprosess

• Skjermene må konfigureres med forhåndsdefinerte visninger tilpasset skjermens forholdstall (aspect ratio), funksjon og plassering

• Skjermene skal alltid vise den riktige skjermkonfigurasjonen ved oppstart

• Operatøren skal overvåke at playeren viser en html side levert av Ruter

• Operatøren skal laste inn applikasjonen på nytt om det skulle oppstå problemer

• Kjøretøyet skal ha en web-server ombord som skjerm-playerene kan laste inn DPI applikasjonen og annet statisk innhold fra

Oppdatering av statisk innhold

• DPI-applikasjonen skal holdes oppdatert når Tjenestemottaker publiserer nye versjoner av applikasjonen eller media-filene applikasjonen er avhengig av. Disse gjøres tilgjengelig som pakker i ZIP-format og blir beskrevet i en manifest-fil tilgjengelig på definerte URLer for produksjons-miljøet og pre-produksjonsmiljøet.

• Tjenesteyter skal regelmessig sjekke om nye versjoner av DPIs nedlastbare pakker er tilgjengelige i Tjenestemottaker produksjons-kanal

• Når nye pakker er tilgjengelige skal Tjenesteyter laste disse ned og påse at alle kjøretøyer har fått installert det nye innholdet innen de begynner å kjøre den påfølgende morgen

• Tjenesteyter skal validere at pakken er lastet ned riktig og pakket ut på riktig måte

• Minst 16 GB lagringsplass må være tilgjengelig for å lagre Tjenestemottakers innhold om bord på kjøretøyet

• Tjenesteyter skal laste ned planlagte nye versjoner fra en pre-prod kanal i et test-miljø og påse at versjonen testes før den settes i produksjon

Lydmeldinger

• Når kjøretøyet mottar en MQTT-melding med lydinnhold skal Tjenesteyter spille av lyden som kommer enten i OPUS- eller MP3-format

• Unntaksvis, hvis meldingen definerer en levetid som er forbi, må lydinnholdet ikke spilles

• Når en melding inneholder flere lydfiler må disse spilles av i rekkefølgen de forekommer i meldingen

• Behandling av MQTT-meldinger med lydinnhold skal skje synkront og nye meldinger spilles kun etter at de foregående er ferdigspilt

Spesielle krav til MQTT

Open

Arkitekturskisse for MQTT

• Alle Tjenesteyters kjøretøy/fartøy skal rute datatrafikken gjennom en MQTT broker med bridging mot Tjenestemottaker. Dataemner skal her oversettes mellom kjøretøyets/fartøyets lokale adresser og Tjenestemottakers globale adresser. Tjenestemottaker leverer en konfigurasjonsfil med disse oversettelsene for alle nødvendige dataemner.

• MQTT-broker skal kunne kommunisere med DPI-applikasjonen og RuterSalg-applikasjonen over Websockets.

• Kun MQTT versjon 3.1.1 og 5.0 er støttet av Tjenestemottaker

• All MQTT-kommunikasjon skal være kryptert med TLS v1.2

• All MQTT infrastruktur må spesifikt støtte bridging av meldinger med retain-flagg satt

Spesielle krav til Signalprioritering (TSP)

• Tjenestemottaker skal konsumere dataemnet pe/tsp og umiddelbart sende det 7 bits hex-kodede telegrammet på en VHF-sender i kjøretøyet i henhold til standarden VDV R09.16

• Frekvens 154.725000MHz

• Signalstyrke 1 W

• Modulasjon FFSK, 2400 baud

Krav til ytelses- og funksjonsnivå

Ytelses- og funksjonalitetskravene er utarbeidet for å sikre at Tjenestemottager kan levere sine verdier til sine kunder og eiere. Ved utarbeidelsen av ytelseskrav til tjenestene er følgende prinsipper fulgt:

• Kravene skal være mulig å oppfylle med standard teknologi og normale kvalitetsrutiner.

• Kravene skal baseres på Tjenestemottakers erfaringer fra innsamling av lignede data.

• Kravene skal tillate et normalt bortfall i forhold utenforliggende hendelser.

• Kravene skal ha handlingsrom for forbedring av tjenesten for Tjenesteyter.

• Kravene skal være målbare av både Tjenesteyter og Tjenestemottaker basert på utvekslede data.

• Kravene skal være begrunnet i forhold til verdien de har for Tjenestemottaker

Generelle krav til API-bruk

Alle dataemner beskrevet i API-dokumentet skal produseres av respektive Tjenesteyter eller Tjenestemottaker dersom annet ikke er oppgitt. Dokumentets avsnitt 1.4 List of topics beskriver denne ansvarsfordelingen. Tjenesteyter plikter å produsere alle dataemner, korrekt utfylt, merket med Producer: Vehicle.

Ytelsesnivåer

Tjenestemottakers transporttjenestekontrakter kan inneholde økonomiske insentiver som helt eller delvis kan basere seg på ytelsene definert i denne avtalen. Det er definert tre ytelsesnivåer som kan benyttes til å regulere insentiver.

• Absolutt: Dataemner som ved bortfall gjør det umulig å benytte andre dataemner og dermed fører til bortfall av digital kundeopplevelse.

• Kritisk: Dataemner som ved bortfall forringer digital kundeopplevelse sterkt, samt Ruters mulighet til å følge opp produksjonen.

• Normal: Dataemner som ved bortfall forringer digital kundeopplevelse uten at det går ut over Ruters mulighet til å følge opp produksjonen.

Alle ytelsesnivåene måles pr avgang. Hvis en avgang etterfølger en tomkjøring i sitt vognløp, inngår tomkjøringen i kravet til ytelsesnivå for avgangen. Altså stilles samme ytelseskrav til tomkjøringer som til ruteavganger.

Funksjonsnivåer 👁‍🗨

Enkelte oppdrag kan være av en art at Tjenestemottaker ikke ser det fordelaktig med leveranse på alle elementer i denne avtalen.

Tjenestemottakers transporttjenestekontrakter kan derfor inneholde en beskrivelse av hvilket funksjonsnivå hver enkelt kjøretøytype skal levere.

Hvis kjøretøyet skal levere flere funksjonstyper, skal kjøretøyet levere på alle dataemner til sammen beskrevet i funksjonsnivåtabellen

Tjenestemottakers transporttjenestekontrakter kan inneholde en beskrivelse av hvilke funksjonsnivåer som skal oppfylles. Komplette funksjonssett gjelder hvis ikke annet er definert.

Definisjoner

Kjøreoppdrag (Block): Et vognløp kan bestå av et eller flere kjøreoppdrag hvor kjøreoppdrag er en sammenhengende periode i tjeneste for Ruter som kan inneholde både tomkjøringer og avganger uten pauser imellom. Et typisk kjøreoppdrag strekker seg fra utkjøring fra depot til retur til depot men andre varianter kan finnes. 

Alle ovennevnte ytelsesmålinger og registreringer av brudd på avtalen fanges automatisk opp av Tjenestemottakers systemer med unntak av der det nevnes spesifikt at det ikke fanges.

Tjenesteyter vil selv kunne gjøre tilsvarende målinger for å verifisere Tjenestemottakers funn ved å logge datastrømmer i den felles MQTT-infrastrukturen eller om bord i kjøretøy/fartøy.

For brudd på krav som ikke har et definert ytelsesnivå kan Tjenestemottaker følge opp disse i henhold til andre avtaler/kontrakter som benytter seg av denne avtalen.

Godkjenning av dataprodusenter

Før et kjøretøy/fartøy kan starte sine dataleveranser til Tjenestemottakers produksjonsplattform, skal en sekvens av tester ha blitt gjennomført og godkjent, i riktig rekkefølge. Dette bidrar til å sikre gode og stabile tjenesteleveranser.

SIT (Site Integration Test)

Dette er den første testen som en Tjenesteyter må gjennomgå. Den skal i utgangspunktet kun utføres én gang per Tjenesteyter, og inneholder:

·         Testing av nettverkskonnektivitet mellom Tjenesteyter og Tjenestemottaker

·         Velformethet for MQTT-meldinger

Ved signifikante endringer i infrastruktur hos Tjenesteyter (bytte av IT-leverandør eller liknende) skal det utføres ny SIT.

CAT (Customer Acceptance Test)

CAT skal utføres for hver kjøretøytype som skal settes i produksjon, og forutsetter godkjent SIT. Testen utføres i samarbeid mellom Tjenesteyter og Tjenestemottaker, og skal kvalitetssikre at alle relevante data produseres og konsumeres om bord i denne kjøretøytypen.

VV (Vehicle Verification)

VV er en test som utføres av Tjenesteyter på hvert enkelt kjøretøy som skal gå i produksjon. Den forutsetter at kjøretøytypen er godkjent gjennom en CAT, og rapporteres i et onlineskjema som tilgjengeliggjøres av Tjenestemottaker.

Sanksjoner

Sanksjoner for brudd på avtalens ytelsesnivå kan defineres i Tjenestemottakers transporttjenestekontrakter.

Livssyklusforvaltning

Tjenesteyter har totalansvar for livssyklusforvaltning av utstyr, programvare og andre ytelser som er nødvendig for å opprettholde det til enhver tid avtalte tjenestenivå.

Tjenesteyteren skal aktivt sørge for at leveransen er tidsmessig i tiden fra driftssetting og gjennom hele kontraktsperioden.

Oppstart av ny leveranse 👁‍🗨

I forbindelse med oppstart av ny leveranseavtale hvor det er spesifisert at denne avtalen kommer til anvendelse vil det også være angitt minimumsversjonen som skal benyttes ved oppstart av leveransen. Tjenesteyter kan ikke velge og levere på et lavere versjonsnivå en angitt i leveranseavtalen. Dette er uavhengig om det er en major eller minor versjon som er oppgitt.

Endringsbestemmelser 👁‍🗨

Tjenesteyter forstår at den ytelse som leveres er dynamisk av natur. Det ligger innenfor avtalen at Tjenesteyter forplikter seg til å oppdatere sin plattform hver gang ny major versjon av API/plattform-versjon slippes fra Tjenestemottakers side. Dette avstedkommer intet krav på økt godtgjørelse med unntak for de situasjoner der en ny versjon krever vesentlig oppgradering av Tjenesteyters plattform uten at dette burde vært forutsett av Tjenesteyter.

Ved nye minor versjoner er Tjenesteyter ikke forpliktet til å levere på denne med unntak av når en ny leveranseavtale spesifiserer at dette er minimumsversjonen som kan benyttes eller at det er inngått en avtale utover leveranseavtalen som spesifiserer dette.