Files

Denis Lugowski c05ffa964b feat: Update seed yaml skill

2026-02-16 19:43:12 +01:00

9.4 KiB

Raw Permalink Blame History

name, description

name	description
seed-yaml-sync	Use when modifying seed files in template/ or demo/ directories - ensures structural consistency, visibility condition correctness, and test data synchronization between template and demo form

Seed YAML Synchronization

Overview

The Legal Consent Hub has two interdependent seed file directories that must stay synchronized:

Template (seed/template/) - isTemplate: true - defines the form structure, element types, options, visibility conditions, section spawn triggers, and template sections.
Demo form (seed/demo/) - isTemplate: false - a realistic SAP S/4HANA application form with pre-filled values derived from the template. Used for development testing and UI validation.

Changes to either directory can break the other. This skill ensures consistency.

File Structure

legalconsenthub-backend/src/main/resources/seed/
├── template/                              # Template (source of truth for structure)
│   ├── _main.yaml                         # Main file: isTemplate, name, !include directives
│   ├── section_01_angaben_zum_itsystem.yaml
│   ├── section_02_modulbeschreibung.yaml
│   ├── ... (16 sections total)
│   └── section_16_informationen_zur_kuenstlichen_intelligenz.yaml
│
└── demo/                                  # Demo form (SAP S/4HANA test data)
    ├── _main.yaml                         # Main file: isTemplate, name, !include directives
    ├── section_01_angaben_zum_itsystem.yaml
    ├── section_02_rollen_und_berechtigungen.yaml
    ├── ... (11 sections total)
    └── section_11_informationen_zur_kuenstlichen_intelligenz.yaml

File Format

_main.yaml contains form metadata and includes section files:

isTemplate: true  # or false for demo
name: Name des IT-Systems

formElementSections:
  - !include section_01_angaben_zum_itsystem.yaml
  - !include section_02_modulbeschreibung.yaml
  # ... more sections

Section files contain a single section definition (title, subSections, elements).

The SplitYamlLoader class merges these files before deserialization.

When to Use

Adding, removing, or modifying form elements in template sections
Changing visibility conditions, section spawn triggers, or options
Adding or modifying template sections
Changing element types, references, or clonable settings
Any edit to files in either template/ or demo/ directory

The Synchronization Rules

Rule 1: Template is the structural source of truth

The template defines ALL structural properties. The demo form must mirror them exactly:

Property	Template defines	Demo form mirrors
`reference`	Yes	Must match exactly
`title`	Yes	Must match exactly
`type`	Yes	Must match exactly
`options[].label`	Yes	Must match exactly
`options[].processingPurpose`	Yes	Must match exactly
`options[].employeeDataCategory`	Yes	Must match exactly
`options[].columnConfig`	Yes	Must match exactly
`visibilityConditions`	Yes	Must match exactly
`sectionSpawnTriggers`	Yes	Must match exactly
`isClonable`	Yes	Must match exactly
`tableRowPreset`	Yes	Must match exactly
`options[].value`	Defaults (empty/false)	Realistic SAP S/4HANA values
`description`	Yes	Must match exactly

Rule 2: Demo form values must be contextually appropriate

The demo form simulates a realistic "SAP S/4HANA Einfuehrung" (introduction) scenario. When adding test data:

RADIOBUTTON: Set value: 'true' for the selected option, empty string for others
CHECKBOX: Set value: 'true' for checked options, value: 'false' for unchecked
TEXTAREA/TEXTFIELD: Set value to realistic SAP S/4HANA content
TABLE: Set value to JSON arrays with realistic SAP data (e.g., role IDs, processing IDs)
DATE: Set value to a realistic date string
RICH_TEXT: Set value to formatted content

Demo form context: The form represents an "Einfuehrung" (introduction) of SAP S/4HANA with:

art_der_massnahme = "Einfuehrung" selected
luv_beabsichtigt = "Ja" (performance/behavior monitoring intended)
personenbezogene_daten_verarbeitet = "Ja"
Modules: FI/CO, HCM, SCM (3 spawned module sections)
5 processing operations (V001-V005)
5 roles (R001-R005), 6 permissions (P001-P006), 4 scopes (S001-S004)
5 interfaces (IF001-IF005)

