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:

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:

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:
  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="..."/>). 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:
  1. 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.
  2. In den Expert Einstellungen der Kontrolle überschreiben Sie den Eintrag name mit dem Wert odataMediaResource.



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

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:
  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 Anzeigeseite 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 Datenfeldzuordnung, sowie eine Schaltfläche mit Sprungziel 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 aus (abhängig vom Funktionsergebnistyp) und die anzuzeigenden Datenfelder.
  5. Wechseln Sie nun in die Expert Settings der Ansichtstabelle und definieren Sie folgende Settings:
  6. odata.functionImport.name
    Funktionsname (aus Service Metadaten)
  7. odata.functionImport.parameter
    Mapping der Feld-GUIDs für die Funktionsparameter auf die OData Funktionsparameter Namen (gemäß den Service Metadaten).