ALPinterface - Point

Transkript

1 ALPinterface - Point Import von Punktobjekten für ALPregio, ALPcms und outdooractive.com Document Version 1.3.4, 27/02/2012 Seite 1 von 26

2 Einführung Dieses Dokument beschreibt den Import von georeferenzierten Punktobjekten (im nachfolgenden POI, Point of Interest genannt), in das Content Management System ALPcms. Diese POIs stehen dann für die Verwendung in ALPregio Regionsportalen, dem Freizeitportal outdooractive und der outdooractive API zur Verfügung. Ein Content Management System (im nachfolgenden KundenCMS genannt), das Daten importieren möchte, implementiert dafür eine Datenschnittstelle für die Übertragung von POIs in das ALPcms. Dieses Dokument beschreibt zunächst die Funktionsweise des Datenaustausches und erläutert die beteiligten XML-Schnittstellen. Der Abschnitt Reihenfolge und Aufgaben bei der Implementierung gibt einen Überblick über den Ablauf der Implementierung und im Abschnitt Problembehandlung werden bekannte Lösungsmöglichkeiten aufgeführt. Am Ende des Dokumentes sind XML Beispiele aufgeführt, die neben dem XML Schema als Dateien zur Verfügung stehen. Seite 2 von 26

3 Datenaustausch Der Datenaustausch erfolgt über XML Schnittstellen, die über http erreicht werden können. Das ALPcms kann zur Synchronisierung jederzeit POIs beim KundenCMS abrufen: KundenCMS ALPcms XML Datei mit POI(s) Das KundenCMS ruft die AlpInterface URL mit einer Liste von IDs und einem CMS Key auf, um POI Änderungen zu melden oder neue POIs zu übertragen. ALPcms holt anschließend die Daten der POIs ab, die in der ID-Liste aufgeführt wurden KundenCMS alpinterface?key=kundencms&ids=12,13 ALPcms XML Datei mit POI(s) Dieser Aufruf ist unter Umständen zeitlich verzögert (asynchron). Seite 3 von 26

4 Schnittstellen Das KundenCMS implementiert folgende Schnittstelle, die über http erreichbar ist: Get POIs Parameter ids ist komma getrennte Liste von einer oder mehreren IDs, z.b.: 1920 oder 1920,1921,1922 (die ID Liste umfaßt maximal 100 Ids) Liefert die Daten für alle POIs der Liste Für gelöschte POIs wird workflow auf deleted gesetzt Für nicht vorhandene POIs wird error auf not-found gesetzt Beispiel-URL: ALPcms stellt folgende Schnittstellen über http zur Verfügung, die es dem KundenCMS ermöglichen, die Aktualisierung bestimmter POIs zu initiieren: Update POIs nach ID Parameter ids ist komma getrennte Liste von einer oder mehreren ids, z.b.: 1920 oder 1920,1921,1922 ALPcms ruft anschließend die Schnittstelle Get POIs beim KundenCMS mit dieser ID-Liste auf die ID Liste darf maximal 100 IDs umfassen Beispiel: Seite 4 von 26

5 POI XML Das KundenCMS liefert über die oben beschriebene Schnittstelle XML Dokumente mit folgenden Eigenschaften: Ein POI XML Dokument kann keinen, ein oder mehrere POIs umfassen Ein POI kann in einem XML Dokument auch als gelöscht markiert werden Es folgt dem XML-Schema: (das XML Schema steht nicht online zur Verfügung. Es wird zu Projektbeginn per von Alpstein versendet) Die wichtigsten Informationen zu einem POI sind id, category, title und point. Nur POIs, die diese Attribute gesetzt haben, können in ALPregio Portalen und outdooractive veröffentlicht werden und stehen über die outdooractive API zur Verfügung Sind Informationen zu einem der im Folgenden aufgelisteten Attribute nicht vorhanden, muß das entsprechende XML Element leer bleiben oder ausgelassen werden. Ist zum Beispiel kein Autor zu einem POI bekannt, muß eine der folgenden Varianten gewählt werden: o Kein <author> Element unterhalb des Elements <poi> o <author /> o <author></author> Seite 5 von 26

