Properties (Formular-Parameter)¶

Properties sind Schlüssel/Wert-Paare, die Administratoren und Key-User pflegen, ohne dass ein Formular neu entwickelt werden muss. Ein Formular liest sie zur Laufzeit als ctx.params.<name> (im Skript) bzw. ${param:<name>} (in Leittexten, Vorbelegungen und Bedingungen).

Typische Anwendungsfälle:

E-Mail-Adressen einer zuständigen Stelle (z.B. Personalabteilung), die sich im Laufe der Zeit ändern können
Grenzwerte (z.B. Genehmigungs-Betrag), ab denen ein Formular anders reagiert
Textbausteine / Leittexte, die eine Fachabteilung selbst pflegt
Mail-Schablonen mit Platzhaltern, die ein onSubmit-Skript füllt

Der Clou: Diese Werte liegen nicht im Schema. Ein Key-User ändert sie im laufenden Betrieb — das Formular selbst bleibt unangetastet.

Schlüssel-Konvention¶

Ein Schlüssel ist nach dem Muster <bereich>.<name> aufgebaut:

Schlüssel	Gilt für	Beispiel
`<formularId>.<name>`	genau ein Formular	`urlaubsantrag.mailEmpfaenger`
`global.<name>`	alle Formulare	`global.supportMail`

Beim Öffnen eines Formulars werden zuerst alle global.*-Werte geladen und anschließend die <formularId>.*-Werte darüber gelegt. Ein formularbezogener Wert überschreibt also einen gleichnamigen globalen Wert. Im Formular steht der Wert dann unter dem nackten Namen bereit — also ctx.params.mailEmpfaenger, ctx.params.supportMail (ohne Präfix).

Sprachvarianten (`@sv`, `@en`)¶

Ein Schlüssel mit @ und einem Sprachcode am Ende ist die Fassung für diese Sprache, zum Beispiel urlaubsantrag.msgText.1.2@sv. Ohne @ ist es die Basissprache des Formulars.

Heute lesen nur die Workflow-Mailtexte solche Varianten (siehe Workflow-Workshop, 5.4). In ctx.params und ${param:…} tauchen sie nicht auf — dort gilt weiterhin nur der Eintrag ohne @. Sprachabhängige Hilfetexte und Links sind geplant.

Aufbau einer Property¶

Feld	Zweck
Schlüssel	`<formularId>.<name>` oder `global.<name>` (eindeutig)
Wert	der eigentliche Wert (`ctx.params.<name>`)
Zusatzwert	optionaler zweiter Wert, z.B. eine Mail-Schablone (`ctx.paramsExtra.<name>`)
Bemerkung	interne Notiz für die Pflegenden (nicht im Formular sichtbar)

Der Zusatzwert eignet sich für längere Texte (Textbausteine, Mail-Schablonen), während der Wert knapp bleibt (Adresse, Zahl, Kennzeichen).

Datei-Anlage¶

Jede Property kann zusätzlich eine Datei tragen (z.B. ein Vorlage-Dokument, das ein onSubmit-Skript als Mail-Anhang verwendet). Im Editor unter Datei-Anlage per „Datei anhängen…" hochladen; bestehende Anlagen lassen sich Herunterladen, Ersetzen oder Entfernen. Die Datei wird Base64-kodiert in der Property gespeichert und reist beim Formular-Transport mit.

Bulk-Import aus Excel/CSV¶

Über den Knopf „⬆ Import (Excel/CSV)" oben rechts lassen sich viele Properties auf einmal aus einer .xlsx- oder .csv-Datei einspielen (vorhandene Schlüssel werden aktualisiert, neue angelegt). Erkannt werden die Spalten Schlüssel, Wert, Zusatzwert und Bemerkung (Kopfzeile case-insensitiv; ohne erkennbare Kopfzeile gilt genau diese Reihenfolge). Beispiel-CSV:

Schlüssel;Wert;Zusatzwert;Bemerkung
urlaubsantrag.maxTage;30;;jährlicher Höchstanspruch
urlaubsantrag.mailEmpfaenger;personal@example.com;Sehr geehrte…;Genehmigungsmail
global.firmenname;Kehrmann Consulting AB;;

