Connector für OData - Integration in Applikationen

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 (z.B. "d:\temp\files\odata\${appGuid}").

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.

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 der Eingabeseite in den Eigenschaften der Speichern-Schaltfläche 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:

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

Beachten Sie bitte, dass die Reihenfolge der Feld GUIDs und Parameternamen in den beiden Listen exakt übereinstimmen muss.

Weitere Informationen

Allgemeines

Systemvoraussetzungen

Daten konsumieren

Daten anbieten

Verwendung in Prozessen

Expert-Settings

Appendix