Externe Datenquellen¶

KCForms kann Wertelisten (Lookups), Such-Picker und Skripte nicht nur aus der eigenen Datenbank speisen, sondern auch aus externen Datenbanken — z. B. einem ERP-System, einem zentralen Adressbestand oder einer Spiegeltabelle. Die Verbindungen werden einmal eingerichtet und stehen danach in Lookups, Pickern und Skripten (db.on("name"), siehe db) zur Verfügung.

Wo konfigurieren¶

System-Administration → Schnittstellen & Verteilung → Datenquellen. Links die Liste Externe Datenquellen, rechts der Editor. Über + Neu legst du eine Quelle an, Verbindung prüfen testet sie sofort (zeigt bei Erfolg Produkt und Version der Ziel-Datenbank), Speichern legt sie ab.

Oben zeigt der Kasten Haupt-Datenbank die Datenbank von KCForms selbst (Produkt, Adresse, Benutzer, Treiber). Er ist nur zur Information: Die Haupt-Datenbank wird über die Umgebungsvariablen SPRING_DATASOURCE_URL, …_USERNAME und …_PASSWORD eingestellt, nicht hier — siehe Datenbank.

Felder¶

Feld	Bedeutung
ID	Eindeutiger Name, z. B. `sap-export`. Unter diesem Namen erscheint die Quelle in der Auswahl Datenquelle und wird in Skripten angesprochen (`db.on("sap-export")`).
Datenbank-Typ	MySQL, MariaDB, PostgreSQL, Microsoft SQL Server oder Oracle. Die Auswahl füllt Treiber-Klasse, URL-Vorlage und Validierungs-SQL passend vor.
Treiber-Klasse	JDBC-Treiber. Wird aus dem Typ vorbelegt; nur bei Sonderfällen ändern.
URL	JDBC-Verbindungs-URL. Die Vorlage zeigt das Format je Typ.
Benutzername / Passwort	Anmeldedaten. Das Passwort wird nie im Klartext zurückgeliefert (nur ein „gesetzt"-Hinweis).
Initiales SQL-Statement	Optional; wird bei jedem Verbindungsaufbau ausgeführt (z. B. `ALTER SESSION …`).
Validierung SQL-Statement	Prüf-Abfrage für die Pool-Gesundheit. Default `select 1` — bei Oracle automatisch `select 1 from dual`.
Mindest-/Höchstanzahl Verbindungen	Pool-Größe (HikariCP `minimumIdle` / `maximumPoolSize`).
Maximum Wait (ms)	Wartezeit auf eine freie Verbindung, bevor abgebrochen wird.
Abandon Timeout (s)	Diagnose-Schwelle für hängende Verbindungen (Leak-Detection) + Keepalive-Takt.
Autocommit / Keep Alive	Autocommit-Modus bzw. periodisches Wachhalten von Leerlauf-Verbindungen.
Datenbank (Catalog)	Nur angeben, wenn statt der Default-Datenbank der Verbindung eine andere genutzt werden soll.
aktiviert	Deaktivierte Quellen sind nicht wählbar und liefern zur Laufzeit eine Fehlermeldung.

JDBC-Treiber¶

KCForms bringt die Treiber für MySQL, MariaDB, PostgreSQL, Microsoft SQL Server und Oracle mit. Für eine andere Datenbank muss das passende Treiber-JAR in das Backend aufgenommen werden (pom.xml, neu bauen).

MySQL läuft dabei über den MariaDB-Treiber. Eine Datenquelle vom Typ „MySQL“ mit der Treiber-Klasse com.mysql.cj.jdbc.Driver funktioniert trotzdem unverändert. Fehlt der Treiber von Oracle, verbindet KCForms automatisch über MariaDB. Was das für die Verschlüsselung bedeutet, steht unter Datenbank → Der Treiber für MySQL.

URL-Vorlagen (Platzhalter <…> ersetzen):

Typ	URL-Vorlage
MySQL	`jdbc:mysql://<HOST>:3306/<DATENBANK>?useUnicode=true&characterEncoding=UTF-8`
MariaDB	`jdbc:mariadb://<HOST>:3306/<DATENBANK>`
PostgreSQL	`jdbc:postgresql://<HOST>:5432/<DATENBANK>`
SQL Server	`jdbc:sqlserver://<HOST>:1433;databaseName=<DATENBANK>;encrypt=true;trustServerCertificate=true`
Oracle	`jdbc:oracle:thin:@<HOST>:1521/<SERVICE>`

Nutzung in Lookups und Pickern¶

Im Formular-Editor hat jedes Feld mit einem Lookup (kc:lookup) oder Picker (kc:picker) in den Eigenschaften eine Auswahl Datenquelle:

Interne KCForms-DB (Standard),
eine eingerichtete externe Quelle — die Auswahl von Tabellen und Spalten zeigt dann die Tabellen dieser Quelle, und die Werte kommen zur Laufzeit von dort.

Im Schema steht die Quelle als dataSourceId im Lookup bzw. Picker:

"lieferant": {
  "type": "string",
  "kc:lookup": {
    "dataSourceId": 4,
    "table": "LIEFERANTEN",
    "keyColumn": "NR",
    "valueColumn": "NAME",
    "orderBy": "NAME ASC"
  }
}

dataSourceId ist die interne Nummer der Quelle — der Formular-Editor trägt sie bei der Auswahl selbst ein. Von Hand geht auch der Name ("dataSourceId": "sap-export"); das ist beim Transport zwischen Systemen robuster, weil die Nummern dort verschieden sein können. Eine unbekannte Nummer oder ein unbekannter Name ergibt einen Fehler. Ohne dataSourceId (oder mit 0 bzw. "intern") wird die KCForms-Datenbank abgefragt.

Dialekt-Handling

Das Zeilen-Limit setzt KCForms passend zur Datenbank: MySQL, MariaDB und PostgreSQL mit LIMIT, SQL Server mit TOP, Oracle mit ROWNUM. Freies SQL (sql-Modus) muss ansonsten zur Ziel-Datenbank passen (Spaltennamen, Funktionen; bei Oracle z. B. FROM DUAL).

LDAP als Lookup-Quelle¶

Neben Datenbanken kann eine Werteliste auch aus einem LDAP-Verzeichnis kommen — z. B. um in einem Workflow einen Bearbeiter/Genehmiger aus dem Verzeichnis zu wählen. Dieselbe Auswahl Datenquelle listet unter LDAP-Verzeichnisse alle aktivierten LDAP-Konnektoren (siehe LDAP-Zugriff).

Nach der Auswahl erscheinen statt Tabelle und Spalten vier LDAP-Felder:

Feld	Bedeutung
Basis-DN	Suchwurzel, z. B. `ou=Users,dc=firma,dc=de`.
Filter	LDAP-Filter, z. B. `(objectClass=inetOrgPerson)` für Benutzer oder `(objectClass=groupOfNames)` für Gruppen.
keyAttr	Attribut, dessen Wert gespeichert wird — meist `uid` (oder `sAMAccountName` bei AD), `dn` ist auch erlaubt.
valueAttr	Attribut, das angezeigt wird — meist `cn` (voller Name).

Im Schema:

"bearbeiter": {
  "type": "string",
  "title": "Zugewiesener Bearbeiter",
  "kc:lookup": {
    "ldapConnector": "kcads",
    "ldapBase": "ou=Users,dc=kcforms,dc=test",
    "ldapFilter": "(objectClass=inetOrgPerson)",
    "keyAttr": "uid",
    "valueAttr": "cn"
  }
}

Gespeichert wird die uid (z. B. oliver), angezeigt der cn (z. B. Anna Beispiel). Die Liste wird bei jedem Öffnen live aus dem Verzeichnis geladen und alphabetisch nach Anzeigewert sortiert. Für Active Directory analog mit sAMAccountName / displayName.

LDAP im Picker (Such-Dialog)¶

Auch der Picker (kc:picker — der „…"-Knopf mit Such-Dialog) unterstützt LDAP als Quelle. Ideal, wenn viele Treffer möglich sind und man mehrere Felder auf einmal füllen will (z. B. Bearbeiter-Login und Name und E-Mail). Im Picker-Editor dieselbe „Datenquelle"-Auswahl; im LDAP-Modus gibst du an:

Basis-DN und Filter wie beim Lookup,
Anzeige-Attribute (Komma-Liste) — die Spalten im Dialog, z. B. cn, uid, mail,
Suchattribute (Komma-Liste) — der Suchbegriff wird server-seitig als (|(cn=*x*)(uid=*x*)…) in den LDAP-Filter gehängt,
set-Zuordnung — welches Formularfeld welches Attribut übernimmt.

"bearbeiter_pick": {
  "type": "string", "title": "Bearbeiter suchen…",
  "kc:picker": {
    "ldapConnector": "kcads",
    "ldapBase": "ou=Users,dc=kcforms,dc=test",
    "ldapFilter": "(objectClass=inetOrgPerson)",
    "columns": [{"column":"cn","title":"Name"},{"column":"uid","title":"Login"},{"column":"mail","title":"E-Mail"}],
    "search": ["cn","uid","mail"],
    "set": {"bearbeiter":"uid","bearbeiter_name":"cn","bearbeiter_mail":"mail"}
  }
}

Die Pagination passiert nach der Verzeichnis-Suche in KCForms; die Treffermenge wird durch die Seitengröße des Konnektors gedeckelt.

Ausprobieren im DB-Client¶

System-Administration → Werkzeuge & Diagnose → DB-Client hat oben dieselbe Auswahl der Datenquelle. Damit setzt du SQL interaktiv gegen die gewählte Quelle ab — praktisch, um Tabellen, Spalten und Filter zu prüfen, bevor du sie in einen Lookup übernimmst.

Sicherheit¶

Die Verwaltung ist Administratoren vorbehalten. Jede Quelle verbindet sich ausschließlich mit den dort hinterlegten Zugangsdaten. Gib dem Datenbank-Benutzer einer externen Quelle möglichst nur Leserechte auf die benötigten Tabellen — Skripte können über db.on(...) sonst auch schreiben.