Der Import lässt Datei-Anlagen unberührt — er schreibt nur die Textspalten.

Pflege im Admin-Bereich¶

Die Verwaltung findet sich unter System-Administration → Formular-Konfiguration → Properties. Sie zeigt eine Tabellen-Übersicht aller Properties (Schlüssel, Wert, Zusatzwert, Bemerkung, Datei, Aktualisiert) mit Filterfeld und Spalten-Sortierung. Über die Checkboxen lassen sich einzelne Zeilen auswählen; der Export (als CSV oder Excel/.xlsx) übernimmt die Auswahl — ohne Auswahl werden alle (gefilterten) Zeilen exportiert. Ein Klick auf eine Zeile öffnet den verschieb- und größenverstellbaren Editor-Dialog; über „Duplizieren" wird aus einem Datensatz eine neue Property abgeleitet. Neue Einträge über „+ Neue Property".

Wer darf pflegen — das Recht `PROPERTIES`¶

Der Zugriff ist über die Berechtigung PROPERTIES (technisch PERM_PROPERTIES) gesteuert. Zwei Wege:

Administratoren (Gruppe ADMIN) haben automatisch alle Rechte und damit auch Zugriff auf die Properties-Pflege.
Key-User bekommen die Berechtigung PROPERTIES einer Gruppe zugewiesen (Benutzer & Zugang → Gruppenverwaltung, Abschnitt Berechtigungen der Gruppe). Sie sehen dann im Zahnrad-Menü nur den Eintrag „Properties" und landen in einer reduzierten Ansicht, die ausschließlich die Property-Pflege zeigt — die übrige System-Administration bleibt ihnen verborgen.

Pflege im Formular-Editor¶

Bei vielen Formularen ist die zentrale Liste lang. Die Properties eines Formulars bearbeiten Sie deshalb auch direkt im Formular-Editor. Dort sehen Sie nur die Einträge dieses Formulars, auch wenn es Hunderte andere gibt.

Schritt 1 — Dialog öffnen. Öffnen Sie das Formular im Formular-Editor. Klicken Sie oben rechts auf „⋯ Mehr" und dann auf „🔧 Properties …".

Die Kopfzeile des Formular-Editors: neben dem Formular-Auswahlfeld ist das Menü „Mehr" aufgeklappt, der Eintrag „Properties …" ist hervorgehoben

Schritt 2 — Überblick. Es öffnet sich ein Fenster mit der Überschrift „Properties —" und dem Namen des Formulars. Daneben steht in grauer Schrift, womit alle Schlüssel hier beginnen (zum Beispiel begutachtung-workflow.*). Hat das Formular noch keine Properties, ist die Liste leer.

Der Properties-Dialog eines Formulars, noch ohne Einträge. Oben die Knöpfe CSV, Excel, Workflow-Mailtexte erzeugen und Neue Property

Schritt 3 — einen Eintrag anlegen. Klicken Sie auf „+ Neue Property". Im Feld Schlüssel steht der Anfang schon da, etwa begutachtung-workflow.. Schreiben Sie dahinter nur noch den Namen, zum Beispiel maxTage. Tragen Sie den Wert ein und klicken Sie auf Speichern. Im Formular erreichen Sie den Eintrag dann als ctx.params.maxTage bzw. ${param:maxTage}.

Das Fenster „Neue Property": Der Schlüssel beginnt bereits mit dem Formularnamen, darunter Wert, Zusatzwert und Bemerkung

Ein vorhandener Eintrag öffnet sich mit einem Klick auf seine Zeile. Dort können Sie ihn ändern, duplizieren oder löschen.

Der Dialog zeigt dieselbe Tabelle und denselben Editor wie die Administration — mit Datei-Anlage, Zusatzwert, Bemerkung, Duplizieren und Export. Zwei Unterschiede:

Sie sehen und bearbeiten nur Schlüssel, die mit <formularId>. beginnen. Bei „+ Neue Property" steht dieser Anfang schon im Schlüsselfeld. global.*-Einträge und die Einträge anderer Formulare bleiben der Administration vorbehalten.
Der Excel-/CSV-Import fehlt hier. Er kann beliebige Schlüssel schreiben und gehört deshalb in die Administration.

