Deklarative Systemkonfiguration

Wofür ist es gedacht?

Die Backend-API von docuteam Context bietet Funktionen, um Archive und deren zugehörige Konfigurationen deklarativ mit versionierten YAML-Dateien zu verwalten.

Typische Anwendungsfälle sind:

• Konfigurationsänderungen vor der Anwendung vorzubereiten und zu prüfen,
• eine gut lesbare Historie von Konfigurationsänderungen zu führen,
• dieselbe Konfiguration in einer anderen Umgebung wiederzuverwenden,
• einen bekannten Konfigurationsstand wiederherzustellen.

Die API verwendet eindeutige globale Rollen:

• '@system-config:getConfig' für die Get-Endpunkte
• '@system-config:applyConfig' für die Apply-Endpunkte

Was kann konfiguriert werden?

Die Konfiguration umfasst derzeit diese archivbezogenen Einstellungen:

• Einstellungen für die Attachment-Verbindung,
• App-Konfiguration,
• Box-Verbindungen,
• Concept Schemes,
• Listen,
• Regeln,
• Formulare.

Aufbau der Konfiguration

Das folgende Beispiel zeigt eine Konfiguration mit allen konfigurierbaren Entitäten:

version: 1
archives:
  - name: myArchive
    attachment:
      connection:
        region: context
        endpoint: http://localhost:9000
        accessKey: admin
        secretKey: ENV(SECRET_KEY)
        bucketName: context-s3-mock
        downloadUrlMaxAgeInSeconds: 60
        maxFileSizeInBytes: 5368709120
        allowedMimeTypes:
          - application/pdf
          - image/jpeg
    appConfig:
      appTitle: Development server
      header:
        icon: <encoded_image>
        backgroundColor: "#FFFFFF"
        textColor: "#000000"
      menu:
        backgroundColor: "#FFFFFF"
        textColor: "#000000"
        textColorHover: "#222222"
    conceptSchemes:
      - name: Persons
    boxConnections:
      - name: public-box
        url: https://example.com/box
        namespace:
          - public
        token: ENV(SECRET_KEY)
    enumerations:
      - name: AgentRelators
        type: regularEnumeration
        data:
          processInfoArchivist:
            de: processInfoArchivist
            en: processInfoArchivist
            fr: processInfoArchivist
          staff:
            de: staff
            en: staff
            fr: staff
    rules:
      - name: Publication
        type: accessRestrictionRule
        data:
          label:
            de: Sichtbar für anonyme Besucher
            en: Visible to anonymous visitors
            fr: Visible pour les visiteurs anonymes
          description:
            de: Alle Benutzer sehen alles
            en: All users see everything
            fr: Tous les utilisateurs enregistrés voient tout
          permissions:
            - group: public
              policy: publishMetadataAndDigitalObjects
            - group: fullAccess
              policy: publishMetadataAndDigitalObjects
            - group: partialAccess
              policy: publishMetadataAndDigitalObjects
    forms:
      - name: "[Record] Agents with Relator Enumeration"
        type: recordResourceForm
        data:
          sections:
            - content:
                - property: refCodeAdmin
                  readonly: true
                - property: unitTitle
                  required: true
                - relation: hasAgent
                  relatorEnumeration: AgentRelators
                  repeat: true
                - relation: hasAgent
                  relator: origination
        active: true

version bezeichnet die aktuell implementierte Version.

archives ist eine Liste der vorhandenen Archive. Die Eigenschaft name bezeichnet dabei den eindeutigen Bezeichner eines Archivs. Wenn überhaupt kein Konfigurationszustand vorhanden sein soll, kann der Wert von archives leer bleiben. Die minimal gültige Konfiguration lautet daher:

version: 1
archives:

connection definiert einen Verbindungspunkt für Attachments. Er kann leer bleiben, wenn keine Verbindung enthalten sein soll. Wenn eine Verbindung konfiguriert wird, müssen jedoch alle folgenden Eigenschaften vorhanden sein: region, endpoint, accessKey, secretKey, bucketName, downloadUrlMaxAgeInSeconds, maxFileSizeInBytes, allowedMimeTypes.

