182 lines
9.4 KiB
Markdown
182 lines
9.4 KiB
Markdown
---
|
|
name: seed-yaml-sync
|
|
description: 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:
|
|
|
|
1. **Template** (`seed/template/`) - `isTemplate: true` - defines the form structure, element types, options, visibility conditions, section spawn triggers, and template sections.
|
|
2. **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:
|
|
```yaml
|
|
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:
|
|
|
|
1. **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.
|
|
2. **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).
|
|
3. **formElementExpectedValue must match an option**: The expected value must correspond to an actual `label` (for RADIOBUTTON) or `label` (for CHECKBOX) of the referenced element.
|
|
4. **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
|
|
5. **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:
|
|
1. Create the section file with appropriate naming
|
|
2. Add the `!include` directive to the corresponding `_main.yaml`
|
|
3. 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` |