Status: Arbeitsfassung
Dokumentenhistorie:

Grundsätzliches

Motivation

Die Velometrik GmbH unterhält Produktdatenbanken mit Produkten, die für die Ergonomie rund um das Radfahren von Bedeutung sind. Sie enthalten die für eine Produktbewertung aus ergonomischer Sicht wichtigen Produkteigenschaften. Dazu wurden und werden Bewertungsregeln entwickelt, die ergonomische Anforderungen mit bestimmten Produkteigenschaften verknüpfen. Die Tatsache, daß die Produkteigenschaften und nicht die Produkte selbst bewertet werden, sichert ein hohes Maß an Objektivität.

Die Bewertungsregeln sind das Ergebnis von Erfahrungen sowie von Forschungen – eigenen und solchen von verschiedenen Partnern.

Da die ständige Verbesserung der Bewertungsregeln, ebenso wie die ständige Weiterentwicklung der Produkte permanente Änderungen nach sich ziehen, stellt die Velometrik GmbH Interessenten diesen Webservice zur Verfügung, direkt oder indirekt als spezielle Anwendung¹ zur Verfügung, wodurch der Nutzer immer die neuesten Produkte anhand der neuesten Methoden auswählen kann, ohne dafür Softwareupdates installieren zu müssen. Während sich die Verfahren und die Produkte ständig weiterentwickeln können, bleibt der Webservice selbst in seiner Funktionsweise unverändert.

Technisches

Der Webservice benutzt das HTTP-Protokoll. Clientrequests nimmt er i.allg. als HTTP GET Anforderung entgegen.

