Beispiel-Datenquellen für DataHandler

Suche

Die Datenquelle Suche basiert auf einem Faceting (Gruppierung) der Solr-Suche und lädt etwa alle Werte eines Metadatums. Derartige Datenquellen werden etwa über metadata-YML angelegt, wenn data=search gewählt wird.

Beispiel für eine Liste aller Tag-Felder

// Schematische Darstellung der Einträge in der MetaDb
Class=agorum.api.object.data.SearchDataHandler

// das Feld, das gruppiert werden soll
Facet=ag_tags 

// Sortierung
FacetSort=index

// maximale Anzahl von Element, die gleichzeitig geladen werden
Limit=100 

// ${query} dient als Einschränkungskriterium, kann etwa der eingegebene Wert eine DropDown Box sein)
// Das Feld selbst ist ein Array
// Hinweis: Wenn ${query} nicht belegt ist (also keine Eingabe gemacht wurde), dann wird nach diesem Element (Array-Eintrag) nicht gesucht
Query=[ 'ag_tags:${query}', 'ag_tags:*' ] 

Beispiel einer reinen Suche

// Schematische Darstellung der Einträge in der MetaDb
Class=agorum.api.object.data.SearchDataHandler

// das Feld, das als Text-Wert definiert wird (in einer Combobox)
Text=name

// das Feld, das als Wert-Feld definiert wird (in einer Combobox)
Value=name

// maximale Anzahl von Element, die gleichzeitig geladen werden 
Limit=100

// ${query} dient als Einschränkungskriterium, kann etwa der eingegebene Wert eine DropDown Box sein)
// Das Feld selbst ist ein Array
// Hinweis: Wenn ${query} nicht belegt ist (also keine Eingabe gemacht wurde), dann wird nach diesem Element (Array-Eintrag) nicht gesucht 
Query=[ 'name:${query}', 'identifier:ag_kundenakte' ] 

Beispiel eines Facet mit Abhängigkeiten

// Schematische Darstellung der Einträge in der MetaDb
Class=agorum.api.object.data.SearchDataHandler

// das Feld, das gruppiert werden soll 
Facet=acbasicarchive_aktescope 

// Sortierung 
FacetSort=index 

// maximale Anzahl von Element, die gleichzeitig geladen werden 
Limit=100

// ${query} dient als Einschränkungskriterium, kann etwa der eingegebene Wert eine DropDown Box sein)
// Das Feld selbst ist ein Array
// in diesem Beispiel gibt es noch die Abhängigkeit von bis zu zwei weiteren Metadaten: "acbasicarchive_aktesection" und "acbasicarchive_aktearea"
// Hinweis: Wenn ${query}, ${acbasicarchive_aktesection} oder ${acbasicarchive_aktearea} nicht belegt ist (also keine Eingabe gemacht wurde oder das Metadatum nicht belegt ist), dann wird nach diesem Element (Array-Eintrag) nicht gesucht 
Query=[ 'acbasicarchive_aktesection_cs:${acbasicarchive_aktesection}', 'acbasicarchive_aktearea_cs:${acbasicarchive_aktearea}', 'inpath:9999', 'acbasicarchive_aktescope:${query}',  'acbasicarchive_aktescope:*' ] 

JDBC

Die Datenquelle JDBC enthält eine Verbindung zu einer Datenbank und einen Select, der die gewünschten Felder für die Datenquelle liefert.

agorum core liefert im Standard bereits Treiber für folgende Datenbanken mit:

• MySql/MariaDb (agorum core open + agorum core pro)
• ProstgreSQL (agorum core open + agorum core pro)
• Oracle (agorum core pro)
• MS SQL Server (agorum core pro)

Die Treiber befinden sich im Installationsverzeichnis unter INSTALLDIR/agorumcore/jboss/server/default/lib.

Neue JDBC-Treiber können Sie als JAR-Datei in dieses Verzeichnis kopieren. Die Treiber stehen nach einem Neustart von agorum core zur Verfügung.

Beispiel für eine JDBC-Verbindung

Class=agorum.api.object.data.JdbcDataHandler

// JDBC-Treiber für die Datenbank
// Oracle
Driver=oracle.jdbc.OracleDriver

// MS SQL Server
// Driver=com.microsoft.sqlserver.jdbc.SQLServerDriver

