Innledning

Overordnet

Denne avtalen regulerer og beskriver Ruters krav til digitale tjenester i tilknytning til sin produksjon. Avtalen beskriver 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, og deler av Viken.

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 (ADT) er gjenstand for oppgraderinger i livsløpet til avtalen i henhold til et eget versjonshåndteringsregime. Tjenestemottaker ønsker å motivere Tjenesteytere til å oppgradere til nyere versjoner i takt med Ruters egne versjonslanseringer. Versjons- og livsløpshåndtering er beskrevet i eget kapittel.

Kontaktpunkt for avtalen

Alle feilmeldinger og annen teknisk kontakt skal rettes 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.

Beskrivelse av plattformen

Avtale om Digitale tjenester beskriver i denne versjonen i hovedsak leveranser av digitale tjenester for to varianter av persontransport. Rutesatt og bestillingstransport.

Rutesatt transport baserer seg i stor grad på planlagte oppdrag mellom faste punkter basert på tidtabeller.

Bestillingstransport er mer dynamisk av natur, og lar planlegges enten ad-hoc eller med kort tidshorisont.

Ruters digitale plattform støtter begge variantene, men kan benytte forskjellig type teknologi og grensesnitt.

Open

Open

Funksjonsnivåer

Noe forskjellig funksjonalitet mellom transporttypene og kjøretøykategoriene gjør det nødvendig å stille forskjellige krav til forskjellige kjøretøy. 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.

*) Funksjoner med spesialkrav utover det som er definert i ITxPT.

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 v. 3.x

Oppdrag og plandata

Plandata for rutesatte 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 (blocks) til sine operative systemer fra Tjenestemottakers operative ruteplandatabase hver gang det er publisert en endring.

Den operative plandatabasen er den autoritative kilden til produksjonssatt trafikk, og vil til enhver tid være oppdatert med plandata for de neste 10 dager. Det er Tjenesteyters ansvar å validere datasettets innhold mot sin produksjon.

Planlagte data publiseres på NeTEx-format i henhold til nordisk NeTEx profil: Nordic NeTEx Profile

API for den operative plandatabasen: https://adt.transhub.io/3.x/traffic-plan/

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. Den planleggingen er beskrevet nærmere i oppdragsbeskrivelsen og rutebeskrivelsen i kontrakten.

Utenom vognløpsnummer og turnummer kan ingen referanser brukt i planleggingsfasen regnes som korrekte. Vognløpsnummer ligger i Block > PrivateCode, og turnummer ligger i ServiceJourney > KeyValue i NeTEx-eksporten.

I fremtiden kan SIRI ET brukes til å publisere akutte endringer (ekstraoppdrag), men vi vil varsle aktuelle Tjenestetilbydere før grensesnittet tas i bruk.

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

Oppdrag for bestillingstransport

For funksjonskategoriene i bestillingstransport finnes det forskjellige måter å formidle data og oppdrag på. Funksjonsmatrisen beskriver de forskjellige varianter som er gyldige for hvilken type bestillingstransport.

Tjenestemottakers Førerapplikasjon

Tjenestemottaker publiserer oppdrag og kjørelister gjennom en forhåndsavtalt applikasjon.

Fører registrerer påbegynt oppdrag og de faktiske hente- og leveringstider.

Tjenesteyter skal til enhver tid ha avtalt versjon av applikasjon installert på sine enheter.

Spesielle krav til Førerapplikasjon vedlikeholdes i et vedlegg til denne avtalen.

Vedlegg - Oppdragsutveksling og rapportering

SUTI

For kjøretøy i funksjonskategori M2Y (B2B) vil all overføring av oppdrag, herunder avbestillinger, nye bestillinger og øvrige endringer gjennom hele døgnet fortløpende utveksles gjennom tjenestemottakers SUTI endepunkt.

Tjenesteyter skal fortløpende bekrefte og rapportere tilbake, gjennom samme grensesnitt, mottak av oppdrag, oppdrag tildelt løyve (bil) og de faktiske hente- og leveringstider, inkludert GPS-posisjon.

SUTI i henhold til beskrivelse på http://SUTI.se

SUTI selvdeklarasjon: https://ruter.atlassian.net/l/c/TPVdcuv8

Y2M (tjenesteYter2tjenesteMottaker)

Dette funksjonsnivået benyttes i konfigurasjoner hvor Tjenesteyter er den initierende parten i oppdragsutveksling og rapportering. Dette er typisk i kontrakter der Tjenesteyter selv sitter med bestillingsmottaket, enten direkte i kjøretøyet (praiing) eller gjennom eget kjørekontor.

Tjenestemottaker vil tilby Tjenesteyter grensesnitt både for oppslag og rapportering.

