Legen Sie hier den Titel der neuen Fremddatengruppe fest.
Datenbankverbindung
Hier kann die gewünschte Verbindung
ausgewählt werden.
Datahandler
Hier wird bei einer OData-Verbindung der geeignete Datahandler automatisch eingetragen.
Tabelle/ Ansicht
Sie können den Namen der Tabelle bzw. Ansicht direkt eintragen oder auf
"Suchen" klicken und im folgenden
Dialog
nach dem Tabellen- bzw. Sichtnamen suchen. Klicken Sie auf "OK", wenn Sie die Tabelle oder
Sicht ausgewählt haben. Alle Informationen zu den Einstellungen zur Anmeldung finden Sie
hier.
Die gewünschten Datenfelder, die vom OData-Service bereitgestellt und in der Applikation
angezeigt werden sollen, können jetzt auf dem Reiter Datenfelder
ausgewählt und mit Applikations-Elementen verbunden werden.
2. Datentypen
Bei der Auswahl der Datenfelder konvertiert der Connector
den OData-Datentyp automatisch in den entsprechenden Intrexx-Datentyp. Dabei sind folgende Besonderheiten zu beachten:
OData definiert im Gegensatz zu Intrexx unterschiedliche Datentypen für Datum und Uhrzeit.
In Intrexx werden alle OData-Datum/Uhrzeit-Datentypen in den datetime-Datentyp konvertiert.
Umgekehrt werden Intrexx Datumswerte standardmäßig in den OData-Datentyp Edm.DateTime umgewandelt.
Unter Umständen definiert der Service aber einen anderen Datumstyp. In diesem Fall kann der korrekte OData-Datentyp
in den Expert Settings des jeweiligen Felds hinterlegt werden.
OData definiert sogenannte komplexe Datentypen. Hierbei handelt es sich um eine Bündelung von mehreren
Feldern aus einfachen Datentypen zu einem neuen komplexen Datentyp. Als Beispiel könnte man die
Felder Straße, PLZ und Ort zu einem komplexen Datentyp "Adresse" zusammenfassen. Da Intrexx keine
komplexen Datentypen kennt, werden diese zu mehreren Intrexx-Datenfeldern konvertiert. Um die Eindeutigkeit
des Namens eines solchen Feldes zu gewähren, bildet sich dieser dann aus den Bestandteilen
<Name des komplexen Datentyps>/<Feldname>, also z.B. "Adresse/Ort".
3. Referenzen
1:1 Beziehungen
In Intrexx Applikationen können Referenzen auf beliebige
Datengruppen gebildet werden. Handelt es sich bei der Ausgangsdatengruppe und der referenzierten Datengruppe
um Fremddatengruppen aus einer OData-Verbindung, so kann zwischen diesen eine 1:1 Beziehung hergestellt werden,
sofern in den Service Metadaten eine entsprechende Beziehung definiert ist.
Bei einer 1:1 Beziehung zwischen zwei OData-Fremddatengruppen (OData Terminologie: "Entity Sets")
müssen keine Primär- und Fremdschlüssel-Datenfelder bestimmt werden. Bei OData-Referenzen wird der Beziehungstyp
direkt aus den Metadaten des OData Services ermittelt und ausgewählt. So werden z.B. die möglichen Beziehungen zwischen
einem Seminar und einer Raumbuchung automatisch vom Connector für OData anhand der Service-Metadaten ermittelt und zur
Auswahl angeboten. Klicken Sie anschließend auf "Weiter". Im nächsten Schritt können die
gewünschten Datenfelder auf dem Reiter Datenfelder
ausgewählt werden.
1:n Beziehungen
Beziehungen vom Typ 1:n zwischen OData Datengruppen werden über Eltern-Datengruppen (z.B. Flüge) und
untergeordnete Kind-Datengruppen (z.B. Buchungen)
in Intrexx abgebildet. Wenn Sie die Datenbankverbindung in den Eigenschaften der Kind-Datengruppe
einrichten und die entsprechende OData-Collection (Tabelle) auswählen,
werden anschließend die möglichen 1:n Beziehungen zur Auswahl angeboten.
Für das Erstellen und Entfernen von m:n Beziehungen zwischen zwei OData-Fremddatengruppen steht das Velocity-Callable
"ODataLinksCallable" zur Verfügung.
Impersonation GUID
GUID eines Impersonation Benutzers oder "null" für den aktuellen Benutzer.
Source DG GUID
Guid der Ausgangsdatengruppe.
Source Record ID
ID des Ausgangsdatensatzes.
Target Navigation Property
Name der OData Navigation Property, welche die Beziehung definiert.
Target DG GUID
Guid der Zieldatengruppe.
Target Record ID
ID des Zieldatensatzes.
4. Dateien
4.1. Binäre Datenfelder
OData Datenfelder vom Typ Edm.Binary (BLOB) werden in Intrexx als
File-Datentyp behandelt. Damit lassen sich binäre Daten in Intrexx-Datei-Datenfeldern
speichern. Da aus OData Binary Feldern nicht automatisch der Dateityp als auch die benötigten Datei-Metadaten
ermittelt werden können, müssen diese in den Expert-Settings
des Datenfeldes hinterlegt werden. Zunächst kann eine allgemein zu verwendende Dateiendung definiert werden.
Dies ist nur bei OData-Diensten nötig, die nicht über den
Intrexx-OData-Provider zur
Verfügung gestellt werden.
Der Dateityp wird beim Speichern der binären Daten automatisch als Dateinamen-Erweiterung verwendet.
Derzeit lässt sich nur ein Dateityp pro Feld für alle Datensätze definieren. Außerdem wird ein
OData-spezifischer Datei-Speicherort
mit dem Alias "odata" benötigt, um die Dateien temporär zu speichern.
Legen Sie dazu im Modul Integration
einen neuen Dateispeicherort an und tragen
Sie den Aliasname "odata" ein. Als Pfad kann ein beliebiges Verzeichnis mit dem Platzhalter "${appGuid}" gewählt werden. Deaktivieren
Sie die Option "Dateien exportieren" und führen Sie den Funktionstest
durch. Handelt es sich bei dem zu konsumierenden Service um einen vom
Intrexx-OData-Provider bereitgestellten
Service, so werden die benötigten Dateimetadaten automatisch vom Dienst zur Verfügung gestellt. Eine
weitere Möglichkeit, den Inhalt von binären Feldern als Download zu ermöglichen, besteht über einen
Aufruf der Callable-Methode "$ODataMediaResourceCallable.getDownloadURIForBinaryProperty()".
Diese generiert eine URL, die auf einer Ansichts- oder Eingabeseite in einem Download-Link eingefügt werden kann:
Mit dieser Methode ist es möglich, den Dateinamen und Content-Type dynamisch zu definieren, indem diese
Werte aus anderen Feldern ermittelt werden.
4.2. Media-Link-Entries
Für den Zugriff und die Manipulation von Dateien bietet OData ab Version 2.0 sogenannte
Media-Link-Entries. Diese stellen die empfohlene Methode für den Zugriff auf binäre Daten dar.
Ein Entity-Type kann in einem OData-Service als Media-Link-Entry definiert werden. Dazu wird der
Entity-Type im Service-Metadata-Dokument mit dem Attribut "HasStream" gekennzeichnet.
Die Felder eines Media-Link-Entries beschreiben dann eine sogenannte Media-Resource, bei der es sich
wiederum um einen beliebigen Dateityp handeln kann, wie z.B. ein Dokument, ein Bild oder ein Video- oder Audiostream.
Eine Entity-Collection vom Typ Media-Link-Entry bildet dann eine Sammlung von Dateien, wobei ein
Media-Link-Entry genau eine Datei beschreibt. Im Gegensatz zu BLOB Feldern, bei denen die komplette Datei als binäre
(Base64-codierte) Datenstruktur neben den weiteren Datenfeldern innerhalb des XML-Antwortdokuments geliefert wird,
erhält man bei einer Abfrage eines Media-Link-Entry nur die URL zu der Media-Resource (d.h. der Datei).
Über die URL kann dann die Datei wie üblich in einem Browser aufgerufen bzw. heruntergeladen werden. Da die Datei hier nicht
codiert in ein XML Dokument eingebettet werden muss, bieten Media-Link-Entries einen wesentlich
effizienteren Mechanismus für den Zugriff auf Dateien. Da ein Media-Link-Entry sowohl die Datei selbst (Metadaten) als auch
den Zugriffspfad zu dieser auf dem Server beschreibt, werden für die Abfrage der Metadaten und dem Download der Datei zwei
HTTP-Requests benötigt. Gleiches gilt für die Neuanlage eines Media-Link-Entries, z.B. wenn eine neue Datei über den
OData-Service hochgeladen oder eine bestehende aktualisiert werden soll. Im Folgenden werden nun die Schritte beschrieben,
um in Intrexx zum einen Dateien aus Media-Link-Entries anzuzeigen oder herunterzuladen und zum anderen Dateien
als Media-Link-Entry auf dem OData-Server zu speichern.
4.3. Anzeige und Download von Dateien aus Media-Link-Entries
Da es sich bei den Metadaten-Feldern eines Media-Link-Entries um gewöhnliche OData-Datenfelder handelt, können diese
wie gewohnt auf einer Ansichts- oder Eingabeseite in Intrexx dargestellt werden. Um die Anzeige oder den Download einer
Media-Ressource zu ermöglichen, muss zunächst ein Link für die Ressource generiert werden, der ein Intrexx-Servlet
aufruft, das dann die Datei über den OData-Dienst anfordert und an den Browser weiterleitet. Dafür beinhaltet der
Connector ein spezielles Velocity-Callable, das den Link so aufbereitet, dass dieser in
Ansichts- bzw. Eingabeseiten
eingebettet werden kann. Erstellen Sie dafür auf einer Ansichtsseite unterhalb einer OData-Datengruppe
für Media-Link-Entries das Element Statischer Text für Programmierung.
Für einen Download-Link wird der Aufruf des Velocity-Callables wie folgt definiert:
<a target="_blank" href="$ODataMediaResourceCallable.getDownloadURI($ProcessingContext, $DC.getRecId(), '<GUID_DATENGRUPPE>', $DC.getValueHolder('<Kontroll-Name des Felds mit Dateiname>').getValue(), 'inline')">Download Media Resource</a>
Dieser Code generiert einen Link auf der Ansichtsseite für den Download der Media Ressource. Dabei können dem
Callable folgende Parameter übergeben werden:
$ProcessingContext
Das aktuelle Processing-Context-Objekt.
Record ID
Die ID des Media-Link-Entry-Datensatzes.
Datengruppen GUID
Die GUID der Datengruppe, die den Media-Link-Entry enthält.
Dateiname
Optional kann hier ein Dateiname für den Download übergeben werden.
Dieser wird beim Speichern der Datei im Browser als Vorauswahl angezeigt.
Im Beispiel oben wird der Dateinamen aus einem Feld auf der Ansichtsseite ermittelt,
das über die Metadaten der Media Resource befüllt wird. Falls ein solches Feld nicht zur
Verfügung steht, kann 'null' übergeben werden.
Content Disposition Type
Dieser (optionale) Wert bestimmt den Content-Disposition-Type des Downloads, d.h. ob
die Datei direkt im Browser eingebettet werden soll (Wert "inline")
oder nur als Download verfügbar sein soll (Wert "attachment"). Dieser
Wert ist optional und kann auch als "null" definiert werden.
Da das Velocity-Callable nur eine URI zu der Media-Ressource zurückgibt, kann diese flexibel
in verschiedenen HTML-Kontrollen verwendet werden (z.B. als Link in <a href="..."/> oder als Bild in <img src="..."/>).
4.4. Upload von Dateien als Media-Link-Entries
Das Speichern und Aktualisieren von Dateien als OData-Media-Ressource lässt sich über eine der Media-Link-Entry-Datengruppe
zugeordnete Eingabeseite realisieren. Auf dieser können wie gewohnt
die Datenfelder für die Media-Resource-Metadaten platziert werden. Der Upload der eigentlichen Datei wird über das
Element Dateiauswahl gesteuert. Gehen Sie dabei wie folgt vor:
Durch diesen Requestwert werden beim Speichern des Datensatzes automatisch zwei OData-Requests erzeugt.
Zunächst wird für die hochgeladene Datei ein Media-Link-Entry über den OData-Dienst erzeugt. Anschließend
werden mit einem zweiten Request die Werte aus den Datenfeldern auf der Eingabeseite als Metadaten für den
Media-Link-Entry gespeichert. Architekturbedingt muss sowohl beim Upload als auch Download von Dateien zwischen dem Browser und dem
OData-Server die Datei zunächst auf dem Intrexx-Portalserver zwischengespeichert werden. Dies kann bei
sehr großen Dateien zu Ressourcenengpässen (insbesondere beim Hauptspeicher des Portalservers) und
Performanceproblemen führen. In diesem Fall sollten die URIs zu den Media-Ressourcen direkt aus dem
OData-Feed-Entry ermittelt und in die Applikationsseite eingebunden werden, so dass ein Zugriff auf die
Datei aus dem Browser heraus direkt über den OData-Server stattfindet. Insbesondere Video- und Audio-Stream-Ressourcen
lassen sich nur auf diese Weise einbinden.
4.5. Dateien mit Intrexx-OData-Provider-Services
Eine wesentlich flexiblere und performantere Möglichkeit zur Verwaltung von Dateien über OData bieten die
upFile-Funktionen, die in jedem Intrexx-OData-Service automatisch zur Verfügung stehen. Damit können Dateien
mit der vollen Unterstützung für Mehrfach-Datei-Datenfelder gespeichert und abgefragt werden.
Einziger Nachteil dabei ist, dass die Dateikontrollen in Intrexx diesen Ansatz nicht unterstützen,
weshalb in Intrexx-Webapplikationen der Download bzw. Upload von Dateien mit JavaScript oder Groovy-Skript projektspezifisch
realisiert werden muss. Folgende OData-Funktionen bietet ein Intrexx-Service zur Verwaltung von Dateien:
upFileList
Die upFileList-Funktion 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 Mehrfach-Dateidatenfelder ausgeführt werden. Als Parameter werden erwartet:
recId: Der Primärschlüssel des Datensatzes mit dem Dateifeld
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 uploadFile-Methode 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 downloadFile-Methode erwartet:
recId: Der Primärschlüssel des Datensatzes mit dem Dateifeld
fileId: Die ID der Datei
fieldGuid: Die Feld GUID des Dateifeldes
disposition (optional): Der Content-Disposition Header Typ (entweder inline oder attachment)
5. OData-Function-Imports
Neben dem Zugriff auf Entity-Collections (Tabellen) bietet OData auch die
Möglichkeit, sogenannte Function-Imports zu definieren und über den Service
auszuführen. Function-Imports lassen sich mit Stored-Procedures in
Datenbankmanagementsystemen vergleichen. Sie können Eingabeparameter empfangen und einen einzelnen
Datensatz oder eine Menge von Datensätze als Ergebnis zurückliefern. Da Intrexx keine direkte
Unterstützung von Stored-Procedures bietet, muss für den Aufruf von Function-Imports folgende
Vorgehensweise angewendet werden:
Ermitteln Sie aus den Metadaten des Services den Namen der aufzurufenden Funktion
(z.B. GetProductsWithRating), die benötigten Eingabeparameter,
ob das Ergebnis aus einem Datensatz (OData-Entry) oder einer Ergebnismenge
(OData-Entity-Set) besteht und den Entity-Type (Tabelle in der Intrexx-Datengruppe) des Ergebnisses.
Erstellen Sie eine Ansichtsseite für die Parameter der Funktion und eine weitere
Seite zum Anzeigen der Ergebnisse des Funktionsaufrufs.
Platzieren Sie auf der Ansichtsseite für die Funktionsparameter pro Parameter ein
Eingabefeld mit dem
entsprechenden Datentyp, aber ohne Verknüpfung,
sowie eine Schaltfläche
mit Sprung auf die Ansichtsseite mit den Ergebnissen.
Erstellen Sie auf der Ergebnisseite eine Ansichtstabelle
(im Falle von einer Ergebnismenge), wählen Sie die entsprechende Datengruppe
(abhängig vom Funktionsergebnistyp) und die anzuzeigenden Datenfelder aus.