Zum Inhalt

Transport zwischen Systemen (DEV → QS → PROD)

Mit dem Transport überträgst du ein Formular samt allem, was es zum Laufen braucht, von einem KCForms-System auf ein anderes — typisch von der Entwicklung (DEV) über die Qualitätssicherung (QS) in die Produktion (PROD). Das sendende System schickt ein Paket per HTTPS an das empfangende.

Was wird transportiert

Bestandteil Hinweis
Formular-Definition Schema und Kopfdaten (Titel, Katalog, Ordner, Einstellungen)
Skripte alle Hooks und die Hilfsfunktionen des Formulars
Übersetzungen die Formular-Texte in allen Sprachen (sv, en …)
Druckvorlagen die, auf die das Formular verweist (Kopf-/Fußzeile)
Skript-Bibliotheken die dem Formular zugewiesenen, samt Reihenfolge — und die, die ein Feld über Prüfung durch Validator verwendet, auch wenn sie nicht zugewiesen sind
Datei-Bibliotheken die dem Formular zugewiesenen samt Zuordnung und die von einem Validator verwendeten
Bilder & SVGs alle, die das Formular verwendet: Bild- und SVG-Elemente, Bilder in Kopf- und Fußzeile (eigene und zentrale Druckvorlagen), Seitenbilder aus dem PDF-Import und Bilder, die ein Leittext über /api/assets/… einbindet
Versionsgeschichte die eingefrorenen Stände versionierter Formulare, damit alte Datensätze am Ziel mit ihrem Layout öffnen (Versionierung)
Sections Feldgruppen aus dem Section-Repository, die das Formular verwendet
Properties die Formular-Properties <formId>.* inkl. Datei-Anlagen (abwählbar) — siehe Properties

Bewusst nicht enthalten:

  • Datensätze — jedes System hat seine eigenen Inhalte.
  • Benutzer, Gruppen, Berechtigungen und Zugriffsregeln — das Rechtekonzept ist je System eigenständig.
  • Theme — bewusst je System, damit DEV, QS und PROD optisch unterscheidbar bleiben.
  • Globale Properties (global.*), Datenquellen, Konnektoren und Mail-Einstellungen — Systemkonfiguration.
  • Stammdaten in eigenen Tabellen (Lookups) — eigener Weg, z. B. Datenbank-Export/-Import.

Einrichten: empfangendes System (z. B. QS)

  1. System-Administration → Schnittstellen & Verteilung → Transport öffnen.
  2. Im Bereich Transport-Empfang auf Generieren klicken (oder einen eigenen Token eintragen).
  3. Den Token kopieren und Speichern — danach wird er nur noch maskiert angezeigt; der Status zeigt „aktiv".

Solange kein Token gesetzt ist, lehnt das System jeden eingehenden Transport ab (HTTP 503).

Einrichten: sendendes System (z. B. DEV)

  1. System-Administration → Schnittstellen & Verteilung → Transport öffnen.
  2. Unter Zielsysteme mit + Neues Ziel anlegen:
    • Name (z. B. „QS"),
    • URL des Zielsystems (z. B. https://kcforms-qs.firma.local), ohne /api/…,
    • den Token des Zielsystems.
  3. Ping prüft, ob das Ziel erreichbar ist und den Token annimmt; das Ergebnis steht unter Letzter Status.

Transport auslösen

In der Formularliste per Rechtsklick auf ein Formular → 📤 Transportieren …:

  1. Zielsystem wählen.
  2. Die Checkbox Properties (konfigurierbare Werte) dieses Formulars mitübertragen ist vorbelegt; bei Bedarf abwählen.
  3. Vorschau zeigen — ein Probelauf am Ziel zeigt, was dort neu, aktualisiert oder übersprungen würde (noch ohne zu speichern).
  4. 📤 Übertragen — führt den Transport aus und zeigt das Ergebnis.

Nur Properties überträgt ausschließlich die Properties des Formulars — etwa um einen geänderten Grenzwert nachzuziehen, ohne das Formular selbst anzufassen.

Vorschau überspringen

Unter Betrieb & Überwachung → System-Einstellungen → Transport — Vorschau lässt sich der Probelauf abschalten („Ohne Vorschau direkt übertragen“). Standard ist „Immer mit Vorschau“.

Was am Ziel passiert

  • Formular: neu angelegt oder aktualisiert.
  • Skripte: Alle Skripte des Formulars am Ziel werden durch die aus dem Paket ersetzt. Ein auf DEV gelöschter Hook verschwindet also auch am Ziel.
  • Druckvorlagen und Skript-Bibliotheken: neue werden angelegt, vorhandene (gleicher Name bzw. Titel) aktualisiert; mitgelieferte Standard-Vorlagen bleiben unangetastet. Die Zuordnung der Bibliotheken wird auf die Reihenfolge aus dem Paket gesetzt. Eine Bibliothek, die nur ein Validator braucht, wird angelegt, aber dem Formular nicht zugewiesen — genau wie auf dem sendenden System.
  • Datei-Bibliotheken: Die Datei wird am Ziel unter demselben Pfad geschrieben; eine vorhandene Datei gleichen Namens wird ersetzt. Die Zuordnung zum Formular wird wie im Paket gesetzt.
  • Datenbank-Tabellen des Formulars (inkl. Detail-Tabellen) werden abgeglichen: fehlende Spalten kommen dazu, vorhandene bleiben unverändert.
  • Properties: nach Schlüssel abgeglichen (vorhandene aktualisiert, neue angelegt).

Sicherheit

  • Token wechseln: Bei Personalwechsel oder Verdacht auf Missbrauch im Bereich Transport-Empfang einen neuen generieren und speichern — der alte gilt sofort nicht mehr.
  • Empfang abschalten: Empfang deaktivieren löscht den Token; das System nimmt danach keine Transporte mehr an.
  • Protokoll: Jeder eingehende Transport — auch abgelehnte und Probeläufe — erscheint unter Letzte Empfänge (Zeit, Status wie ok, dryRun, unauthorized, error, Formular, Quelle, Prüfsumme).
  • HTTPS verwenden: Produktiv das Zielsystem nur hinter HTTPS betreiben — sonst reist der Token im Klartext durchs Netz.

Große Formulare brauchen etwas Geduld

Am Ziel werden Tabelle und Spalten angelegt. Auf einem langsamen System (z. B. einem NAS) dauert das je Spalte einige Sekunden. Das sendende System wartet deshalb bis zu 10 Minuten auf die Antwort (einstellbar über kcforms.transport.push-timeout-seconds).

Paketformat

Das Paket ist JSON mit einem Versionsfeld (derzeit 7). Ein System lehnt Pakete einer neueren Version ab, die es noch nicht kennt — so kann ein älteres Produktivsystem nicht versehentlich ein Paket mit unbekanntem Inhalt einspielen. Beim Aktualisieren also zuerst das Zielsystem aktualisieren.

Ein Paket trägt immer die niedrigste Version, die zu seinem Inhalt passt. Version 7 brauchen nur Formulare mit Datei-Bibliotheken; alle anderen gehen als 6 und lassen sich auch an ein Ziel übertragen, das noch nicht aktualisiert ist.

Siehe auch