// MariaDb/MySql
// Driver=org.mariadb.jdbc.Driver
// Driver=com.mysql.jdbc.Driver 

// PostgreSQL
// Driver=org.postgresql.Driver


// Datenbank Benutzer
Username=DB User

// Datenbank Passwort
Password=DB Password

// JDBC-Connection URL
// Oracle
URL=jdbc:oracle:thin:@//db-server:1521:SCHEMA-NAME

// MS SQL Server
// URL=jdbc:sqlserver://db-server:1433;databaseName=SCHEMA-NAME

// MariaDb/MySql
// URL=jdbc:mariadb://db-server:3306/SCHEMA-NAME?useUnicode=true&characterEncoding=UTF-8&useSSL=false
// URL=jdbc:mysql://db-server:3306/SCHEMA-NAME?useUnicode=true&characterEncoding=UTF-8&useSSL=false
​​​​​​
// PostgreSQL
// URL=jdbc:postgresql://db-server:5432/SCHEMA-NAME

// Die zurückgegebenen Feldnamen werden kleingeschrieben (true)
LowerCaseKeys=true

// Die zurückgegebenen Werte werden nicht kleingeschrieben (false)
LowerCaseValues=false

// Die Datenbankabfrage, ${query} beinhaltet einen Filter, etwa aus einer Combobox
Query=SELECT text, value FROM testtable WHERE name=${query} OR value=${query}

// Für neue Einträge
CreateQuery=insert into testtable (name, value) values ('${query}', '${value}') 

// Zum Löschen von Einträgen
DeleteQuery=delete from testdata where name = '${query}' and value = '${value}'

// Zum Ändern von Einträgen
UpdateQuery=update testtable set value = '${newValue}' where name = '${query}' and value = '${oldValue}'

Um einen solchen Handler zu verwenden, verwenden Sie die JavaScript-Bibliothek common/data.

Parameter für eine JDBC-Verbindung

Für die folgenden Werte können Sie Platzhalter vergeben, die das System durch die Werte aus übergebenen Parametern beim Aufruf ersetzt:

• Driver
• URL
• Username
• Password

Beispiel
Eine URL wird etwa folgendermaßen angegeben:

jdbc:mariadb://${host}:3306/${database}?useUnicode=true&characterEncoding=UTF-8&useSSL=false

So können die Werte host und database beim Aufruf des DataHandlers über die JavaScript-Bibliothek common/data als Parameter mitgeben. Diese ersetzt das System dann zur Laufzeit.

Inline-JavaScript beim JDBC-Handler anhand einer Kostenstelle

Sie können in ein SQL-Statement im JDBC-Handler ein Inline-JavaScript definieren.

Beispiel für den Eintrag Query=, mit dem ein where-Statement erstellt werden soll, wenn der Parameter query belegt ist:

Query=select Kostenstelle value, Kostenstellenbezeichnung text, Kostenstelle v from Kostenstelle_demo_jdbc ${js: global.query ? ('where Kostenstellenbezeichnung like \'%' + query + '%\'') : '';}

Selbiges als mehrzeiliges Inline-Skript

Query=select Kostenstelle value, Kostenstellenbezeichnung text, Kostenstelle v from Kostenstelle_demo_jdbc ${{js:
  if (global.query) {
    'where Kostenstellenbezeichnung like \'%' + query + '%\'';
  }
  else {
    '';
  }
}}

Handler aufrufen

let data = require('common/data');

//Jetzt den gewünschten Händler setzen über die Übergabe des MetaDB-Schlüssels

let handler = data.handler('MAIN_MODULE_MANAGEMENT/customers/agorum.demo.jdbc.handler/data/sample-jdbc-mysql-handler-inline-js');

let parameters = {
  query: '0129'
};

let myData = handler.read(parameters);

myData;

Weitere Beispiele von Inline-JavaScript

Query=select * from verify_lieferschein ${{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 ');
}}

Statements durch Gruppierung steuern

Je nachdem, welche parameters übergeben werden, müssen Sie das Statement durch eine Steuerung der Gruppierung anpassen:

• $O[...]$
• $P( ...)$
• $B(...)$
• $M[...]$

Beispiel

Query=SELECT id as value,name as text, description as value1, UUID as value2 FROM globalobject $O[WHERE $P(name LIKE '%${query}%')$ $B(OR)$ $P(UUID like '%${query}%')$]$ LIMIT 1000

