DataHandler-Manager

Hinweis: Diese Dokumentation bezieht sich auf die aktuellste Version des agorum core template managers. Aktualisieren Sie ggf. das hier beschriebene Plug-in, um die Dokumentation verwenden zu können.

Mithilfe des DataHandler-Managers erledigen Sie folgende Aufgaben bequem und einfach über eine Bedienoberfläche:

DataHandler für ein Konfigurationsprojekt anlegen
DataHandler bearbeiten
DataHandler testen
DataHandler löschen
DataHandler kopieren
DataHandler für Entwicklungszwecke als CSV-DataHandler anlegen

Hinweise:

Für eine Übersicht der hier aufgeführten DataHandler (DataHandler-Typen) und deren Funktion siehe Beispiel-Datenquellen für DataHandler.
Die DataHandler providerDataHandler und SearchEngineTermsDataHandler werden lediglich intern bei agorum für Entwicklungszwecke verwendet.

Den DataHandler-Manager öffnen

Der DataHandler-Manager ist im agorum core template manager automatisch enthalten. Sie öffnen ihn folgendermaßen:

Klicken Sie oben rechts in der Kopfleiste auf und dann auf DataHandler-Manager.

Ergebnis: Die Bedienoberfläche des DataHandler-Managers öffnet sich.

Bedienoberfläche des DataHandler-Managers

Einen DataHandler für ein Konfigurationsprojekt anlegen

Legen Sie ein Konfigurationsprojekt über den agorum core template manager an, sofern noch keines existiert.
Öffnen Sie den DataHandler-Manager.
Wählen Sie im Feld Projekt auswählen ein Konfigurationsprojekt, in das der DataHandler erstellt werden soll.

Ergebnis:

• Die Einstellung DataHandler-Auswahl auf Projekt einschränken wird automatisch gesetzt.
• Sie können den Haken bei Bedarf jederzeit entfernen, um im Feld DataHandler auswählen auch DataHandler angezeigt zu bekommen, die im Konfigurationsprojekt nicht existieren.
Wählen Sie im Feld Typ des DataHandlers auswählen einen DataHandler-Typ.

Ergebnis:

• Die Einstellung DataHandler-Auswahl auf Typ des DataHandlers einschränken wird automatisch gesetzt.
• Sie können den Haken bei Bedarf jederzeit entfernen, um im Feld DataHandler auswählen auch DataHandler angezeigt zu bekommen, die nicht zum gewählten DataHandler-Typ passen.
Befüllen Sie die weiteren Felder zum DataHandler ab dem Feld Name des DataHandlers eingeben.

Die Felder sind abhängig vom Typ des DataHandlers, d. h. je nachdem, welchen DataHandler-Typ Sie gewählt haben, variieren die angezeigten Felder.
Klicken Sie unten auf Speichern.

Ergebnis: Das System legt den DataHandler im gewählten Konfigurationsprojekt an.

Tipps:
• Sie können den angelegten DataHandler nach dem Speichern rechts direkt testen.
• Über rechts neben dem Feld Projekt auswählen gelangen Sie direkt zu den Einträgen in der MetaDB und zu den Ordnern des Konfigurationsprojekts.

Hinweis: Beim JDBC-DataHandler und den dort enthaltenen Querys ist Inline-JavaScript möglich. Wenn Sie hier eine Variable mit global. definieren, taucht diese Variable im Abschnitt parameters input rechts auf. Sie können dort dann weitere Einschränkungen vornehmen, etwa nur auf eine Artikelnummer einschränken, sofern Sie eine solche Variable angeben.

Beispiel einer SelectQuery:

select * from verify_lieferschein_demo_jdbc 
${{js: 
 let where = '';
 let query = [];
  if (global.LieferscheinNr || global.BestellNr || global.Artikelnummer) {
    if (global.LieferscheinNr) {
      query.push(' LieferscheinNr = \'' + global.LieferscheinNr + '\'');    
    }    
    if (global.BestellNr) {
      query.push(' BestellNr = \'' + global.BestellNr + '\'');
    }
    if (global.Artikelnummer) {
      query.push(' Artikelnummer = \'' + global.Artikelnummer + '\'');
    }
    where = ' where ';  
  }  
  where + query.join(' and ');
}}

In diesem Beispiel wurden bei den Variablen LieferscheinNr, BestellNr und Artikelnummer das global. vorangestellt. Diese Variablen tauchen nun rechts im Abschnitt parameters input auf:

