E Anlage 24 EFM_Anh 7_EFM-Leitfaden Integration_v0.9_191211_MVU 200122.pdf

[Seite 1]

Anlage 24 Anhang 7

Leitfaden Integration [INT_ANW]

Inhaltsverzeichnis Seite

1 Hinweise zum Umgang mit SAMs 1

2 Umgang mit MACtr 1 2.1 Hintergrund 1 2.2 Abschalten der Prüfung der MACTR 2 2.3 Umstellung auf KA konformes Erzeugen der MACTR 2

3 Informationen zur KIM-Modul-Schnittstelle 2 3.1 kim_ticket_valid_on_route(): Schnittstellenfunktion für die Ticketvalidierung auf Basis von zwei Haltestellen 2 3.2 kim_get_last_error_text(): Schnittstelle für Fehlertexte 2 3.3 kim_get_allowed_tariff_zones_time(): Schnittstelle für Freigabenberechnung mit Uhrzeiten 4 3.4 kim_get_value_set_type(): Übermittelt als Resultat den Berechtigungstyp eines Tickets 5

4 Verfügbarkeit und Anwendung aller tagesaktuellen Sperrlisten und der Aktionsliste im 24-Std. Rythmus 6

5 Parameter Betriebsende 6

6 Löschfristen für zeitlich abgelaufene Berechtigungen 7

7 Zurückgenommen markierte Berechtigungen 7

[Seite 2]

Anlage 24 Anhang 7

Änderungsnachweis

Rhein-Main-Verkehrsverbund Servicegesellschaft mbH (rms GmbH) Am Hauptbahnhof 6 60329 Frankfurt am Main

[Seite 3]

Anlage 24 Anhang 7

1 Hinweise zum Umgang mit SAMs Um Fehler im Zusammenhang mit dem SAM und den aktuellen Anforderungen des RMV zur Anzeige differenzierter Fehlermeldungen in den folgenden Fällen zu umge- hen bzw. zu fixen, schlagen wir die einheitliche Vorgehensweise/Darstellungsweise aller eT-Gerätehersteller im eTicket RheinMain vor und bitten um Umsetzung zur Si- cherstellung eines einheitlichen KA-konformes eTicketing im eTicket RheinMain:

Betrifft alle Geräte des eTRM, die mit einem SAM zur EFS-Kontrolle ausgestattet sind: Busdrucker. Mobile Kontrollgeräte, EKS, Fahrkartenautomaten, Multifunktions- terminals, u. v. m.

Fälle, in denen:

1. Kein SAM im Gerät vorhanden ist
2. Der SAM-Aktivierungsschlüssel nicht verfügbar ist oder nicht geladen werden konnte
3. Die zeitliche Gültigkeit des SAMs abgelaufen ist
4. Für die Ausgabe von Berechtigungen aus Aktionsmanagement die dazu erforderlichen Schlüssel nicht oder nicht vollständig im SAM verfügbar sind. Führen dazu, dass vorzugsweise bereits beim Hochfahren des Termi- nals/Druckers/Kontrollgeräts - spätestens aber beim Anmelden/Schichtbeginn - in den Fällen 1-3 eine Kontrollmeldung erscheint, die aktiv vom Gerätenut- zer/Fahrer/Prüfer bestätigt/weggeklickt werden muss. Für die Kontrollmeldung soll folgender oder ähnlicher Text verwendet werden: „Ein Problem ist mit dem SAM-Modul aufgetreten. Bitte kontaktieren Sie Ihren Sys- temadministrator. Die eTicket-Funktionen stehen nicht zur Verfügung!“ Sollte Fall 4 nicht bereits beim Hochfahren/Anmelden mit kommuniziert werden kön- nen, dann soll spätestens zum Zeitpunkt des Einlesens eines Nutzermediums und des Transaktionserzeugungsversuchs oben aufgeführte Kontrollmeldung erscheinen (statt so etwas wie „Internal System Error“ o. ä.). Alle Fälle führen dazu, dass die eTicket-Funktionalitäten in der Form deaktiviert wer- den und das kundenseitige Auflegen eines NM keine Informationen mehr über das NM oder die darauf befindlichen Daten und Berechtigungen mehr anzeigt oder vali- diert. Der Verkauf von Berechtigungen soll ebenso verhindert werden. SAM-Module und der notwendige Betreiberaktivierungsschlüssel werden bei der üfB des eTicket RheinMain bezogen.

