Connector für OData - Daten anbieten - Funktionen
Die OData-Spezifikation definiert sogenannte Function-Imports, womit Funktionen oder Methoden über einen OData-Service ausgeführt werden können. Mit dem Intrexx-OData-Provider kann über Function-Imports Groovy-Skript serverseitig ausgeführt werden, dessen Aufruf über einen OData-Request erfolgt und die Eingabeparameter empfangen und Rückgabewerte an den Aufrufer zurückgeben können.
Hier erfahren Sie, wie Sie Funktionen definieren und das entsprechende Groovy-Skript verfassen können.
Um die Inhalte nachzuvollziehen, sollte ein Dienst erstellt und aktiviert sein. Wie Sie einen eigenen Service erstellen können, erfahren Sie hier. Die folgende Beschreibung bezieht sich auf das dort verwendete Beispiel. Prinzipiell können Funktionen natürlich beliebig definiert werden und damit den Standard eines OData-Service-Angebots entsprechend erweitern.
Allgemeine Eigenschaften
Den Dialog "Funktionen" erreichen Sie mit einem Doppelklick auf den aktiven OData-Dienst - hier aus unserem Beispiel mit dem Namen "Kalender1". Damit werden die Eigenschaften des Dienstes geöffnet. Hier sollte die Einstellung "Dienst ist aktiv" gesetzt sein.
Datengruppen
Unter "Datengruppen" sind im Beispiel die Applikation "Kalender1" und die darin enthaltene Datengruppe eingebunden.
Mit Klick auf 
"Datengruppe bearbeiten" kann hier der Setname ("IX_CAL_CALENDAR") ermittelt und kopiert werden, da dieser später in unserer Beispielfunktion verwendet wird. Schließen Sie den Dialog mit "Abbrechen".
Wählen Sie dann im linken Bereich den Eintrag "Funktionen" aus.
Funktionen
Mit Klick auf 
"Funktion hinzufügen" kann eine neue Funktion erstellt werden.
Eigenschaften einer Funktion
Name
Geben Sie hier einen eindeutigen Funktionsnamen an, der weder Leer- noch Sonderzeichen enthalten darf. Für unser Beispiel verwenden wir hier den Namen "getIX_CAL_CALENDAR".
HTTP-Methode
Wählen Sie dann aus, mit welcher HTTP-Methode die Funktion aufgerufen werden kann. Für unser Beispiel verwenden wir hier die Methode "GET".
Entity Set Name (optional)
Definiert, auf welchem Entity Set die Funktion operiert. Hier wird der Setname, der zuvor in den Datengruppen-Eigenschaften ermittelt wurde, eingetragen.
Rückgabetyp
Definiert den Typ des Rückgabewerts der Funktion. Dieser kann entweder ein OData-Datentyp sein (z.B. Edm.String, Edm.Int32, Edm.Double, ...) oder ein Entity-Type. Informationen zum Thema "Entity-Type als Rückgabetyp" finden Sie hier.
Im Beispiel wird hier ebenfalls der Setname "IX_CAL_CALENDAR" verwendet.
Ist Collection
Definiert, ob es sich bei dem Rückgabewert um einen oder mehrere Datensätze bzw. Werte handelt.
Parameter
Liste der Eingabe-Parameter einer Funktion.
Ein neuer Parameter kann mit Klick auf "Parameter hinzufügen" hinzugefügt, ein bestehender, markierter Parameter mit "Parameter bearbeiten" bearbeitet werden.
Parameter bearbeiten
Pro Parameter muss ein eindeutiger Name sowie ein Datentyp definiert werden. Der Name darf weder Leer- noch Sonderzeichen enthalten.
Der Typ definiert den Datentyp des Parameters - entweder einen OData-Datentyp (z.B. Edm.String, Edm.Int32, Edm.Double...) oder einen Entity-Type.
Der Modus ist rein informativ und gibt an, ob der Parameter für die Ein- oder Ausgabe oder beides verwendet wird.
Klicken Sie "Fertig stellen".
Groovy-Skript
Die eigentliche Funktionslogik wird mit Groovy-Skript implementiert. Dazu kann über den Link "Groovy-Skript bearbeiten" unten im Dialog der Groovy-Editor geöffnet werden. In Groovy stehen alle Standard-Intrexx-Kontextobjekte und Klassen zur Verfügung. Darüber hinaus werden noch zusätzliche OData-spezifische Kontextobjekte angeboten:
-
g_guidODataService (Typ String)
Beinhaltet die GUID des OData-Services.
-
g_oFunctionParameters (Typ Map)
Beinhaltet die Funktionsparameter und deren Werte.
-
g_oProducerContext (Typ IProducerCommandContext)
Kontext-Objekt des OData-Producers. Bietet Zugriff auf die OData-Servicekonfiguration und den Verarbeitungskontext.
-
g_oFunctionContext (Typ CallFunctionCommandContext)
Kontext-Objekt der OData-Funktion. Bietet Zugriff auf die Funktionseigenschaften, die Eingabeparameter und –werte und optionale OData-Query-String-Variablen.
Zugriff auf Funktionsparameter in Groovy
Auf Eingabeparameter einer Funktion kann in Groovy wie folgt zugegriffen werden:
def l_param = g_oFunctionParameters['BusinessPartnerName']
Definition der Rückgabewerte einer Funktion
Der Groovy-Rückgabewert einer Funktion muss dem in den Funktionseigenschaften definierten Datentyp entsprechen.
Beispiel 1: Einfacher Rückgabewert vom Typ Edm.String
Das folgende Groovy-Skript gibt einfach den Eingabewert vom Typ Edm.String als Ergebnis zurück:
def l_param = g_oFunctionParameters['BusinessPartnerName']
def l_ret = "Parameter value: " + l_param
return l_ret
Beispiel 2: Rückgabewert vom Typ Entity Type
Um einen einzelnen Datensatz als Rückgabewert der Funktion zu definieren, werden die Felder des Entity-Types einer Map hinzugefügt und diese zurückgegeben.
def l_param = g_oFunctionParameters['ID']
// load record from database
// return record value as entity type
def l_entity = [:]
l_entity['ID'] = 1;
l_entity['DeliveryStatus'] = 'OPEN';
l_entity['OrderStatus'] = 1;
l_entity['BillingStatus'] = 'OPEN';
return l_entity
Beispiel 3: Rückgabewert vom Typ Entity-Collection
In diesem Beispiel werden Datensätze anhand eines Eingabeparameters geladen und das Ergebnis als Entity-Collection zurückgegeben. Aus Gründen der Übersichtlichkeit sind die Anweisungen zum Laden der Datensätze nicht enthalten:
def l_param = g_oFunctionParameters['BusinessPartnerName']
// load records from database
// return record values as entities
def l_entity1 = [:]
l_entity1['ID'] = 1;
l_entity1['DeliveryStatus'] = 'OPEN';
l_entity1['OrderStatus'] = 1;
l_entity1['BillingStatus'] = 'OPEN';
l_entity1['TotalSum'] = 1200.00d;
def l_entity2 = [:]
l_entity2['ID'] = 2;
l_entity2['DeliveryStatus'] = 'OPEN';
l_entity2['OrderStatus'] = 1;
l_entity2['BillingStatus'] = 'OPEN';
l_entity2['TotalSum'] = 2300.00d;
return [l_entity1, l_entity2]
Hier wird pro Datensatz eine Map initialisiert, in der die Feldnamen als Key und die Werte als Values gespeichert werden. Zuletzt werden die Map-Objekte in ein Groovy-List-Objekt gespeichert und als Ergebnis zurückgegeben. Der OData-Provider wandelt dann die Datenstruktur gemäß den Datentypen automatisch in das erforderliche OData-Format (JSON/XML) um.
Entity Type als Rückgabetyp
Mit dem Entity Type als Rückgabetyp können Datensätze von Datengruppen geliefert werden. Dazu hier ein Beispiel zur Konfiguration.
Klicken Sie auf "Groovy-Skript bearbeiten", um den Groovy-Skript-Editor zu öffnen.
Fügen Sie das folgende Skript ein:
return [["STRID":1,"STR_TITLE":"Hello world"],["STRID":2,"STR_TITLE":"Hello world2"]]"STRID" entspricht dabei dem Datenfeldnamen des Primärschlüssels, "STR_TITLE" ist der Datenfeldname des Termintitels. Beide Datenfeldnamen können ganz einfach im Editor auf dem Reiter "Applikationsstruktur" ermittelt und im Skript eingefügt werden.
Aufruf im Browser
Nun kann die Datensatz-Collection abgerufen werden. Die URL kann auf dem Reiter "Allgemein" ermittelt werden. Sie entspricht der dortigen "Endpunkt-URL", an die dann lediglich noch der Teil "<Funktionsname>?$format=json" angehängt wird.
Soll nur ein einzelner Datensatz abgerufen werden, formulieren Sie das Groovy-Skript wie folgt:
return ["LID":1,"STRHEADLINE":"Hello world"]Deaktivieren Sie außerdem die Einstellung "Ist Collection" auf dem Reiter "Funktionen".
Senden Sie uns eine E-Mail