6 POI XML - Struktur Unterhalb des Wurzelelements <pois> ist für jeden POI ein XML-Knoten <poi> vorhanden, der folgenden Aufbau hat: <?xml version="1.0" encoding="utf-8"?> <pois xmlns:xsi=" xmlns=" xsi:schemalocation=" alp.interface.pois.xsd"> <source>kundencms</source> <owner>berchtesgaden</owner> <poi id="1920" workflow="online"> <category>65</category> <author>peter Mustermann</author> <point> </point> <contact>... </contact> <descriptions>... </descriptions> </poi> <images>... </images> Ein POI besteht aus: einer im KundenCMS eindeutige ID einem workflow Status (online/offline) einer Kategorie einer Georeferenz (Lat/Lng; WGS84) einem XML-Block für die Kontaktinformationen einem XML-Block für Textbeschreibungen einem XML-Block für Bilder Seite 6 von 26

7 Kontaktdaten Im Block <contact> werden alle Kontaktdaten eines POI übertragen: Straße (<street>), Hausnummer (<number>), Ort (<municipality>), Postleitzahl (<postalcode>) Telefonnummer (<tel>) und Telefaxnummer (<fax>) URL zur Homepage (<url>) <contact> <address> <street>salzbergstraße</street> <number>41</number > <municipality> Berchtesgaden</municipality > <postalcode>83471</postalcode> </address> <tel>+49(0)8652/947960</tel> <fax>+49(0)8652/947969</fax> <url> </contact> Text Im Block <descriptions> sind der Titel und alle Textfelder eines POI enthalten. Für jede Sprache wird je ein <description lang= de > Element eingefügt, das Elemente für folgende Textfelder haben kann POI Titel (<title>) Beschreibungstext (<text>): wird z.b. auf der POI Detailseite ausgegeben Parkmöglichkeiten (<parking>) Anfahrtsbeschreibung (<getting_there>) Öffnungszeiten (<businesshours>) Preisinformationen (<fee>) Seite 7 von 26

8 Bilder Im Block <images> sind alle Bilder zu einem POI enthalten. Für jedes Bild wird je ein <image> Element eingefügt, das folgende Informationen enthält: ein innerhalb des KundenCMS eindeutigen Bezeichner für dieses Bild (folgt den selben Regeln für ID-Werte, die im Abschnitt Elemente und Attribute für POI IDs beschrieben sind). Die Ids für Bilder und POIs müssen eindeutig sein, d.h. dass ein Bild und ein POI nicht dieselbe Id haben dürfen URL zum Bild (<img src= >) eine Georeferenz (falls vorhanden) (<point>): Standort, von dem aus das Bild aufgenommen wurde Für jede Sprache ein Beschreibungsblock mit Bildtitel (<title>) Weitere Attribute Im Block <attributes> werden optional zusätzliche URLs zu Informationen im Internet und Audio- und Videodateien übertragen. Für Beherbergungsbetriebe kann die Hotelsterne Bewertung und die Auszeichnung von RADfreundlichen/wanderfreundlichen Betrieben übermittelt werden. Die Reihenfolge ist dabei: hotelstars, tags, context Im folgenden werden die einzelnen Punkte erläutert <attributes> <hotelstars>****s</hotelstars> <!-- alternativ: 25 oder > <tags> <tag id="cyclingfriendly" /> </tags> <context id="default"> <link type="web" title="informationen beim Institut für Zeitgeschichte" href=" </context> </attributes> Seite 8 von 26

9 Zusätzliche URLs und URLs zu Audio- und Videodateien Im Block <attributes> können links zu weiteren Informationen über einen POI im Internet und zu Audio- (mp3) und Videodateien (youtube URL) übermittelt werden. Die Links sind zusätzlich in <context> Blöcken zusammengefasst, die jeweils das Attribut id haben müssen. Im Kontext default werden Links übermittelt, die allgemein zu einem POI zusätzlich zur Verfügung stehen. Für spezielle Links, die z.b. im Zusammenhang mit der outdooractive Partner API (Javascript) zum Einsatz kommen, wird jeweils ein weiterer Kontexte verwendet. Der Block <attributes> ist optional, muß sich aber zwischen den Blöcken <contact> und <descriptions> befinden Mögliche Typen für die Links: i) web eine Url zu einer Seite mit weiterführenden Informationen zum jeweiligen POI ii) web.wikipedia eine Url zum Wikipedia-Artikel des POI iii) booking eine Url direkt zu einer Seite, auf der die jeweilige Unterkunft (POI) gebucht werden kann iv) video.youtube eine Url zu einem YouTube Video v) audio.mp3 eine Url zu einer MP3 Datei Es dürfen mehrere Links eines Typs übermittelt werden Die id eines Kontext darf nicht mit oa. Beginnen Seite 9 von 26

