Changelog Konfiguration

Die Changelog Konfiguration ermöglicht es Administratoren, eine automatische Protokollierung von Datenbankänderungen einzurichten. Für konfigurierte Tabellen und Felder werden PostgreSQL-Trigger angelegt, die INSERT-, UPDATE- und DELETE-Operationen in dedizierten Log-Tabellen festhalten.

Erreichbarkeit

Die Seite ist über das Menü Administration → Changelog Konfiguration erreichbar.

Anwendungsfälle

Der Changelog ist immer dann sinnvoll, wenn eine Anwendung wissen muss, was sich wann in der Datenbank geändert hat — ohne dass die Änderung selbst dafür sorgen muss, das irgendwo zu notieren. Typische Szenarien:

Audit-Trail: Nachvollziehen von Änderungen

Wer hat wann welchen Datensatz geändert? Der Changelog protokolliert automatisch jeden INSERT, UPDATE und DELETE in den konfigurierten Tabellen. Nützlich z. B. bei Reklamationen, Compliance-Anforderungen oder zur Fehleranalyse.

Beispiel: Eine Anwendung überwacht die Tabelle der Auftragsköpfe. Jede Änderung am Status oder Betrag wird im Log festgehalten. Der Sachbearbeiter kann später nachvollziehen, wann der Auftrag geändert wurde.

Synchronisierung mit Drittsystemen (Job-Queue)

Eine Anwendung möchte Änderungen in einer Tabelle erkennen und an ein externes System weitergeben (z. B. ERP, Outlook, Fremdsystem). Der Changelog dient dabei als Job-Queue: Neue Einträge signalisieren ausstehende Synchronisierungsaufgaben. Nach der Verarbeitung werden die Einträge — oder die gesamte Tabelle — gelöscht.

Beispiel: Abwesenheiten werden in be Portal erfasst. Ein Hintergrundjob liest die Changelog-Tabelle, überträgt die Änderungen nach Outlook und löscht die verarbeiteten Einträge anschließend.

Reaktion auf Datenänderungen

Eine Anwendung soll automatisch auf bestimmte Feldänderungen reagieren — z. B. eine Benachrichtigung auslösen oder einen Folgeprozess anstoßen. Der Changelog liefert die Grundlage: Er erkennt, ob sich die relevanten Felder tatsächlich geändert haben, und schreibt nur dann einen Eintrag.

Beispiel: Ändert sich das Feld „Genehmigungsstatus" in der Bestellanforderung, soll der zuständige Einkäufer informiert werden. Der Changelog erkennt diese Änderung und stellt den Auslöser bereit.

Grundprinzipien

Vor der Konfiguration sind folgende Grundprinzipien wichtig zu verstehen:

1. Jede Anwendung pflegt ihre eigenen Definitionen

Changelog-Definitionen sind package-spezifisch. Jede Anwendung (Package) legt ihre eigenen Definitionen an und besitzt die zugehörige Log-Tabelle. Es gibt keine gemeinsam genutzten Definitionen zwischen Packages.

2. Die Anwendung entscheidet selbst über die Log-Daten

Was mit den Einträgen in der Log-Tabelle passiert, bestimmt die Anwendung, der die Definition gehört — nicht das Changelog-System. Je nach Nutzungsmuster bleiben Einträge dauerhaft erhalten (Audit-Log) oder werden nach der Verarbeitung gelöscht (Job-Queue).

3. Fremde Changelog-Tabellen darf man nicht mitnutzen

Nur weil Tabelle Dab010 in Changelog-Definition A konfiguriert ist, bedeutet das nicht, dass eine andere Anwendung diese Daten verwenden kann. Die Einträge könnten bereits verarbeitet und gelöscht worden sein. Wer Änderungen an einer Tabelle verfolgen möchte, muss eine eigene Changelog-Definition anlegen.

4. Eine Log-Tabelle pro Definition — für alle konfigurierten Tabellen

Alle Änderungen an allen in einer Definition konfigurierten Tabellen landen in einer einzigen Log-Tabelle. Nicht eine Log-Tabelle pro Quelltabelle, sondern eine pro Definition. Die Quelltabelle ist im Log-Eintrag über die Spalte table_name unterscheidbar.

Benutzeroberfläche

Die Seite ist in zwei Bereiche gegliedert:

1. Changelog Definitionen

Eine Changelog-Definition ist der übergeordnete Konfigurationseintrag. Sie fasst alle zu überwachenden Tabellen unter einem gemeinsamen Matchcode zusammen und steuert, ob die Überwachung aktiv ist.

2. Changelog Tabellendefinitionen

