Aller au contenu
Langue:DeutschEnglish Last updated: 2026-11-14

agate-SIP-Import

agate (das Anton-Vorbereitungs-Tool für SIPs aus losen Datei-Ablagen) kann SIPs (BagIt oder E-ARK) direkt per HTTP an Anton schicken. Anton nimmt das ZIP entgegen, prüft es, legt ein Backup an, importiert die Inhalte als Verzeichnungseinheiten unter dem gewählten Bestand und gibt agate Bescheid wenn alles fertig ist.

Der gesamte Pfad läuft asynchron — agate kann parallel weiterarbeiten oder andere SIPs vorbereiten.

BagIt oder E-ARK

agate liefert ein SIP als BagIt-Bag oder als E-ARK-SIP 2.2.0, je nach Einstellung in agate. Beide tragen dieselbe metadata.json. Anton erkennt die Form am Inhalt des ZIP (bagit.txt oder METS.xml); der Dateiname bleibt sip-agate-<bestand_id>.zip, und beide nehmen dieselben Wege: Direkt-Import, Eingangskorb, Upload auf /import/sip-anton und anton:import --from-sip.

BagIt E-ARK
metadata.json data/meta/metadata.json dmdSec mit OTHERMDTYPE="anton-import-format", meist metadata/descriptive/metadata.json
Dateien data/content/ representations/rep1/data/
Prüfung vor dem Import Manifeste des Bags Prüfsummen im METS, für metadata.json und jede Datei, die sie nennt
Prüfbericht — Prüfung nach E-ARK (eark-ip) als Prüf-Ereignis beim Lauf

Eine fehlende oder veränderte Datei bricht den Import ab, bevor etwas geschrieben ist. Der E-ARK-Prüfbericht hält den Import nicht auf: Ob die Dateien unverändert sind, entscheiden die Prüfsummen. E-ARK-Pakete aus anderen Werkzeugen nimmt Anton ebenfalls an, siehe unten.

E-ARK-Pakete aus anderen Werkzeugen

Ein E-ARK-Paket ohne anton-import-format (etwa aus RODA-in, commons-ip oder ESSArch) erkennt Anton ebenfalls am Inhalt, auf allen Wegen und unter jedem Dateinamen. Trägt der Name kein Ziel (…-agate-<bestand_id>.zip), wartet das Paket im Eingangskorb.

  • Beschreibung: aus der ersten EAD im Paket (EAD3 oder EAD 2002, gelesen wie beim EAD-Import), sonst aus Dublin Core als ein Datensatz, sonst ein Datensatz mit dem Namen des Pakets (METS LABEL oder OBJID).
  • Dateien: Die Dateien der Master-Repräsentation hängen als Ordner und Datensätze unter der Beschreibung. Nennt ein <dao> der EAD eine Datei des Pakets, wird sie Medium dieser Verzeichnungseinheit.
  • Repräsentationen: Der Eingangskorb zeigt jede Repräsentation mit der Zahl ihrer Dateien und einem Vorschlag (aus PREMIS, aus dem Namen, sonst die erste als Master und die übrigen «unbestimmt»). Für jede wählt man Master, Original (Fassung), Nutzungskopie oder eigene Einträge; genau eine muss Master sein, höchstens eine Nutzungskopie. Eine Datei einer Fassung oder Nutzungskopie hängt am Medium der Master-Datei mit gleichem Ordner und Namen ohne Endung; Dateien ohne Paar und eigene Einträge kommen unter einen Ordner mit dem Namen ihrer Repräsentation. Ohne Wahl im Eingangskorb (Import mit Ziel im Dateinamen, Konsole) gilt der Vorschlag, «unbestimmt» als eigene Einträge.
  • Prüfung: Jede Datei jeder Repräsentation wird vor dem Import gegen ihre Prüfsumme im METS geprüft.

Workflow

┌──────────┐    HTTP-POST     ┌──────────┐
│  agate   │ ───────────────▶ │  Anton   │
│          │   sip.zip        │          │
└──────────┘                  └──────────┘
                                    │
                                    ▼ async Job
                              ┌──────────┐
                              │  Import  │
                              │  BagIt   │
                              │  validate│
                              │  + apply │
                              └──────────┘