appConfig konfiguriert das Erscheinungsbild der Anwendung. Alle Eigenschaften sind optional. Der Block kann also entweder vollständig leer bleiben oder nur die gewünschten Eigenschaften enthalten.

boxConnections ist eine Liste von Box-Verbindungen. Sie kann leer bleiben, wenn keine Verbindungen enthalten sein sollen. Wird eine Verbindung definiert, muss sie alle folgenden Eigenschaften enthalten: name, url, namespace und token.

conceptSchemes ist eine Liste der Concept Schemes. Sie kann leer bleiben, wenn keine Concept Schemes enthalten sein sollen. Zu beachten ist, dass das Concept Scheme 'locationManagement' immer zusammen mit einem Archiv angelegt wird und nicht unabhängig davon entfernt werden kann.

enumerations ist eine Liste der Listen (enumerations). Sie kann leer bleiben, wenn keine Enumerationen enthalten sein sollen. Wird eine Enumeration hinzugefügt, muss sie alle folgenden Eigenschaften enthalten: name, type und data.

rules ist eine Liste der Regeln. Sie kann leer bleiben, wenn keine Regeln enthalten sein sollen. Wird eine Regel hinzugefügt, muss sie alle folgenden Eigenschaften enthalten: name, type und data.

forms ist eine Liste der Formulare. Sie kann leer bleiben, wenn keine Formulare enthalten sein sollen. Wird ein Formular hinzugefügt, muss es alle folgenden Eigenschaften enthalten: name, type, data und active.

Die minimale Konfiguration für ein einzelnes Archiv ist daher:

version: 1
archives:
  - name: myArchive
    attachment:
      connection:
    appConfig:
    conceptSchemes:
    boxConnections:
    enumerations:
    rules:
    forms:

Hinweis: Unter der Eigenschaft data von Listen, Regeln und Formularen werden die Inhalte der jeweiligen Entität definiert. Es findet keine weitere Validierung der Inhalte innerhalb von data statt.

Umgebungsvariablen

Geheime Eigenschaften können mit ENV(<env_variable_key>) als Wert auf Umgebungsvariablen verweisen.

Nach dem Anwenden einer Konfiguration merkt sich ein nachfolgender Lesevorgang die angewendeten Namen der Umgebungsvariablen und exportiert die geheimen Werte als ENV(<env_variable_key>).

Wurde für ein Geheimnis nie ein Umgebungsvariablenname erfasst (z. B. weil es als literaler Wert statt als ENV(...)-Referenz gesetzt wurde), wird der exportierte Wert als "****" mit einem Kommentar maskiert, der auf die Verwendung der ENV(...)-Funktion hinweist:

secretKey: "****" # use ENV(KEY_NAME) to reference a secret environment variable

Wird dieser Wert unverändert erneut angewendet, schlägt der Request fehl, da **** weder ein gültiger Geheimniswert noch eine gültige Umgebungsvariablenreferenz ist.

Aktuellen Konfigurationszustand abrufen

Verwende den Endpunkt GET /api/system-config/get, um den aktuellen Systemkonfigurationszustand als YAML zu exportieren.

Der Response-Content-Type ist application/yaml.

Der Endpunkt liefert die Konfiguration als serialisierten YAML-Text zurück, also als YAML-String und nicht als JSON-Objekt.

Der Endpunkt GET /api/system-config/get/as-file liefert denselben YAML-Inhalt als herunterladbare Datei mit dem Namen system-config.yaml.

Flags

Der Endpunkt unterstützt das folgende optionale Query-Flag:

• includeInfo=true
  Fügt am Anfang des exportierten YAML einen info-Block hinzu. Dieser Block enthält Metadaten zum Export:
  • date: den Zeitstempel des Exports im ISO-Format,
  • user: den Benutzernamen des authentifizierten Benutzers, falls verfügbar.