10 <attributes> <context id="default"> <link type="web" title="informationen beim Institut für Zeitgeschichte" href=" /> <link type="booking" title="ferienwohnung Meier bei Tiscover buchen" href=" /> <link type="video.youtube" title="screencast: Beispiel" href=" /> <link type="audio.mp3" href=" /> </context> <context id="ar-bgl"> <link type="web" href=" /> </context> </attributes> POIs mit Tags auszeichnen POIs können durch einen Block <tags> innerhalb des Blocks <attributes> mit Tags ausgezeichnet werden. Die Auszeichnung eines Betriebes erfolgt durch die Auflistung des entsprechenden Tags im Block <tags> Innerhalb des Blocks <attributes> werden die Tags nach der Hotelsterne-Bewertung und vor den Blöcken aufgeführt (siehe XML Schema) <attributes> <tags> <tag id="cyclingfriendly" /> <tag id="hikingfriendly" /> </tags> </attributes> RADfreundliche und wanderfreundliche Betriebe RADfreundliche und wanderfreundliche Betriebe können ebenfalls über Tags gekennzeichnet werden. RADfreundlich: tag id cyclingfriendly Wanderfreundliche: tag id hikingfriendly Seite 10 von 26

11 POI XML - Elemente und Attribute Im Folgenden werden die einzelnen Elemente und Attribute eines POIs erklärt (Pflicht Elemente/Attribute sind fettgedruckt): 1) id ein innerhalb des KundenCMS eindeutigen Bezeichner für diesen POI Zahlenwert oder String aus den Zeichen: abc, ABC, 012, -, _ Z.B. 1920, , abatfxf, Das Attribut id muß gesetzt sein. Ein POI ohne id kann nicht importiert werden 2) category ein innerhalb des KundenCMS eindeutigen Bezeichner für eine oder mehre Kategorien des POI. Hat eine POI mehr als eine Kategorie, gilt die erste Kategorie als Hauptkategorie und sollte entsprechend gewählt werden Zahlenwert oder String aus den Zeichen: abc, ABC, 012, -, _ ein POI kann einer oder mehreren Kategorien zugeordnet werden jede Kategorie wird im ALPcms einem internen Dokumenttyp zugewiesen. Diese Zuordnung wird durch das Alpstein Projektmanagement durchgeführt anhand der Kategorie wird unter anderem das Symbol (Marker) ausgewählt, dass den POI auf einer Karte visualisiert z.b. Hotel, Parkplatz, Restaurant, Kirche, Das Element category darf nicht leer sein ein POI ohne Kategorie kann nicht auf Kartendarstellungen angezeigt werden Seite 11 von 26

12 3) workflow optionale Angabe des Workflow status definiert, ob ein POI aktuell veröffentlicht wird oder bereits gelöscht wurde Mögliche Werte: online, offline, deleted Default: online 4) lastmodified mit lastmodified kann das Datum der letzten Änderung eines POI, die durch einen Benutzer durchgeführt wurde, übertragen werden Dieses Datum wird bei der Visualisierung als letzte Änderung angezeigt POI Updates können auch asynchron und mit größerer Zeitverzögerung übertragen werden oder ein POI wird aufgrund fehlender Daten erneut synchronisiert. Aus diesem Grund ist das Datum der Übertragung über AlpInterface nicht für die Visualisierung geeignet. Format: YYYY-MM-DD HH:MM:SS ( :55:32) 5) error wird im Fehlerfall gesetzt, z.b. wenn im KundenCMS zu einer Id kein POI gefunden werden kann Mögliche Werte: not found 6) source eindeutiger Bezeichner eines KundenCMS wird zu Projektbeginn durch Alpstein vergeben und kommuniziert Seite 12 von 26