2 Umgang mit MACtr

2.1 Hintergrund Im RMV-Einzugsgebiet wurde die Bildung der MACTR (auch MACKontrolle bzw. Transaktions-MAC genannt) von der expliziten Verwendung des MACTR-Schlüssels der Organisation 36 auf die KA konforme Verwendung gemäß [ANW_Nutzung TR_KEY] (KA v1.3.0) umgestellt. Dies hat zur Folge, dass parallel unterschiedlich gebildete MACs existieren. Da bei den nach altem Verfahren erzeugten MACs nicht erkennbar ist, mit welchem Schlüs- sel die MAC gebildet wurde, würde eine nach [ANW_Nutzung TR_KEY] (KA v1.3.0) durchgeführte MAC-Prüfung für alte MACs im Rahmen der Kommandoausführung

Leitfaden Integration [INT_ANW]_v0.9.docx; Stand 11.12.2019 Planung • Beratung • Service Seite 1

[Seite 4]

Anlage 24 Anhang 7

SAM.CHECK ENTITLEMENT fehlschlagen. Um dies zu verhindern, ist die Prüfung der MACs im RMV-Gebiet aktuell abgeschaltet.

2.2 Abschalten der Prüfung der MACTR Im Rahmen der Kontrolle ist das Kommando SAM.CHECK ENTITLEMENT mit dem Parameter P1 = 01 („Mit Prüfung der Reihenfolge der Transaktionsverarbeitung (Vorgänger-Kommando ist GET CHALLENGE).“ ohne MACTR Prüfung) zu verwen- den. Dies gilt bis zu einem Stichtag, der per Anforderung vom RMV (als PV) bzw. der rms rechtzeitig bekanntgegeben wird, zu dem die MACTR-Validierung wieder eingeschal- tet werden muss.

2.3 Umstellung auf KA konformes Erzeugen der MACTR Die MACTR ist konform der Verfahrensanweisung [ANW_Nutzung TR_KEY] (KA v1.3.0) zu bilden.

3 Informationen zur KIM-Modul-Schnittstelle Im Folgenden werden die im eTicket RheinMain zu verwendenden KIM-Modul- Schnittstellenfunktionen beschrieben, die bis zur Ablösung durch das KA PKM-Modul Anwendung finden. Eine detaillierte Anleitung zur Funktionsweise findet sich in der Online-Dokumentation, die innerhalb des HaCon-Distribution-Packages von der In- formationsplattform (SharePoint der rms) beziehbar ist.

3.1 kim_ticket_valid_on_route(): Schnittstellenfunktion für die Ti- cketvalidierung auf Basis von zwei Haltestellen Die Richtlinien des RMV besagen, dass ein Kunde nur dann einstiegsberechtigt ist, wenn das Ticket für die gesamte Fahrt gültig ist. Der Prüfprozess berücksichtigt die räumliche Prüfung der Tarifgebiete, die ohne Halt zwischen zwei Haltestellen durch- fahren werden. Somit ist nur ein Aufruf an die KIM-Bibliothek nötig, da zwei Haltestel- len gleichzeitig validiert werden.

Für die automatisierte Validierung mit dem RMV-KIM-Modul ist die Schnittstellenfunk- tion „kim_ticket_valid_on_route()“ zu verwenden. Die Schnittstelle nutzt die Eingabeparameter (Start-Tarifgebiet, Ziel-Tarifgebiet, Via- Tarifgebiet, Sortenschlüssel), Datum, Uhrzeit, Einstiegshaltestelle sowie die Infopool- Nummer der nächsten Haltestelle. Für die räumliche Gültigkeitsprüfung werden alle durchfahrenen Tarifgebiete zwischen den beiden Haltestellen ausgewertet. Die zwei- te Haltestelle von kim_ticket_valid_on_route() wird nicht ausgewertet, wenn dort ein negativer Wert übergeben wird (z. B. -1). Damit ist der Parameter optional. Weicht der Rückgabewert des Aufrufs von „gültig“ mit Code=0 oder von „räumlich ungültig“ mit Code=8 ab, soll der dazu gültige letzte Fehlertext mit der Schnittstellen- funktion „kim_get_last_error_text()“ abgerufen und am Display dargestellt werden können (vgl. Kap. „3.2 kim_get_last_error_text(): Schnittstelle für Fehlertexte“).

