Zum Hauptinhalt springen

Archiv kopieren

Wozu dient es?​

Die Kopierfunktion dupliziert den Inhalt eines Quellarchivs in ein Zielarchiv.

Mögliche Anwendungsfälle:

  • Veröffentlichung einer gefilterten Version eines Archivs: aus einem internen Archiv mit Zugriffsbeschränkungen werden nur die Datensätze, die öffentlich zugänglich sein dürfen (typischerweise jene ohne aktive Schutzfrist), in ein zweites Archiv kopiert, das einem breiteren Publikum zugänglich ist,
  • ein neues Archiv anlegen, das auf der Struktur und den Inhalten eines bestehenden Archivs aufbaut,
  • einen Snapshot eines Archivs für Prüf-, Schulungs- oder Reporting-Zwecke behalten.

Die Kopie ist wiederholbar: Bei einem erneuten Lauf auf demselben Quell-/Ziel-Paar werden nur die Unterschiede angewendet (angelegt, aktualisiert, gelöscht, unverändert) — einschliesslich Datensätzen, die aus dem Filter herausfallen — sodass das Zielarchiv über die Zeit mit dem Quellarchiv synchron bleibt.

Für den Endpoint wird die globale Rolle @archive:copyArchive benötigt (siehe Rollenkonfiguration).

Optionen​

Das Verhalten des Kopiervorgangs wird über folgende Query-Parameter gesteuert:

  • sourceArchiveId — das Archiv, aus dem gelesen wird.
  • targetArchiveId — das Archiv, in das geschrieben wird. Muss sich von der Quelle unterscheiden. Existiert es noch nicht, wird es automatisch erstellt.
  • forceOverride (Standard false) — erlaubt das Überschreiben eines bestehenden Archivs, das nicht selbst durch einen früheren Kopierlauf entstanden ist. Ohne dieses Flag wird das Kopieren in ein solches Archiv verweigert, um versehentlichen Datenverlust zu vermeiden.
  • forceUpdateAllRecords (Standard false) — wendet Aktualisierungen auf jeden Datensatz im Ziel an, auch wenn dieser unverändert erscheint. Nützlich nach Konfigurationsänderungen, die abgeleitete Daten betreffen.
  • cloneAttachments (Standard false) — kopiert auch die physischen Attachment-Dateien, siehe Umgang mit Attachments.

Ein Quellarchiv sollte bei erneuten Läufen immer in dasselbe Zielarchiv kopiert werden. Das Kopieren mehrerer unterschiedlicher Quellen in dasselbe Ziel wird nicht unterstützt: Da die Kopie das Ziel mit der Quelle synchronisiert, würden Datensätze aus einer vorhergehenden Quelle als «fehlend» erkannt und gelöscht.

Was wird kopiert?​

Ein Kopierlauf überträgt von der Quelle ins Ziel:

  • Konfiguration: Concept Schemes, Listen, Regeln, Konfigurationen und Formulare.
  • Normdaten: Akteur:innen, Akzessionen, Konzepte, Standorte und Orte.
  • Records: die Record Resources, abhängig vom Filter (siehe unten).
  • Attachments: optional auch die physischen Attachment-Dateien.

Die Beziehungen zwischen den kopierten Elementen bleiben erhalten, sodass beispielsweise ein Datensatz im Ziel weiterhin auf denselben (kopierten) Akteur oder Standort verweist.

Filter​

Der Request-Body kann Filter enthalten, die einschränken, welche Datensätze kopiert werden. Konfiguration und Normdaten werden immer vollständig kopiert, damit die einbezogenen Datensätze ihren Kontext (Formulare, Listen, Normdaten) behalten.