Zwei Pfade

  1. Direkt-Import — Wenn der Filename die Konvention sip-agate-<bestand_id>.zip einhält, startet der Import sofort unter dem angegebenen Bestand.

  2. Eingangskorb — Sonst landet das SIP im Eingangskorb unter /sip/inbox. Bearbeiter:innen sehen alle wartenden Uploads und weisen pro Eintrag manuell einen Bestand zu oder verwerfen das SIP.

Der Eingangskorb verhindert, dass unzugeordnete SIPs den Speicherplatz still aufessen — Bearbeiter:innen sehen aktiv, was wartet.

Dasselbe gilt für den manuellen Upload im Reiter Manueller Upload von SIP-Import (anton-import-format): Ein SIP mit sip-agate-<bestand_id>.zip erscheint in der Liste und wird mit Importieren gestartet, jedes andere landet im Eingangskorb. Ein SIP, dessen Inhalt schon importiert ist oder gerade importiert wird, nimmt der Upload nicht an.

Eingangskorb (/sip/inbox)

Sichtbar für Editor- und Admin-Rollen unter Import / Export → SIP Inbox. Pro Zeile:

  • SIP-Filename, Hochladedatum
  • Vorschau (Anzahl Dateien, Paketprüfung BagIt oder E-ARK, NARA-Kategorien)
  • Aktionen: Bestand zuweisen (öffnet Auswahl) oder Verwerfen

Vokabular-Mapping: NARA → Tenant-Objekttyp

agate spricht intern in NARA-Standard-Kategorien (StillImage, Audio, Textual, Video, Geospatial …). Anton übersetzt diese beim Import in die tenant-spezifische Werteliste „Objekttyp" (Bild, Akte, Foto, Plan, Sammlung …).

Das Mapping ist pro Tenant konfigurierbar. Vorteil: agate muss das spezifische Vokabular des Archivs nicht kennen.

Konfiguration:

Setting::setValue('nara_to_objecttype_map', [
    'StillImage' => 'Bild',
    'Textual'    => 'Akte',
    'Audio'      => 'Tonaufnahme',
    // ...
]);

Wenn für eine NARA-Kategorie kein passender Tenant-Typ existiert, bleibt das object_type-Feld leer (statt den Import abzubrechen) und kann später von Hand vergeben werden.

HTTP-API

Endpoint: POST /api/sip/upload

Request:

  • Multipart-Form mit file-Feld (sip.zip, BagIt oder E-ARK)
  • Header Authorization: Bearer <api_token> (Sanctum-Token, siehe API-Authentifizierung)

Response: 202 Accepted mit JSON, das die Job-ID enthält:

{
  "job_id": "01J5XYZ...",
  "status": "queued",
  "callback_url": "https://your-anton.ch/api/sip/status/01J5XYZ..."
}

agate pollt anschliessend callback_url bis status: completed (oder failed).

Importprotokoll

Jeder agate-SIP-Import steht als Lauf im Importprotokoll — mit Signatur IMPORT-{jjjj}-{NNN}, Dateiname, Prüfsumme, Zeitpunkt, Ergebnis und den angelegten Datensätzen. Damit ist der Importpfad auch nachträglich auditierbar; ein Akzessions-Archiv braucht es dafür nicht.

Formatumwandlung in agate

Anton wendet auf SIPs keine Format-Regel an: Die Prüfsummen eines SIP belegen, dass die gelieferten Dateien unverändert angekommen sind. agate wendet die Format-Regeln des Archivs deshalb selbst an, bevor es ein SIP abschliesst; die Schalter liest es über die API aus Anton.

Was agate mit einer Datei getan hat, steht in metadata.json beim Dateieintrag (format_normalization). Anton legt dafür am Medium je Regel ein Ereignis format-normalization an, wie bei einer Umwandlung in Anton selbst. Es nennt die Regel, die Werkzeugversionen und die Prüfsummen vor und nach der Umwandlung. Die Prüfsumme der Datei, wie sie bei agate ankam, bleibt damit erhalten.

Original und Nutzungskopie