Abschnitt parameters input

Für das Verwenden von Inline-JavaScript beim JDBC-DataHandler siehe Beispiel-Datenquellen für DataHandler.

Keyword „MetaDbDefaults“ in export.yml aktivieren

Bei der Anlage eines neuen DataHandlers für das gewählte Konfigurationsprojekt erstellt das System in der Datei export.yml automatisch einen Eintrag mit dem Keyword MetaDbDefaults. Der Eintrag ist zu diesem Zeitpunkt noch deaktiviert, Sie müssen ihn also aktivieren, wenn Sie einen Export über die export.yml ausführen möchten.

So gehen Sie vor, um das Keyword in der export.yml zu aktivieren:

Öffnen Sie links in der Seitenleiste Explorer.

Öffnen Sie Ihr Konfigurationsprojekt und dort den Ordner yml:

Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/yml

Doppelklicken Sie auf die Datei export.yml.

Entfernen Sie das # vor dem Eintrag - MetaDbDefaults, um das Keyword zu aktivieren:

Vor Änderung

- ac: /agorum/roi/customers/<Konfigurationsprojekt>
- sync: /agorum/roi/customers/<Konfigurationsprojekt>
#
# register MetaDbDefaults
#
# - MetaDbDefaults: MAIN_MODULE_MANAGEMENT/customers/<Konfigurationsprojekt>/Data

# Call "- Package: ..." to the beginning
- Package: /agorum/roi/customers/<Konfigurationsprojekt>/deploy/pre


# Map UUIDs
- MapUUIDs: /agorum/roi/customers/<Konfigurationsprojekt>/doc

# Here is a final "- Package: ..." call
- Package: /agorum/roi/customers/<Konfigurationsprojekt>/deploy/post

Nach Änderung

- ac: /agorum/roi/customers/<Konfigurationsprojekt>
- sync: /agorum/roi/customers/<Konfigurationsprojekt>
#
# register MetaDbDefaults
#
- MetaDbDefaults: MAIN_MODULE_MANAGEMENT/customers/<Konfigurationsprojekt>/Data

# Call "- Package: ..." to the beginning
- Package: /agorum/roi/customers/<Konfigurationsprojekt>/deploy/pre


# Map UUIDs
- MapUUIDs: /agorum/roi/customers/<Konfigurationsprojekt>/doc

# Here is a final "- Package: ..." call
- Package: /agorum/roi/customers/<Konfigurationsprojekt>/deploy/post

Hinweis: Bei bereits existierenden Projekten, die vor agorum core 10.1.2 angelegt wurden, existiert der Eintrag - MetaDbDefaults nicht. Diesen müssen Sie händisch in die export.yml eintragen. Fügen Sie den Eintrag so ein, dass er nach den Einträgen mit - ac und - sync steht (siehe obige Beispiele). Verwenden Sie zum Einfügen etwa die Schaltfläche MetaDb Key kopieren im DataHandler-Manager.

Speichern Sie die Änderungen.

Einen DataHandler bearbeiten

Sie können einen vorhandenen DataHandler jederzeit bearbeiten, um etwa den Namen oder weitere Felder anzupassen.

Gehen Sie zum Bearbeiten folgendermaßen vor:

Wählen Sie im Feld DataHandler auswählen (zum Bearbeiten) einen vorhandenen DataHandler, den Sie bearbeiten möchten.

Tipp: Um die Auswahl des DataHandlers einzuschränken, setzen Sie vor Auswahl des DataHandlers optional den Haken bei den Einstellungen DataHandler-Auswahl auf Typ des DataHandlers einschränken und DataHandler-Auswahl auf Projekt einschränken.
Ändern Sie den Inhalt der gewünschten Felder, etwa den Namen des DataHandlers.
Klicken Sie unten auf Speichern.

Ergebnis: Das System aktualisiert den DataHandler.

Schaltfläche „MetaDb-Key kopieren“

Diese Schaltfläche steht neben dem Feld MetaDb-Key für Metadatum und DataHandler zur Verfügung. Mit ihrer Hilfe kopieren Sie den korrekten Pfad und den MetaDb-Key zum DataHandler, um ihn dann etwa in die export.yml einzutragen.

MetaDb-Key kopieren

Einen DataHandler testen

Sie können einen vorhandenen DataHandler auf seine Funktion hin testen, etwa um bei einem JDBC-DataHandler gleich die Verbindung zur externen Datenbank zu prüfen und gleichzeitig das Ergebnis des Abrufs zu erhalten.