Grensesnittet kan benyttes både av tjenesteyters kjørekontor og ombord i kjøretøyet.

Ved bestilling gjennom Tjesteyters kjørekontor, kan Tjenesteyter gjøre oppslag på:

• Kundeinformasjon

• Antall tilgjengelige turer

• Egenandel, inkludert evt. oppnådd tak

Når kunde setter seg i bil, skal Tjenesteyter gjøre oppslag fra kjøretøyets takstameter og be om oppdaterte oppdragsdetaljer, i tilfelle dette har endret seg siden den opprinnelige bestilling.

Tjenesteyter initierer avtalt identifiseringsflyt med passasjer, som bekrefter turen på sin mobiltelefon. For spesielt skjermede passasjerer vil det utarbeides egne flyter som hensyntar dette.

Ved endt tur skal det – uten opphold – leveres rapporteringsdata som beskriver turen.

Nødvendige datafelter er beskrevet i beskrivelsen av grensesnittet.

https://ruter.atlassian.net/l/c/W96Rw2fE

Event Reporting API

Tjenesteyter vil få tilgang til et Event Reporting API for maskinell registrering av hendelser.

Kvalitetsproblemer som skyldes forhold utenfor tjenesteyters kontroll unntas gebyr dersom det registreres korrekt i Ruterlogg. Eksempler på slike forhold kan være at hele mobilnettet faller ut eller feil som skyldes tjenestemottaker. Forhold som må anses som normale gir ikke unntak for gebyr, f.eks. problemer med tjenesteyters IT-utstyr eller dårlig mobildekning på visse geografiske områder. Slike forhold er innarbeidet i ytelseskravene.

Hendelser der tjenesteyter påberoper seg fritak for gebyr, skal rapporteres korrekt inn til Event Reporting APIet, slik at det kan behandles maskinelt av Tjenestemottaker. Bruk av Event Reporting API er obligatorisk for operatørene i kategori “Rutesatt transport”, men valgfritt for operatørene i kategori “Bestillingstransport”.

Dette gjelder:

• Innstilte avganger

• Forsinkelser

• Brudd på datakvalitet

Krav til løsninger

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

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

For kjøretøy som kun betjener funksjonskategorier for bestillingstransport og/eller er definert som personbil tillates dataleveranser fra utstyr uten ITxPT-merking der tjenesteyter finner det formålstjenlig.

Spesielle krav til Salg/billettering

Spesielle krav til Salg/billettering vedlikeholdes i et vedlegg til denne avtalen.
Vedlegg – Krav Salg/Billettering

Spesielle krav til kortlesere for validering av reiserett

I kontrakter hvor det kravstilles validering av reiserett i andre posisjoner enn ved fører, er det behov for kortlesere.

Tjenestemottaker vil levere ferdigkonfigurerte kortlesere klare til førstegangsinstallasjon hos tjenesteyter.

Tjenesteyter skal besørge montering i henhold til vedlagt spesifikasjon, herunder både strøm og nettverk. Kortleserne skal ha tilgang til nødvendige endepunkter – både om bord, og backoffice.  

Tjenesteyter skal aktivt overvåke enhetene, både gjennom elektronisk overvåkning i tillegg til daglig visuell inspeksjon.

Tjenestetyter har ansvar for at alle avganger blir kjørt med det korrekte antall fungerende kortlesere.

Bytte av kortleser skal rapporteres inn til Tjenestemottaker så snart enheten er skiftet ut. Innmeldingen skjer elektronisk ved at Tjenesteyter melder inn byttet på webportal. Sammendrag fra innmeldt skjema skrives ut og klistres på defekt enhet, og legges i kasse for defekte deler på lager.

Tjenestemottaker sørger for at Tjenesteyter har tilgang på tilstrekkelig antall fungerende kortlesere til sitt reservedelslager, basert på Tjenesteyters løpende rapportere behov.

Tjenestemottakers valg av leverandør og/eller kortlesermodell vil kunne endres i løpet av avtalens løpetid.

Vedlegg – Ruters monteringsveiledning - Kortleser, v1.0

Spesielle krav til Dynamisk Passasjerinformasjon (DPI)

Spesielle krav til Dynamisk passasjerinformasjon vedlikeholdes i et vedlegg til denne avtalen
Vedlegg – Krav Dynamisk passasjerinformasjon

Spesielle krav til MQTT

For kjøretøy i funksjonskategorier omfattet av MQTT, skal alle Tjenesteyters kjøretøy/fartøy 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 både Websockets og standard MQTT protokoll.

• Kun MQTT versjon 5.0 er støttet av Tjenestemottaker for ADT 3.

• 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

• Broker skal konfigureres med støtte meldingsstørrelser opp til 4096 kB

Spesielle krav til lydsignal ved utløsning av stoppknapp