Bedeutung der Gruppierungen

Beispiel mit Kostenstelle und Gruppierung

Query=select Kostenstelle value, Kostenstellenbezeichnung text, Kostenstelle v from Kostenstelle_demo_jdbc $O[ where Kostenstellenbezeichnung like $P('%${query}')$]$

value & text sind ungleich (lookup)

Wenn ein Metadatum auf einem JDBC-DataHandler aufbauen soll und dieses in einer form verwendet wird, werden Tabellenwerte ausgelesen und dem Benutzer angezeigt. Für diesen Prozess ist ein SELECT notwendig. Besitzen nun wie in folgendem Beispiel die ausgelesene Tabellen verschiedene Werte für value und text, benötigt agorum core Unterstützung:

v;text;value
"0050";"0050 - Ausstehende Einlagen auf das Komplementär-Kapital, nicht eingefordert";"0050"
"0060";"0060 - Ausstehende Einlagen auf das Komplementär-Kapital, eingefordert";"0060"
"0070";"0070 - Ausstehende Einlagen auf das Kommandit-Kapital, nicht eingefordert";"0070"
"0080";"0080 - Ausstehende Einlagen auf das Kommandit-Kapital, eingefordert";"0080"

Damit das System den Text und nicht den value-Wert anzeigt, wird ein lookup-Eintrag benötigt.

Bedingungen, die für ein lookup notwendig sind

• Sie verwenden einen JDBC-DataHandler.
• Der JDBC-DataHandler verweist auf eine Datenbank, deren value- & text-Werte unterschiedlich sind.
• Diese Datenquelle wird in einem Metadatum verwendet.
• Sie planen, die Datenquelle in einer aguila-form zu verwenden.

Beispiel

Die Datenquelle lautet folgendermaßen:

MAIN_MODULE_MANAGEMENT/customers/TESTPLUGIN/Data/test_datasource

Der dazugehörige Lookup-Eintrag muss wie folgt angelegt sein:

MAIN_MODULE_MANAGEMENT/customers/TESTPLUGIN/Data/test_datasource_lookup

Dahinter muss ein DataHandler definiert sein, der in der Lage ist, basierend auf dem gelieferten Wert (als query) den korrekten data-Teil zurückzugeben.

• Beispiel für einen solchen lookup-Handler siehe Beispiel zu einem lookup handler.
• Ist kein lookup verfügbar, kommt es zu einer Fehlermeldung, außer text und value besitzen identische Werte.
• Bei Nutzung von aguila oder einem Metadatum (wenn restricted = false ist), wird ebenfalls kein lookup-Handler vorausgesetzt. In diesem Fall wird dieser zwar verwendet, sofern er vorhanden ist; ist er es jedoch nicht, wird der eingegebene Text als Wert verwendet.

CSV

Die Datenquelle CSV basiert auf einer CSV-Datei. Eine solche CSV-Datei wird etwa angelegt, wenn Sie in der Datei metadata.yml im Bereich data eigene Paare für value und text anlegen.

Beispiel für eine CSV-Datei

// Schematische Darstellung der Einträge in der MetaDb
Class=agorum.api.object.data.CsvDataHandler

// Groß-/Kleinschreibung beim Suchen in den Feldern beachten (true/false)
CaseSensitive=false

// Trennzeichen in der CSV Datei
Delimitier=; 

// Kodierung der CSV Datei
Encoding=UTF-8 

// Teilwortsuche (false), oder gesamte Zeichenkette muss passen (true)
Exact=false 

// Pfad oder ID zur CSV Datei selbst
PathOrId=/agorum/roi/customers/demo/data/test_csv.csv 

// Spalte, in der über "query" (erster Parameter) gesucht werden soll
QueryColumn=text 

// Zeichen für die Markierung zusammenhängender Spalten innerhalb der CSV Datei
Quote=" 

// Spalte, die auch Textschlüssel zur Übersetzung enthalten kann
Translate=text 

// true, wenn die CSV Spaltenüberschriften enthält: value, text
WithHeader=true 

Beispiel für Abhängigkeiten eines csv-Handlers über require (common/data) und aguila

CSV-Datei für das Metadatum „agorum_demo_csv_handler_type_a“

value;text
A1;Typ A1
A2;Typ A2
A3;Typ A3