Rule 3: Visibility conditions must be logically consistent

When changing visibility conditions:

Check the condition chain: If element B depends on element A, and element C depends on element B, changing A's options or reference affects B AND C.
sourceFormElementReference must exist: Every sourceFormElementReference value must match an existing element's reference in the same form context (same section or a parent-spawning section).
formElementExpectedValue must match an option: The expected value must correspond to an actual label (for RADIOBUTTON) or label (for CHECKBOX) of the referenced element.
Operator consistency:
- EQUALS / NOT_EQUALS: Compare against option labels (RADIOBUTTON) or option labels with value 'true' (CHECKBOX)
- IS_EMPTY / IS_NOT_EMPTY: No expected value needed
AND vs OR logic:
- AND: All conditions must be true (used for nested dependencies)
- OR: Any condition can be true (used for showing across multiple art_der_massnahme values)

Rule 4: Section spawn triggers must reference existing templates

Every sectionSpawnTriggers[].templateReference must match a section's templateReference in the template directory where isTemplate: true in _main.yaml.

Rule 5: Table cross-references must be valid

When a table column has columnConfig.sourceTableReference:

The referenced table must exist in the same form context
sourceColumnIndex must be a valid column index in the referenced table
If rowConstraint is used, all constraint references must be valid

Rule 6: Only extend demo data when contextually appropriate

When new elements or sections are added to the template:

DO add demo data when:

The element is visible in the "Einfuehrung" path (check visibility conditions)
The element belongs to a spawned section that would be active (e.g., rollen_berechtigungen_template, verarbeitung_mitarbeiterdaten_template, etc.)
The element is a new table column in an existing table that has data

DO NOT add demo data when:

The element is only visible for "Aenderung IT-System" or "Einstellung IT-System" paths
The element belongs to a template section that wouldn't spawn in the demo scenario
Adding data would be contradictory to the existing demo context (e.g., adding "Nein" data where parent says "Ja")

Rule 7: Section naming conventions

Template sections are named by functional purpose:

section_01_angaben_zum_itsystem.yaml
section_07_rollen_und_berechtigungen.yaml
section_02_modulbeschreibung.yaml (template section for spawned modules)

Demo sections include spawned section instances:

section_07_modul_sap_finance_and_controlling_fico.yaml (spawned from template)
section_08_modul_sap_human_capital_management_hcm.yaml (spawned from template)
section_09_modul_sap_supply_chain_management_scm.yaml (spawned from template)

Rule 8: _main.yaml must include all sections

When adding a new section file:

Create the section file with appropriate naming
Add the !include directive to the corresponding _main.yaml
Maintain logical section ordering

Checklist for Template Changes

When you modify files in the template/ directory, verify each item:

Structural sync: Every changed element's structure (type, options labels, visibility conditions, spawn triggers) is mirrored in the corresponding demo section for elements that exist there
New elements: If a new element is visible in the "Einfuehrung" path, add it to the demo form with appropriate SAP S/4HANA test data
Removed elements: If an element is removed from the template, remove it from the demo form
Visibility chain integrity: If you changed a visibility condition's source reference or expected value, trace all downstream dependencies
Spawn trigger integrity: If you changed spawn triggers, verify the template section references still exist
Table column consistency: If you added/removed/reordered table columns, update all tables that cross-reference this table (check sourceTableReference, sourceColumnIndex, filterCondition.sourceColumnIndex)
Option label changes: If you renamed an option label, update all visibility conditions that reference that label as formElementExpectedValue
_main.yaml update: If you added/removed a section file, update template/_main.yaml

Checklist for Demo Form Changes

When you modify files in the demo/ directory, verify:

No structural drift: You haven't changed any structural property that should come from the template (types, labels, visibility conditions, spawn triggers)
Value consistency: New values are consistent with the SAP S/4HANA "Einfuehrung" context
Table data alignment: Table JSON arrays all have the same length within a single table element
Cross-reference integrity: Table values that reference other tables use valid IDs from those tables
_main.yaml update: If you added/removed a section file, update demo/_main.yaml

9.4 KiB Raw Permalink Blame History