Die Antworten kommen i.allg. als JSON-Objekte oder -Arrays (s. www.json.org). Das sind Zeichenketten, die mit { bzw. enden. JSON-Objekte sind eine (von haus aus ungeordnete) Menge von Schlüssel/Wert-Paaren. Arrays enthalten im Gegensatz dazu ausschließlich (geordnete) Werte, die bei der Verarbeitung über ihre Position mittels eines Index ansprechbar sind. JSON-Objekt und JSON-Array werden im folgenden zusammengefaßt als JSON-Konstrukt bezeichnet. Beginnt die Antwort statt mit einem der beiden öffnenden Klammersymbole mit einer natürlichen Zahl, dann repräsentiert diese Zahl einen Fehlerkode. Es folgt ein Leerzeichen und der Rest der Antwort beschreibt den Fehler. Die Fehlertexte sind, weil nur für den Softwaretest gedacht, ausschließlich in englisch. Eine Ausnahme ist der Fehler 5, der den jeweiligen Status von ungueltigen oder fehlenden Kundenantworten als JSON-Objekt bereitstellt.

Eine Reihe von Werten in den JSON-Konstrukten kommen sowhl als code- als auch als text-Eintrag. Während der Kode der internen Verarbeitung dient, benutzt man den Text zum Anzeigen in der gewünschten Sprache. Die Texte sind in utf-8 kodiert.

Erläuterungen zum Datenmodell

Begriffsdefinitionen

Ein Produkt ist ein Gegenstand, der unter vorwiegend ergonomischen Gesichtspunkten zum Kauf ausgewählt wird. Es gehört zu genau einer Produktart. Für alle Produkte einer Produktart sind dieselben Eigenschaften von Bedeutung. Es handelt sich zuerst um Eigenschaften, die eine Produktbewertung unter ergonomischen Gesichtspunkten erlauben, aber auch um Eigenschaften, die Geschmacksfragen berücksichtigen (z.B. Design).

Ein Modell umfaßt eine Reihe von weitestgehend identischen Produkten einer Produktart, die sich nur in ihren Abmessungen unterscheiden.
Achtung ! Das ist nicht unbedingt das, was der Hersteller eines Produktes unter einem Modell versteht!

Eine (austauschbare) Komponente ist eine zu einem Produkt gehörende Einheit, die mit verschiedenen Produkten einer bestimmten Produktart bestückbar ist. Da dies i.allg. nicht alle Produkte einer Produktart sind oder sein können, wird für jedes Produkt eine bestimmte Vorauswahl getroffen.
Normalerweise gibt es an einem Fahrrad nur eine Komponente je Produktart. Um jedoch Sonderfälle wie Tandems (mit je zwei Satteln und Lenkern) ebenfalls abdecken zu können, werden Komponentenarten definiert. Eine Komponentenart gehört zu genau einer Produktart. Es kann aber mehrere Komponentenarten je Produktart geben.

Bewertungsfilter

Feste Bewertungsfilter

Die vergleichende Produktbewertung erfolgt immer innerhalb einer Produktart, mit den folgenden Optionen:

• Es werden alle aktiven² Produkte einer Produktart bewertet.
  Die Eigenschaft aktiv wird von Velometrik gesetzt.

• Es werden nur die zu einem Modell gehörenden, aktiven Produkte bewertet.

• Es werden nur die als Komponente eines Produktes vorgesehenen, aktiven Produkte bewertet.

Vom Händler konfigurierbare Bewertungsfilter

• Der Händler kann für alle seine Arbeitsstationen die für die Bewertung zu berücksichtigenden Produkte festlegen (individuelle Produktauswahl). Berücksichtigt werden davon alle aktiven Produkte.

• Der Händler kann für eine einzelne Arbeitsstation festlegen, welche Marken bewertet sollen. Es werden dann alle Produkte dieser Marke bewertet (nicht nur die der individuellen Produktauswahl).

Zusätzlich gilt die Beschränkung

Ablauf der Produktbewertung

Die Kommunikation zwischen Client und Server läuft wie folgt ab:

1. Der Client fordert ein Abfrageformular an. Das enthält alle für die Produktauswahl innerhalb bestimmter Produktarten zu stellenden Fragen in einer bestimmten Sprache.

2. Der Server liefert die Fragen in der gewünschten Sprache, zuzüglich weiterer Informationen:

   • Datentyp der Antwort

   • Die Antwortvorgaben bei dem entsprechenden Antworttyp

   • Muß die Frage zwingend beantwortet werden ? (Pflichtfrage)

   • Gibt es Erläuterungen zu der Frage ?

   • Die anfangs leere Antwort und das Ergebnis ihrer formalen Überprüfung (anfangs ebenfalls leer)

3. Der Client nimmt die Antworten vom Benutzer entgegen.
   Die vom Server übergebenen, zusätzlichen Informationen zu jeder Frage reichen aus, um die Antworten lokal auf Vollständigkeit und die numerischen Angaben hinsichtlich einer gültigen Zahleneingabe zu prüfen.

4. Der Client schickt die (möglichst geprüften) Antworten mit der Angabe der Produktart, innerhalb derer Produkte hinsichtlich der gegebenen Antworten zu bewerten sind, evtl. mit einer Filteroption an den Server.

5. Der Server bewertet die ihm bekannten, aktiven Produkte und schickt das Ergebnis an den Client.

6. Es kann mit einer anderen Produktart oder modifizierten Antworten bei Punkt [l] weitergehen.

7. Der Benutzer entscheidet sich für ein Produkt, oder er bricht die Produktauswahl clientseitig ab.

Anforderungen und Antwortobjekte

Eine GET-Anforderung

Die URL beginnt, wie üblich, mit Protokollbezeichnung, Servername und Port, gefolgt von dem Servicenamen /vmkservice, z.B. http://morpheus.prodam.at:8015/vmkservice, was in den folgenden Beschreibungen der einzelnen Anforderungen durch drei Punkte ... symbolisiert wird.

Eine POST-Anforderung

HTTP-POST-Anforderungen werden benutzt, um größere Datenblöcke (z.B. Druckbilder) an den Webservice zu übergeben. Deren Aufbau wird für jede Anforderung getrennt spezifiziert.

/info: Anforderung allgemeiner Informationen

Einige, in dieser Spezifikation zwecks beliebiger Erweiterbarkeit offen gelassen Festlegungen lassen sich mit der Info-Anforderung erfragen. Bislang sind die folgenden Informationen abrufbar:

Die GET-Parameter:

Hinweis: Wenn mit dem Request eine ws_id übergeben wurde, dann ist die zugehörige station_nr implizit ebenfalls gegeben.
Hinweis: Aus Performanzgründen ist es i.allg. keine gute Idee, Info-Requests vor jeder Bewertung aufzurufen. Ihr Aufruf sollte sich auf das Hochfahren der Anwendung, und bei länger laufenden Anwendungen auf tägliche Aktualisierungen beschränken.

Herstellerauswahl als JSON-Objekt:

/start: Anforderung eines Abfrageformulars

Die GET-Parameter:

Beispiel: Anforderung eines Abfrageformulars für Sattel und Lenker

.../start?lang=deu&produktart=sattel&produktart=lenker

Das Eingabeformular als JSON-Array:

Wie man sieht, werden bereits Platzhalter für die Antworten mitgeliefert, damit das nach der Umwandlung in das von der benutzten Programmiersprache abhängigem Format sofort zur Verfügung steht.

/bewerten: Anforderung einer Produktbewertung

:

Die Parameter umfassen die Fragecodes aller beantworteten Fragen mit den Antworten als Wert, sowie einiger Steuerparameter, vor die # gesetzt wird, um zufällige Übereinstimmungen mit einem Fragecode zu vermeiden.

Je nach gewünschtem Bewertungsfilter, sind genau die hier aufgeführten Parameter anzugeben. Bei Angabe einer hier nicht aufgeführten Kombination ist das Verhalten des Webservice undefiniert.

Die Angabe einer Emailadresse ist optional. Wenn sie nicht angegeben wurde, können keine Antworten gespeichert werden. Zum anonymen Speichern kann die beim Speichern des Druckbildes zurückgegebene, anonyme Emailadresse verwendet werden.

Beispiel: Anforderung einer Produktbewertung für alle Sattel

.../bewerten?%23artcode=sattel&sitzknochenabstand=12&geschlecht= ...

hinweise gibt es in Abhängigkeit von der Produktart der bewerteten Produkte.

Hinweis: Geplant sind Einstellhinweise für die Produktart .

Zum Umgang mit der Produktbewertung:

Jedes Produkt erhält eine Bewertung, die seine Eignung in Prozenten bzgl. der übergebenen Antworten wiedergibt. Diese Zahlen können intern für die Anwendungsentwicklung verwendet werden, sie sollten allerdings nicht anzeigt werden, weil ihre Interpretation einer Erklärung bedarf. Ohne diese nachfolgend gegebene Erklärung sind sie eher irritierend, weil die Produkte mit ihrer Bewertung meist schlechter erscheinen als sie es tatsächlich sind.

• Ein Produkt mit der Bewertung 0 ist aus ergonomischer Sicht für den Kunden unbrauchbar.

• Der Einsatz eines Produktes mit der Bewertung 1 ist möglich aber nicht zu empfehlen.

• Ein Produkt mit einer Bewertung ab ca. 10 ist grundsätzlich einsetzbar.

• Ein Produkt mit einer Bewertung ab ca. 30 ist bereits recht gut geeignet.

• Ein Produkt mit einer Bewertung ab ca. 50 gehört zu den Favoriten.

• Ein Produkt mit einer Bewertung ab ca. 90 besitzt keine nennenswerten Einschränkungen.

Die Bewertung wird nach den üblichen Regeln auf ganze Zahlen gerundet, mit einer Ausnahme: Bewertungen  > 0 werden immer auf 1 aufgerundet. Das ermöglicht die Unterscheidung zwischen unbrauchbaren und nicht zu empfehlenden Produkten.

Für die Anzeige ist statt der Bewertung das Ranking vorgesehen. Das mit 1 beginnende Ranking definiert die Reihenfolge der Produkte ihrer Eignung entsprechend. Produkte mit derselben Bewertung haben zwangsläufig dasselbe Ranking. Ungeeignete Produkte erhalten das Ranking 0, was als Ausschluß vom Ranking gelesen werden kann.

Die Produkte sind nach Ranking und (bei selbem Ranking) nach Typ sortiert, was sich überdies in ihrer laufenden Nummer ausdrückt. Produkte mit dem Ranking 0 stehen am Ende der Liste.

Der Client sollte eine Bewertung nach Möglichkeit mit formal geprüften Antworten anfordern. Tut er das nicht, und sind die Antworten fehlerhaft, dann antwortet der Webservice mit dem Fehler 5, dem ein JSON-Objekt mit dem Fragecode als Schlüssel und dem Antwortstatus als Wert folgt. Enthalten sind nur die fehlerhaften Antworten.

Der Client hat außerdem dafür zu sorgen, daß bei einer Bewertungsanforderung für ein Modell oder eine Komponente dieses Modell bzw. die Komponente tatsächlich existiert. Sollte das nicht der Fall sein, ist das Ergebnis nicht definiert.

Anforderung einer Produktabbildung

(Nicht mehr in dieser Version)

Das geschieht momentan noch außerhalb des Webservice über einen gesonderten HTTP-Server. Schlüssel ist die vmkid, d.h. die Bilder tragen den Namen <vmkid>.jpg.

/produkt: Anforderung von Produktdaten

Die GET-Parameter:

Zurückgegeben wird ein JSON-Array mit JSON-Objekten, die die Schlüssel ’eigenschaft’ und ’wert’ haben. Wenn es das Produkt nicht gibt, oder keine Eigenschaften erfaßt wurden, ist das Ergebnis ein leeres Array (’[ ]’).

/antworten: Anforderung von gespeicherten Kundenantworten

Die Anforderung erfolgt mittels .../antworten?email=<emailadresse>.

Das zurueckgegebene JSON-Objekt ist leer, wenn die Emailadresse unbekannt ist, oder noch keine Antworten zu dieser Emailadresse gespeichert wurden.

/dbld: Speichern eines Druckbildes und Versand als Email

Die Datenübergabe an den Webservice erfolgt hier als POST-Request. Vor den eigentlichen Druckwerten stehen einige Kopfzeilen:

1. Zeile: "’dbld <station_nr>"’

2. Zeile: "’[<emailadresse>]"’ (darf leer sein)

3. Zeile: "’<n_zeilen>,<n_spalten>"’

4. Zeile: Zeile n der Druckwerte beginnend mit der 1. Spalte

5. Zeile: Zeile n-1 der Druckwerte ...

Die Druckwerte sind durch ein einzelnes Leerzeichen voneinander getrennt. Das Druckbild wird für den Kunden mit der angegebenen Emailadresse gespeichert. Wurde keine Emailadresse übergeben, dann wird zum Speichern pro forma eine solche erzeugt. Zurückgegeben wird die zum Speichern benutzte Emailadresse. Erst danach wird der Emailversand gestartet, natürlich nur sofern eine Emailadresse mitgeliefert wurde. Das heißt, ein erfolgreiches Ende dieses Requests bedeutet nicht automatisch den erfolgreichen Emailversand.

Der Versandstatus wird in der Datenbank festgehalten, so daß gescheiterte Sendeversuche später prinzipiell wiederholbar sind.

/set: Einstellungen für eine Station speichern

Historisches

/set war ursprünglich nur dafür gedacht, individuelle Einstellungen eines Händlers für seine Arbeitsstation zu speichern. Später wurde es notwendig, für das Zusammenspiel von Webanwendung und Arbeitsstation automatisch Informationen von der Arbeitsstation an den Webservice zu senden, die dieser wiederum der Webanwendung zur Verfügung stellt. Während anfangs nur einzelne Werte übertragen werden mußten, wurden es später auch zusammengesetzte Informationen.

Die GET-Parameter:

Für what ist bislang vorgesehen:

• hersteller: Dazu wird eine durch Komma getrennte Liste von Herstellerkodes erwartet. Zusätzliche Leerzeichen dürfen nicht enthalten sein. Die Herstellerkodes kann man mit /info erfragen.

• stationhersteller: true oder false um die Verwendung der Herstellercodes als Filter ein- bzw. auszuschalten.

• local_ip : um die IP-Adresse mitzuteilen, über die die Arbeitsstation im LAN erreichbar ist.

• stationsinfo : um Statusinformationen als JSON-Objekt mitzuteilen:

  • features Spezielle Features der Stationssoftware (Array). (Diese Features können nicht der Stationsverwaltung entnommen werden, weil sie sich nach einem automatischen Update zu einem nicht genau definierten Zeitpunkt ändern können.) Aktuell:

    • vmks_proxy: Der Webservice wird über http://<local_ip>/vmkservice umgeleitet.

    • ws_tunnel: Die URL ws://<local_ip>/messages ist in Wahrheit ein Websockettunnel zum eigentlichen Websocket Server.

  • local_ip: Erübrigt das Mitteilen der local_ip mit einem weiteren /set.

  • konfiguration: Lokale Einstellungen an der Arbeitsstation. (noch nicht weiter definiert)

Verschlüsselte Anforderungen

Die oben beschriebenen unverschlüsselten Anfragen sind nur im Intranet erlaubt. Im Internet hingegen sind nur verschlüsselte Anfragen erlaubt, mit denen folgendes erreicht werden soll:
Unterbinden von nicht authorisierten Anfragen
Abfischen vom Emailadressen verhindern

Verschlüsselt werden nur die Requestparameter, die danach wie folgt vereinheitlicht erscheinen:

Die GET-Parameter:

Die Parameter werden also weiterhin genau so, wie bei den einzelnen Requests beschrieben , erstellt, danach verschlüsselt und die von der Verschlüsselung erzeugten Binärdaten werden hexadezimal kodiert. Für die Verschlüsselung steht eine Referenzimplementierung in C zur Verfügung. Jede Station besitzt ihren eigenen Schlüssel, der auch beim Webservice hinterlegt ist.

Beim Speichern eines Druckbildes werden nur die Zeilen 2 und 3 des PUT-Requests verschlüsselt. In der Zeile 2 steht dann

hdr <verschluesselte_zeilen_2_und_3>.

Die weiteren Zeilen rücken nach.

Serviceinterne Informationen

Für die Fehlersuche kann in einem Webbrowser .../inspect aufgerufen werden. Die dafür interessanten, ausführlichen internen Informationen gibt der Webservice allerdings nur bei lokalen Anfragen und bei Anfragen aus dem Intranet heraus. Zur Fehlersuche auf einem im Internet agierenden Webservice ist eine Anmeldung mit ssh erforderlich. Dann kann ein Textbrowser wie z.B lynx zum Einsatz kommen.

Ergänzungen für Browserclients

Mit der Version 1.1 wurde der Ergonomiewebservice um die für Browserclients erforderliche Sessionverwaltung ergänzt. Browserclients können verschieden verwendet werden, wovon schließlich abhängt, was sie mit dem Webservice tun dürfen. D.h. neben der Sessionverwaltung gibt es nun auch ein Rechtekonzept. Um dieses zu erläutern, bedarf es zunächst einiger Begriffsdefinitionen.

Begriffe

Abstrakte Begriffe

• Arbeitsstation: Eine Arbeitsstation ist eine Hardwareeinheit, an die direkt Meßtechnik angeschlossen werden kann. Sie kommuniziert mit dem Webservice i.a. mit einer symmetrischen Verschlüsselung ohne Schlüsseltausch über das Internet.

• Html- oder virtuelle Station: Eine Html- oder virtuelle Station ist eine Station, deren Bedienoberfläche mit HTML5 und Javascript realisiert wurde. Sie benötigt i.a. einen Webserver mit HTTPS.

• Interne/Externe Station: Eine interne Station ist eine Htmlstation, die sich im selben Intranet (192.168.*, 10.*) wie der zugehörige Webserver befindet. Alle anderen Stationen sind externe Stationen (im Internet).

• Händlerstation: Eine Händlerstation ist eine Htmlstation, die der Händler benutzt.

• Endkundenstation: Eine Endkundenstation ist eine Htmlstation, die der Endkunde eines Händlers benutzt.

• Portalserver: Der Portalserver ist der Webserver einer Htmlstation, die ihrerseits den Webservice nutzt.

• Öffentliche/Private Station: An einer öffentlchen Station ist bei der Anmeldung das Passwort gleich dem Benutzernamen. Wenn das nicht so ist, handelt es sich um eine private Station.

• Verifizierte Email(adresse): Ein Endkunde kann prinzipiell immer eine falsche Emailadresse angeben. Das läßt sich nicht verhindern. Deshalb darf er, nur mit einer Emailadresse ausgestattet, keine zugehörigen Daten abrufen. Dazu muß die Emailadresse verifiziert werden, etwa indem er an genau diese Emailadresse ein Passwort zugesendet bekommt, mit dem er sich vor dem Abrufen der Daten anmelden muß.

• ws_id: Die ws_id (WebserviceId) ist die SessionId einer vom Webservice erstellten Session.

Mit dem Webservice verbundene Webportale

• Stationsportal: Einstiegspunkt für Händlerstationen

• sitzknochen.de: Velometrik Onlineshop mit Ergonomieberatung (Endkundenstation, geplant)

• Händlerportal: Verwaltungs- und Auswertungswerkzeug für Händler, auf dieselbe Datenbank wie der Webservice zugreift, ohne ihn direkt zu benutzen.

• www.sitzknochen.de: Endkundenstation von Velometrik

• Ergonomieportal: Zugang für Endkunden mit eigener Sessionverwaltung ohne feste Verknüpfung mit einem bestimmten Händler

• Stationsverwaltung: Velometrikinternes Verwaltungstool für alle Stationen, das die erfaßten Stationsdaten auf die Datenbanken verteilt, die diese Daten benötigen

Hinweis: Nur das Stationsportal und sitzknochen.de benutzen das Ergonomieportal direkt. Alle anderen Webportale sind mit dem Webservice nur indirekt dadurch verbunden, daß sie dieselbe Produktdatenbank verwenden bzw. bedienen.

Grundsätzliches

Die Einbindung des Webservice in eine Webanwendung erfolgt clientseitig in Ajax-Manier, mit dem einzigen Unterschied, daß statt XML das JSON-Format Verwendung findet.
Htmlstationen sind abstrakte, von Velometrik definierte Einheiten. Sie haben wie die Arbeitsstationen eine Stationsnummer zur Identifikation, die aber nur intern Verwendung findet. Extern werden sie über den Namen des Portalusers identifiziert, mit dem man sich unter Benutzung des zugehörigen Passworts anmeldet. Außerdem ist von vornherein festgelegt, ob es sich um eine Händler- oder um eine Endkundenstation handelt. Aus Sicherheitsgünden ist auch festgelegt, welcher Portalserver diese Station benutzen darf. Das wird mit dem CORS-Protokoll (Cross Origin Ressource Sharing) vom Browser überwacht. Statt der dem Benutzer i.a. nicht bekannten Stationsnummer wird mit der als Cookie übergebenen ws_id gearbeitet, an die webserviceseitig weitere Informationen gebunden sind.
Darüber hinaus akzeptiert der Webservice im Internet nur HTTPS.

Es folgt eine Übersicht der für eine HTML-Station erforderlichen Daten:

• Stationsnummer: Velometrikinterne eindeutige Kennung

• Portaluser/Passwort: für die Anmeldung einer HTML-Station

• Portalserver: Name des für die Auslieferung der HTML-Seiten zuständigen und dazu zum Zugriff auf den Webservice berechtigten HTTP-Servers. Das betrifft sowohl den direkten Zugriff als auch den Zugriff mittels XMLHttpRequest.

• Stationsart: Händler- oder Endkundenstation

Hinweis: Da es mittlerweile Browser-Voreinstellungen gibt, bei denen auch mit CORS-Protokoll keine Cross Origin Zugriffe mehr möglich sind, wird der Webservice zukünftig serverseitig in die Domäne der Webanwendung umgeleitet. Die Zuordnung des Portalservers zur Station ist aus anderen Gründen weiterhin erforderlich.

Zusätzliche Requests

/login: Eine Session anlegen

Historisches

Die Anmeldung wurde notwendig, um virtuelle Arbeitsstationen, d.h. Stationen ohne eigene, vom Webservice identifizierbare Hardware zu ermöglichen. Praktisch handelt es sich dabei um Web-(Browser-)anwendungen. Der Webservice wird hierbei als XMLHttpRequest eingebunden. Ursprünglich sollten Browseranwendung und Webservice von voneinander unabhängigen Servern kommen, was jedoch aufgrund verschärfter Sicherheitsrestriktionen zunehmend schwieriger wurde, so daß der Entschluß fiel, ihn mit dem Apache-Modul mod_proxy in die Webanwendung einzubinden. Für den Browser befindet er sich damit auf demselben Server, obwohl er tatsächlich immer noch auf einem anderen Server laufen kann. Bei den (Apache2-) Webanwendungen ist das Umstellen problemlos möglich (mod_proxy), nicht aber bei den Arbeitsstationen mit ihrem Stationsproxy. Bis alle in Betrieb befindlichen Arbeitsstationen umgerüstet sind, werden deshalb alte Vorgehensweisen weiterhin unterstützt.

Cookies

Wie allgemein üblich erfolgt die Identifizierung der Websession mit einem Cookie, der ws_id. Dieses Cookie ist an den ausgebenden Server und innerhalb von dessen Verzeichnisstruktur an einen festen Pfad gebunden. Das ist zu beachten, sobald der Webservice über einen Proxy umgeleitet wird. Speziell bei der Arbeitsstation sind eine Reihe von Problemen zu lösen:

• Beim Anmelden an den Webservice von einer Browseranwendung ist i.a. nicht bekannt,

  • ob es überhaupt eine physikalische Arbeitsstation gibt,

  • ob diese vom Browser aus erreichbar ist,

  • ob die Stationssoftware die Umleitung des Webservice unterstützt.

• Nach erfolgreichem Anmelden und Empfang der lokalen IP (local_ip) der Arbeitsstation sowie deren Softwarefeatures muß zur Vermeidung von Cross-Origin-Problemen alles (Stationsportal und Webservice) auf den Stationsproxy der Arbeitstation weitergeleitet werden, über den dann auch die gesamte Kommunikation mit dem Internet erfolgt. Bei dieser Weiterleitung jedoch kann das empfangene Cookie nicht mitgenommen werden.

Zweistufiges Login

Wenn aufgrund eines Serverwechsels nach der Anmeldung ein Cookie evtl. nicht mitgenommen werden kann, kommt ein zweitufiges Anmeldeverfahren zum Einsatz. Der Webservice liefert dann als Antwort (nicht als Cookie!) eine login_id, die bei der Weiterleitung als Parameter weitergegeben wird. Das ist nur als GET- oder POST-Parameter möglich. Mit dieser login_id muß sofort die zweite Loginstufe ausgeführt werden. Sie verliert danach gemeinsam mit dem ursprünglichen Cookie ihre Gültigkeit. Sie verliert ihre Gültigkeit auch dann, wenn statt der 2. Loginstufe ein anderes Request ausgeführt wird oder wenn zu viel Zeit vergangen ist.

Login-Szenarien

Es folgt die Beschreibung der Abläufe beim Anmelden unter den verschiedenen Bedingungen.

Abläufe aus Sicht der Webanwendung bei einer Händlerstation

Es wird angenommen, daß die Webanwendung eine Anmeldeseite hat, bei deren Aufruf der aktuelle Anmeldestatus erfragt und in Abhängigkeit vom Ergebnis entschieden wird, wie weiter zu verfahren ist.
Der aktuelle Anfragestatus wird mit /ping erfragt. Danach geht es wie folgt weiter:

• Pingstatus pong oder unknown ⇒ (Neu)Anmeldung erforderlich

• Pingstatus logged_in ⇒ Prüfen, ob Arbeitsstation vorhanden und erreichbar

  • local_ip in der Pingantwort ⇒ Prüfen, ob Arbeitungsstation tatsächlich erreichbar ist

    • Arbeitsstation ist erreichbar und ...

    • Arbeitsstation ist nicht erreichbar ⇒ Nach Rückfrage weiter direkt zur Produktberatung ohne Arbeitsstation

  • Keine local_ip in der Pingantwort ⇒ Weiter direkt zur Produktberatung ohne Arbeitsstation

• Sonstiger Pingstatus ⇒ Fehler

• Händlerstation ohne physikalische Arbeitsstation

• Händlerstation mit physikalischer Arbeitsstation

  • Station ist erreichbar

    • Webservice ist auf den Stationsproxy umgeleitet

    • Webservice wird direkt angesprochen

  • Station ist nicht erreichbar

Abläufe aus Sicht der Webanwendung bei einer Endkundenstation

Anmeldevarianten aus Sicht des Webservice

Der Webservice muß anhand der ihm übergebenen (GET-) Parameter und den ihm bekannten Informationen über die sich anmeldende Station entscheiden, wie vorzugehen ist.

1. portaluser/passwort sind angegeben. ⇒ Es handelt sich um die 1. Loginstufe.

   1. Der Portaluser ist mit dem angegebenen Passwort bekannt und es handelt sich um eine Händlerstation.

      1. Die zugehörige physikalische Arbeitsstation hat sich u.a. mit ihrer local_ip beim Webservice gemeldet.

         1. Die Arbeitsstation hat den Webservice in ihre eigene Domäne umgeleitet. (Sie hat dem Webservice das Feature vmks_proxy gemeldet.) ⇒ Zweistufiges Login ist erforderlich.
            Die login_id wird zurückgegeben.

         2. Die Arbeitsstation kümmert sich nicht um den Webservice, der weiter direkt über das Internet angesprochen wird. ⇒ Die Anmeldung ist aus Sicht des Webservice beendet.
            Die ws_id wird als Cookie zurückgegeben.

      2. Eine local_ip ist nicht bekannt. ⇒ Es handelt sich um eine virtuelle Station.
         Die ws_id wird als Cookie zurückgegeben.

   2. Der Portaluser ist mit dem angegebenen Passwort bekannt und es handelt sich um eine Endkundenstation.
      (Das wird erst für die nächste Version spezifiziert.)

   3. Einen Portaluser mit dem angegebenen Passwort gibt es nicht. ⇒ Abbruch

2. Eine login_id ist angegeben. ⇒ Es handelt sich um die 2. Loginstufe.

   1. Es gibt eine vorbereitete Session mit dieser login_id und es handelt sich um eine Händlerstation.
      Die Session geht nunmehr an den Stationsproxy. Dazu wird eine neue ws_id als Cookie zurückgegeben. Das zuvor für das Stationsportal ausgelieferte Cookie verliert seine Gültigkeit.

   2. Es gibt eine vorbereitete Session mit dieser login_id und es handelt sich um eine Endkundenstation.
      (Das wird erst für die nächste Version spezifiziert.)

   3. Es gibt keine vorbereitete Session mit dieser login_id oder sie ist zu alt. ⇒ Abbruch

3. Die angegebenen Parameter sind ungültig.

(Alter Text)
Eine Station gehört immer einem Händler, der sich zum Anlegen einer Session mit Portaluser und dem (nur ihm bekannten) Passwort anmelden muß. (einstufige Anmeldung) Da ein Händler prizipiell mehrere Stationen haben kann, benötigt er in diesem Falle für jede Station einen anderen Portaluser.

Im Falle einer Endkundenstation muß die Anmeldung für den Endkunden mit seiner Emailadresse und seinem Passwort und für seinen Händler mit dessen Portaluser und Passwort erfolgen. Der Endkunde kennt nur seine Anmeldedaten. Die des Händlers kann und darf er nicht kennen. Damit unter diesen Umständen ein Login möglich wird, ohne ihm den hierfür notwendigen Usernamen und gar das Passwort zuspielen zu müssen, wird eine zweistufige Anmeldung verwendet. Zum leichteren Verstehen des Ablaufs, kann man sich als Portalserver einen Webshop vorstellen.

Die erste Stufe muß der Portalserver beim Ausliefern der Einstiegsseite an den Endkunden ausführen. Er nimmt Emailadresse und Passwort (sofern ein Kundenkonto existiert) entgegen und prüft, ob er diesen Kunden kennt. Eine anonyme Anmeldung ist ebenfalls möglich.

Nun schickt der Portalserver die Emailadresse (sofern bekannt) erweitert um das Prüfungsergebnis der Email mit seinen Anmeldedaten an den Webservice. Von dem erhält er eine login_id, die er an den Client weitergibt, und mit der sich dieser seinerseits innerhalb kurzer Zeit beim Webservice melden muß, um die Anmeldung perfekt zu machen. Die ws_id der Session wird sowohl dem Client als auch dem Portalserver mitgeteilt. Letzterer benötigt diese SessionId z.B., um den Webservice nötigenfalls nachträglich über die erfolgreiche Verifizierung der Kunden-Emailadresse zu unterrichten, die der Kunde z.B. erst beim Auslösen der Bestellung mitgeteilt hat.

Die GET-Parameter:

Zurückgegebenen wird die ws_id (Das ist die SessionId.) als Cookie.

Bei Angabe einer redirect-url erfolgt eine Weiterleitung (HTTP Status 302) an eben diese. Damit läßt sich u.U. die Browser-Beschränkung Cookies von nicht besuchten Webseiten blockieren umgehen.

Da ohne redirect-url außer der als Cookie zurückgegebenen ws_id ebenfalls keine weiteren Daten geliefert werden, ist der HTTP-Status folgerichtig 204 no data.

Sollte die Anmeldung fehlschlagen (Portaluser und/oder Passwort falsch) kommt die entsprechende Fehlermeldung ohne daß eine Umleitung erfolgt. Weil das i.a. clientseitig schlecht zu handhaben ist, kann für diesen Fall mit fail eine alternative Umleitung angegeben werden.

/ping: Anklopfen

Mit /ping werden Statusinformationen bereitgestellt, d.h. man erfährt ...

• ob der Webservice evtl. interne Probleme hat,

• ob ein Cookie gesetzt war,

• ob dieses Cookie aktuell ist, sowie

• verschiedene Informationen zur angemeldeten Station.

Dazu sind folgende Statusantworten definiert:

Zurückgegeben wird ein JSON Objekt mit dieser und weiteren Informationen zur angemeldeten Station. Es enthält folgende Schlüssel:

• status: s. obige Tabelle

• haendler: Firmenname des Händlers

• standort: Standort der Station

• optionen: Die für diese Stationen gebuchten Optionen wie Produktgruppen für die Beratung, Styles, spezielle Konfigurationen u.a.

• addons: Besonderheiten für diese Station:

  • advertisement: Diashow
    Die Dias haben eine mit beginnende laufende Nummer als Schlüssel. Innerhalb eines Dias sind folgende Schlüssel definiert:

    • image: Die Image-URL

    • title: Titel zum Dia

    • text: Text zum Dia

• lang: Sprachkode für die Station

• portalserver: Der für die Station explizit festgelegte Portalserver

• Bei einer Händlerstation kommt dazu (sofern bekannt) ...

  • local_ip: Die IP-Adresse einer Arbeitsstation ⁴ im lokalen Netzwerk.

• Bei einer Endkundenstation kommt dazu ...

  • ... in der Loginstufe 1:

    • login_id: Id zur Weitergabe an den Client für die 2. Loginstufe

    • ws_id: Duplikat der als Cookie übergebenen ws_id

  • ... in der Loginstufe 2, falls sich ein Endkunde angemeldet hat:

    • email: Emailadresse, mit der sich der Endkunde angemeldet hat

    • verified: Ergebnis der Emailverifikation

/logout: Session beenden

/logout identifiziert die zu löschende Session anhand der vom Browser als Cookie zurückgegebenen ws_id und löscht sie, so daß weitere Requests mit dieser ws_id nicht mehr bedient werden. Schließlich wird die ws_id als Cookie mit einem Verfallsdatum in der Vergangenheit zurückgegeben, was den Browser anweist, seinerseits das Cookie zu löschen.
/logout hat keine GET-Parameter.

/store: Antworten nachträglich speichern

Wenn beim Ausführen von /bewerten eine Emailadresse bekannt ist - entweder durch direkte Angabe oder aus der Session -, werden die Antworten sofort in der Datenbank gespeichert. Oft ist es aber so, daß der Kunde nicht gleich am Anfang einer Beratung seine Emailadresse preisgeben will. In einem Onlineshop will er zunächst seine Bestellung zusammentragen, ehe er tatsächlich bestellt, was i.a. die Angabe der Emailadresse erfordert.
Deshalb werden alle Antworten in den Sessiondaten festgehalten, um sie später noch speichern zu können. Das erledigt man mit /store.

Die GET-Parameter:

Nach dem Speichern werden die Anworten in der Session gelöscht. Wenn keine Emailadresse angegeben wurde, wird nur gelöscht. Das ist unbedingt notwendig, bevor in einer Händlerstation mit einer neuen Beratung begonnen wird. Andernfalls werden die Antworten des neuen Kunden mit denen seines Vorgängers vermischt gespeichert!
Da das Verifizieren der Emailadresse nur dem Portalserver möglich ist, wird dieser Parameter nur akzeptiert, wenn der Request ganau von diesem kommt. Sobald die Emailadresse verfiziert wurde, ist es dem Endkunden erlaubt, weitere Anworten (zu einem anderem Formular) abzurufen.

Verwendung der Requests aus dem vorhergehenden Abschnitt

Einschränkungen bei /antworten

In der Version 1.0 konnten von jeder Station die Kundenantworten eines jeden Kunden abgerufen werden, dessen Emailadresse bekannt war. Das ist jetzt aus Datenschutzgründen strikt reglementiert. Es gelten die folgenden Regeln: Das gesamte Regelwerk befindet sich derzeit in der Umsetzung:

• Händlerstation: Ein Händler kann nur die Antworten seiner Kunden abrufen⁵.

• Endkundenstation: Ein Endkunde kann nur seine eigenen Antworten abrufen und auch nur dann, wenn die Email verifiziert werden konnte, d.h. wenn er sich mit Email und Passwort angemeldet hat.

• Ergonomieportal (außerhalb des Webservice): Ein Endkunde kann bestimmen, welche Händler seine Daten abrufen dürfen.

• Ein Abruf der Antworten ohne Absenderangabe (Die Statio ist nicht zu ermitteln.) aus dem Internet ist nicht möglich.

Die GET-Parameter des Requests haben sich nicht geändert, weil die Stationsnummer aus dem Kontext ersichtlich ist (z.B. die Session).

Erlaubte und verbotene Requests

Die folgende Aufstellung zeigt alle möglichen Konstellationen, für die erlaubte Requests definiert sind.

Bei allen hier nicht aufgeführten Konstellationen ist kein Request erlaubt.

Es folgt eine Auflistung der erlaubten Requests für jede Konstellation:

Bei einzelnen, erlaubten Requests kann es Einschränkungen geben, die der Dokumentation dieser Requests zu entnehmen sind. Z.B. darf nur der Portalserver eine Emailadresse als verifiziert klassifizieren.

Probleme bei CORS Requests

Der Velometrik-Ergonomiewebservice wurde ursprünglich auch entwickelt, um ihn in fremde Webanwendungen mittels JavaScript XMLHttpRequest einbinden zu können. Diese Technologie wurde leider auch mißbraucht, um das Benutzerverhalten beim Internetsurfen nachzuverfolgen, so daß es nun einschränkende Einstellungen in den Browsern gibt, die das einschränken oder verhindern. Davon ist auch der Einsatz unseres Webservice betroffen.

Während es im Firefox aktuell noch möglich ist, das CORS-Protokoll (Cross Origin Ressource Sharing) einzuhalten, verursacht die Voreinstellung Websiteübergreifendes Tracking verhindern bei Apples Safari diverse Probleme.

Anhang