CSV für das Metadatum „agorum_demo_csv_handler_type_b“ (mit einer Abhängigkeit vom Metadatum „agorum_demo_csv_handler_type_a“)

value;text;agorum_demo_csv_handler_type_a
B1;Typ B1 (A1);A1
B2;Typ B2 (A1);A1
B3;Typ B3 (A1);A1
B4;Typ B4 (A2);A2
B5;Typ B5 (A2);A2
B6;Typ B6 (A2);A2
B7;Typ B7 (A2);A2
B8;Typ B8 (A2);A2
B9;Typ B9 (A3);A3
B10;Typ B10 (A3);A3

CSV für das „Metadatum agorum_demo_csv_handler_type_c“ (mit einer Abhängigkeit vom Metadatum „agorum_demo_csv_handler_type_b“)

value;text;agorum_demo_csv_handler_type_b
C1;Typ C1(B1);B1
C2;Typ C2(B1);B1

C3;Typ C3(B2);B2
C4;Typ C4(B2);B2
C5;Typ C5(B2);B2

C6;Typ C6(B3);B3
C7;Typ C7(B3);B3
C8;Typ C8(B3);B3
C9;Typ C9(B3);B3
C10;Typ C10(B3);B3

C11;Typ C11(B4);B4

Zugehöriges JavaScript

let data = require('common/data');
let handler_a = data.handler('MAIN_MODULE_MANAGEMENT/customers/agorum.demo.csv.handler/Data/agorum_demo_csv_handler_type_a');
let handler_b = data.handler('MAIN_MODULE_MANAGEMENT/customers/agorum.demo.csv.handler/Data/agorum_demo_csv_handler_type_b');
let handler_c = data.handler('MAIN_MODULE_MANAGEMENT/customers/agorum.demo.csv.handler/Data/agorum_demo_csv_handler_type_c');


let parameters_a = { 
};
let query_a = 'A1';
let value_a = handler_a.read(query_a, parameters_a);

value_a;

let parameters_b = {
  agorum_demo_csv_handler_type_a: value_a[0].value
};
let query_b = '';
handler_b.read(query_b, parameters_b);

Ergebnis

[ 
  {
    "agorum_demo_csv_handler_type_a" : "A1",
    "text" : "Typ B1 (A1)",
    "value" : "B1"
  }, 
  {
    "agorum_demo_csv_handler_type_a" : "A1",
    "text" : "Typ B2 (A1)",
    "value" : "B2"
  }, 
  {
    "agorum_demo_csv_handler_type_a" : "A1",
    "text" : "Typ B3 (A1)",
    "value" : "B3"
  } 
]

aguila-Oberfläche, bei der von oben nach unten die Auswahl abhängig von dem zuvor ausgewählten Wert ist

let aguila = require('common/aguila');

let form = aguila.create({
  width: 300,
  height: 300,
  type: 'agorum.composite.form.basic',
  name: 'basicForm',

  elements: [
    {
      name: 'agorum_demo_csv_handler_type_a',
    },
    {
      name: 'agorum_demo_csv_handler_type_b',
    },
    {
      name: 'agorum_demo_csv_handler_type_c',
    }    
  ]
});


form.on('input', data => {
  if (data.name === 'agorum_demo_csv_handler_type_a' ) {
    let parameters = {
      agorum_demo_csv_handler_type_a: data.value
    };
    form.set('agorum_demo_csv_handler_type_b.dataSourceParameter', parameters);
  }
  else if (data.name === 'agorum_demo_csv_handler_type_b' ) {
    let parameters = {
      agorum_demo_csv_handler_type_b: data.value
    };
    form.set('agorum_demo_csv_handler_type_c.dataSourceParameter', parameters);
  }
});

form;

Um die Auswahl einzuschränken, können in einer CSV-Datei beliebig viele abhängige Spalten vorkommen. Die Spalten können Sie über die parameters mitgeben.

USER, USER-GROUP, GROUP, GROUP-USERS

Diese Datenquellen sind spezifisch eingebaut und liefern entweder:

• Benutzer
• Benutzer sowie Benutzergruppen
• nur Benutzergruppen

Beispiel einer User-/ Gruppen-Definition

// Schematische Darstellung der Einträge in der MetaDb
Class=agorum.api.object.data.UserGroupDataHandler

