IEEE Software Requirements Specification Template
Werbung
Schnittstelle zwischen iTIXI und Buchhaltung Version 2.0.6 Entwurf Author Martin Jonasse Open Source 20.02.2014 Schnittstelle zwischen iTIXI und Buchhaltung Page ii Table of Contents 1. Einführung................................................................................................................................1 1.1 Zweck und Umfang ..................................................................................................................... 1 1.1 Zielgruppe .......................................................................................................................................... 1 1.2 Referenzen ......................................................................................................................................... 1 2. Konfiguration ...........................................................................................................................2 2.1 2.2 Software Schnittstelle .................................................................................................................. 3 Muster-Rechnungen..................................................................................................................... 4 3. Anwendungsfälle ......................................................................................................................8 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 Paket Lieferscheine...................................................................................................................... 8 Anwendungsfall “Fahrten disponieren” ...................................................................................... 9 Anwendungsfall „Zonen planen“ .............................................................................................. 10 Anwendungsfall „Export Lieferscheine“ ................................................................................... 11 Anwendungsfall „Import Lieferscheine“ ................................................................................... 13 Anwendungsfall „Monatsrechnung erstellen“ ........................................................................... 14 Anwendungsfall „Rechnung für Mitgliederbeitrag erstellen“ ................................................... 15 Schnittstellen Daten ................................................................................................................... 16 4. Tarifzonen...............................................................................................................................18 4.1 4.2 4.3 4.4 iTixi –> Verwaltung –> Zonen .................................................................................................. 19 iTixi –> Verwaltung –> Zonenplan ........................................................................................... 20 Zonengestaltung ........................................................................................................................ 21 Abhängigkeit Fahrt, Adresse, Zonenplan .................................................................................. 22 5. Anhang 1: Objekt Eigenschaften ..........................................................................................24 5.1 5.2 5.3 Fahrgast Eigenschaften .............................................................................................................. 24 Fahrt Eigenschaften ................................................................................................................... 25 Eigenschaften und Tarifgestaltung ............................................................................................ 26 6. Anhang 2: Datei Formate ......................................................................................................27 6.1 6.2 6.3 Dateinamen ................................................................................................................................ 27 Datei-Format Comma Seperated Values (csv) .......................................................................... 27 Datei-Format Microsoft Excel 2003 (xml) ................................................................................ 28 7. Anhang 3: Einschränkungen ................................................................................................29 7.1 7.2 TIXI ZUG .................................................................................................................................. 29 BUSPRO.................................................................................................................................... 29 Schnittstelle zwischen iTIXI und Buchhaltung Page iii Revisionen Name Datum Reason For Changes Version Martin Jonasse 26.02.2014 Initial Dokument 2.0.0 Josi Conrad 01.03.2014 Korrekturen/Änderungen 2.0.1 Martin Jonasse 15.03.2014 Anpassungen in labels, Datei Formate hinzugefügt 2.0.2 Martin Jonasse 01.04.2014 Anpassungen für Herr Thomann/TCA (BUSPPRO), Yeldez Gwerder und Ferdinand Dettling von TIXIZUG. 2.0.3 Martin Jonasse 04.11.2014 Update für die Implementierung, die in der iTIXI Applikation stattgefunden hat. 2.04 Martin Jonasse 14.11.2014 Update für die Korrekturen für Buspro (keine double-quotes, Zeilenabschluss mit CRLF, keine mehrzeilige Felder) 2.05 Martin Jonasse 20.02.2015 Upgrade für Vormund (custodian) 2.06 Schnittstelle zwischen iTIXI und Buchhaltung Page 1 1. Einführung 1.1 Zweck und Umfang Die iTIXI Dispo-Software verwaltet Abläufe und Daten, die für den Betrieb einer Tixi Organisation notwendig sind. Die vorliegende Spezifikation befasst sich mit den wirtschaftlichen Aspekten der Tixi Organisation und mit der Schnittstelle zwischen der iTIXI Software und der Buchhaltung-Software im besonderen. Diese Schnittstelle befasst sich ausschliesslich mit dem Zahlungsverkehr zwischen dem Fahrgast und der Tixi Organisation. Fahrgäste, (Mitglieder des Tixi Vereins) zahlen für: 1. die Mitgliedschaft im Tixi Verein (Zahlungsverkehr; einmal im Jahr) 2. jede Fahrt die mit einem Tixi Fahrzeug durchgeführt wird a. Bezahlung mit Bargeld oder Coupons (am Ende der Fahrt) b. Bezahlung per Monatsrechnung (Zahlungsverkehr im Folge-Monat) In der Schnittstelle zu der Buchhaltung sind inbegriffen: Adressdaten von allen Tixi Vereinsmitgliedern Liste der Fahrten für Mitglieder, diese Liste ist sozusagen der Lieferschein für bezogene Leistungen. In der Schnittstelle zu der Buchhaltung sind ausdrücklich ausgeschlossen: Investitions- und Betriebskosten für Fahrzeuge, z.B. Benzinkosten. Vergütungen, Spesen für Fahrer und/oder Betriebsangehörige der TixiOrganisation. Gönnerbeitrage, Spendenaktionen etc. 1.1 Zielgruppe Diese Spezifikation richtet sich an Entwickler und Administratoren der iTIXI Applikation und / oder der Buchhaltung-Software. 1.2 Referenzen ID Dokument Name Bemerkung Ref.1 iTIXI_FAKTURA.pdf Rechnungsablauf TIXIZUG (Bestandesaufnahme). Ref.2 iTIXI_BUSPRO.pdf Konfigurationen BUSPRO (Evaluation der Software) Ref.3 Offerte für Buspro U/Referenz 22550/ET, Thomann Computer Assembly AG Ref.4 iTIXI_Specification_ Muster Lieferscheine (csv, xml, xlsx) und TIXIZUG Accounting_Bill_of_Delivery Reglement für Fernfahrten. Ref.5 iTIXI_SRS_Liste.xlsm Anforderung F-120/R-122 Schnittstelle zwischen iTIXI und Buchhaltung Page 2 2. Konfiguration Die iTIXI Dispo-Software (grün) enthält eine Schnittstelle zu der Debitoren Buchhaltung (gelb) und der Finanzbuchhaltung (rot). Die iTIXI Dispo-Software erzeugt alle Daten, die für die Fakturierung (Rechnungen) an Fahrgäste notwendig sind: Jahresrechnung für Mitgliederbeiträge der Fahrgäste. Monatsrechnungen für Mitglieder mit Monatsrechnung. Schnittstelle zwischen iTIXI und Buchhaltung Page 3 2.1 Software Schnittstelle Die Software Schnittstelle (rot) zwischen der iTIXI Applikation und Buchhaltung-Software ist sehr einfach als Datei basierte Import- /ExportSchnittstelle realisiert: Die iTIXI Applikation hat eine Export Use Case, welche eine Datei auf der Workstation des Benutzers zur Verfügung stellt. Die Buchhaltung-Software hat ein Import Use Case, welche die obenerwähnte Datei einliest und verarbeitet. Für den Benutzer braucht es daher zwei manuelle Schritte, um die iTIXI Daten in die Buchhaltung zu importieren. Die iTIXI Applikation unterstützt die folgenden Exportdatei-Formate: o CSV: für die BUSPRO Applikation o XML: für andere Applikationen Schnittstelle zwischen iTIXI und Buchhaltung Page 4 2.2 Muster-Rechnungen Rechnungen werden im Fakturierungs-Modul der Debitoren Buchhaltung erzeugt, d.h. ausserhalb der iTIXI Dispo-Software. 2.2.1 Monatsrechnung (Fernfahrt) Tarif: 0.70 CHF/km, 10 CHF/Std Rechnungsadresse = Wohnadresse Schnittstelle zwischen iTIXI und Buchhaltung Beleg für Monatsrechnung (Fernfahrt), ausfüllen gemäss Reglement für TIXI-Fernfahrten: Page 5 Schnittstelle zwischen iTIXI und Buchhaltung 2.2.2 Monatsrechnung (kantonal) Tarif: 3 CHF/Begleitperson, 3 CHF/Fahrt (Stand 2013) Rechnungsadresse <> Wohnadresse Page 6 Schnittstelle zwischen iTIXI und Buchhaltung Page 7 2.2.3 Unterschiede zwischen den Rechnungsarten Rechnungs-Eigenschaft Monatsrechnung (Kantonal/Angrenzend) Monatsrechnung (Fernfahrt) Art der Abrechnung? Pauschal, pro Fahrt Nach Aufwand Beleg-Art? Plandaten der DispoSoftware Hardcopy (Papier), unterschrieben vom Fahrer Nacharbeit in FIBU? Keine, automatisch Manuelles erfassen der effektive Kosten, gemäss Beleg. Ausgewiesene Fahrten? Hin- und Rückfahrten werden ausgewiesen. Nur der Rückfahrt wird ausgewiesen, um Abgrenzungen über das Ende des Monats zu vermeiden. Schnittstelle zwischen iTIXI und Buchhaltung 3. Anwendungsfälle 3.1 Paket Lieferscheine Legende: iTIXI = grün, Buchhaltung = gelb Das Paket Lieferscheine besteht aus drei iTIXI Anwendungsfälle (erstellen von Stammdaten für Lieferscheine): Zonen Planen Zonenplan erstellen. Kunden Stammdaten Stammdaten mit Verweis auf den Zonenplan Fahrten disponieren Plandaten für ein oder mehrere Fahrten eines Kunden Zwei Anwendungsfälle sind für das Erstellen von Lieferscheine / Rechnungen: Export Lieferscheine iTIXI Import Lieferscheine Buchhaltung Monatsrechnung erstellen Buchhaltung Jahresrechnung erstellen Buchhaltung Page 8 Schnittstelle zwischen iTIXI und Buchhaltung Page 9 3.2 Anwendungsfall “Fahrten disponieren” Subsystem iTIXI(Mandant xy) -> Fahrgast -> Fahrauftrag Akteure Disponent, Manager, Administrator Auslöser/ Vorbedingungen Kunde (Fahrgast) erteilt einen Auftrag oder Dauerauftrag. Ergebnisse/ Nachbedingungen Ein Fahrauftrag (Hinfahrt, eventuell auch Rückfahrt) ist erfasst und durch die Dispo-Software bestätigt. Ein Auftrag für ein Fernfahrt hat zwingend ein Hinfahrt und ein Rückfahrt. Nicht-funktionale Anforderungen 1. Der Betrieb muss die Ressourcen haben um den Fahrauftrag durchzuführen, d.h. verfügbare Fahrzeuge und Fahrer. 2. Bei Kantonale- und Angrenzend-Fahrten kann nicht garantiert werden, dass der gleiche Fahrer und Fahrzeug für Hin- und Rückfahrt zuständig sind. Ablaufbeschreibung 1. Kundenwunsch entgegen nehmen. 2. Kundenwunsch in der Dispo-Software erfassen. 3. Fahrauftrag bei Kunde bestätigen. 4. Auftrag abschiessen (Speichern). Ausnahmen, Fehlersituationen Freie Kapazität nicht vorhanden, Varianten anbieten. Varianten Andere Fahrzeiten, nur Hin- oder Rückfahrt, Sammelaufträge, Fahrtoptimierung, extra Fahrzeuge (und Fahrer) aufbieten. Regeln 1. So viel Kunden wie möglich (Resourcen) bedienen. 2. Auftragserteilung (telefonisch) so schnell (kurz) als möglich. Anforderungen iTIXI_SRS_Liste / F-90 / F-100 Ansprechpartner, Stakeholder Martin Jonasse (Requirements Engineer) Änderungshistorie 04.11.2014 Update für die Implementierung in iTIXI Schnittstelle zwischen iTIXI und Buchhaltung Page 10 3.3 Anwendungsfall „Zonen planen“ Subsystem iTIXI(Mandant xy) -> Unterhalt -> Zonenplan Akteure Manager, vorzugsweise Administrator Auslöser/ Vorbedingungen Konfigurieren des Systems (erstmalig), oder ändern des Zonenplanes. Ein Zonenplan z.B. eines ÖV Betriebes ist als Vorlage vorhanden. Die Tarifstruktur/Tarifnamen ist/sind bekannt und in der Buchhaltung implementiert. Ergebnisse/ Nachbedingungen Vollständige Liste mit Ortsnamen, und Zonenamen. Nicht-funktionale Anforderungen Tarifnamen sind in der Buchhaltung-Software (z.B. BUSPRO) identisch. Ablaufbeschreibung 1. 2. 3. 4. Ausnahmen, Fehlersituationen Ortschaften die nicht im Zonenplan aufgeführt sind, haben keinen Tarif (Null-Tarif = Kilometer-Tarif anwenden). Varianten Ortschaften liegen in mehrere Zonen, siehe Kapitel 4. D.h. die ÖV Zonen sind nicht deckungsgleich mit den politische Gemeinden. Regeln Anforderungen iTIXI_SRS_Liste / F-120 / R-130 Ansprechpartner, Stakeholder Martin Jonasse (Requirements Engineer) Änderungshistorie 27.02.2014 Version 1.0 erstellt 04.11.2014 Update für die Implementierung in iTIXI Beispiel: siehe iTIXI Mandant „TIXI24“ -> Unterhalt -> Zonenplan. Tarifstruktur bestimmen. Zonen auf Papier planen. Ortsnamen innerhalb der Zonen bestimmen. Ortsnamen in iTIXI -> Mandant „xyz“ -> Unterhalt -> Zonenplan mittels Hinzufügen, Bearbeiten, Löschen auflisten. Eine Ortschaft liegt in einer Zone (m:1 Beziehung). Der Ortsname ist in der Tabelle eindeutig (unique). Schnittstelle zwischen iTIXI und Buchhaltung Page 11 3.4 Anwendungsfall „Export Lieferscheine“ Subsystem iTIXI(Mandant xy) -> Bereitstellen -> Lieferscheine Akteure Disponent Auslöser/ Vorbedingungen Ergebnisse/ Nachbedingungen Export Datei(en) sind auf einer lokalen Arbeitsstation abgelegt. Nicht-funktionale Anforderungen Lokale Arbeitsstation verwendet Windows 7 oder höher. Ablaufbeschreibung 1. iTIXI öffnen 2. bei Mandant xy anmelden 3. Menu Bereitstellen -> Monatsrechnung öffnen. 4. Button „Exportieren“ anklicken. 5. Ablageort (Ordner xy) auswählen. 6. Wenn nötig, den Dateiname ändern (anstelle Default). 7. Wenn nötig, den Datei-Type ändern (XML anstelle CSV). 8. Button „Speichern“ oder „Abbrechen“ anklicken. 9. Tab „Mitglieder“ kontrollieren (Sheet1, alle Fahrgäste). 10. Tab „Fahrten“ kontrollieren (Sheet2, alle Fahrten, Monat xy). Ausnahmen, Fehlersituationen Varianten Als Default wird der Vormonat angezeigt. Mittels Button „Monatsauswahl“ kann ein anderer Monat angezeigt werden. Regeln Ein Fahrgast kann keine, eine, oder mehrere Fahrten im Vormonat gemacht haben (1:mc Beziehung Fahrgast:Fahrt). Anforderungen iTIXI_SRS_Liste / F-120 / R-122 Ansprechpartner, Stakeholder Martin Jonasse (Requirements Engineer) Änderungshistorie 27.02.2014 Version 1.0 erstellt Erste Woche des Monats, und alle Fahraufträge sind erfasst (und geschlossen), und Zonenplan ist erstellt (siehe Kapitel 3.2). Filesystem Fehler, wenn keine Berechtigung in „Ordner xy“. Tab „Fahrten“ ist leer, wenn keine Fahrten vorhanden sind. 04.11.2014 Update für die Implementierung in iTIXI 20.02.2015 Korrigiert von XLS nach XML (Excel kompatibel) Schnittstelle zwischen iTIXI und Buchhaltung 3.4.1 Screenshots Screenshot 1: Liefermonat auswählen Screenshot 2: warten Screenshot 3: download Page 12 Schnittstelle zwischen iTIXI und Buchhaltung 3.5 Anwendungsfall „Import Lieferscheine“ Subsystem Buchhaltung-Software(Mandant xy) Akteure Disponent Auslöser/ Vorbedingungen Export Datei(en) sind auf einer lokale Arbeitsstation abgelegt (siehe Kapitel 3.3). Ergebnisse/ Nachbedingungen Fahrgastdaten sind à jour Fahrten für Monat xy sind à jour Nicht-funktionale Anforderungen Lokale Arbeitsstation verwendet Windows 7 oder höher. Die Buchhaltung-Software ist lokal oder in einer Wolke. Ablaufbeschreibung Buchhaltung-Software (z.B. BUSPRO) öffnen Import Funktion aufrufen Etc. Ausnahmen, Fehlersituationen Abhängig von der Buchhaltung-Software. Varianten Abhängig von der Buchhaltung-Software. Regeln Abhängig von der Buchhaltung-Software. Anforderungen iTIXI_SRS_Liste / F-120 / R-122 Ansprechpartner, Stakeholder Martin Jonasse (Requirements Engineer) Änderungshistorie 27.02.2014 Version 1.0 erstellt Page 13 Schnittstelle zwischen iTIXI und Buchhaltung Page 14 3.6 Anwendungsfall „Monatsrechnung erstellen“ Subsystem Buchhaltung-Software (Mandant xy) Akteure Disponent Auslöser/ Vorbedingungen Fahrgastdaten und Fahrtdaten sind erfolgreich importiert (siehe Kapitel 3.4). Tarife sind in der Buchhaltung implementiert. Ergebnisse/ Nachbedingungen Monatsrechnungen sind erstellt. Nicht-funktionale Anforderungen Lokale Arbeitsstation verwendet Windows 7 oder höher. Die Buchhaltung-Software ist lokal oder in einer Wolke. Ablaufbeschreibung Buchhaltung-Software (z.B. BUSPRO) öffnen Etc. Ausnahmen, Fehlersituationen Spesen, Wartezeit und effektive gefahrene Kilometer müssen in der Buchhaltungs-Software und in der entsprechende Rechnung nachträglich „eingepflegt“ werden. Diese Angaben werden nicht in der Dispo-Software erfasst Varianten Abhängig von der Buchhaltung-Software. Regeln Abhängig von der Buchhaltung-Software. Anforderungen iTIXI_SRS_Liste / F-120 / R-122 Ansprechpartner, Stakeholder Martin Jonasse (Requirements Engineer) Änderungshistorie 27.02.2014 Version 1.0 erstellt 31.03.2014 Version 1.1 Spesen ergänzt 04.11.2014 Update für die Implementierung in iTIXI Schnittstelle zwischen iTIXI und Buchhaltung Page 15 3.7 Anwendungsfall „Rechnung für Mitgliederbeitrag erstellen“ Subsystem Buchhaltung-Software(Mandant xy) Akteure Disponent Auslöser/ Vorbedingungen Ergebnisse/ Nachbedingungen Rechnungen für Mitgliederbeiträge sind erstellt. Nicht-funktionale Anforderungen Lokale Arbeitsstation verwendet Windows 7 oder höher. Die Buchhaltung-Software ist lokal oder in einer Wolke. Ablaufbeschreibung Buchhaltung-Software (z.B. BUSPRO) öffnen Etc. Ausnahmen, Fehlersituationen Abhängig von der Buchhaltung-Software. Varianten Abhängig von der Buchhaltung-Software. Regeln Abhängig von der Buchhaltung-Software. Anforderungen iTIXI_SRS_Liste / F-120 / R-122 Ansprechpartner, Stakeholder Martin Jonasse (Requirements Engineer) Änderungshistorie 27.02.2014 Version 1.0 erstellt Fahrgastdaten sind erfolgreich importiert (siehe Kapitel 3.4). Tarif ist in der Buchhaltung implementiert. Schnittstelle zwischen iTIXI und Buchhaltung Page 16 3.8 Schnittstellen Daten Rechnung(en) werden periodisch (monatlich, jährlich) in der BuchhaltungSoftware erzeugt. Jede Rechnung basiert auf Lieferschein Objekte die monatlich über die Export/Import-Schnittstelle ausgetauscht werden: Person Objekte Fahrt Objekte 3.8.1 Business Rules Die Schnittstelle ist eine Datei, sie enthaltet: o alle Personen (2’700 oder mehr, unbegrenzt) die zur Zeitpunkt der Export-Vorgang in der Datenbank vorhanden sind, sowie o alle Fahrten eines bestimmten Monates. Umfang: null bis 4'200 Fahrten (oder mehr, unbegrenzt). Die Beziehung zwischen „Person“ und „Fahrt“ Objekte ist 1:mc. Eine Person kann keine, eine, oder mehrere Fahrten pro Monat referenzieren. Ein Person ist ein Fahrgast (passenger), Fahrer (driver) oder Vormund (custodian). o Ein Fahrgast kann kein oder ein Vormund referenzieren (1:c). o Ein Vormund vertritt keine, eine oder mehrere Fahrgäste (1:mc). o Fahrgäste können entweder mit Bargeld(Coupons) oder per Monatsrechnung bezahlen. Es gibt keine Mischformen, per Monatsende kann der Zahlungsmodus gewechselt werden. Ein Fahrgast, oder sein Vormund, können Fahrten monatlich in Rechnung gestellt werden, insofern „hasMonthlyBilling = TRUE“. o Ein Fahrgast, oder sein Vormund, kann eine jährliche Mitgliederbeitrag für den TIXI Verein in Rechnung gestellt werden. Alle Daten werden in einer Datenbank vorgehalten, der Primärschlüssel (ID) bleibt stabil, auch wenn die Inhalte der Eigenschaften ändern können. An der Schnittstellen werden Werte übergeben, fehlt ein Wert in der Datenbank, so wird NULL, string(4), übergeben. Alle Daten werden in den UTF-8 Zeichensatz abgebildet. Schnittstelle zwischen iTIXI und Buchhaltung Page 17 3.8.2 Fahrgast-Daten Die Export-Datei enthält die Fahrgast-Daten, aktuell zu dem Zeitpunkt des Exportes (dies ist der Zeitstempel der Export-Datei). Die Person-ID ist der Primärschlüssel in der iTIXI Datenbank-Tabelle für Fahrgäste. Dieser Schlüsselwert wird nur einmal während der Lebensdauer der Datenbank vergeben (autoincrement value). Es werden immer alle Personen, die in der Datenbank vorhanden sind, exportiert. Personen mit der Eigenschaft ist_aktive = false, werden mindestens ein Jahr in der Datenbank vorgehalten, bevor der Datensatz gelöscht wird. Eine Liste der Eigenschaften ist in Anhang 1 enthalten. 3.8.3 Fahrt-Daten Die Export-Datei enthält alle Fahrt-Daten für einen ganzen Monat, z.B. Februar 2014 (dies ist ein Auswahl Kriterium im Export Use Case). Die Fahrt-ID ist der Primärschlüssel in der iTIXI Datenbank-Tabelle für Fahrten. Dieser Schlüsselwert wird nur einmal während der Lebensdauer der Datenbank vergeben (autoincrement value). Es werden immer alle Fahrten, die für den betreffenden Monat in der Datenbank vorhanden sind, exportiert. Fahrten werden mindestens ein Jahr in der Datenbank vorgehalten, bevor der Datensatz gelöscht wird. Fahrt-Eigenschaften, können auch abgeleitete Werte sein, z.B. „Tarif“, siehe Kapitel 4. Eine Liste der Eigenschaften ist in Anhang 2 enthalten. Schnittstelle zwischen iTIXI und Buchhaltung Page 18 4. Tarifzonen Tarifzone, Definition: Ein Gebiet (Zone), innerhalb der ein bestimmter Fahrpreis zu entrichten ist. Falls ein Fahrt sich über mehr als ein Zone erstreckt, wird der höchste Zone (Zonenpreis) berechnet. Die Tarifzone ist eine (abgeleitete) Eigenschaft, die durch den Abfahrts- und Ankunftsort einer Fahrt bestimmt ist (siehe Kapitel 4.3). Die Preis-Gestaltung und –Berechnung erfolgt vollumfänglich in der BuchhaltungSoftware. Schnittstelle zwischen iTIXI und Buchhaltung 4.1 iTixi –> Verwaltung –> Zonen In dieser Webseite (Use Case) werden Zonen mit Zonenname und Priorität definiert. Benutzerberechtigung: Administrator. Eine höhere Priorität bedeutet eine höhere Preis. Es können maximal 1000 Zonen definiert werden. Die Zone mit Priorität 1001 (Fernfahrt) wird durch die Software erzeugt. Page 19 Schnittstelle zwischen iTIXI und Buchhaltung Page 20 4.2 iTixi –> Verwaltung –> Zonenplan In dieser Webseite (Use Case) wird der Zonename mit dem Ortsnamen verknüpft. Benutzerberechtigung: Administrator. Für jeden Ortsnamen darf nur eine einzige Eintragung vorgenommen werden (eindeutig, englisch: unique). Fahrten von / nach Ortsnamen die nicht in dieser Tabelle aufgeführt sind, haben einen leeren Zonenamen (null, Fernfahrt). Schnittstelle zwischen iTIXI und Buchhaltung Page 21 4.3 Zonengestaltung Für die Zonengestaltung wird ein Element aus der Abfahrts- und Zieladresse verwendet: Ortsname Postleitzahl Zone meist auch die politische Gemeinde, oder durch die Post vergebene Adresse, oder durch Tixi Organisation festzulegen. Wegen zu grossem Aufwand wird darauf verzichtet die Eigenschaft „Zone“ im Objekt „Adresse“ einzuführen. 4.3.1 Politische oder postalische Grenzen Da Tixi-Betriebe meist durch politische Instanzen (Bund, Kanton, Gemeinde) subventioniert sind, ist der Ortsname die logische Wahl für die Zonengestaltung: die Tarife können klar dem Geldgeber zugeordnet werden. Für regionale und kantonal tätige Tixi Organisationen ist dies ein optimale Lösung. Daher wird auf die Verwendung von PLZ verzichtet. 4.3.2 Zonen des Öffentlichen Verkehrs Die Zonen für den öffentlichen Verkehr wie Busbetriebe oder Stadtbahnen, richten sich nach einer Kombination von Haltestellen und politischen Grenzen. Dadurch werden Ortschaften oft tarifmässig „zerteilt“. Das ist für einen Tixi Betrieb ebenso wenig geeignet, weil mit zu grossem Aufwand verbunden (siehe oben, Zone). 4.3.3 Ortsname und Kreise Wenn nun doch eine Unterteilung eines Ortes aus tariflichen Anforderungen notwendig ist, so kann der Ansatz der Stadt Zürich gewählt werden: Aus Verwaltungstechnischen Gründen ist die Stadt in „Kreise“ aufgeteilt: diese Kreise müssen im Objekt „Adresse“ Eigenschaft „Ortsname“ eingepflegt werden, und in entsprechend viele „Zonenplan“ Objekte angelegt werden. Schnittstelle zwischen iTIXI und Buchhaltung Page 22 4.4 Abhängigkeit Fahrt, Adresse, Zonenplan Die Eigenschaften „Zone“ wird aus der „Fahrt“ wie folgt abgeleitet: Jede Fahrt hat eine Abfahrtsadresse (Von). Jede Abfahrtsadresse hat einen Ortsnamen. Jede Abfahrt-Ortsname referenziert einen Ortsnamen im Zonenplan. o Falls vorhanden, wird der gefundene Zonename zurückgegeben. o Falls nicht vorhanden, ist Zonename leer (null, Fernfahrt). Das Gleiche gilt auch für die Zieladresse (Ankunftsort). Die Zone für den Fahrt, ist die Zone mit der höchsten Priorität. Beispiel für TIXIZUG, Fahrt von Zug nach Luzern: Abfahrtsort= Zug, Zonename = kantonal = Priorität 1 Ankunftsort = Luzern, Zonename = null = Priorität 1001 Dieser Fahrt fällt somit in die Zone „Fernfahrt“ Schnittstelle zwischen iTIXI und Buchhaltung Page 23 4.4.1 Beispiel Tarifgestaltung Die Tarifgestaltung wird anhand eines Beispiels für TIXIZUG (2014) erklärt. TIXIZUG hat drei Zonen: Kantonal, Angrenzend, Fernfahrt. Kantonal alle Ortschaften innerhalb des Kantons Zug Angrenzend alle Ortschaften angrenzend an den Kanton Zug Fernfahrt alle andere Ortschaften Jeder Fahrt referenziert eine Zeile in der folgenden Zonen-Matrix (in der Buchhaltung hinterlegt): NZ FahrtTarif FahrTarif WarteTarif Begleit-Tarif Bearbeit.Tarif CHF/Fahrt CHF/km CHF/Std. CHF/Pers. CHF/Rech. Kantonal 4.00 0.00 0.00 4.00 5.00 Angrenzend 8.00 0.00 0.00 4.00 5.00 Fernfahrt 0.00 0.70 10.00 0.00 5.00 Nach-Zone Beim Importieren werden die folgenden Fahrt-Eigenschaften an die Schnittstelle geliefert, siehe auch Anhang 2: o zone o fahr_km o begleiter Index VZ im Zonen-Matrix gefahrene Kilometer (mit dem Kunde) Anzahl Begleitpersonen Die Von-Zone und Nach-Zone indexieren die obige Zonen-Matrix. Die Berechnung vom Fahrpreis (Formel) ist wie folgt: o Fahrpreis = Fahrt-Tarif[zone] + (Fahr-Tarif[zone] * fahr_km) + (Warte-Tarif[zone] * wartezeit) + (Begleit-Tarif[zone] * begleiter) + (Spesen gemäss Beleg) + Bearbeitungs-Tarif Bitte beachten: Spesen, Wartezeit und effektive gefahrene Kilometer werden nur in der Buchhaltung erfasst, d.h. nachdem die Lieferscheine importiert wurden. Schnittstelle zwischen iTIXI und Buchhaltung Page 24 5. Anhang 1: Objekt Eigenschaften 5.1 Fahrgast Eigenschaften In jeder Export-Datei (CSV, XML) sind mehrere Fahrgast-Objekte mit Eigenschaften gespeichert. Eigenschaft Name Grund-Type (MySQL) Bemerkung person_id INTEGER Fremdschlüssel, ID des Persons title VARCHAR Wohnadresse: Anrede (NULL, Herr, Frau, Dr. ...) firstname VARCHAR Wohnadresse: Vorname(n) des Persons lastname VARCHAR Wohnadresse: Familienname des Persons street VARCHAR Wohnadresse: Strasse Leerzeichen Nummer postalCode_city VARCHAR Wohnadresse: Postleitzahl Leerzeichen Ortsname country VARCHAR Wohnadresse: Land discr TEXT Unterscheidet Personen wie: „passenger“ (Fahrgast) „custodian“ (Vormund) „driver“ (Fahrer) custodian_id VARCHAR Fremdschlüssel (INTEGER), referenziert den Vormund (person_id), oder ist NULL (kein Vormund). isActive VARCHAR Ist Aktiv (TRUE) oder nicht (FALSE) isInWheelChair VARCHAR Hat Rollstuhl (TRUE) oder nicht (FALSE) hasMonthlyBilling VARCHAR Hat Monatsrechnung (TRUE) oder nicht (FALSE) entryDate VARCHAR Eintrittsdatum in den TIXI Verein dd.mm.yyyy oder NULL. Bitte beachten: Nach person_id aufsteigend sortiert. Schnittstelle zwischen iTIXI und Buchhaltung Page 25 5.2 Fahrt Eigenschaften In jeder Export-Datei (CSV,XML) sind keine, eine, oder mehrere Fahrt-Objekte gespeichert. Jedes Fahrt-Objekt ist mit einem Fahrgast verknüpft. Eigenschaft Name Grund-Type (MySQL) Bemerkung drivingOrder_id BIGINT Primärschlüssel, ID der Fahrt pickUpDate VARCHAR Abfahrt: Datum (dd.mm.yyyy) pickUpTime VARCHAR Abfahrt: Zeit (hh:mm) orderStatus VARCHAR Status der Fahrauftrag (Fahrt): PENDING pendent COMPLETED ausgeführt CANCELED annuliert passenger_id INTEGER Fremdschlüssel, ID des Fahrgastes, entspricht Person_id in Kapitel 5.1 start_street VARCHAR Abfahrt: Strasse Nummer start_postalCode_city VARCHAR Abfahrt: Postleitzahl Ort start_countery VARCHAR Abfahrt: Land target_street VARCHAR Ankunft: Strasse Nummer target__postalCode_city VARCHAR Ankunft: Postleitzahl Ort target_country VARCHAR Ankunft: Land distance DOUBLE Gefahrene Kilometer (mit dem Kunden) companion INTEGER Anzahl Begleitpersonen (0, 1, 2, ...) zone VARCHAR Zone, siehe Kapitel 4 pois VARCHAR Details zu keine, eine oder mehrere „Orte von Interesse“ die angefahren wurden, z.B. (OVI1)(OVI2). Diese Details werden von einzelne Kunden für Rückvergütungen von Versicherungsleistungen benötigt. Bitte beachten: Sortierung: pickUpDate (aufsteigend) und pickUpTime (aufsteigend). Schnittstelle zwischen iTIXI und Buchhaltung Page 26 5.3 Eigenschaften und Tarifgestaltung Für die Erstellung einer Monatsrechnung für ein Fahrgast müssen die folgenden Bedingungen erfüllt seit: 1. (Fahrgast.hasMonthlyBilling == TRUE) and 2. (Fahrt.passenger_id == Fahrgast.person_id) and 3. (Fahrt.orderStatus == COMPLETED) and 4. (Fahrt.drivingOrder_id != NULL) Falls erwünscht, kann jeden Fahrgast auch die Kantonale und Angrenzende Fahrten als Bargeldzahlung in der Debitorenbuchhaltung zugeordnet werden. Der aufmerksame Leser hat sofort bemerkt, dass es in Kapitel 4.3.1 keine Tarife für isInWheelChair (Rollstuhl-Tarif) noch entryDate (Kundentreue-Tarif) hat. Selbstverständlich soll auch dies in der Buchhaltung möglich sein. Alle Eigenschaften können für die Tarif-Gestaltung herangezogen und in der Tabelle aus Kapitel 4.3.1 implementiert werden, z.B. Ortsname. Beispiel: Für Kunden in Cham müsste ein Tarif von CHF 5.- pro Fahrt verrechnet werden. Für Kunden in Hünenberg und alle andere Gemeinden angrenzend an Cham müsste ein reduzierte Tarif von CHF 2.- pro Fahrt verrechnet werden, um die Mehr-Kilometer (siehe oben) zu kompensieren. Politisch und fiskalisch nennt sich das ein „Quid pro quo“ Tarif. Schnittstelle zwischen iTIXI und Buchhaltung 6. Anhang 2: Datei Formate Die iTIXI Buchhaltungsschnittstelle erzeugt (exportiert) zwei Dateiformate: Comma Seperated Values (CSV) und Excel 2003, XMLSS Format (XML). 6.1 Dateinamen Die Standard-Dateiname (default) lautet Mandant.Lieferscheine.YYYYMMDD.HHMMSS.mmm.extension Mandant Lieferscheine YYYYMMDD HHMMSS mmm extension variabele Text, z.B. TIXI24 (Test-Kunde), TIXIZUG fixe Text Jahr (2014), Monat (11), Tag (04) Stunden (10), Minuten (39), Sekunden (15) Milisekunden (999) “xml” oder “csv” 6.2 Datei-Format Comma Seperated Values (csv) Eine Tabelle (Zeilen, Spalten) mit Text Felder. Erste Zeile mit Spalten-Überschriften. Keine, eine, mehrere Zeilen mit Daten. Zeichensatz UTF-8. Jeder Spalte mit semi-colon(;) Zeichen getrennt. Enclosures mit double-quote(“) Zeichen sind keine vorhanden. Alle Zeilen werden mit CRLF abgeschlossen. Dieses Format wird für die BUSPRO Schnittstelle verwendet. Muster-Datei: Page 27 Schnittstelle zwischen iTIXI und Buchhaltung Page 28 6.3 Datei-Format Microsoft Excel 2003 (xml) Dateiformat Excel 2003 (XMLSS) Workbook mit zwei Worksheets o Sheet1: Personen o Sheet2 Fahrten für Monat xx – Jahr xxxx Bitte beachten: Excel kann als Drehscheibe zum Exportieren in anderen Formate verwendet werden. Schnittstelle zwischen iTIXI und Buchhaltung Page 29 7. Anhang 3: Einschränkungen 7.1 TIXI ZUG TIXI ZUG gestaltet seine Tarif-Zonen als „kantonal“ (Kanton Zug) und „angrenzend“. Momentan (2014) gilt folgendes: 7.2 BUSPRO fahrgast_id: BUSPRO hat maximal 8 Stellen, iTIXI hat 11 Stellen. BUSPRO erwartet in jeder Zelle ein Wert, d.h. 0 oder „0“ (nicht null).