Ab anton-import-format 0.6 kann ein SIP zu einer Datei mehr als den Master liefern: die Datei vor einer Umwandlung (versions, Rolle original) und eine Nutzungskopie (access_copy). Der Master bleibt das Medium.

  • Original: Anton bewahrt es hinter dem Medium auf (Fassung «Original», mit eigenen Prüfsummen und Ereignissen, in DIMAG über media:versions-to-cloud), nie als eigenes Medium. Hat agate die Datei umgewandelt und das Original behalten, verweist das Ereignis format-normalization auf diese Fassung.
  • Nutzungskopie: Die Einstellung import_access_copy entscheidet. derive (Vorgabe): Anton rechnet die Webfassung selbst, die gelieferte Kopie wird nicht gespeichert. adopt: Anton übernimmt sie als Webfassung, wenn sie zum Master passt (Bild → JPEG, PDF → PDF, Video → MP4, Audio → MP3) und die Prüfsumme stimmt; sonst rechnet es selbst. Der Entscheid steht als Ereignis «Nutzungskopie» am Medium. Eine übernommene Webfassung ersetzt media:conversions nur mit --replace-supplied. Das Vorschaubild rechnet Anton immer selbst.
  • Prüfung: Original und Nutzungskopie werden vor dem Import geprüft wie der Master: Virenprüfung, Prüfsumme, bei E-ARK gegen das METS ihrer Repräsentation (representations/<source>/data/). Ein Fehler bricht den Import ab, bevor etwas geschrieben ist.
  • Formatversion: agate fragt Anton über GET /api/import-format, welche Version des Formats sein Import liest, und schreibt Original und Nutzungskopie nur, wenn Anton 0.6 oder neuer meldet. Ein metadata.json in einer neueren Version, als Anton liest, weist Anton ab.

Was der Import übernimmt

Der Import übernimmt die Beschreibung aus metadata.json weitgehend wie der native Import: alle Sprachen des Titels, Verzeichnungsstufe, Objekttyp, Altsignaturen, Umfang, Sprachen, alle Textfeldarten, die das Archiv kennt, alle Ereignisse mit Akteur:in und Ort, Schlagwörter, Orte, Akteur:innen als Schlagwort (actors, ohne Datum und Ort) und Feldwerte.

Nicht übernommen werden identifier (die Signatur vergibt Anton) sowie private, release_year, vacat und formset_id (Zugang und Formular bestimmt Anton). Das Protokoll des Laufs nennt solche Felder, ebenso unbekannte Sprachen, Textfeld- und Ereignisarten.

An bestehenden Normdaten füllt der Import nur leere Textfelder; ein abweichender Text bleibt stehen und wird gemeldet.

Ein Import legt nur an. Nennt ein Paket eine UUID, die es in Anton schon gibt, wird es abgewiesen, bevor etwas geschrieben und bevor die Datenbank gesichert wird. Das gilt auch für eine korrigierte Lieferung aus agate, deren UUIDs gleich bleiben: Korrigiert wird über die Update-Tabelle, die Datensätze auch über die uuid findet, oder man löscht die Lieferung vorher in Anton. GET /api/sips/{id}/status nennt den Grund in refusal: code ist existing_records, dazu count und bis zu 100 records mit id, uuid und identifier.

  • Normdaten suchen: Eine Referenz kann unter resources Kennungen tragen, zum Beispiel GND oder Wikidata. Anton sucht zuerst über die Kennung, dann über den Namen. Trägt ein Eintrag gleichen Namens eine andere Kennung desselben Anbieters, entsteht ein eigener Eintrag, und das Protokoll nennt ihn. Beim Import gibt es keinen Netzzugriff.
  • Unbekannte Normdaten: Anton legt sie als vorläufig an (siehe Normdaten). Steht create-actors, create-places oder create-keywords auf aus, wird nichts angelegt: Die Verknüpfung entfällt mit einer Warnung, der Import läuft weiter.
  • Ziel über die API: Der Dateiname sip-agate-<id>.zip startet den Import unter diesem Datensatz. Ohne ihn nimmt POST /api/sips/import das Ziel aus parent der obersten Einträge (uuid, identifier oder id). Nennen sie keinen Datensatz, wartet das Paket im Eingangskorb. Nennen sie verschiedene oder einen unbekannten Datensatz oder liegt das Ziel im Akzessionsarchiv, wartet es ebenfalls dort, und die Antwort nennt den Grund in target_problem.
  • Protokoll über die API: GET /api/sips/{id}/status liefert warnings und notes. GET /api/import-format meldet unter delivery, was die Instanz übernimmt.