// minimale Anzahl Zeichen, die als query vorhanden sein müssen, damit gesucht wird (z.B: in einer Combobox)
MinChars=2

// user=Benutzer, group=Benutzergruppen, user-group=Benutzer und Benutzergruppen, group-users=Benutzer einer Benutzergruppe
Type=user

// Name der Benutzergruppe, in der gesucht werden soll, gilt, wenn Type=group-users
Group=GRP_Demo

JS

Der JS-DataHandler ruft ein Skript auf, das Daten zurückgeben oder manipulieren kann. Der JS-Handler kann ebenfalls verwendet werden, um etwa einen weiteren Handler aufzurufen, um diese Logik zu verleihen.

Folgende Parameter können Sie an den JS-DataHandler übergeben:

MAIN_MODULE_MANAGEMENT/customers/Standard/Data/user-group

// Schematische Darstellung der Einträge in der MetaDb
Class=agorum.api.object.data.JsDataHandler

// Pfad oder ID zu einer JS-Datei
Script=/agorum/roi/customers/demo/js/TestDataHandler.js

// oder Inline JavaScript Code
Script.js=Inline JavaScript Code

Beispiel: TestDataHandler.js

/* global sc, sca, query, parameters, command, path */

let items = [];
if (command === 'read') {
  items.push({
    text: 'dies ist Kommando: ' + command,
    value: 'dies ist die Query: ' + query
  });
}
items;

Beispiel: ParameterizedDataHandler.js

Für dieses Beispiel:

• muss der MetaDB-Key Limit angelegt werden
• muss der Parameter elementName angegeben werden

/* global sc, sca, query, parameters, command, path */
let metadb = require('common/metadb');

// Lese die MetaDB-Keys des DataHandlers aus
let limit = metadb.getParameter('limit', parameters, path, 100, 'number'); 

// Setze die Einstellungen des DataHandlers
let elementName = parameters.elementName;

let items = [];
if (command === 'read') {  
  // Füge Elemente hinzu, bis die Anzahl <Limit> entspricht.
  while (items.length < limit) {
    let count = items.length + 1;
    items.push({
      text: 'Dies ist ' + parameters.elementName + ' Nummer: ' + count,
      value: count
    });
  }
}

// apply limit
items = items.splice(0, limit);

items;

Beispiel: completeQuery

Dieses Beispiel verwendet completeQuery aus Parameters, sofern die completeQuery mitgegeben wurde. Dieser Parameter wird mitgegeben, wenn der DataHandler im Rahmen eines Suchfilters verwendet wird.

/* global sc, sca, query, parameters, command, path */
let objects = require('common/objects');
let metadb = require('common/metadb');

if (command !== 'read') {
  throw 'This data handler does not support the command "' + command + '"';
}

let items = [];
let limit = metadb.getParameter('limit', parameters, path, 100, 'number');

if (parameters.lookup) {
  // if query is set, try to find the object, cause query should be the uuid
  let obj = query && objects.tryFind(query);
  if (obj) {
    items.push({
      text: obj.name,
      value: obj.UUID
    });
  }
} else {
  let q = query || '';
  if (parameters.completeQuery) {
    q += ' (' + parameters.completeQuery + ')';
  }

  items = objects.query(q).limit(limit).search('name', 'uuid').rows.map(row => {
    return {
      text: row.name,
      value: row.uuid
    };
  });
}

items;

Beispiel: Metadaten für Lieferantenname und Lieferantennummer

Beispiel für den Lieferantennamen und die Lieferantennummer siehe Beispiel-Metadatum mit einem JS-Handler definieren.

Verwendung des JS DataHandlers innerhalb der Suche

Bei Verwendung des JS DataHandlers innerhalb der Suche liefert das System in parameters.filterSelection alles mit, was in der Suche gewählt wurde. So kann der DataHandler darauf reagieren und etwa in Abhängigkeit der Auswahl nur eine passende Untermenge liefern (Aufbau des Parameters filterSelection siehe Einen Filter vorbelegen).

Beispiel

/* global sc, sca, query, parameters, command, path */

let items = [];
if (command === 'read') {
  let filterValue = parameters.filterSelection.nameDesFilters.value;

  items.push({
    text: 'dies ist Kommando: ' + command,
    value: 'dies ist die Query: ' + query
  });
}
items;