3.2 kim_get_last_error_text(): Schnittstelle für Fehlertexte Kommt es bei einem Aufruf einer KIM-Funktion zu einem Fehler, so wird die entspre- chende Funktion abgebrochen und ein passender Fehlercode als Zahl zurückgege- ben. Der Aufrufer muss diese Zahl dann interpretieren. Der Fehlercode des letzten aufgetretenen Fehlers soll durch die Schnittstellenfunktion

Leitfaden Integration [INT_ANW]_v0.9.docx; Stand 11.12.2019 Planung • Beratung • Service Seite 2

[Seite 5]

Anlage 24 Anhang 7

„kim_get_last_error_code()“ zusätzlich abgefragt werden. Mit der Schnittstellenfunk- tion „kim_get_last_error_text()“ erhält man einen Fehlertext mit inhaltlicher Beschrei- bung des Fehlers. Dieser Text beinhaltet auch zusätzliche Metainformationen, wie z. B. die Nummer der zur Anwendung gekommenen Tarifversion. Da es sich um kei- ne Alternative zum Logging handelt, wurde der Beschreibungstext möglichst knapp gehalten. In allen Fällen, in denen der Rückgabecode ungleich 0 (kein Fehler) zurückgegeben wird, sollen die Fehlertexte ebenfalls für das Logging im Geräte-HGS bereitgestellt werden. Die Funktion „kim_get_last_error_text_size()“ liefert die Länge des Fehlertextes. Die nachfolgende Tabelle gibt einen Überblick über die definierten Fehlercodes in KIM und die daraus resultierenden Fehlertexte:

Leitfaden Integration [INT_ANW]_v0.9.docx; Stand 11.12.2019 Planung • Beratung • Service Seite 3

[Seite 6]

Anlage 24 Anhang 7

*: Die Texte können nur erscheinen, wenn die Erweiterung „kim_ticket_valid_on_route()“ umgesetzt wurde.

Die in spitzen Klammern (<>) eingeschlossenen Texte beschreiben dynamische Wer- te, wie Funktionsparameter (z. B. Sortenschlüssel) oder berechnete Werte (z. B. Ta- rifversion). Bei der Ticketvalidierung werden die Texte für alle Tarifversionen, die bei der Prüfung berücksichtigt werden, konkateniert. Dafür werden die jeweiligen Tarif- versionen aufgelöst. Beispiel: „Tarifversion 34: Unbekannte Tarifrelation (6); Tarifver- sion 33: Kein Fehler (0)“. Die Anzeige des Textes soll entweder sehr klein und nicht auffallend am Rand des Displays o. ä. angezeigt werden oder bei Bedarf gesondert einblendbar sein. Die An- zeigemöglichkeit des Fehlertextes bei einer „ungültigen Validierung“ soll: • dem Fahrer oder Prüfpersonal als weitere Entscheidungsgrundlage dienen • dem Kunden eine Begründung zur Ursache liefern können • bei der Niederschlagung eines Ersatzfahrscheins oder EBEs helfen eine Hilfestellung bei der Analyse und Feststellung technischer Fehlerursachen im Kontrollumfeld dienen.

3.3 kim_get_allowed_tariff_zones_time(): Schnittstelle für Freigabenbe- rechnung mit Uhrzeiten Hintergrund: Die vormals verwendete Schnittstellenfunktion „kim_get_allowed_tariff_zones()“ berechnet die Freigabe einer Tarifrelation und gibt diese als Text zurück. Dieser Text beinhaltet eine Liste von TZ-Codes der freigege- benen Tarifgebiete. Als Inputparameter werden die Ticketdaten (Start-Tarifgebiet, Ziel-Tarifgebiet, Via-Tarifgebiet sowie Sortenschlüssel) und ein Datum erwartet. Das Datum ist zum einen wichtig, um die korrekte Tarifversion zu ermitteln, und zum an- deren, um Tickets mit unterschiedlichen Freigaben korrekt auswerten zu können. Bei