13 7) owner eindeutiger Bezeichner der Benutzergruppe ( Schublade ) des ALPcms, für die Daten importiert werden. Innerhalb des KundenCMS oft ebenfalls eine Benutzergruppe oder Mandant. Zahlenwert oder String aus den Zeichen: abc, ABC, 012, -, _ die POIs eines KundenCMS können dadurch für verschiedene Projekte unterschieden freigeschaltet/genutzt werden eine Schublade kann z.b. eine Gemeinde sein, wenn ein KundenCMS die POIs mehrerer Gemeinden liefert, die in verschiedenen Projekten zum Einsatz kommen owner kann auch für alle POIs, die ein KundenCMS importiert, gleich sein z.b. bglt owner kann für alle POIs eines XML Dokumentes gesetzt werden owner kann bei den einzelnen POIs überschrieben 8) point definiert die geografische Lage des POI geografisches WGS84 Koordinatenpaar in Länge und Breite (Georeferenz) Reihenfolge der Koordinaten im XML: Lat, Long Dezimale Darstellung z.b.: Genauigkeit: die Koordinaten können auf 6-7 Stellen gekürzt werden Das Element point darf nicht leer sein ohne eine Georeferenz wird ein POI nicht veröffentlicht Seite 13 von 26

14 9) title der Titel/Name eines POI wird in POI Listen, z.b. im CMS aufgeführt wird auf der Karte angezeigt, wenn der Benutzer auf der Karte über das Symbol eines POI fährt nach Möglichkeit für alle POIs vorhanden, d.h. z.b. Parkplatz am Wald ohne Titel ist ein POI in Ergebnislisten für die Benutzer schwer zu von anderen POIs zu unterscheiden 10) author der Autor der Daten eines POI (falls diese Information vorhanden ist) als Text der Autor eines Bildes z.b. Peter Mustermann 11) contact alle Kontaktdaten zu einem POI sind Elemente oder Attribute des XML Knoten contact Adresse, Telefon, , url (zur Homepage des POI) alle Kontaktdaten sind sprachunabhängig 12) description/descriptions der XML Knoten descriptions enthält für jede Sprache (bis jetzt wird nur deutsch de unterstützt) ein description Element alle sprachabhängigen Textbeschreibungen eines POI sind Elemente des XML Knoten description z.b. Beschreibung, Anfahrt Seite 14 von 26

15 13) images die Bilder eines POI mit Bildtitel und URL zur Bilddatei die Bilder können georeferenziert sein 14) hotelstars die Hotelsterne-Bewertung wird nur für Kategorien von Beherbergungsbetrieben berücksichtigt Zeichenfolge: *, *S,..., *****S Oder alternativ: 1, 1.5,..., 5.5 Oder alternativ: 1, 15,..., 55 siehe (Sternkategorien nach Hotelstars Union) 15) businesshours Öffnungszeiten als Textbeschreibung 16) fee Preise als Textbeschreibung Seite 15 von 26

16 Rückgabewert der Benachrichtigung Der Aufruf der ALPcms-URL zur Benachrichtigung über Änderungen liefert ein XML-Dokument der folgenden Form zurück: <update jobid="jobid"/> Die Aktualisierung der Daten wird asynchron ausgeführt, den Fortschritt und Erfolg kann man mit Hilfe der jobid abfragen: Dieser Aufruf liefert den Status in Form eines XML-Dokuments: <update state="status" message="..."/> Das Message-Attribut ist optional; der Status kann folgende Werte beinhalten: running: Die Anfrage wartet auf Ausführung oder wird gerade ausgeführt. done: Die Aktualisierung wurde erfolgreich durchgeführt. failed: Die Aktualisierung schlug fehl (nähere Informationen finden sich im message-attribut) jobnotfound: Zur angegebenen jobid wurde keine Anfrage gefunden. Seite 16 von 26

17 Hütten Informationen zu Berghütten werden im Block <hut> übermittelt: <hut officialavhut="true" haswinterroom="true" winterroomneedskey="true" winterroomheated="true" hasseminarroom="true" accesskeyneeded="true"> <classification>ii</classification> <childrenminage>8</childrenminage> <landlord> <name>marion Meyer</name> <address> <street>dudenstr.</street> <number>2</number> <municipality>mering, Schwab</municipality> <postalcode>86415</postalcode> </address> <tel>0049/8321/2509</tel> </landlord> </hut> Seite 17 von 26