Vorschläge statt Tatsachen

Ein Paket kann Verknüpfungen als Vorschlag liefern (suggestions an einem Eintrag, ab anton-import-format 0.9). Sie werden nur abgelegt: Nichts kommt an den Datensatz und kein Normdatensatz entsteht, bevor jemand entschieden hat. Einen Modus, der Vorschläge ab einer bestimmten Sicherheit selbst übernimmt, gibt es nicht.

Entschieden wird in der Prüfliste für Vorschläge unter Daten-Import. Sie braucht die Befugnis «Vorschläge prüfen und bestätigen», die sich Konten ab der Rolle Editor geben lässt. Die Liste filtert nach Stand, Art, Bestand, Einstufung und Quelle und zeigt je Vorschlag den Datensatz, die Textstelle und die Einträge ähnlichen Namens.

  • Bestätigen schreibt die Verknüpfung als Schlagwort oder als Ereignis, wie der Vorschlag es sagt, einzeln oder für alle ausgewählten. Ist nicht klar, welcher Eintrag gemeint ist, bleibt der Vorschlag offen, bis jemand wählt.
  • Neu anlegen erstellt einen eigenen Eintrag, auch neben einem gleichnamigen. Er bleibt vorläufig, bestätigt ist die Verknüpfung, nicht der Eintrag.
  • Verwerfen behält den Vorschlag mit Person und Zeitpunkt. Eine spätere Lieferung schlägt ihn nicht noch einmal vor.

Grosses Paket auf dem Server

Die API nimmt ein Paket bis 5 GB an. Ein grösseres, .zip oder .tar, legt man per SSH auf den Server und startet den Import dort:

php artisan sip:import-file --env=<slug> /pfad/platte-7.zip --parent=123 --dry-run
php artisan sip:import-file --env=<slug> /pfad/platte-7.zip --parent=123 --user=<konto>

--dry-run prüft nur und schreibt nichts: Format, Ziel, vorhandene UUIDs, Dubletten, Anzahl Einträge, Links und Platz, bei ZIP wie bei TAR. Ohne --parent gilt parent der obersten Einträge in metadata.json. Der Lauf steht im Importprotokoll wie jeder andere, das Paket bleibt liegen, wo es ist.

Zwei Dinge sind anders als bei der API:

  • Eine Datei scheitert an Prüfsumme, Format oder Virenprüfung: Sie wird nicht angehängt, das Protokoll nennt sie, der Lauf geht weiter und endet als «Mit Fehlern abgeschlossen» (with_errors, Exit-Code 2).
  • Der Lauf bricht ab, weil die Datenbank oder der Speicher versagt: Die Datenbank wird nicht zurückgesetzt, damit nichts verloren geht, was in der Zwischenzeit erfasst wurde. Mit --resume=<lauf> geht es weiter; vorhandene Datensätze und angehängte Dateien werden übersprungen. Zurücksetzen ist eine bewusste Entscheidung: anton:restore --file=<Sicherung des Laufs>.

Konfigurations-Checkliste

Damit agate-Imports funktionieren:

  1. setting('enable_sip_anton_import') auf true setzen (default false aus Sicherheitsgründen)
  2. API-Token für agate erzeugen (siehe API-Authentifizierung)
  3. NARA-Mapping anlegen (siehe oben) — Default-Mapping vorhanden, aber tenant-spezifische Werte sind wahrscheinlich nötig
  4. Queue-Worker muss laufen (Anton-Standard: Supervisor)

Häufige Stolpersteine

  • Wiederholte Uploads mit gleichem Filename funktionieren — Anton prüft den Original-Filename, nicht den UUID-suffixed Pfad auf Disk.
  • NARA-Kategorie ohne Tenant-Typ bricht den Import nicht ab. Das object_type bleibt leer.
  • Wrapper-Datensatz oben am SIP bekommt keinen Objekttyp aufgedrückt — Hardcoded "Agate SIP" wurde entfernt.

Verwandte Seiten