Leitfaden Integration [INT_ANW]_v0.9.docx; Stand 11.12.2019 Planung • Beratung • Service Seite 4

[Seite 7]

Anlage 24 Anhang 7

diesen Fahrkarten handelt es sich z. B. um die 65+-Karte oder die CleverCard. Die Tarifdaten haben sich mittlerweile so weiterentwickelt, dass die Auswertung der Frei- gabe uhrzeitscharf erfolgen muss. Aus diesem Grund ist die Funktion nicht mehr ausreichend. Die Schnittstellenfunktion „kim_get_allowed_tariff_zones_time()“ erhält die gleichen Parameter wie kim_get_allowed_tariff_zones(), allerdings zusätzlich mit einer Uhrzeit als Integer im Format HHMMSS. Mit Hilfe dieser Schnittstellenfunktion kann die Frei- gabe dann uhrzeitscharf berechnet werden. Aus Gründen der Abwärtskompatibilität bleibt die Funktion „kim_get_allowed_tariff_zones()“ erhalten. Diese verwendet gegenwärtig 0 Uhr für die Berechnung der Freigabe. Um das Defaultverhalten konfigurierbar zu machen, wurde diese Uhrzeit in der tarifkern.cfg einstellbar gemacht. Dazu wurde ein neuer Parameter mit Namen kim.default_frg_time erstellt. Dort wird ebenfalls das Format HHMMSS für die Uhrzeit verwendet. Ein Eintrag könnte dann z. B. wie folgt ausse- hen: kim.default_frg_time = “060000“. Der Parameter kommt auch zur Anwendung, wenn die Uhrzeit in der Funktion „kim_get_allowed_tariff_zones_time()“ nicht verwendet wird. Der Parameter ist optio- nal, wird ein negativer Wert übergeben, dann wird er nicht ausgewertet. Sollte der Parameter kim.default_frg_time in der tarifkern.cfg fehlen, dann wird als Default (vom Default) die Uhrzeit 11:00 Uhr gewählt.

3.4 kim_get_value_set_type(): Übermittelt als Resultat den Berechti- gungstyp eines Tickets Die Schnittstellenfunktion „kim_get_value_set_type()“ wird auch nach Einführung des KA PKM-Moduls weiterhin verwendet. Hintergrund: Viele Fahrkartenarten im RMV haben Merkmale, die bei einer Kontrolle von eTicket RheinMain nicht automatisch überprüft werden können. Allen Fahrkar- tenarten des eTicket RheinMain wurden deshalb technische Flags zugewiesen, wel- che auf die verschiedenen Merkmale hinweisen. Die Flags werden in einer Bit- Struktur in den Kontrolldateien gespeichert. Sie können bei der Kontrolle eines EFS anhand des dort gespeicherten Sortenschlüssels über die KIM-Modul-Schnittstelle zur Ermittlung des Berechtigungstyps eines Tickets („kim_get_value_set_type()“) eingelesen und am Display des Terminals angezeigt bzw. daraus weitere Aktionen abgeleitet werden.

Für einen EFS wurden folgende Merkmale als möglich definiert:

Leitfaden Integration [INT_ANW]_v0.9.docx; Stand 11.12.2019 Planung • Beratung • Service Seite 5

[Seite 8]

Anlage 24 Anhang 7

Sind die Bits 1 bis 6 bei EFS gesetzt, werden auf dem Terminaldisplay Datenanzei- gefelder eingeblendet, welche für das Prüfpersonal auf den ersten Blick als “Eyecat- cher“ (ohne “Scroll-Down“ oder Umblättern) erkennbar sind. Ein Datenanzeigefeld stellt anhand eines Symbols/Piktogramms (beispielsweise einer kleinen Symbolfigur) das jeweilige Merkmal dar.

Folgendermaßen kann die Anzeige dieser Merkmale umgesetzt werden:

6 EFS ist für die 1. Klasse gültig

