Konfigurationsprojekte in agorum core

Dieses Dokument erklärt die Begriffe Konfigurationsprojekt und Plugin in agorum core, wann Sie ein Konfigurationsprojekt erstellen und welche Struktur ein Konfigurationsprojekt hat.

Was ist ein Konfigurationsprojekt?

Ein Konfigurationsprojekt ist eine standardisierte Projektstruktur in agorum core, die Anpassungen, Erweiterungen und Konfigurationen für ein System oder einen Kunden bündelt.

Merkmale eines Konfigurationsprojekts

Speicherort: /agorum/roi/customers/<projektname>/
Pflichtdatei: yml/project.yml – definiert Projektname, Version und Abhängigkeiten
Exportsteuerung: yml/export.yml – steuert, welche Komponenten exportiert werden
Standardisierte Struktur: Feste Ordner für JavaScript, Konfiguration, Deployment usw.

Typische Inhalte

Metadaten-Definitionen (yml/metadata.yml)
Ordnerstrukturen (yml/structure-basis.yml)
JavaScript-Komponenten (js/)
Deployment-Skripte (deploy/)
Workflows (workflows/)
ALBERT | AI Konfigurationen (ai/)

Vorteile eines Konfigurationsprojekts

Strukturiert: Klare Ordnerstruktur für alle Komponenten
Versionierbar: Export als ZIP-Datei mit Versionsnummer
Transportierbar: Import auf anderen Systemen möglich
Wartbar: Änderungen nachvollziehbar und dokumentiert
Testbar: Automatisierte Tests in test/js/

Wann erstelle ich ein Konfigurationsprojekt?

Erstellen Sie ein Konfigurationsprojekt, wenn Sie:

Anwendungsfall	Beispiel
Kundenspezifische Anpassungen vornehmen	Metadaten, Ordnerstrukturen, Workflows für einen Kunden
Wiederverwendbare Funktionen entwickeln	Bibliotheken, Utilities, UI-Komponenten
Systemerweiterungen erstellen	Neue Funktionen, Integrationen, Automatisierungen
Konfigurationen versionieren möchten	Export/Import zwischen Systemen (Entwicklung → Produktion)

Wann wird ein Konfigurationsprojekt zum Plugin?

Ein Plugin ist technisch gesehen ein Konfigurationsprojekt. Der Unterschied liegt in der Bereitstellung (Veröffentlichung) und der Wiederverwendbarkeit.

Ein Konfigurationsprojekt kann zum Plugin werden, wenn:

Wiederverwendbarkeit: Die Funktionalität ist für mehrere Kunden/Systeme relevant.
Allgemeingültigkeit: Ein Plugin sollte keine kundenspezifischen Anpassungen enthalten.
Verteilung/Veröffentlichung: Installation über den agorum core plugin manager.
Konventionen: Ein Plugin sollte alle agorum core Konventionen und Standards erfüllen.

Aspekt	Konfigurationsprojekt	Plugin
Zweck	Kundenspezifische Anpassung	Allgemeine, wiederverwendbare Erweiterung
Zielgruppe	Ein Kunde / ein System	Mehrere Kunden/Systeme
Verteilung	Manueller Export/Import	Über agorum core plugin manager
Support	Projektspezifisch	Allgemeiner Support durch Anbieter

Projektstruktur für Konfigurationsprojekte

Ein agorum core Konfigurationsprojekt befindet sich unter /agorum/roi/customers/<projektname>/ und folgt einer standardisierten Ordnerstruktur. Diese Struktur unterstützt den agorum core template manager für Export und Import von Projekten.

Standardstruktur

Ein agorum core Konfigurationsprojekt folgt dieser Standardstruktur:

