Connector für OData in Applikationen
Fremddatenzugriff einrichten
Datentypen
Referenzen
Dateien
OData Function Imports
Fremddatenzugriff einrichten
Eine Verbindung zu einer OData-Datenquelle, die mit dem Connector für OData im Integrationscenter konfiguriert wurde, kann in jeder beliebigen Intrexx Applikation benutzt werden. Legen Sie dazu eine neue Fremddatengruppe über das
Kontextmenü des
Applikationsknotens an.
Der Dialog zur Auswahl der Fremddatenverbindung öffnet sich automatisch.
Legen Sie den
Titel der neuen Fremddatengruppe fest. In der Auswahlliste
Datenbankverbindung kann die gewünschte Verbindung ausgewählt werden. In der Auswahlliste
Datahandler wird bei einer OData-Datenbankverbindung der geeignete Datahandler automatisch eingetragen. Sie können den Namen der
Tabelle bzw.
Ansicht direkt eintragen oder auf
Suchen klicken.
Hier kann nach dem Tabellen- bzw. Sichtnamen gesucht werden kann. Tragen Sie im Feld
Filter 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. Markieren Sie die gesuchte Tabelle bzw. Sicht im unteren Teil des Dialogs und klicken Sie dann auf
OK.
Im unteren Bereich wird die Art der Anmeldung definiert. Mit der Option
Anmeldung als aktueller Benutzer werden beim Aufruf der Seite, auf der die OData Verbindung integriert ist, die Anmeldedaten des aktuellen Portalbenutzers abgefragt. Mit der Option
Anmeldung als statischer Benutzer kann ein fester OData Benutzer zur Anmeldung eingesetzt werden. Klicken Sie auf den Link
Benutzer auswählen.
Hier haben Sie die Möglichkeit, zusätzliche Benutzer einzurichten. Klicken Sie anschließend auf
Benutzer auswählen.
Die Login-Informationen des statischen Benutzers sind nun eingetragen. Die gewünschten Datenfelder, die vom OData Service bereitgestellt werden, können jetzt auf dem Reiter
Datenfelder ausgewählt und in der Intrexx Applikation mit den Elementen 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 zum Beispiel 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 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 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 Datentyp
File behandelt. Dadurch lassen sich binäre Daten in Intrexx Dateifeldern 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. Dieser kann im Integrationsmodul des Portal Managers erstellt werden. Legen Sie dazu unter
Dateispeicherorte einen neuen Speicherort an und tragen Sie unter Aliasname
odata ein. Unter
Pfad kann ein beliebiges Verzeichnis mit dem Platzhalter
${appGuid} gewählt werden. Deaktivieren Sie anschließend noch 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-/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 und werden im Folgenden beschrieben.
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-/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, zum Beispiel 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 anzeigen/downloaden zu können und zum anderen Dateien als Media Link Entry auf dem OData Server zu speichern.
Anzeigen/Download von Dateien aus Media Link Entries
Da es sich bei den Metadaten Felder eines Media Link Entries um gewöhnliche OData Datenfelder handelt, können diese wie gewohnt auf einer Ansichts-/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, welches den Link so aufbereitet, damit dieser in Ansichts-/Eingabeseiten eingebettet werden kann. Erstellen Sie dafür auf einer Ansichtsseite (unterhalb einer OData Datengruppe für Media Link Entries) ein Element vom Typ
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="..."/>). Der folgende Screenshot zeigt die Einbindung einer Bilddatei sowohl als Download-Link als auch als direkt eingebettetes Bild:
Upload von Dateien als Media Link Entries
Das Speichern/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 eine
Dateiauswahl-Kontrolle gesteuert. Gehen Sie dabei wie folgt vor:
- Platzieren Sie auf der Eingabeseite eine neue Dateiauswahl-Kontrolle und wählen Sie in den Eigenschaften unter Verknüpfung zu Datenfeld die Auswahl Keine Verknüpfung.
- In den Expert Einstellungen der Kontrolle überschreiben Sie den Eintrag name mit dem Wert odataMediaResource.
- In den Expert-Einstellungen der Speichern-Schaltfläche auf der Eingabeseite wird ein neues Attribut benötigt. Der Name des Attributs lautet rq_odaction. Als Wert ist upload einzutragen.
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-/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. 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 OData Funktionen bietet ein Intrexx 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 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 und 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 Anzeigeseite 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 Datenfeldzuordnung, sowie eine Schaltfläche mit Sprungziel auf die Ansichtsseite mit den Ergebnissen.
- Erstellen Sie auf der Ergebnisseite eine Ansichtstabelle (im Falle von einer Ergebnismenge), wählen Sie die entsprechende Datengruppe aus (abhängig vom Funktionsergebnistyp) und die anzuzeigenden Datenfelder.
- Wechseln Sie nun in die Expert Settings der Ansichtstabelle 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).