Für eine Fahrkartenart können mehrere Bits gleichzeitig gesetzt sein. Dabei werden dann die einzelnen Bit-Werte addiert um einen neuen Bit-Wert für dieses Produkt zu erhalten. Die kompletten personenbezogenen Daten sind zudem ebenso wie in Kapitel 3 „An- zeige Dateninhalte des EFS“ des Dokuments „Anzeige eTicket RheinMain am Fah- rer-/Prüferdisplay von (((eTicket-Deutschland Akzeptanzterminals“ anzuzeigen.

Weitere Beispiele siehe auch in der “RMV-Tarifdaten-Spezifikation“.

Hinweis zu Bit 7: Dieser Bit-Wert besagt, dass es sich um eine Fahrkartenart handelt, die „in ganz Hessen gültig“ ist. Dieser Text wurde gleichfalls durch den RMV im eTi- cket RheinMain als Standard festgelegt und kann statt einer Liste aller freigegebenen Tarifgebiete im Kontext der Gültigkeit von elektronischen Fahrtberechtigungen (EFS), die in ganz Hessen gültig sind, bei der Validierung am Terminal angezeigt werden.

Hinweis zu Bit 8: Dieser besagt, dass das dem EFS zu Grunde liegende EFM- Produkt nicht zu einer gültigen Validierung führen darf, da dieses nicht zur Fahrt be- rechtigt - beispielsweise „Zuschlag 1. Klasse“ oder „FV-Ergänzungskarte“. In diesem Fall muss die Gerätesoftware auf dem Nutzermedium nach einem anderen, zur au- tomatisierten Validierung gültigen, EFS suchen oder das Validierungsergebnis „un- gültig“ anzeigen.

4 Verfügbarkeit und Anwendung aller tagesaktuellen Sperrlisten und der Aktionsliste im 24-Std. Rhythmus Die Verfügbarkeit und Anwendung aller tagesaktueller Sperrlisten sowie der Aktions- liste vom vHGS ist im Terminal zum Betriebsbeginn im 24-Std. Rhythmus sicherzu- stellen. Ebenfalls ist sicherzustellen, dass erzeugte Transaktionsdaten im 24-Std. Rhythmus, spätestens zum Betriebsende (via TMS), an das vHGS übertragen wer- den.

5 Parameter Betriebsende Das Gültigkeitsende eines RMV-EFS beinhaltet grundsätzlich den Timestamp 23:59:58 Uhr. Damit der RMV-EFS in der automatisierten eKontrolle (KIM-Modul

Leitfaden Integration [INT_ANW]_v0.9.docx; Stand 11.12.2019 Planung • Beratung • Service Seite 6

[Seite 9]

Anlage 24 Anhang 7

bzw. PKM) bis zum Zeitpunkt des tariflichen Betriebsendes am Folgetag noch gültig validiert werden kann, muss ein vom RMV derzeit auf 04:59:58 Uhr festgelegter Zeit- punkt im HGS eingestellt werden können (Parameter).

6 Löschfristen für zeitlich abgelaufene Berechtigungen Bei zeitlich abgelaufenen Berechtigungen ist folgende Verfahrensweise zu berück- sichtigen:

 Zeitlich < 24 Stunden abgelaufenen Berechtigungen: werden niemals ge- löscht, selbst dann nicht, wenn Platz zur Ausgabe einer neuen Berechtigung benötigt wird.

 Zeitlich 24-72 Stunden abgelaufene Berechtigungen: wenn Platz für die Aus- gabe einer neuen Berechtigung benötigt wird, ist ein Löschen schon 24 Stun- den nach Erreichen des zeitlichen Gültigkeitsendes ohne Durchführen einer Rücknahmetransaktion und ohne Rückfrage an den Kunden zulässig.

 Zeitlich > 72 Stunden abgelaufene Berechtigungen sind bereits bei Einlese- vorgängen ohne Durchführen einer Rücknahmetransaktion und ohne Rückfra- ge an den Kunden zu löschen. Bei Löschvorgängen ist die Prioritätenliste stets zu aktualisieren.

7 Zurückgenommen markierte Berechtigungen Zurückgenommen markierte Berechtigungen sind im eTicket RheinMain in der Kon- trolle nicht anzuzeigen. Bei Platzbedarf oder bei zeitlich unkritischen Einlesevorgän- gen (Automat, Infoterminal, mobile Kontrolle, personenbediente Vertriebsstelle) kön- nen rückgenommen markierte Berechtigungen gelöscht werden.

Leitfaden Integration [INT_ANW]_v0.9.docx; Stand 11.12.2019 Planung • Beratung • Service Seite 7