/agorum/roi/customers/<projektname>/
├── ai/                              # ALBERT | AI-bezogene Dateien (optional)
│   ├── knowledge/                   # KI-Wissensdokumente
│   ├── presets/                     # KI-Voreinstellungen
|   ├── templates                    # KI-Chat-Vorlagen
│   ├── tools/                       # KI-Tool-Definitionen
│   └── prompts/                     # Benutzerdefinierte Prompts
├── csv/                             # CSV-Dateien für Metadaten-Drop-Downs
├── deploy/                          # Deployment-Skripte
│   ├── pre/                         # Wird VOR dem Export ausgeführt
│   │   ├── js/                      # JavaScript Pre-Deployment-Skripte
│   │   └── messages/                # Lokalisierungsdateien für UI-Texte und Meldungen
│   └── post/                        # Wird NACH dem Export ausgeführt
│       └── js/                      # JavaScript Post-Deployment-Skripte
├── doc/                             # Projektdokumentation
│   ├── project-description.html     # Projektbeschreibung (wird ggf. im Plugin Manager angezeigt)
|   └── uninstall.html               # Deinstallationsbeschreibung (im Plugin Manager angezeigt)
├── js/                              # Haupt-JavaScript-Verzeichnis
│   ├── aguila/                      # aguila-Widget-Definitionen (UI)
│   ├── lib/                         # Wiederverwendbare Bibliotheken
│   ├── utils/                       # Hilfsfunktionen
│   ├── data/                        # DataHandler für Metadaten
│   ├── decorators/                  # UI-Erweiterungen für agorum.cards
│   ├── contenttask/                 # ContentTask-Definitionen
│   ├── cardlets/                    # Cardlet-Komponenten
│   ├── override/                    # System-Overrides
│   ├── service/                     # Service-Handler
│   └── tests/                       # Test-Skripte
├── templates/                       # Projektvorlagen
├── test/                            # Bereich für automatisierte Tests
│   ├── js/                          # JavaScript-Dateien für Tests, kann auch Unterordner haben
│   └── resources/                   # Vom Test verwendete Dateien, z. B. PDF-Dateien
├── update/                          # Update-Skripte nach Datum sortiert
├── uninstall/                       # Deinstallations-Skripte
    ├── pre/js/
    └── post/js/
├── yml/                             # Zentrale Konfigurationsdateien
│   ├── export.yml                   # Export-Steuerung
│   ├── metadata.yml                 # Metadaten-Definitionen
│   ├── metadata-collection.yml      # Metadaten-Sammlungen
│   ├── project.yml                  # Projektdefinition
│   ├── structure-basis.yml          # Ordnerstrukturen
|   └── uninstall.yml                # Uninstall-Informationen  
└── workflows/                       # Workflow-Definitionen

Minimale Projektstruktur

Für ein einfaches Projekt benötigen Sie mindestens:

/agorum/roi/customers/<projektname>/
├── yml/
│   ├── project.yml               # Pflicht: Projektdefinition
│   └── export.yml                # Pflicht: Export-Konfiguration
├── doc/
│   └── project-description.html  # Empfohlen: Projektbeschreibung
└── js/                           # Optional: JavaScript-Code
    └── lib/

Zentrale Konfigurationsdateien

Datei	Beschreibung	Link
project.yml	Projektdefinition mit Name, Version, Abhängigkeiten zu anderen Projekten, Lizenzinformationen und Metadaten-Präfixen.	Beschreibung der Datei "project.yml"
export.yml	Steuert den Export/Import von Projektkomponenten.	Beschreibung der Datei "export.yml"
metadata.yml	Deklarative Metadaten-Definition mit Gruppen, Feldquellen, Präfixen, Speicherpfaden, Feldtypen und Vererbung (~, ~~).	Metadaten mit YML definieren (metadata.yml)
metadata-collection.yml	Definition von Metadaten-Sammlungen mit Feldern, Typen, Listen, Defaults, Overrides und Filter.	metadata-collection.yml definieren
structure-basis.yml	Deklarative Ordnerstrukturen mit Pfadschemata (+/--/--:), ACL-Vererbung (^), Flags und Namensregeln.	Struktur mit der Datei structure-basis.yml definieren
uninstall.yml	Definiert, welche Komponenten beim Deinstallieren eines Konfigurationsprojekts/Plugins entfernt werden sollen.	uninstall-Struktur anlegen

JavaScript-Ordnerstruktur

Ordner	Beschreibung
aguila/	UI-Widget-Definitionen für das aguila-Framework. Enthält browser-seitige Komponenten, Formulare und Ansichten.
lib/	Wiederverwendbare Bibliotheken und gemeinsame Funktionen. API-Wrapper und Kernlogik.
utils/	Hilfsfunktionen und Helper-Module für allgemeine Aufgaben.
data/	DataHandler für Metadaten-Drop-Downs und Datenquellen-Handler.
decorators/	UI-Erweiterungen für agorum.cards zur Anpassung der Anzeige.
contenttask/	ContentTask-Definitionen zum Reagieren auf Dateitypen (z.B. .ac.js, .msg, .eml).
cardlets/	Kleine Widget-Komponenten und Dashboard-Elemente.
override/	Überschreiben von System-Komponenten und Explorer-Anpassungen.
service/	Backend-Services und API-Endpunkte.
templates/	JavaScript-Vorlagen für wiederverwendbare Muster.
tests/	Automatisierte Tests und Test-Suites.