Tjenestemottaker tilgjengeliggjør en lydfil gjennom sin CDN. Tjenesteyter skal laste ned og benytte den til enhver tid publiserte filen som eneste lydvarsling i passasjerområdene.

Spesielle krav til passasjertelling (APT)

Sensorer som benyttes skal kategorisere av- og påstigende i kategoriene definert i gjeldende API-dokument.

Tjenestemottaker skal motta kategoriene BIKE, PRAM og WHEELCHAIR i tillegg til ADULT og CHILD.

For sensorer som benytter høyde som et element i kategoriseringen, definerer Tjenestemottaker følgende verdier:

Ytelseskrav til funksjonsnivåer

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 for veigående materiell og normale kvalitetsrutiner.

• Kravene skal baseres på Tjenestemottakers erfaringer fra innsamling av lignende 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.

• Kravene brukes til økonomiske incitamenter som skal belønne forbedringer av datakvaliteten.

• Ytelseskravene skal evalueres minst årlig og justeres dersom de ikke fungerer etter intensjonen, så lenge justeringen er i tråd med uttalt intensjon.

Generelle krav

Alle dataemner beskrevet i APIet skal produseres av respektive Tjenesteyter (PUB) eller Tjenestemottaker (SUB) dersom annet ikke er oppgitt. Tjenesteyter plikter å produsere alle dataemner, korrekt utfylt, merket med  PUB.

Tjenesteyter skal selv være i stand til å overvåke og måle kvalitet på leveransen av egne tjenester.

Tjenestemottaker kan ved behov gjøre tjenesteyter oppmerksom på elementer ved leveransekvaliteten som bør utbedres. Tjenesteyter skal undersøke årsak og utbedre de bakenforliggende elementene i henhold til nærmere avtalte frister. 

Ytelsesnivåer

Tjenestemottakers transporttjenestekontrakter kan inneholde økonomiske insentiver som helt eller delvis kan basere seg på ytelsene definert i denne avtalen.

Det er definert 3 ytelsesnivåer som kan benyttes til å regulere insentiver.

Intensjonen med ytelsesnivåene er å insentivere tjenesteyter til å fokusere på de viktigste dataemnene først, siden dataemnene på nivåene under har liten eller ingen verdi uten data på nivåene over.

Beregning av datakvalitet

Hvilke avganger måles

Operatøren definerer hvilke avganger den har som intensjon å betjene i signon-meldingen under “service-vinduet”. Det er disse avgangene som måles.

Eksempler

Dersom denne intensjonen senere endrer seg skal det sendes en oppdateringsmelding, som igjen endrer hvilke turer som blir målt.

Måleperiode for rutesatt transport

Mottak av signon definerer starten av en måleperiode.

Mottak av signoff definerer slutten av måleperioden.

Hele måleperioden har samme ytelseskrav. Det er flere grunner til det:

• Tidspunktene for når en ruteavgang faktisk begynte og sluttet beregnes basert på innsamlede data, slik at å basere målingene på dette vil være kompliserende.

• Data både før og etter ruteavgangene viktige for å kunne gi god kundeopplevelse og følge opp produksjonen.

Tjenestemottaker vil tilstrebe at ytelsen bare måles der det er relevant og at ytelseskravene for de ulike dataemnene tar høyde for operativt arbeid mellom ruteavganger.

Eksempel

Figuren under illustrerer et vognløp, en blokk og tre avganger.

Når kjøretøyet logger på og av på denne blokken, defineres service-vinduet på denne måten:

Hvis signoff ikke sendes slutter måleperioden 2 timer etter planlagt ankomst på siste holdeplass i intensjonen som er definert av service-vinduet:

Måling av assignment-tjenesten (gjelder rutesatt transport)

Se ytelseskravene i tabellen under.

Eksempler

Signon er mottatt under 20 minutter etter avgang fra første avgang og signoff er mottatt under 2 timer etter ankomst siste avgang. Alle avgangene er godkjent.

Signon som sendes mer enn 20 minutter etter planlagt avgang i turen godkjennes ikke.

Signon som sendes etter dette godkjennes ikke turene som er sendt for sent.

Måleperiodene brukes for å definere når de andre tjenestene måles. De måles over hele perioden og gjelder for alle turene definert av service-vinduet.

Måleperiode for bestillingstransport

Datakvaliteten måles per planlagt blokk. Fra planlagt start av innleietid til planlagt slutt av innleietid, eller siste registrerte pull-in hvis den er etter avtalt slutt av innleietid.

Måling av DPI

For at DPI skal godkjennes, må både skjermer og funksjonalitet få status godkjent i måleperioden.

Slik måler vi skjermstatus

