Fremddatengruppe erstellen
Eine bestehende Verbindung zu einer OData-Datenquelle kann in jeder beliebigen Intrexx-Applikation verwendet werden. Wie und wo Sie eine Verbindung erstellen und konfigurieren können, erfahren Sie hier.
Um die Verbindung in eine Applikation einzubinden, markieren Sie den Applikationsknoten und legen eine neue Fremddatengruppe über das Hauptmenü "Neu / Fremddatengruppe" an.
Legen Sie den Titel der neuen Fremddatengruppe fest und wählen Sie dann die gewünschte OData-Datenbankverbindung aus. Der geeignete Datahandler wird dann automatisch eingetragen.
Sie können den Namen der gewünschten Tabelle bzw. Ansicht direkt eintragen oder auf
"Suchen" klicken und im folgenden Dialog nach dem Tabellen- bzw. Sichtnamen suchen.
Tabellen / Sichten suchen
Filter
Tragen Sie hier eine Zeichenfolge für die Suche ein. Das Zeichen * dient als Platzhalter für beliebige Zeichen. A* findet alle Tabellen bzw. Sichten, deren Name mit A beginnt. *A* liefert als Ergebnis alle Tabellen, deren Name den Buchstaben A enthält.
Tabelle / Sichten
Wählen Sie die gesuchte Tabelle bzw. Sicht hier aus.
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 Applikationselementen verbunden werden.
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".
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. Im nächsten Schritt können die Datenfelder für die Kind-Datengruppe auf dem Reiter "Datenfelder" selektiert werden. Auf Ansichts- und Eingabeseiten der Eltern-Datengruppen gibt es dann die Möglichkeit, abhängige Datensätze aus Kind-Datengruppen in Ansichtstabellen anzuzeigen.
m:n Beziehungen
Für das Erstellen und Entfernen von m:n Beziehungen zwischen zwei OData-Fremddatengruppen steht das Velocity-Callable "ODataLinksCallable" zur Verfügung.
Erstellen einer m:n Beziehung:
$ODataLinksCallable.createLink(<Configuration GUID>, <Service GUID>, <Impersonation GUID>, <Source DG GUID>, <Source_Record_ID>, <Target Navigation Property>, <Target DG GUID>, <Target_Record_ID>)
Entfernen einer m:n Beziehung:
$ODataLinksCallable.deleteLink(<Configuration GUID>, <Service GUID>, <Impersonation GUID>, <Source DG GUID>, <Source_Record_ID>, <Target Navigation Property>, <Target DG GUID>, <Target_Record_ID>)
Dabei werden folgende Parameter benötigt:
-
Configuration GUID
GUID der OData Konfiguration.
-
Service GUID
GUID des OData Services.
-
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.
Dateien
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-Dateidatenfeldern 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 Aliasnamen "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:
<a target="_blank" href="$ODataMediaResourceCallable.getDownloadURIForBinaryProperty($ProcessingContext, $DC.getRecId(), '<GUID_DATENGRUPPE>', '<BINARY_PROPERTY NAME>', '<FILE_NAME>','CONTENT_TYPE', '<DISPOSITION_TYPE>')">Download File</a>
Mit dieser Methode ist es möglich, den Dateinamen und Content-Type dynamisch zu definieren, indem diese Werte aus anderen Feldern ermittelt werden.
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.
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.
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:
-
Platzieren Sie auf der Eingabeseite eine neue Dateiauswahl und wählen Sie in den Eigenschaften auf dem Reiter "Datenfeld" die Option "Keine Verknüpfung".
-
Ändern Sie auf dem Reiter "Expert" den Wert des Expert-Attributs "name" in "odataMediaResource".
-
Legen Sie auf dem Expert-Reiter in den Eigenschaften der Speichern-Schaltfläche auf der Eingabeseite das neue Expert-Attribut "rq_odaction" mit dem Wert "upload" an.
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.
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
-
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 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)
-
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.
-
Wechseln Sie in den Eigenschaften der Tabelle auf den Reiter "Expert" und definieren Sie folgende Settings:
-
odata.functionImport.name
Funktionsname (aus Service-Metadaten)
-
odata.functionImport.parameter
Mapping der Feld-GUIDs für die Funktionsparameter auf die OData-Funktionsparameter Namen (gemäß den Service Metadaten).
-
Beachten Sie bitte, dass die Reihenfolge der Feld GUIDs und Parameternamen in den beiden Listen exakt übereinstimmen muss.
Senden Sie uns eine E-Mail