Wird das Flag nicht gesetzt oder auf einen anderen Wert als true gesetzt, wird der info-Block nicht ausgegeben.

Beispiele

Aktuelle Konfiguration ohne Metadaten abrufen:

curl \
  -H "Accept: application/yaml" \
  -H "Authorization: ******" \
  "http://localhost:3333/api/system-config/get"

Aktuelle Konfiguration inklusive Export-Metadaten abrufen:

curl \
  -H "Accept: application/yaml" \
  -H "Authorization: ******" \
  "http://localhost:3333/api/system-config/get?includeInfo=true"

Beispielantwort mit includeInfo=true:

version: 1
archives:
  - name: myArchive
    attachment:
      connection:
    appConfig:
    conceptSchemes:
    boxConnections:
    enumerations:
    rules:
    forms:
info:
  date: 2026-06-10T12:00:00.000Z
  user: alice

Das exportierte YAML kann geprüft, versioniert und später erneut an den Apply-Endpunkt gesendet werden. Falls ein info-Block vorhanden ist, wird er beim Import ignoriert.

Konfiguration anwenden

Verwende den Endpunkt POST /api/system-config/apply, um eine YAML-Konfiguration zu validieren und anzuwenden.

Sende das YAML-Dokument selbst als rohen Request-Body mit dem Content-Type application/yaml.

Der Request-Body wird zunächst als reiner Text eingelesen und anschließend als YAML interpretiert. Mit anderen Worten: Der Endpunkt erwartet einen YAML-String im Body.

Der Endpunkt POST /api/system-config/apply/as-file akzeptiert denselben YAML-Inhalt als Datei-Upload.

Flags

Der Endpunkt erfordert den Query-Parameter dryRun=true oder dryRun=false, um anzugeben, ob die Konfiguration angewendet oder nur validiert werden soll (dry run). Bei dryRun=true validiert das System das YAML, löst Verweise auf Umgebungsvariablen auf, vergleicht den gewünschten Zustand mit dem aktuellen Zustand und gibt die geplanten Änderungen zurück, wendet diese aber nicht an.

Beispiele

Konfiguration validieren, ohne sie anzuwenden:

curl \
  -X POST \
  -H "Content-Type: application/yaml" \
  -H "Authorization: ******" \
  --data-binary @system-config.yaml \
  "http://localhost:3333/api/system-config/apply?dryRun=true"

Konfiguration anwenden:

curl \
  -X POST \
  -H "Content-Type: application/yaml" \
  -H "Authorization: ******" \
  --data-binary @system-config.yaml \
  "http://localhost:3333/api/system-config/apply?dryRun=false"

Antwort

Der Endpunkt liefert einen Plain-Text-Statusbericht zurück, der das Ergebnis der Validierung und des Apply-Vorgangs beschreibt.

Typische Antworten sind:

• No changes
  Die übermittelte Konfiguration entspricht bereits dem aktuellen Systemzustand.

• Eine Liste geplanter oder ausgeführter Änderungen, zum Beispiel:

  update Archive myArchive
  - attachment.connection.endpoint: http://old.example -> http://new.example

• Wenn Änderungen erfolgreich angewendet wurden, endet die Antwort mit:

  Changes applied successfully.

Validierung und Umgebungsvariablen

Beim Import wird das YAML strikt geparst und validiert:

• ungültige YAML-Syntax,
• fehlende Pflichtfelder,
• unbekannte Eigenschaften,
• doppelte Archivnamen oder doppelte Namen von Box-Verbindungen innerhalb desselben Archivs

führen zu einem 400 Bad Request.

Verweise auf Umgebungsvariablen in der Form ENV(MY_KEY) werden beim Import aufgelöst. Falls eine referenzierte Umgebungsvariable fehlt, schlägt der Request fehl.

Eine exportierte Datei mit einem info-Block kann unverändert an den Apply-Endpunkt zurückgesendet werden, da der info-Block beim Import ignoriert wird.