En måleperiode er i praksis det samme som et vognløp; fra kjøretøyet logger på, til det logger av. I løpet av måleperioden skal hver skjerm på kjøretøyet ha fått status godkjent minst en gang.

Målet med måleperiode er å unngå evt. strukturelle, langvarige feil (og ikke straffe mindre enkelthendelser). Hensikten er å sikre at tjenesteyter og tjenestemottaker skaper gode kundeopplevelser.

Eksempler

Slik måler vi funksjonalitet

I løpet av måleperioden må 97 % av forventede ACK-meldinger være mottatt og godkjent hos tjenestemottaker for å bli godkjent for DPI.

For å ta høyde for hendelser der det blir forsinkelser godtar vi opptil 1 min forsinkelser i meldingene (f.eks. ved dårlig nett eller skjerm-restart).

Eksempel

Datakvalitet for en måleperiode

Datakvaliteten beregnes til 1 minus trekk for brudd:

• Brudd på ytelsesnivå 1 gir 1 poeng trekk, ellers går man videre til neste ytelsesnivå.

• Brudd på ytelsesnivå 2 gir 0,5 poeng trekk, ellers går man videre til neste ytelsesnivå.

• Brudd på ytelsesnivå 3 gir trekk som følger:

  • DPI: 0,25 poeng trekk

  • Rutersalg: 0,10 poeng trekk

  • APC: 0,05 poeng trekk

  • Hvert resterende dataemne: trekk 0,1 poeng / antall resterende dataemner (antall resterende dataemner i ADT 3.2 er 11)

Ikke målte dataemner teller som godkjent. "Ikke målt" betyr at Ruter ikke har implementert målingen av dataemnet. Hvis Ruter f.eks. ikke måler datakvaliteten på vindusviskerstatus vil den være godkjent, uavhengig av kvaliteten på innsendte data.

Eksempler - Rutesatt transport

Eksempler - Bestillingstransport

Datakvalitet for en avgang

Avgangen får samme datakvalitet som måleperioden den er en del av.

Dersom flere måleperioder er registrert på samme avgang vil den beste telle. Dette kan f.eks. skje hvis mer enn 1 kjøretøy betjente samme avgang.

Konsekvensene for brudd og eller overoppnåelse av ytelseskrav er definert i transporttjenestekontrakt operatøren har inngått med Ruter.

Ytelseskrav

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.

For rene BackOffice to BackOffice integrasjoner, avtales testløp fra gang til gang.

SIT (Site Integration Test)

Før oppstart og ved signifikante endringer i infrastruktur hos Tjenesteyter skal det kjøres en SIT test.

• Testing av nettverkstilkobling mellom Tjenesteyter og Tjenestemottaker

• Velformethet for meldinger og rapporter både M2Y, Y2M og MQTT

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.

Tjenesteyter er forpliktet til å sørge for at nødvendige data om kjøretøy til enhver tid er registrert og korrekt i Oppdragsgivers kjøretøydatabase; FRIDA. Registering i FRIDA er en forutsetning for at kjøretøyene er synlige i onlineskjema for VV.

Det anbefales at VV utføres av Tjenesteyter per kjøretøytype før oppgradering av ny major-versjon.

Versjons- og livsløpshåndtering

Versjonshåndtering

Avtale om Digitale Tjenester endres gjennom versjonering og tjenestemottaker kan velge å gi ut to typer nye versjoner, major og minor. Versjonene er nummerert som [major].[minor] i avtalen.

Minor versjon

Tjenestemottaker kan velge å gi ut nye minor versjoner av avtalen og tilhørende dokumentasjon for å ivareta nye leveranseavtaler eller piloter som inkluderer f.eks. nye kjøretøy klasser eller funksjoner. En minor versjon endrer ikke funksjonalitet og krav fra foregående versjoner med samme major versjon.

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. 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.

Major versjon

Tjenestemottaker gir ut en major versjon når man ønsker å legge til eller endre funksjoner for leveranser knyttet til denne avtalen.

Tjenesteyter forplikter seg til å kople seg til Ruters digitale tjenester slik som de er beskrevet i denne avtalen på enten siste eller nest siste major versjon, men står selv fritt til å bestemme migrasjonstakten. Endringsbestemmelse for versjons oppgradering er beskrevet i eget punkt.

Livsløpshåndtering

Tjenesteyter har totalansvar for livssyklusforvaltning av utstyr, programvare og andre ytelser som er nødvendig for å opprettholde er høyt tjenestenivå.

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

Oppstart av ny leveranse

Betingelsene i ADT gjelder fra kontraktinngåelse. Ved oppstart av ny leveranseavtale hvor det er spesifisert at denne avtalen kommer til anvendelse skal Tjenesteyter levere på nyeste versjon.

Endringsbestemmelse for avtalen

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.

Sanksjoner

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

Definisjoner