Hat das Formular einen Workflow, steht dort zusätzlich der Knopf „✉ Workflow-Mailtexte erzeugen" — er legt für jeden Stufenwechsel eine Mail-Schablone an und lässt vorhandene unverändert (siehe Workflow-Workshop, 5.3).

Wer darf das? Jeder, der den Formular-Editor öffnen darf — also Administratoren und Gruppen mit dem Recht FORM_STUDIO. Das Recht PROPERTIES ist dafür nicht nötig.

Zugriff im Formular¶

Leittexte und Bedingungen (`${param:…}`)¶

In kc:text, kc:visibleIf, kc:defaultValue und anderen Ausdrücken steht der Wert als Makro ${param:<name>} bzw. — in JS-Bedingungen — als ctx.params.<name> bereit:

{
  "willkommen": {
    "type": "string",
    "kc:text": "${param:willkommen}"
  },
  "grenzwert": {
    "type": "number",
    "kc:readonly": true,
    "kc:defaultValue": "${param:limit}"
  },
  "ueberGrenze": {
    "type": "string",
    "kc:text": "⚠️ Betrag über dem Grenzwert von ${param:limit} €.",
    "kc:visibleIf": "kc.num(betrag) > kc.num(ctx.params.limit)"
  }
}

Scripting (`ctx.params` / `ctx.paramsExtra`)¶

In allen Server-Hooks (onLoad, onSubmit, …) liegen die Werte unter ctx.params (Wert) und ctx.paramsExtra (Zusatzwert):

var to      = ctx.params.mailEmpfaenger;       // Empfänger-Adresse
var vorlage = ctx.paramsExtra.mailEmpfaenger;   // Mail-Schablone (Zusatzwert)
var grenze  = kc.num(ctx.params.limit);

var text = String(vorlage)
    .replace("{betrag}", kc.num(ctx.form.betrag).toFixed(2))
    .replace("{grenzwert}", grenze.toFixed(2));

if (kc.num(ctx.form.betrag) > grenze) {
    mail.send({ to: to, subject: "Genehmigung erforderlich", body: text });
}

Nur lesend

ctx.params ist zur Laufzeit schreibgeschützt — es spiegelt die im Admin gepflegten Werte. Wer einen Wert ändern will, tut das in der Properties-Verwaltung, nicht im Skript.

Transport auf ein anderes System¶

Die zu einem Formular gehörenden Properties (Prefix <formId>.) können auf ein anderes KCForms-System übertragen werden — analog zum Formular-Transport:

Beim Formular-Transport: Der Push-Dialog zeigt die Checkbox „Properties (konfigurierbare Werte) dieses Formulars mitübertragen" (Standard: an). Die <formId>.*-Properties reisen dann inkl. Datei-Anlagen mit.
Einzeln je Formular: Der Knopf „Nur Properties" im Push-Dialog überträgt ausschließlich die Properties eines Formulars, ohne das Formular selbst — z.B. um einen geänderten Grenzwert nachzuziehen.

Globale Properties (global.*) reisen bewusst nicht mit — sie sind systemweite Konfiguration und werden pro System gepflegt. Auf der Zielseite werden die Properties nach Schlüssel abgeglichen (vorhandene werden aktualisiert, neue angelegt).

Beispiel-Formular¶

Das Beispiel „Konfigurierbares Formular (Properties)" (Formular-ID property-demo) zeigt alle vier Zugriffsarten an einem Stück:

Leittext aus property-demo.willkommen und der globalen global.supportMail
Vorbelegung zweier Read-only-Felder aus property-demo.ansprechpartner und property-demo.limit
Bedingung: ein Warntext erscheint, sobald der eingegebene Betrag den Grenzwert aus property-demo.limit übersteigt
Scripting: das onSubmit liest Empfänger und Mail-Schablone aus property-demo.mailEmpfaenger / dessen Zusatzwert

Installieren über System-Administration → Formular-Bausteine → Beispiele → „Konfigurierbares Formular (Properties)" (danach im Katalog Beispiele, Ordner Konfiguration). Die zugehörigen Demo-Properties werden dabei automatisch mit angelegt. Ändere anschließend in der Properties-Pflege z.B. property-demo.limit und beobachte, wie Grenzwert-Anzeige und Warntext im Formular sofort mitziehen.