18 1) classification AV-Klassifizierung der Hütte Mögliche Werte: I,II,III,AMH,MH,seH 2) officialavhut Offizielle Hütte eines Alpenvereins 3) open Die Hütte ist zur Zeit geöffnet 4) childrenminage Mindestalter für Kinder auf der Hütte 5) landlord Name, Anschrift und Telefonnummer des Pächters (vgl. Block <address /> ) 6) Tags Es wird eine Liste der möglichen Tags mit Tag Id zur Verfügung gestellt 7) openinghours Informationen über die Öffnungzeiten der Hütte period: Block für eine Zeitspanne im Jahr für die Öffnungszeiten definiert werden open: Block der für Wochentage und Uhrzeiten die Öffnungszeiten definiert (innerhalb einer Zeitspanne) Seite 18 von 26

19 8) seminarroomequipment Textbeschreibung der Ausstattung des Seminarraums 9) accesskey Textbeschreibung mit Informationen über den Zugangsschlüssel 10) winterroomkey Textbeschreibung mit Informationen über den Zugangsschlüssel für den Winterraum Seite 19 von 26

20 Kodierung der XML-Daten Die XML-Dokumente, die zum Datenaustausch vom KundenCms geliefert werden, müssen neben dem XML Schema folgende Punkte erfüllen: Die Textinhalte der XML Dokumente müssen UTF-8 kodiert sein Im XML-Header muß UTF-8 als encoding angegeben werden: <?xml version="1.0" encoding="utf-8"?> Das Kaufmanns und & (&) und das Kleinerzeichen < (<) müssen in jedem Fall als XML-Entity kodiert werden Andere Sonderzeichen sollten nicht in Entities kodiert werden URLs mit Leerzeichen müssen URL-kodiert sein In allen anderen Textfeldern, wie z.b. die Langbeschreibung, sind nur folgende HTML Elemente erlaubt: <b></b>, <strong></strong>, <i></i>, <br />, <p></p> Textfelder mit HTML Elementen müssen in einem CData Abschnitt stehen: <![CDATA[Textfeld]]]]> Der http header content/type sollte folgendermaßen gesendet werden: Content-Type: text/xml;charset=utf-8 Werkzeuge für die XML Schema Validierung xml-copy-editor ( xmlstarlet ( xmllint ( Eclipse ( Seite 20 von 26

21 Reihenfolge und Aufgaben bei der Implementierung 1. Informationen austauschen a. Alpstein: Dokumentation, ein Zugang zum ALPcms und die Werte für source (in den Beispielen KundenCMS ) und owner (alle für das KundenCMS/Projekt relevanten Benutzergruppen) werden übermittelt b. KundenCMS: Zweispaltige Liste aller Kategorien wird an Alpstein übermittelt i. Spalten: Kategorie-Id, Kategorie-Name ii. CSV oder Excel Datei c. Alpstein: Zuordnung der Kategorien zu internen Alpstein Kategorien 2. Implementierung und Konfiguration a. KundenCMS: Implementierung der Schnittstelle, die für ids eines POIs ein XML nach dieser Dokumentation liefert b. KundenCMS: Validierung der Schnittstelle gegen das AlpInterface XML Schema c. Alpstein: Eintragen der Interface URL des KundenCMS, der Kategorienzuordnung und der Benutzergruppen in die AlpInterface-Dokumentation 3. Erste Datenübertragung a. KundenCMS: manueller Aufruf der AlpInterface-URL (z.b. im Browser) ncms&ids=12 b. KundenCMS/Alpstein: POI mit ID 12 sollte im ALPcms vorhanden sein 4. Implementierung Datenupdates a. KundenCMS: Implementierung des automatisierten Aufruf der AlpInterface-URL bei Änderungen an POIs im KundenCMS 5. Initialer Datenimport Seite 21 von 26

22 a. Bitte Nachts durchführen b. Best Practice: AlpInterface-URL für POIs in Blöcken von z.b. 100 IDs aufrufen mit 2 Sekunden sleep() zwischen den Requests c. Alternativ: AlpInterface-URL für einzelne POIs aufrufen. Bitte 2 Sekunden sleep() zwischen den Requests Seite 22 von 26

23 Problembehandlung Wenn die Übertragung von POIs über AlpInterface nicht funktioniert, helfen die folgenden Informationen in vielen Fällen weiter. Das Alpstein Team steht bei Fragen und für die Problembehandlung gerne zur Verfügung: Status bei AlpInterface Abrufen o Status ist failed o Rückgabeinformation anschauen o Implementierung der XML Ausgabe anpassen, falls die Validierung gegen das AlpInterface XML Schema (wird vom System immer als erstes geprüft) nicht erfolgreich war Status ist running o Das Update wurde noch nicht bearbeitet. Bei hoher Last am AlpInterface durch viele parallele Updates durch verschiedene KundenCMS kann ein Update durchaus auch längere Zeit dauern. Status ist jobnotfound o Eventuell liegt der Update Aufruf länger zurück o Update erneut versuchen Status ist done, aber POI erscheint nicht im ALPcms o Ist die Kategorie-ID des POIs in der Liste, die an Alpstein übermittelt wurde, enthalten? POI erscheint im ALPcms, aber nicht im ALPregio o Ist der workflow Status published? o Wann wurde der POI Übermittelt? Die POIs werden jede Nacht in die ALPregio Instanzen übertragen, d.h. ein POI erscheint erst am nächsten Tag nach einer Änderung im ALPregio. Seite 23 von 26

24 Beispiele Neuer POI oder Update eines POI <?xml version="1.0" encoding="utf-8"?> <pois xmlns:xsi=" xmlns=" xsi:schemalocation=" alp.interface.pois.xsd"> <source>kundencms</source> <owner>berchtesgaden</owner> <poi id="1920" workflow="online" lastmodified=" :55:32"> <category>65</category> <author>peter Mustermann</author> <point> </point> <contact> <address> <street>salzbergstraße</street> <number>41</number > <municipality> Berchtesgaden</municipality > <postalcode>83471</postalcode> </address> <tel>+49(0)8652/947960</tel> <fax>+49(0)8652/947969</fax> <url> </contact> <descriptions> <description lang="de"> <title>dokumentation Obersalzberg</title> <text>eine Ausstellung über die Geschichte des Obersalzberg</text> <parking>großer Parkplatz vorhanden</parking> <getting_there>anfahrt über </getting_there> </description> <description lang="en"> <title>documentation Obersalzberg</title> <text>multimedia Exhibition</text> <parking>big Parking.</parking> <getting_there> </getting_there> </description> </descriptions> <images> <image id="123123" src=" <point> </point> <description lang="de"> <title>dokumentationszentrum</title> </description> <description lang="en"> <title>documentation center</title> </description> </image> </images> </poi> </pois> Seite 24 von 26

25 POI Benutzergruppe überschreiben <?xml version="1.0" encoding="utf-8"?> <pois xmlns:xsi=" xmlns=" xsi:schemalocation=" alp.interface.pois.xsd"> <source>kundencms</source> <owner>bglt</owner> <poi id="1920" workflow="online"> <owner>berchtesgaden</owner> <category>exhibition</category> <author>peter Mustermann</author> <point> </point> </poi> </pois> POI mit mehr als einer Kategorie <?xml version="1.0" encoding="utf-8"?> <pois xmlns:xsi=" xmlns=" xsi:schemalocation=" alp.interface.pois.xsd"> <source>kundencms</source> <owner>berchtesgaden</owner> <poi id="1920" workflow="online"> <categories> <category>hotel</category> <category>restaurant</category> <category>fewo</category> </categories> </poi> </pois> POI wurde gelöscht <?xml version="1.0" encoding="utf-8"?> <pois xmlns:xsi=" xmlns=" xsi:schemalocation=" alp.interface.pois.xsd"> <source>kundencms</source> <owner>berchtesgaden</owner> <poi id="1920" workflow="deleted" /> </pois> Seite 25 von 26

26 POI kann nicht gefunden werden <?xml version="1.0" encoding="utf-8"?> <pois xmlns:xsi=" xmlns=" xsi:schemalocation=" alp.interface.pois.xsd"> <source>kundencms</source> <owner>berchtesgaden</owner> <poi id="1920"> <error>not found</error> </poi> </pois> Seite 26 von 26