Gehen Sie zum Testen folgendermaßen vor:

Wählen Sie im Feld DataHandler auswählen (zum Bearbeiten) einen vorhandenen DataHandler, den Sie testen möchten.

Tipp: Um die Auswahl des DataHandlers einzuschränken, setzen Sie vor Auswahl des DataHandlers optional den Haken bei den Einstellungen DataHandler-Auswahl auf Typ des DataHandlers einschränken und DataHandler-Auswahl auf Projekt einschränken.
Wählen Sie rechts im Feld Test die Art der Query.
Geben Sie im Feld parameters input ggf. weitere Filter ein, um das Suchergebnis einzugrenzen.
Klicken Sie auf Ausführen.

Ergebnis: Das System baut etwa im Falle eines JDBC-DataHandlers die Verbindung zur externen Datenbank auf und zeigt im Feld Ergebnis die ausgelesenen Daten an, die aus der externen Datenbank stammen. Das Ergebnis ist abhängig davon, ob Sie im Feld parameters input ggf. weitere Filter verwendet haben.

Einen DataHandler löschen

Sollten Sie einen DataHandler nicht mehr benötigen, können Sie ihn löschen. Beim Löschen werden die Einträge in der MetaDB in den Serverpapierkorb verschoben, der eigentliche DataHandler, den Sie in dem DataHandler-Manager wählen könnnen, wird jedoch vollständig gelöscht und kann nicht mehr wiederhergestellt werden.

Gehen Sie zum Löschen folgendermaßen vor:

Wählen Sie im Feld DataHandler auswählen (zum Bearbeiten) einen vorhandenen DataHandler, den Sie löschen möchten.

Tipp: Um die Auswahl des DataHandlers einzuschränken, setzen Sie vor Auswahl des DataHandlers optional den Haken bei den Einstellungen DataHandler-Auswahl auf Typ des DataHandlers einschränken und DataHandler-Auswahl auf Projekt einschränken.
Klicken Sie unten auf Löschen.

Ergebnis: Das System löscht den DataHandler. Gleichzeitig verschwindet der DataHandler auch aus dem Unterordner Data im Konfigurationsprojekt.

Einen DataHandler kopieren

Sie können einen vorhandenen DataHandler kopieren, wenn Sie ihn für ein anderes Konfigurationsprojekt benötigen. Gehen Sie dazu folgendermaßen vor:

Wählen Sie im Feld DataHandler auswählen (zum Bearbeiten) einen vorhandenen DataHandler, den Sie kopieren möchten.

Tipp: Um die Auswahl des DataHandlers einzuschränken, setzen Sie vor Auswahl des DataHandlers optional den Haken bei den Einstellungen DataHandler-Auswahl auf Typ des DataHandlers einschränken und DataHandler-Auswahl auf Projekt einschränken.
Klicken Sie unten auf Kopieren.

Ergebnis: Das System leert das Feld DataHandler auswählen (zum Bearbeiten).
Wählen Sie im Feld Projekt auswählen ein Konfigurationsprojekt, in das der zuvor gewählte DataHandler kopiert werden soll.
Ändern Sie im Feld Name des DataHandlers eingeben den Namen des DataHandlers.
Ändern Sie ggf. die weiteren Felder für den DataHandler.
Klicken Sie unten auf Speichern.

Hinweis: Sollten Sie einen DataHandler kopieren und es existiert bereits ein solcher mit dem gleichen Namen im Konfigurationsprojekt, erfolgt eine Abfrage, ob der vorhandene ersetzt werden soll. Das System verschiebt den vorhandenen DataHandler dann in den Serverpapierkorb.

Ergebnis: Das System legt den DataHandler unter Data des Konfigurationsprojekts ab.

Einen DataHandler für Entwicklungszwecke als CSV-DataHandler anlegen

Für Entwicklungszwecke können Sie einen CSV-DataHandler anlegen. Ein solcher ist etwa sinnvoll, wenn Sie einen JDBC-DataHandler benötigen, der Daten aus einer externen Datenbank auslesen soll und diese Daten direkt in einer CSV-Datei aufbereitet werden sollen. Diese CSV-Datei wiederum kann dann zur weiteren Verarbeitung verwendet werden.

Um einen solchen CSV-DataHandler anzulegen, gehen Sie folgendermaßen vor:

Folgen Sie den Schritten 1…6, wie unter DataHandler für ein Konfigurationsprojekt anlegen beschrieben. Sie können die folgenden Schritte auch mit einem vorhandenen DataHandler ausführen.
Klicken Sie rechts im Bereich Test auf CSV-DataHandler anlegen (unter Data.defaults und csv.defaults).

Ergebnis:
• Das System erstellt einen CSV-DataHandler aus dem gewählten DataHandler.
• Diesen CSV-DataHandler finden Sie in Ihrem Konfigurationsprojekt im Ordner Data.defaults/<Name des DataHandlers>.
• Die dazugehörige CSV-Datei finden Sie wiederum in Ihrem Konfigurationsprojekt im Ordner csv.defaults/<Name der CSV-Datei>. Die CSV-Datei lautet exakt gleich wie der CSV-DataHandler.

Hinweis: Die erstellten DataHandler, egal ob CSV-DataHandler oder „normaler“ DataHandler, werden nicht automatisch in die Datei export.yml aufgenommen, sofern Sie ein Konfigurationsprojekt exportieren möchten. Diese müssen Sie manuell in diese Datei aufnehmen.

Die erstellte CSV-Datei besitzt als Inhalt exakt die Namen und Werte, wie sie rechts im Feld Ergebnis dargestellt werden.

Einen Treiber (Driver) für JDBC-DataHandler hinzufügen

Nach der Auswahl eines JDBC-DataHandlers wählen Sie im Feld Driver auswählen oder eingeben entweder einen vorhandenen Treiber oder fügen einen neuen hinzu.

Das Hinzufügen geschieht per händischer Eingabe in das Feld.

Gehen Sie zum Hinzufügen eines Treibers für den JDBC-DataHandler folgendermaßen vor:

Installieren Sie den Treiber (.jar-Datei) für die gewünschte Datenbank unter:
```
<InstallDir>/agorum/agorumcore/jboss/server/default/lib
```
Hinweis: <InstallDir> meint den Pfad, unter dem Sie agorum core installiert haben.
Merken Sie sich den Namen des Treibers für die Datenbank.

Den Namen erhalten Sie vom Hersteller der Datenbank.
Starten Sie agorum core neu.
Öffnen Sie den DataHandler-Manager und tragen Sie den Namen, den Sie sich gemerkt haben, in das Feld Driver auswählen oder eingeben beim JDBC-DataHandler ein.

Beispiel für die Datenbank „DB2“
```
COM.ibm.db2.jdbc.net.DB2Driver
```
Hinweis: Es handelt sich bei diesem Namen nicht um die .jar-Datei, die Sie unter Schritt 1 installiert haben.

Eine eigene Datenquelle für ein System anlegen

Wenn Sie sich auf einem Kundensystem befinden, um etwa Daten aus einer SQL-Datenbank abzurufen und dann weiter auf Ihrem Entwicklungssystem verwenden möchten, besteht die Möglichkeit, eigene Datenquellen für ein System anzulegen. Bei diesem System handelt es sich meistens um das Kundensystem, auf dem Sie sich gerade befinden. Das folgende Beispiel geht von einem JDBC-DataHandler aus, den Sie als eigene Datenquelle anlegen.

So gehen Sie vor, um eine eigene Datenquelle, hier einen JDBC-DataHandler, anzulegen:

Wählen Sie im Feld DataHandler auswählen (zum Bearbeiten) Ihren DataHandler, den Sie auf dem Kundensystem importiert haben.

Tipp: Um die Auswahl des DataHandlers einzuschränken, setzen Sie vor Auswahl des DataHandlers optional den Haken bei den Einstellungen DataHandler-Auswahl auf Typ des DataHandlers einschränken und DataHandler-Auswahl auf Projekt einschränken.
Klicken Sie rechts auf Ausführen.

Ergebnis: Das System stellt im Feld Ergebnis die ausgelesenen Daten des DataHandlers dar.
Klicken Sie auf Eigene Datenquelle für dieses System anlegen (unter Data).

Ergebnis: Ein Dialog öffnet sich.
Wählen Sie den DataHandler-Typ.

Der JDBC-DataHandler ist bereits vorausgewählt.
Klicken Sie auf Vorlage erstellen.