Unterstützte Filtertypen:

  • Access restriction — nimmt Datensätze mit einer bestimmten Zugriffsbeschränkung auf. Dies ist der zentrale Filter für den «öffentliches Archiv»-Anwendungsfall: nur Datensätze ohne aktive Schutzfrist übernehmen.
  • Property value — nimmt Datensätze auf, deren Wert an einem bestimmten Pfad einem regulären Ausdruck entspricht.
  • AND-/OR-Klauseln — kombinieren andere Filter mit logischer UND-/ODER-Verknüpfung.

Ein Datensatz wird nur kopiert, wenn er alle Filter besteht (Filter auf oberster Ebene werden implizit mit UND verknüpft). Von einem Filter ausgeschlossene Datensätze werden zusammen mit ihren untergeordneten Datensätzen ausgeschlossen, auch wenn ein untergeordneter Datensatz für sich betrachtet bestehen würde — der Kontext eines Datensatzes im Baum bleibt erhalten, statt Waisen hochzuziehen.

Beispiel: Archiv veröffentlichen​

Von myArchive in myArchive-public kopieren, nur Datensätze ohne Zugriffsbeschränkung:

PUT /archive/copy?sourceArchiveId=myArchive&targetArchiveId=myArchive-public
{
  "filters": [
    { "type": "accessRestriction" }
  ]
}

Wird dieselbe Anfrage regelmässig ausgeführt, bleibt myArchive-public mit der aktuellen öffentlichen Teilmenge von myArchive synchron.

Umgang mit Attachments​

Attachments sind Binärdateien, die in einem S3-Bucket gespeichert sind. Die Kopie bietet zwei Modi:

Referenz-Modus (cloneAttachments = false, Standard)​

Das Zielarchiv teilt sich den Attachment-Bucket des Quellarchivs. Es werden keine Dateien physisch kopiert — das Ziel verweist lediglich auf dieselben Objekte. Das ist schnell und verbraucht keinen zusätzlichen Speicherplatz, allerdings kann dem Ziel keine eigene Bucket-Konfiguration zugewiesen werden, und es ist auf den Fortbestand des Quell-Buckets angewiesen.

Klon-Modus (cloneAttachments = true)​

Die physischen Attachment-Dateien werden mitkopiert, sodass das Zielarchiv über eigene Kopien verfügt. In diesem Modus kann das Zielarchiv den Bucket der Quelle mitbenutzen (die Dateien werden im selben Bucket unter einem anderen Schlüssel abgelegt) oder vorab über PUT /archive mit einem eigenen Bucket eingerichtet werden, sodass die Dateien bucket-übergreifend kopiert werden. Der Klon-Modus ist die richtige Wahl, wenn das Ziel unabhängig vom Speicher der Quelle sein soll — für den «öffentliches Archiv»-Anwendungsfall zum Beispiel, wenn das öffentliche Archiv in einem separaten, besser zugänglichen Bucket liegen soll.

Ein Moduswechsel zwischen Läufen wird unterstützt: Wenn ein zuvor im Klon-Modus erstelltes Zielarchiv erneut im Referenz-Modus kopiert wird, werden die zuvor geklonten Dateien bereinigt, sodass keine verwaisten Dateien zurückbleiben.

Ein Zielarchiv, das durch einen Kopierlauf entstanden ist, kann selbst wieder als Quelle für einen weiteren Kopierlauf dienen; die zugrunde liegende Speicherung wird über die gesamte Kette hinweg aufgelöst, sodass auf zwischenliegenden Archiven kein Bucket neu konfiguriert werden muss.

Antwort​

Die Antwort ist eine Zusammenfassung des Laufs: Quell-Archiv-ID, Zielarchiv, ob Attachments geklont wurden, sowie Änderungszahlen je Kategorie (angelegt, aktualisiert, gelöscht, unverändert; Datensätze weisen zusätzlich rewired aus). So ist auf einen Blick ersichtlich, was sich im Ziel verändert hat.

Zusätzlich werden die einzelnen Kopierschritte mit denselben Zahlen im Anwendungs-Log geschrieben, sodass ein Kopierlauf durchgängig nachvollzogen werden kann.