Connector für OData in Applikationen

Modul Applikationen Fremddaten einbinden

1. Fremddatengruppe erstellen

Eine Verbindung zu einer OData-Datenquelle kann in jeder beliebigen Intrexx-Applikation verwendet werden. Markieren Sie dazu den Applikationsknoten und legen Sie eine neue Fremddatengruppe über das Hauptmenü Neu / Fremddatengruppe an.

Titel

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:

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.



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:

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: 
<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. 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. 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:
  1. $ProcessingContext
    Das aktuelle Processing-Context-Objekt.
  2. Record ID
    Die ID des Media-Link-Entry-Datensatzes.
  3. Datengruppen GUID
    Die GUID der Datengruppe, die den Media-Link-Entry enthält.
  4. 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.
  5. 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="..."/>). 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:
  1. Platzieren Sie auf der Eingabeseite eine neue Dateiauswahl und wählen Sie in den Eigenschaften auf dem Reiter Datenfeld die Option "Keine Verknüpfung".
  2. Ändern Sie auf dem Reiter Expert den Wert des Expert-Attributs "name" in "odataMediaResource".



  3. 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.

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:

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:
  1. 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.
  2. Erstellen Sie eine Ansichtsseite für die Parameter der Funktion und eine weitere Seite zum Anzeigen der Ergebnisse des Funktionsaufrufs.
  3. 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.
  4. 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.
  5. Wechseln Sie in den Eigenschaften der Tabelle auf den Reiter Expert und definieren Sie folgende Settings:
    1. odata.functionImport.name
      Funktionsname (aus Service-Metadaten)
    2. odata.functionImport.parameter
      Mapping der Feld-GUIDs für die Funktionsparameter auf die OData-Funktionsparameter Namen (gemäß den Service Metadaten).

6. Weitere Informationen

Allgemeines
Systemvoraussetzungen
OData-Daten anbieten
OData-Daten konsumieren
OData in Prozessen
Export / Import
Appendix