Ergebnis: Die Daten des gewählten DataHandlers links in den Feldern verschwinden. Stattdessen wird ein JDBC-DataHandler angezeigt. Dies ist etwa anhand der Felder Typ des DataHandlers auswählen oder DataHandler auswählen (zum Bearbeiten) erkennbar. Der Name wurde automatisch vom eingangs ausgewählten DataHandler übernommen.
Befüllen Sie die weiteren Felder zur neuen Datenquelle / zum neuen JDBC-DataHandler, etwa Driver auswählen oder eingeben, Username, Password und die Querys.
Klicken Sie auf Speichern.

Ergebnis:

• Ihr eigener DataHandler ist angelegt.
• Er ist ebenfalls in der MetaDB des Konfigurationsprojekts unter Data zu sehen.
Klicken Sie auf Ausführen, um zu testen, ob die Verbindung zur SQL-Datenbank besteht und Daten ausgelesen werden können.
Klicken Sie auf CSV-DataHandler anlegen (unter Data.defaults und csv.defaults), um die Daten auszulesen und in eine CSV-Datei zu packen.

Ergebnis:
• Das System erstellt einen CSV-DataHandler aus dem DataHandler. Wenn Sie ihn mit Klick auf Ausführen testen, sehen Sie, dass es sich um die ausgelesenen Daten des Kundensystems und der SQL-Datenbank handelt.
• Diesen CSV-DataHandler finden Sie in Ihrem Konfigurationsprojekt im Ordner Data.defaults/<Name des DataHandlers>.
• Die dazugehörige CSV-Datei finden Sie wiederum in Ihrem Konfigurationsprojekt im Ordner csv.defaults/<Name der CSV-Datei>. Die CSV-Datei lautet exakt gleich wie der CSV-DataHandler.

Einen Lookup-Handler anlegen

Wenn Sie einen JDBC-DataHandler verwenden und dessen ausgelesene Werte etwa in einer form abbilden / anzeigen möchten, benötigen Sie einen sogenannten Lookup-Handler an. Nur mit diesem ist es möglich, die Werte in einer Oberfläche abzubilden.

So gehen Sie vor, um einen Lookup-Handler anzulegen:

Wählen Sie im Feld DataHandler auswählen (zum Bearbeiten) Ihren JDBC-DataHandler.

Tipp: Um die Auswahl des DataHandlers einzuschränken, setzen Sie vor Auswahl des DataHandlers optional den Haken bei den Einstellungen DataHandler-Auswahl auf Typ des DataHandlers einschränken und DataHandler-Auswahl auf Projekt einschränken.
Klicken Sie rechts auf Ausführen, damit Daten selektiert werden.
Klicken Sie rechts auf Lookup-Handler aus gewähltem DataHandler anlegen.

Ergebnis: Das System legt unter Data und Data.defaults des Konfigurationsprojekts aus dem gewählten JDBC-DataHandler einen Lookup-Handler an. Dies sehen Sie an dem Zusatz _lookup im Feld Name des DataHandlers eingeben. Alle anderen Daten aus den Feldern wurden automatisch übernommen.
Ändern Sie das Feld Query (SelectQuery) so ab, dass später im Select-Statement immer nur ein Wert gefunden / geliefert wird. Der LIKE-Operator darf deshalb etwa nicht verwendet werden.

Hinweis: Ein Lookup-Handler kann immer nur mit einem value-Wert arbeiten oder diesen zurückgeben, niemals mehrere auf einmal.

Beispiel
Das folgende Beispiel verdeutlicht das Vorgehen für das Select-Statement, sodass am Ende nur ein konkreter Wert gefunden wird.

Query vor Änderung:
```
select Kostenstelle value, Kostenstellenbezeichnung text, Kostenstelle v from Kostenstelle_demo_jdbc where Kostenstellenbezeichnung like '%${query}%'
```
In dieser Query steht als value Kostenstelle, im where-Statement jedoch noch die Kostenstellenbezeichnung. Beide Angaben müssen gleich lauten.

Query nach Änderung:
```
select Kostenstelle value, Kostenstellenbezeichnung text, Kostenstelle v from Kostenstelle_demo_jdbc where Kostenstelle = '${query}'
```
Nach der Änderung der Query steht, wie auch schon in der value, im where-Statement ebenfalls Kostenstelle. Zusätzlich wurde das like um ein = ersetzt und die % entfernt, damit exakt ein bestimmter Wert gefunden werden kann.
Klicken Sie auf Speichern.
Befüllen Sie rechts das Feld query im Abschnitt parameters input mit einem gültigen value-Wert.
Klicken Sie auf Ausführen.

Ergebnis: Das System zeigt diesen value-Wert im Feld Ergebnis an.