Für jede Changelog-Definition können beliebig viele Tabellendefinitionen angelegt werden. Diese legen fest, welche Tabellen und Felder überwacht werden.

Matchcode-Format

Der Matchcode muss dem regulären Ausdruck ^[A-Za-z_]+\\.[a-z_]+$ entsprechen:

• Teil vor dem Punkt: Buchstaben und Unterstriche (Groß- und Kleinschreibung erlaubt) – üblicherweise der Package-Key

• Teil nach dem Punkt: nur Kleinbuchstaben und Unterstriche – der spezifische Name

Beispiele: BE.outlook_sync, MRP.bestellvorschlag

Technische Funktionsweise

Trigger und Log-Tabellen

Beim Speichern einer Tabellendefinition (sofern die übergeordnete Definition aktiv ist) legt das System automatisch folgende Datenbankobjekte an:

Struktur der Log-Tabelle

Jeder Log-Eintrag enthält:

Trigger-Logik

Der Trigger (system.log_change()) prüft bei jeder Operation, ob mindestens eines der konfigurierten überwachten Felder tatsächlich einen anderen Wert hat. Nur dann wird ein Log-Eintrag geschrieben. Das verhindert unnötige Log-Einträge bei UPDATE-Operationen, die keine relevanten Felder berühren.

Verhalten bei der Datenreplikation

Während einer vollständigen Tabellenreplikation (Full Replication) werden alle Changelog-Trigger temporär deaktiviert, um das massenhafte Schreiben von irrelevanten Log-Einträgen zu verhindern. Die Replikation selbst wird in der Log-Tabelle als FULL_REPLICATION_STARTET / FULL_REPLICATION_COMPLETED markiert. Nach Abschluss der Replikation werden die Trigger wieder aktiviert.

Auswertung der Logs

Es gibt keine vorgefertigte UI zum Anzeigen der protokollierten Änderungen. Die Log-Tabellen sind direkt per SQL abfragbar. Für eine Anzeige im be Portal können jedoch dbStatement- oder dbView-Entitäten im zugehörigen Package definiert werden.

Direktzugriff per SQL

Die Log-Tabelle für eine Definition mit Matchcode C_BDE.buchungen lautet data.changelog_c_bde_buchungen:

SELECT uuid, primary_key, table_name, operation, created_at
FROM data.changelog_c_bde_buchungen
ORDER BY created_at DESC
LIMIT 100;

Das Feld data enthält den vollständigen Datensatz als JSONB. Einzelne Felder können so extrahiert werden:

SELECT
    primary_key,
    operation,
    created_at,
    data ->> 'name1'   AS name1,
    data ->> 'matchcode' AS matchcode
FROM data.changelog_c_bde_buchungen
WHERE operation = 'UPDATE'
ORDER BY created_at DESC;

Anzeige im be Portal via dbStatement-Entität

Es ist möglich, die Log-Daten direkt über be-portal-Seiten anzuzeigen. Dafür wird im Package, das die Changelog-Definition besitzt, eine dbStatement-Entität definiert. Die Log-Tabelle ist für jeden Matchcode fest (statischer Name), daher kann das SQL direkt eingebettet werden:

- entityName: MRP_ChangelogLog
  type: dbStatement
  primaryKeyName: uuid
  permissions:
    read:
      - role: BE.admin
  fields:
    - name: uuid
      dbType: uuid
      label: ID
    - name: primary_key
      dbType: text
      label: Datensatz-PK
    - name: table_name
      dbType: text
      label: Tabelle
    - name: operation
      dbType: text
      label: Operation
    - name: created_at
      dbType: timestamp
      label: Zeitpunkt
    - name: data
      dbType: text
      label: Daten (JSON)
  viewDefinition:
    pgSql: | # sql
      SELECT uuid, primary_key, table_name, operation, created_at,
             data::text AS data
      FROM data.changelog_mrp_meinname
      ORDER BY created_at DESC

Die data-Spalte (JSONB) enthält immer den vollständigen Datensatz. Falls nur bestimmte Felder relevant sind, können diese im SQL direkt per ->> extrahiert und als eigene Felder exponiert werden.

Einschränkungen

• Der Matchcode kann nach dem Erstellen nicht geändert werden.

• System-Definitionen (isSystem = true) können nicht bearbeitet oder gelöscht werden.

• Die konfigurierte Tabelle muss imdata-Schema existieren; nicht vorhandene Tabellen oder Felder werden beim Speichern abgelehnt.

• Es kann immer nur eine Tabellendefinition pro Tabelle und Definition existieren (Unique-Constraint auf table_name + changelog_definition_uuid).