> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://docs.brainframe.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Dokumentformulare

${frame}[Interaktive Demo](https://app.arcade.software/share/cnP8vgBzQ7mGFLG8ib6B)

Dokumentformulare verwandeln die Erstellung und Bearbeitung von Dokumenten in eine geführte, strukturierte Erfahrung. Anstelle eines einzelnen Rich-Text-Editors oder einer Dateivorschau sehen Autoren ein Layout aus **Abschnitten** und **Feldern**, das auf den jeweiligen Dokumenttyp zugeschnitten ist – Metadaten, konfigurierbare Eigenschaften, Risikozusammenfassungen, verknüpfte Dokumente und mehr.

## Zweck

Dokumentformulare dienen dazu, **Dokumenteigenschaften strukturiert darzustellen und zu erfassen**.

Sie sind besonders hilfreich, wenn:

* Dokumente konsistente Metadaten benötigen (Eigentümer, Klassifizierung, Prüfdatum, verknüpfte Assets usw.)
* Risikobezogene Dokumente **anfängliches**, **aktuelles** und **Zielrisiko** auf einen Blick visualisieren sollen
* Verwandte Dokumente sichtbar und direkt im Formular bearbeitbar sein sollen
* Autoren einer festen Struktur folgen sollen, anstatt mit einer leeren Seite zu beginnen

Ein Dokumentformular ersetzt weder Dokumenttypen noch Dokumenteigenschaften. Es handelt sich lediglich um eine andere **Darstellungs- und Bearbeitungsansicht**, die einem Dokumenttyp zugewiesen werden kann. Die zugrunde liegenden Daten bleiben weiterhin in den Dokumenteigenschaften, verknüpften Elementen, Risikobewertungen usw. gespeichert.

> **Hinweis:** Dokumentformulare unterscheiden sich von **Anfrageformularen (Request Forms)**. Anfrageformulare sind öffentliche oder interne Einreichungs-Workflows, die Prozesse auslösen. Dokumentformulare sind Layouts für die Anzeige und Bearbeitung von Dokumenten eines bestimmten Typs.

## Zusammenspiel der Komponenten

| Ebene | Definition |
| ---- |
| **Dokumenteigenschaften** | Benutzerdefinierte Felder, die für ein Dokument ausgefüllt werden sollen (z. B. Eigentümer, Kritikalität, Frist, ...) |
| **Dokumentformular** | Definiert das Layout und die Gruppierung von Feldern/Widgets mithilfe von Abschnitten |
| **Dokumenttyp** | Kann so konfiguriert werden, dass er ein Dokumentformular verwendet oder nicht, und definiert, welche Eigenschaften verpflichtend oder optional sind |

## Zentrale Komponenten

Ein Dokumentformular besteht aus skalierbaren **Abschnitten**, die **Felder** enthalten. Die Felder lassen sich in drei Kategorien einteilen.

### 1. Konfigurierbare Dokumenteigenschaften

Dies sind **arbeitsbereichsdefinierte Dokumenteigenschaften**, die im Formular platziert werden können. Jede Eigenschaft besitzt einen **Antworttyp**, der bestimmt, wie sie in der Benutzeroberfläche dargestellt wird:

| Antworttyp | Eingabeart |
| ---- |
| **1 – Text** | Mehrzeiliges Textfeld |
| **2 – Einzelauswahl** | Dropdown-Liste |
| **3 – Mehrfachauswahl** | Chips / Mehrfachauswahl |
| **4 – Link-Auswahl** | Verknüpfungen zu anderen Dokumenten der konfigurierten Typen |
| **5 – Datum** | Datumsauswahl |

Eigenschaften unterstützen:

* **Titel** und **Beschreibung/Beschriftung** (Hilfetext)
* **Mehrsprachige Übersetzungen** für Titel und Beschriftung (wenn Übersetzungen aktiviert sind)
* **Pflichtfeld-Kennzeichnung** (durchgesetzt in Kombination mit der Dokumenttyp-Konfiguration)

### 2. Widgets

Widgets zeigen erweiterte Dokumentdaten oder spezialisierte Bearbeitungsoberflächen an:

| Widget | Zweck |
| ---- |
| **Dokumentvorschau/-editor** | Rich-Text-Inhalt (Summernote) innerhalb des Formulars |
| **Datei-Upload** | Dokumentdatei anhängen oder ersetzen |
| **Anfängliches / aktuelles / Zielrisiko** | Risiko-Badges basierend auf der neuesten Risikobewertung; die Bearbeitung öffnet das Risikobewertungs-Panel im Bereich Aktivitäten |
| **Verknüpfte Dokumente (spezifisch)** | Verknüpfte Dokumente eines **bestimmten Dokumenttyps**, optional mit direkter Bearbeitung von Eigenschaften/Metadaten |
| **Verknüpfte Dokumente (gruppiert)** | Alle verknüpften Dokumente **nach Typ gruppiert** |
| **Horizontale Linie** | Visueller Trenner |
| **Risiko-Widgets** | **Anfängliches Risiko**, **aktuelles Risiko** und **Zielrisiko** aus der neuesten Risikobewertung des Dokuments. Im Bearbeitungsmodus öffnet eine Stift-Aktion den Risikobewertungs-Workflow in der Aktivitäten-Seitenleiste. Wenn der Dokumenttyp ein Standard-Risiko-KPI besitzt und noch keine Bewertung existiert, kann dieses KPI beim Öffnen der Risikobearbeitung vorausgewählt werden. |

#### Eigenschaften von Widgets für verknüpfte Dokumente

Widgets für verknüpfte Dokumente können pro Feld konfiguriert werden:

* **Anzuzeigender Dokumenttyp** – definiert, welcher verknüpfte Dokumenttyp angezeigt wird (das gruppierte Widget zeigt alle verknüpften Dokumenttypen)
* **Dokumenteigenschaften anzeigen/bearbeiten** – legt fest, welche Eigenschaften des verknüpften Dokumenttyps inline angezeigt werden und ob sie schreibgeschützt oder bearbeitbar sind. Es stehen nur Eigenschaften zur Verfügung, die dem verknüpften Dokumenttyp zugewiesen sind (verpflichtend oder optional).
* **Metadaten anzeigen** – optionale Anzeige von Erstellungsdatum, Änderungsdatum, Prozessstatus sowie anfänglichem, aktuellem und Zielrisiko der verknüpften Elemente.

### 3. Dokumentmetadaten

Schreibgeschützte oder bearbeitbare Dokumentmetadaten:

| Komponente | Zweck |
| ---- |
| **Dokumentname** | Dokumenttitel |
| **Kennung** | Eindeutige Kennung (wenn für den Dokumenttyp aktiviert) |
| **Aktuelle Version** | Aktive Versionsnummer |
| **Erstellungsdatum** | Zeitpunkt der Erstellung des Dokuments |
| **Änderungsdatum** | Zeitpunkt der letzten Änderung |
| **Hinweistext** | Anweisungen für Autoren (werden nicht als Dokumentdaten gespeichert) |

## Abschnitte und Layout

Dokumentformulare verwenden ein **12-spaltiges GridStack-Raster**. Jedes Formular besteht aus einem oder mehreren **Abschnitten**, die jeweils Folgendes enthalten:

* **Position und Größe** – Rasterkoordinaten `x`, `y`, `w`, `h`
* **Titel** – Abschnittsüberschrift für Benutzer
* **Felder** – geordnete Liste aus Metadaten, Eigenschaften und Widgets

Im Formular-Editor können Abschnitte:

* Hinzugefügt und entfernt werden
* Im Raster verschoben und in der Größe angepasst werden
* Mit **übersetzten Titeln** versehen werden (siehe unten)

Beim Anzeigen oder Bearbeiten eines Dokuments werden Abschnitte als **einklappbare Karten** dargestellt. Das Raster passt seine Höhe automatisch an den Inhalt an.

## Benutzerdefinierte Übersetzungen

Mehrsprachigkeit wird auf zwei Ebenen unterstützt.

### Abschnittstitel

Im Formular-Editor kann für jeden Abschnittstitel die Funktion **Übersetzungen** aktiviert werden. Ist sie aktiviert, kann ein Titel für jede aktivierte Sprache des Arbeitsbereichs hinterlegt werden. Diese Werte werden als `title_translated` (sprachabhängige Zuordnung) gespeichert. Zur Laufzeit wählt die Benutzeroberfläche den Titel entsprechend der aktiven Sprache des Benutzers aus, mit Fallback auf Englisch und anschließend auf den Basistitel.

### Beschriftungen von Dokumenteigenschaften

Dokumenteigenschaften können Übersetzungen für Folgendes aktivieren:

* **Titel** – Feldbeschriftung im Formular
* **Beschriftung/Beschreibung** – Hilfetext neben dem Feld

Die Übersetzungen werden unter **Arbeitsbereichseinstellungen → Dokumenteigenschaften** konfiguriert, nicht im Formular-Editor selbst. Das Formular verweist auf die Eigenschaftsdefinition; die übersetzten Bezeichnungen werden zur Laufzeit anhand der Benutzersprache aufgelöst.

## Konfiguration von Dokumentformularen (Formular-Editor)

Dokumentformulare werden unter **Arbeitsbereichseinstellungen → Dokumentformular** verwaltet.

### Erstellen oder Bearbeiten eines Formulars

1. **Titel festlegen** – Name, der bei der Zuweisung an Dokumenttypen angezeigt wird.
2. **Abschnitte hinzufügen** – neue Formulare beginnen mit zwei leeren Abschnitten; weitere können hinzugefügt werden.
3. **Layout gestalten** im Formular-Designer:

* **Linke Palette** – durchsuchbare Liste verfügbarer Komponenten (Metadaten, Eigenschaften, Widgets)
* **Rechte Arbeitsfläche** – GridStack-Abschnitte, in die Komponenten gezogen werden
4. **Komponenten per Drag-and-Drop platzieren** oder Felder innerhalb bzw. zwischen Abschnitten neu anordnen.
5. **Felder konfigurieren**, falls erforderlich:

* **Hinweistext** – Inhalt bearbeiten
* **Verknüpfte Dokumente (spezifisch)** – Dokumenttyp auswählen; Sichtbarkeit von Eigenschaften/Metadaten konfigurieren
* **Verknüpfte Dokumente (gruppiert)** – Sichtbarkeit von Metadaten konfigurieren
6. **Abschnittstitel bearbeiten** – auf das Stiftsymbol eines Abschnitts klicken; optional sprachspezifische Übersetzungen aktivieren.
7. **Speichern** – das Layout wird gespeichert.

### Regeln für die Komponentenpalette

* Die meisten Komponenten können **nur einmal** pro Formular verwendet werden (und werden danach in der Palette ausgeblendet).
* **Horizontale Linie** und **Verknüpfte Dokumente (spezifisch)** können **mehrfach** hinzugefügt werden (z. B. für verschiedene Dokumenttypen).
* **Dokumenteigenschaften** des Arbeitsbereichs erscheinen in der Palette unter dem Typ **Eigenschaft**. Alle Arbeitsbereichseigenschaften stehen zur Verfügung; Sie entscheiden, welche in ein Formular aufgenommen werden.

## Konfigurierbare Dokumenteigenschaften

Dokumenteigenschaften werden separat unter **Arbeitsbereichseinstellungen → Dokumenteigenschaften** definiert. Sie bilden die Bausteine, die Formulare anzeigen können.

### Definieren einer Eigenschaft

Beim Erstellen oder Bearbeiten einer Eigenschaft werden folgende Einstellungen konfiguriert:

| Einstellung | Beschreibung |
| ---- |
| **Titel** | Bezeichnung in Formularen und Filtern (mindestens 3 Zeichen) |
| **Beschreibung/Beschriftung** | Optionaler Hilfetext |
| **Antworttyp** | Text, Einzelauswahl, Mehrfachauswahl, Link-Auswahl oder Datum |
| **Antworttyp-Werte** | Optionen für Dropdowns/Chips, erlaubte Linktypen oder Standardwerte |
| **Übersetzungen** | Sprachspezifische Titel und Beschreibungen (wenn Mehrsprachigkeit aktiviert ist) |

#### Besonderheiten der Antworttypen

* **Text (1)** – optionaler Standardtext
* **Einzelauswahl (2) / Mehrfachauswahl (3)** – Liste von Optionen
* **Link-Auswahl (4)** – ein oder mehrere **Dokumenttypen**, die verknüpft werden dürfen (z. B. Mitarbeiter, Produkt, Kontrolle)
* **Datum (5)** – Datumsfeld

Wie Formulare können Eigenschaften entweder arbeitsbereichsspezifisch oder Brainframe-Standardvorlagen sein (und in den Arbeitsbereich importiert werden).

### Beziehung zu Dokumentformularen

1. **Eigenschaften erstellen** in den Einstellungen für Dokumenteigenschaften.
2. **Eigenschaften per Drag-and-Drop hinzufügen** aus der Palette des Formular-Editors.
3. Zur Laufzeit rendert das Formular jede Eigenschaft mit dem passenden Eingabeelement und liest/schreibt in den Eigenschaftsspeicher des Dokuments.

Eine Eigenschaft muss nicht in einem Formular erscheinen, um Teil eines Dokumenttyps zu sein – siehe Dokumenttyp-Konfiguration unten. Umgekehrt macht das Platzieren einer Eigenschaft im Formular sie nicht automatisch verpflichtend; dies wird durch den Dokumenttyp gesteuert.

## Konfiguration bei Dokumenttypen

Dokumentformulare werden **pro Dokumenttyp** unter **Arbeitsbereichseinstellungen → Dokumenttypen** zugewiesen.

### Dokumentansicht vs. Formularansicht

Jeder Dokumenttyp besitzt eine Einstellung **Ansicht**:

| Ansicht | Verhalten |
| ---- |
| **Dokumentansicht** | Klassische Erfahrung – OnlyOffice, Summernote, Markdown, Diagramm usw., abhängig von Vorlage und Dateityp |
| **Formularansicht** | Das zugewiesene **Dokumentformular** wird für Erstellung, Anzeige und Bearbeitung verwendet. Das Formular hat Vorrang vor dem Standardeditor |

Wenn **Formularansicht** ausgewählt ist:

1. **Ansicht auswählen** – das zu verwendende Dokumentformular auswählen (erforderlich).
2. Dokumenttyp speichern.

Dokumente dieses Typs laden anschließend das Formularlayout über `auth/getDocumentForm` (arbeitsbereichsweit zwischengespeichert). Falls ein Dokument bereits eingebettete `documentFormData` enthält, kann dieser Schnappschuss direkt verwendet werden.

### Verpflichtende und optionale Dokumenteigenschaften

Im selben Dialog für den Dokumenttyp, unabhängig von der Formularzuweisung:

* **Verpflichtende Dokumenteigenschaften** – müssen ausgefüllt werden; die Validierung erfolgt bei Erstellung und Bearbeitung
* **Optionale Dokumenteigenschaften** – verfügbar, aber nicht erforderlich

Diese Listen:

* Definieren, welche Eigenschaften Teil des Datenmodells des Dokumenttyps sind
* Steuern Validierung und Standardinitialisierung
* Begrenzen, welche Eigenschaften **inline in Widgets für verknüpfte Dokumente** angezeigt werden können

**Wichtige Unterscheidung:**

| Konfiguration | Geltungsbereich |
| ---- |
| **Verpflichtend / optional im Dokumenttyp** | Legt fest, welche Eigenschaften existieren und erforderlich sind |
| **Felder im Dokumentformular** | Legt fest, welche Eigenschaften (und Widgets) sichtbar sind und wie sie angeordnet werden |

Eine verpflichtende Eigenschaft sollte normalerweise im Formular erscheinen, damit Autoren sie ausfüllen können. Eine optionale Eigenschaft kann im Formular fehlen und dennoch auf dem Dokument existieren (z. B. zur späteren Befüllung oder ausschließlich für Suche und Filter).

## Zusammenfassung

| Konzept | Rolle |
| ---- |
| **Dokumentformular** | Wiederverwendbares, rasterbasiertes UI-Layout (Abschnitte + Felder) |
| **Dokumenteigenschaft** | Typisierte Definition eines benutzerdefinierten Felds (Text, Auswahl, Datum, Links usw.) |
| **Dokumenttyp** | Wählt Formular- oder Dokumentansicht, weist ein Formular zu und definiert verpflichtende/optionale Eigenschaften |
| **Abschnitt** | Gruppierter, einklappbarer und optional übersetzbarer Block im Formular |
| **Widget** | Spezialisierte Oberfläche für Risiken, Verknüpfungen, Dateien, Editor usw. |
| **Übersetzungen** | Abschnittstitel im Formular-Editor sowie Titel/Beschriftungen von Eigenschaften in den Einstellungen für Dokumenteigenschaften |

Gemeinsam ermöglichen diese Komponenten Administratoren festzulegen, **welche Daten Dokumente enthalten** (Eigenschaften + Regeln des Dokumenttyps) und **wie Autoren mit diesen Daten interagieren** (Formularlayout), ohne das zugrunde liegende Brainframe-Dokumentmodell zu verändern.