Synchronisierung mit Drittsystemen

Diese Anleitung beschreibt die Bausteine zur Ermöglichung einer inkrementellen Synchronisation von Daten des be Portals (PostgreSQL) zu einem Drittsystem (unidirektional).

Technischer Änderungszeitstempel eines Datensatzes

Hierüber können für die Synchronisierung mit einem Drittsystem die neu angelegten und geänderten Datensätze seit Zeitpunkt x abgerufen werden.

Im PostgreSQL gibt es einen „technischen Änderungszeitpunkt“, der bei jeder Aktion im PostgreSQL aktualisiert wird, auch wenn dort Änderungen durchgeführt werden.
Der Feldname für den „technischen Änderungszeitpunkt“ ist updated_at
- Jede Tabelle mit diesem Feld hat einen entsprechenden Index, Namensschema: <Tabellenname>_std_updated_at
- Das Feld updated_at ist non-nullable
- Inhalt des Feldes ist der UTC Zeitpunkt der Änderung in PostgreSQL.
Das Feld updated_at wird von PostgreSQL mithilfe eines DB-Triggers geschrieben
Tabellen im custom Schema werden nicht behandelt.

Löschprotokoll

Hierüber können für die Synchronisierung mit einem Drittsystem die gelöschten Datensätze seit Zeitpunkt x abgerufen werden. Hinweis: Das Lösch-Protokoll wird zyklisch bereinigt.

Löschprotokoll-Tabelle

Die Tabellen für das Löschprotokoll werden im Schema system erstellt. Dabei wird für jeden Tag eine separate Tabelle mit dem Namen deletion_protocol_yyyy_mm_dd erstellt. Im Löschprotokoll wird für jeden Record ein Datensatz mit folgenden Feldern geloggt:

id als PrimaryKey wird von PostgreSQL vergeben
table_fqn Zusammengesetzt aus dem Schema und dem Tabellennamen der Quelltabelle
primary_key_value Wert des Primärschlüssels des gelöschten Records
deleted_at als UTC-Zeitstempel

Konfiguration

Das Schreiben des Löschprotokolls kann für jede Tabelle einzeln konfiguriert werden. Die Default-Einstellung ist false (Löschprotokoll wird nicht geschrieben). Möglich ist dies für fast alle Tabellen in metadata, system und data (DABxxx Tabellen & beng Tabellen).

Aktuell gibt es folgende Tabellen bei denen das Löschprotokoll nicht aktiviert werden kann:

metadata.incremental_replication_changes
process_start_queue
replication integrity_check-Tabellen
replication statistics-Tabellen

Im be Portal können die Tabellen unter Administration → Tabellen Metadata gepflegt werden

OData-Requests zum (De)aktivieren des Triggers:

BASH

// Metadaten für neue Tabelle anlegen
POST https://<api>/odata/v4/TableMetaData
{
	"tableSchema": "data",
	"tableName": "dab010",
	"primaryKeyName": "id",
	"doWriteDeletionProtocol": true
}

// Löschverfolgung de/aktivieren
PATCH https://<api>/odata/v4/TableMetaData(<TableMetaData-UUID>)
{
	"doWriteDeletionProtocol": false
}

Zugriff auf die Löschprotokolldaten per OData

Das Löschprotokoll kann per OData abgerufen werden. Die Id der Entität - protocolId setzt sich aus dem Tabellennamen der Löschprotokolltabelle und einer fortlaufenden Nummer zusammen.

BASH

// Löschprotokoll abrufen
GET https://<api>/odata/v4/DeletionProtocol
{
	"@odata.context": "https://localhost:8080/api/odata/v4/$metadata#DeletionProtocol",
	"value": [
		{
			"protocolId": "deletion_protocol_2024_02_20_1",
			"tableSchema": "data",
			"tableName": "name_of_table",
			"tableFqn": "data.name_of_table",
			"primaryKeyValue": "ab388674-342d-43af-aa88-9c644eb30459",
			"entityName": "NameOfTable"
		}
	]
}

Sonderfall: Vollreplikation einer bereits gefüllten Tabelle

Bei einer Vollreplikation einer bereits gefüllten Tabelle wird ein TRUNCATE anstatt eines DELETE ausgeführt. Dies hat zur Folge, dass die ON DELETE Trigger nicht ausgeführt werden und damit keine Löschprotokolleinträge geschrieben werden.

Beim Wiederfüllen der Tabelle wird automatisch der updated_at Zeitstempel gesetzt. Zudem schreibt die Replication alle während der Vollreplikation auftretenden DabRPL-Delete-Trigger direkt in das Löschprotokoll. Somit kann sichergestellt werden, dass keine Löschungen verloren gehen.

Aufräum-Mechanismus

Die Löschprotokoll-Tabellen werden von der be-api gelöscht. Dazu wird zyklisch (1 mal pro Tag) geprüft, ob bzw. welche Tabellen gelöscht werden müssen. Um das PostgreSQL-System zu entlasten werden nur ganze Tage/Tabellen gelöscht. Die Löschung erfolgt wenn mindestens einer der folgenden Punkte erfüllt ist:

Alle Drittsysteme haben die Meldung “Ich bin synchron bis xxx” abgesetzt
Das maximale Aufbewahrungsalter ist überschritten

Parameter für den Aufräum-Mechanismus

Das minimale vorzuhaltende Alter des Protokolls (Default = 2 Tage)
- Kann per Umgebungsvariable DELETION_PROTOCOL_CLEANUP_MIN_AGE_IN_DAYS überschrieben werden
Das maximale vorzuhaltende Alter des Protokolls (Default = 60 Tage)
- Kann per Umgebungsvariable DELETION_PROTOCOL_CLEANUP_MAX_AGE_IN_DAYS überschrieben werden
- Nach diesem Zeitraum werden die Daten immer gelöscht, auch wenn noch Drittsysteme vorhanden sind, die keine “Synchronisiert” Info zurückgemeldet haben.

Konfiguration der Drittsysteme

Doku bis hier überarbeitet.

Noch zu überarbeitende Punkte: Zugriff auf Löschprotokolldaten per OData, Drittsysteme

Drittsysteme

Die Konfiguration von Drittsystemen erfolgt über zwei neue Tabellen
- third_party_systems → Hier werden Drittsysteme verwaltet
  - name Bezeichnung des Systems
  - commentMemo-Feld für Kommentare
  - considered_by_deletion_protocol_cleanup Relevant für Löschprotokoll-Prüfung
- system.third_party_sync_logs → Synchronitäts-Status-Log Tabelle
  - third_party_system_uuid UUID des Drittsystems-Record
  - synchronized_at Zeitstempel der Synchronisierung
Die Drittsysteme können unter Administration → Drittsysteme gepflegt werden
Jedes Drittsystem meldet per OData den Zeitpunkt einer erfolgreichen Synchronisation
- Dafür benötigt der ALD-User des Drittsystems die Rolle BE.thirdPartySystem und die UUID des third_party_system Datensatzes
- Der Request für die Rückmeldung sieht folgendermaßen aus:
- BASH
```
POST https://<api>/odata/v4/ThirdPartySyncLogs
{
	"system@odata.bind": "ThirdPartySystems(<UUID>)",
	"synchronizedAt": "2024-02-18T05:34:33.371Z"
}
```