Das OData Protokoll
Systemvoraussetzungen
Dienst erstellen
Schnellstart
Server Konfiguration
Beziehungen
Dateien
Das Open Data Protocol (im Folgenden
OData) ist ein standardisiertes Web-Protokoll. Es unterstützt die einfache Integration und Manipulation von Daten und ist weitaus komfortabler für die Entwicklung von Web- und mobilen Applikationen ausgelegt als herkömmliche Webservices. OData basiert auf offenen Webstandards wie HTTP, Atom Publishing Protocol und JSON und baut wie das World Wide Web auf dem REST-Architekturstil
(Representational State Transfer) auf. Allein über die URL lassen sich mit OData komplexe Datenbankabfragen vornehmen. Dementsprechend wird OData auch als
ODBC für das Web bezeichnet.
Mit dem
Connector für OData können Daten konsumiert und angeboten werden. Wenn Sie mit dem
Connector für OData Daten anbieten, stehen Ihnen folgende Features zur Bereitstellung von OData-Diensten mit Intrexx zur Verfügung:
- Erstellen von OData-Services auf Basis von Intrexx Applikationen und Datengruppen.
- Veröffentlichen und Bearbeiten von Daten aus Intrexx Portalen über OData-Dienste.
- Lesender als auch schreibender Datenzugriff in Echtzeit.
- Ausführen von Groovy Skripten und Starten von Intrexx Prozessen.
- Zugriff auf binäre Dateien (Dokumente, Bilder, etc.).
- Datenaustausch zwischen Intrexx Portalen.
- Verschiedene Authentifizierungsmethoden, Einhaltung des vom Portal vorgegebenen Benutzer- und Berechtigungskonzept.
Systemvoraussetzungen
Der Connector für OData unterstützt die OData-Spezifikation Version 2.0. Merkmale, die in Version 3.0 oder höher spezifiziert sind, können zum Teil bereits verfügbar sein, werden aber nicht offiziell unterstützt. Für eine reibungslose Kommunikation zwischen dem Provider und einem OData-Client müssen je nach Verbindungsart (HTTP / HTTPS) die entsprechenden Ports freigegeben sein. Für die Konfiguration und Serviceerstellung wird mindestens ein Intrexx Benutzer benötigt, der die notwendigen Rechte für die Erstellung von OData-Services im Integrationsmodul des Intrexx Portal Managers besitzt.
Dienst erstellen
Ein neuer OData-Dienst kann über das
Kontextmenü Neuer Dienst konfiguriert werden.
Schnellstart
Hier wird gezeigt, wie Termine aus dem persönlichen Kalender in Intrexx über einen OData-Service für externe Zugriffe bereitgestellt werden können. Auf die Termindaten des Kalenders kann dann von einem anderen Portal aus ein Zugriff mit dem Connector für OData oder mit jedem beliebigen OData-Client erfolgen. Legen Sie einen neuen OData-Dienst an.
Tragen Sie hier den Namen
Appointments ein, unter Namespace
PersonalCalendar und geben Sie optional eine Beschreibung an. Achten Sie darauf, dass die Einstellung
Dienst ist aktiv gesetzt ist.
Hier werden die Datengruppen für den Service ausgewählt. Klicken Sie auf
Datengruppe hinzufügen.
Im Dialog
Datengruppen wählen Sie unter Applikation
Persönlicher Kalender die Datengruppe
Kalender aus.
In den Eigenschaften der Datengruppe tragen Sie unter
Setname jeweils
Appointment ein und aktivieren Sie alle zugelassenen Aktionen.
Nun werden die Datenfelder der Kalenderdatengruppe ausgewählt, auf die über den OData-Service zugegriffen werden kann. Wählen Sie dazu die Felder
ID, BenutzerID, Beschreibung, Datum Von, Datum Bis und
Überschrift aus. Klicken Sie auf
Weiter und dann auf
Fertigstellen.
Fügen Sie hier eine weitere Datengruppe - die Datengruppe
Benutzer aus der Applikation
Benutzer - hinzu. Geben Sie dieser den Typ- und Setnamen
Organizer und wählen Sie die Feldnamen
ID und
Nachname sowie
Vorname aus. Abschließend klicken Sie auf
Weiter und
Fertigstellen. Ihr neuer Service wird nun in der Übersicht der vorhandenen Dienste angezeigt.
Bevor der Service verwendet werden kann, muss noch der OData-Anbieter aktiviert werden. Dazu öffnen Sie das
Kontextmenü des Services und wählen Sie
Einstellungen. Der folgende Dialog wird eingeblendet.
Wählen Sie gegebenenfalls eine andere Bindungsadresse und Port, unter dem der Dienst erreichbar sein soll. Beachten Sie bitte, dass der Port nicht bereits von einem anderen Dienst verwendet wird und nicht von einer Firewall blockiert wird. Aktivieren Sie nun die Auswahl
Anbieter ist aktiv und klicken Sie auf
Fertigstellen. Der OData-Server wird nun gestartet und der Dienst automatisch aktiviert. Zum Testen des Diensts können Sie nun in einem Browser die Adresse
http://servername:port/Appointment.svc aufrufen, alternativ können Sie im Integrationsmodul über das Kontextmenü
Metadaten anzeigen des neuen Services auswählen. Ersetzen Sie
servername und
port mit dem Hostnamen des Computers, auf dem der Intrexx Portalserver läuft. Das OData-XML-Dokument, das nun angezeigt wird, listet im ersten Fall die Service-Metadaten oder im zweiten Fall die beiden Datengruppen
Appointment und
Organizer auf.
Im nächsten Schritt kann der OData-Dienst konsumiert werden.
Verwenden des Service
Mit dem bereitgestellten Dienst ist es nun z.B. möglich, Termine aus einem Intrexx Portal in einem zweiten Portal darzustellen, ohne direkt auf die Datenbank des Portalservers zugreifen zu müssen. Daneben kann mit jedem beliebigen OData-Client oder Browser auf die Termine zugegriffen werden. Im Folgenden wird davon ausgegangen, dass Termine aus einem anderen Portal in einem Kalender angezeigt werden sollen. Um das Beispiel nachzuverfolgen, können Sie entweder ein zweites Portal anlegen oder das gleiche Portal verwenden, in dem der OData-Dienst angelegt wurde. Verbinden Sie sich nun mit dem Portal Manager mit dem Portal, in dem der OData-Service konsumiert werden soll.
Im Modul
Integration öffnen Sie das
Kontextmenü für den Unterpunkt
Connector für OData in
Daten konsumieren. Wählen Sie
Neue Datenquelle und tragen Sie als Namen
Appointments ein. Unter Authentifizierung wählen Sie
Intrexx und einen gültigen Benutzer aus dem Portal, von dem der Dienst bereitgestellt wird. Klicken Sie auf Weiter. Im nächsten Schritt erfassen Sie einen neuen Dienst, indem Sie auf
Dienst erfassen klicken.
Geben Sie als Namen für den Dienst
Appointments ein und als URL die Adresse
http://servername:port/Appointments.svc. Ersetzen Sie
servername und
port mit dem Hostnamen des Computers, auf dem der Intrexx Portalserver läuft. Klicken Sie auf
Fertigstellen und
Weiter, bis die Seite
Verbindungstest erscheint.
Klicken Sie dort auf
Test. Haben Sie die Service URL und den Benutzer korrekt eingegeben, erscheint der Text OK, bei falscher Authentifizierung erscheint folgende Meldung:
Mit den richtigen Authentifizierungsdaten kann der OData-Service-Client nun als Fremddatenquelle in Intrexx-Applikationen verwendet werden. Die Termine aus dem Service-Portal sollen nun in einer Kalenderansicht dargestellt werden. Erstellen Sie dafür eine neue Applikation auf Basis der Vorlage
Leere Applikation. Geben Sie der Applikation einen Namen und löschen Sie die vorgegebene Datengruppe. Anschließend legen Sie eine neue Fremddatengruppe an und wählen unter Datenbankverbindung
Appointments. Klicken Sie auf
Suchen und wählen Sie die Tabelle
Appointments.Appointment. Bestätigen Sie mit
OK.
Auf dem Reiter
Datenfelder wählen Sie alle verfügbaren Datenfelder aus und bestätigen wieder mit
OK.
Fügen Sie nun der Übersichtsseite eine neue Kalenderkontrolle hinzu. Im folgenden Dialog erstellen Sie ein neues
Kalenderplugin, wählen die
Fremddatengruppe aus und verknüpfen die Eigenschaften mit den Feldern aus der OData-Datengruppe.
Bestätigen Sie mit
OK und aktivieren Sie das Plugin als Pflicht-Plugin. Schließen Sie nun den Dialog wiederum mit
OK.
Sie können die Anwendung nun veröffentlichen. Termine, die über die neue Anwendung erfasst werden, werden über den OData Service in der Kalender Datengruppe des angebundenen Portals gespeichert.
Server Konfiguration
|
OData-Services werden von Intrexx an eine festgelegte TCP/IP Adresse und Port gebunden und bereitgestellt. Bevor auf einen OData-Service zugegriffen werden kann, muss der OData-Server über das Kontextmenü Einstellungen entsprechend konfiguriert und aktiviert werden.
|
Allgemeine Informationen zu den Funktionen des
Kontextmenüs erhalten Sie
hier.
Troubleshooting und Anhang finden Sie
hier.
Beziehungen
Beziehungen und Referenzen zwischen Intrexx-Datengruppen werden in OData als Associations und Navigation Properties abgebildet. Dabei können 1:1 und 1:n Beziehungen definiert werden. Beziehungen mit m:n Kardinalität lassen sich über eine m:n Datengruppe abbilden. Associations definieren in OData die Beziehungen und deren Kardinalität zwischen Entity Types. Navigation Properties wiederum fügen den Entity Types Properties hinzu, mittels derer von einem Datensatz zu einem referenzierten Datensatz navigiert werden kann, ohne dass dem Entity Type explizit die Foreign Key bzw. Referenzdatenfelder hinzugefügt werden müssen. Über den Dialog
Beziehungen werden die dafür notwendigen Einstellungen getroffen.
Dateien
Um über einen OData-Service auf Dateien aus Dateifeldern in Datengruppen zugreifen zu können, muss dem Service das entsprechende Dateifeld hinzugefügt werden. Da Intrexx für Dateifelder zusätzliche Metadaten Felder vorhält, werden dem Entity Type pro Dateifeld automatisch ein Feld mit dem komplexen Datentyp
IxFile hinzugefügt. Dieser beinhaltet neben der Datei auch Metadaten, wie z.B. Dateiname, Typ und Größe. Des Weiteren stehen drei Funktionen zur Verfügung, um auf Dateien zuzugreifen und diese zu verwalten. Für den Zugriff auf Dateien gibt es zwei Möglichkeiten, die im Folgenden erläutert werden.
Einbetten von Dateien in OData Feeds
Die erste Möglichkeit ist die direkte Einbettung eines Dateiinhalts als Base64 kodierter binärer String in einen OData-Feed bzw. -Entry. Dies stellt die einfachste Methode für den Zugriff auf eine Datei dar, indem diese direkt mit dem Ergebnis einer OData-Abfrage mitgeliefert wird. Der Connector für OData kann den Dateiinhalt extrahieren und lokal als Datei speichern bzw. in ein anderes Dateifeld einer Zieldateigruppe übertragen und die Datei im Browser über die Intrexx Dateikontrolle anzeigen. Auch das Speichern und Aktualisieren von einzelnen Dateien über die Dateikontrolle ist möglich. Der Nachteil dieses Ansatzes ist, dass pro Dateifeld nur eine Datei geliefert werden kann. Im Fall von Mehrfachdateifeldern ist dies immer die erste Datei, wobei beim Speichern immer eine neue Datei hinzugefügt wird. Des Weiteren wird die Performance des Services wesentlich beeinträchtigt, da die Datei zunächst komplett in den Hauptspeicher geladen werden muss, um dort kodiert bzw. dekodiert zu werden. Daher sollte diese Methode nur für kleinere Dateien verwendet werden.
OData Funktionen für Dateien
Eine wesentlich flexiblere und ressourcenschonendere Möglichkeit für den Zugriff auf Dateien über OData bieten die
upFile Funktionen, die in jedem Intrexx OData-Service automatisch zur Verfügung stehen. Darüber können zum einen Dateien gespeichert und abgefragt werden und es wird volle Unterstützung für Mehrfachdateifelder in Intrexx geboten. Einziger Nachteil dabei ist, dass die Dateikontrollen in Intrexx diesen Ansatz nicht unterstützen, weshalb in Intrexx Webapplikationen der Download bzw. Upload von Dateien via JavaScript oder Groovy projektspezifisch realisiert werden muss. Folgende Funktionen bietet ein Intrexx OData-Service zur Verwaltung von Dateien.
- upFileList
Die Funktion upFileList liefert eine Liste mit allen Dateien eines Dateifeldes. Als Parameter werden erwartet:
- recId: Der Primärschlüssel des Datensatzes mit dem Dateifeld.
- fieldGuid: Die Feld-GUID des Dateifeldes.
- upFileAction
Über diese Funktionen können Operationen auf Mehrfachdateifelder ausgeführt werden. Als Parameter werden erwartet::
- recId: Der Primärschlüssel des Datensatzes mit dem Dateifeld.
- fileId: Die ID der Datei.
- fieldGuid: Die Feld-GUID des Dateifeldes.
- Operation: Die auszuführende Dateioperation (entweder delete, moveUp, moveDown, moveTop, refreshMetadata, refreshOrder).
- upFileDownload
Liefert den Inhalt einer Datei als Base64 kodierten String. Als Parameter werden erwartet:
- recId: Der Primärschlüssel des Datensatzes mit dem Dateifeld.
- fileId: Die ID der Datei.
- fieldGuid: Die Feld-GUID des Dateifeldes.
- upFileResource – upload
Ermöglicht einen Stream-basierten Upload einer Datei. Dies ist die schnellste und ressourcenschonendste Methode um Dateien an den Service zu übertragen. Als Parameter werden für die Methode uploadFile erwartet:
- recId: Der Primärschlüssel des Datensatzes mit dem Dateifeld.
- fieldGuid: Die Feld-GUID des Dateifeldes.
- fileName: Der Dateiname.
- contentType: Der Content-Type der Datei.
- upFileResource - download
Ermöglicht einen Stream-basierten Download einer Datei. Dies ist die schnellste und ressourcenschonendste Methode um auf Dateien zuzugreifen. Als Parameter werden für die Methode downloadFile erwartet:
- recId: Der Primärschlüssel des Datensatzes mit dem Dateifeld.
- fileId: Die ID der Datei.
- fieldGuid: Die FeldGUID des Dateifeldes.
- disposition (optional): Der Content-Disposition Header Typ (entweder inline oder attachment).