Webhooks

In docuteam box ist es möglich Webhooks zu konfigurieren, falls gewisse Operationen, die digitale Objekte oder ihre Metadaten verändern, in box stattfinden. Webhooks werden dann POST Requests an andere Systeme (z.B. docuteam feeder) schicken, die JSON Eventdaten über die Änderungen in den Daten enthalten.

Liste der Operationen

Webhooks können für die folgenden Operationen konfiguriert werden:

• Append Object (API)
• Change Record Resource metadata (API)
• Change Record Resource metadata (UI)
• Delete object (API)
• Insert object (API)
• Replace object (API)

Webhook configuration

Beim Erstellen oder Ändern eines Webhooks müssen die folgenden Felder ausgefüllt werden:

Feld
Label	Name des Webhooks
Target URL	Endpunkt, an den der Event geschickt wird (z.B. http://feeder.docuteam.ch)
Token	Token, das für die Authentifizierung mit dem externen System verwendet wird (z.B. docuteam feeder token um Events mittels der Event API zu feeder zu schicken)
Operation	box Operation, die den Webhook aktiviert

Zusätzliche Metadaten

Es ist möglich, beschreibende RDF-Metadaten aus den Record Resources zu den Event-Daten hinzuzufügen, indem ein oder mehrere zusätzliche Metadatenelemente hinzugefügt werden:

• Field label: Bezeichnung des JSON-Feldes in dem Ereignis, wo die zusätzlichen Metadaten gespeichert sind
• Predicate: Ein Matterhorn-RDF-Prädikat aus der Liste der derzeit in Fedora verwendeten Prädikate auswählen (zusätzliche Metadaten werden nur für Metadatenressourcen unterstützt, bei denen das Literal und die Kategorie docuteam/vocab Teil der Record Resource sind, die das Ereignis auslöst).
• Include previous values: Standardmäßig enthält der Event den Wert des Metadatenelements nach der Operation. Das JSON-Feld wird mit field_label_is benannt. Optional kann auch der Wert vor der Operation hinzugefügt werden, der dann in field_label_was gespeichert wird. Beim Erstellen eines Webhooks für die Insert Operation ist der alte Wert immer leer. Beim Erstellen eines Webhooks für die Replace Operation sind der alte und der neue Wert identisch.
• Insert multiple values: Falls das Metadatenelement mehrfach vorkommt (oder die an die box-Operation gesendeten Daten mehrere Record Resources enthalten), wird standardmäßig nur der erste Wert zum Webhook hinzugefügt. Durch Aktivieren dieser Option ist es möglich, mehrere Werte als JSON-Array hinzuzufügen.

Beispiel bei Verwendung der Feldbezeichnung unit_title:

{
    "unit_title_was" => "Old title",
    "unit_title_is" => "New title"
}

Event Struktur

Die Event Struktur hängt vom Typ der Operation ab:

Insert Event

{
  "source": "#box base uri",
  "event_type": "box insert operation",
  "api_key_name": "#box authentication name (not the token) with which the request was executed",
  "root_node_pid": "#PID assigned to the root folder of the SIP",
  "sip_name": "#Name of the root folder of the SIP"
}

Replace Operation

{
  "source": "#box base uri",
  "event_type": "box replace operation",
  "api_key_name": "#box authentication name (not the token) with which the request was executed",
  "pid": "#PID assigned to the file which was replaced",
  "file_name": "#Name of the new file"
}

Change Metadata Operation

{
  "source": "#box base uri",
  "event_type": "box change metadata interface",
  "box_user_name": "#user name of the box user which changed the metadata",
  "pid": "#PID assigned to the Record Resource whose metadata was changed",
}

{
  "source": "#box base uri",
  "event_type": "box change metadata API",
  "box_user_name": "#user name of the box user which changed the metadata",
  "pid": "#PID assigned to the Record Resource whose metadata was changed",
}

Append Metadata Operation

{ 
  "source": "#box base uri#",
  "event_type": "box append operation", 
  "box_api_key": "#box authentication name (not the token) with which the request was executed#", 
  "append_position_pid": "#PID where the data was appended to#",
  "root_node_pid": "#PID assigned to the root folder / root file which was appended"
}