DMS Webhooks

Implementierung von Webhooks in d.3-Repositorys

Über Webhooks in d.3-Repositorys

Mithilfe von Webhooks kannst du bestimmte Prozesse innerhalb eines Repositorys beeinflussen. Webhooks können sich in zwei unterschiedlichen Formen im Repository integrieren: Zum einen kannst du Webhooks für eine Reihe von Ereignissen registrieren, um das Verhalten des Ereignisses zu beeinflussen oder um weitere nachfolgende Aktionen zu starten. Zum anderen kannst du einen Webhook zum automatischen Erstellen von Wertemengen konfigurieren. Mithilfe des Webhooks für Wertemengen werden Werte dynamisch aus Drittsystemen abgerufen oder unter Berücksichtigung von Regeln gebildet.

Die Webhooks kannst du in der d.velop documents-Repositorykonfiguration im Menüeintrag Webhooks für die gewünschten Ereignisse eintragen.

Mit der neusten Version wird statt „x-dv-api-key: APIKEY“ nun „Authorization: Bearer APIKEY“ als Header an den Webhook übergeben.

Ereignisse

Für eine Reihe von Ereignissen, die bei der Arbeit mit Dokumenten in einem Repository auftreten können, kannst du Webhooks aufrufen lassen.

Wenn das Ereignis eintritt, wird an jede eingetragene URL ein HTTP-POST-Request gesendet. Abhängig vom gewählten Ereignis werden im Body des HTTP-POST-Requests verschiedene Informationen an den Webhook übergeben z.B zu einem gespeicherten Dokument. Diese Informationen kannst du innerhalb des Webhooks verwenden, um auf deren Basis weitere Aktionen zu starten.

Für jedes Ereignis werden im Folgenden die Informationsobjekte beschrieben. Diese Informationsobjekte sind jeweils Bestandteile des Request-Bodys und werden in Form von JSON-Objekten repräsentiert.

Suchen

Diese Ereignisse werden ausgelöst, wenn ein Anwender eine Suche im Repository ausführt.

Ereignis 1: "Vor dem Suchen"

Das Ereignis wird vor einer Suche aufgerufen. Die übergebenen Suchkriterien sind zu dem Zeitpunkt noch nicht auf Plausibilität geprüft worden. Folgende Parameter werden übergeben:

Ereignis 2: "Nach dem Suchen"

Das Ereignis wird am Ende der Suche aufgerufen, direkt bevor die Ergebnisse an den Benutzer geliefert werden. Folgende Parameter werden übergeben:

Dokumente und Akten erstellen

Diese Ereignisse werden ausgelöst, wenn ein neues Dokument oder eine Akte im Repository gespeichert wird.

Ereignis 1: "Ablagedialog überprüfen"

Das Ereignis wird aufgerufen, wenn einem neu importierten Dokument Eigenschaften zugewiesen wurden. Folgende Parameter werden übergeben:

Ereignis 2 "Vor dem Erstellen eines Dokuments oder einer Akte"

Das Ereignis wird aufgerufen, bevor ein Anwender ein Dokument oder eine Akte erstellt. Du kannst die Werte der erweiterten Eigenschaften im Webhook ändern. Folgende Parameter werden übergeben:

Ereignis 3: "Nach dem Erstellen eines Dokuments oder einer Akte"

Das Ereignis wird aufgerufen, nachdem ein Anwender ein Dokument oder eine Akte erstellt hat. Der Prozess ist bei diesem Ereignis bereits abgeschlossen. Folgende Parameter werden übergeben:

Neue Version erstellen

Diese Ereignisse werden ausgelöst, wenn eine neue Version eines Dokuments im Repository gespeichert wird.

Ereignis 1: "Vor dem Erstellen einer neuen Version"

Das Ereignis wird aufgerufen, bevor ein Anwender eine neue Version eines Dokuments erstellt. Bei diesem Ereignis wurde geprüft, ob das Dokument bereits im Repository existiert. Die erweiterten Eigenschaften kannst du zu diesem Zeitpunkt noch ändern. Folgende Parameter werden übergeben:

Ereignis 2: "Nach dem Erstellen einer neuen Version"

Das Ereignis wird aufgerufen, nachdem ein Anwender eine neue Version eines Dokuments erstellt hat. Der Prozess ist bei diesem Ereignis bereits abgeschlossen. Folgende Parameter werden übergeben:

Eigenschaften aktualisieren

Diese Ereignisse werden ausgelöst, wenn die Eigenschaften eines Dokuments oder einer Akte geändert werden.

Ereignis 1: "Eigenschaften überprüfen"

Das Ereignis wird aufgerufen, wenn die Dokumenteigenschaften überprüft werden. Folgende Parameter werden übergeben:

Ereignis 2: "Vor dem Aktualisieren von Eigenschaften"

Das Ereignis wird aufgerufen, bevor die Eigenschaften eines Dokuments aktualisiert werden. Du kannst die Werte der erweiterten Eigenschaften im Webhook ändern. Folgende Parameter werden übergeben:

Ereignis 3: "Nach dem Aktualisieren von Eigenschaften"

Das Ereignis wird aufgerufen, nachdem die Eigenschaften eines Dokuments aktualisiert wurden. Der Prozess ist bei diesem Ereignis bereits abgeschlossen. Folgende Parameter werden übergeben:

Dokumente und Akten löschen

Diese Ereignisse werden ausgelöst, wenn ein Dokument oder eine Akte aus dem Repository entfernt wird.

Ereignis 1: "Vor dem Löschen eines Dokuments oder einer Akte"

Das Ereignis wird aufgerufen, bevor ein Benutzer ein Dokument oder eine Akte löscht. Zu diesem Zeitpunkt wurde bereits geprüft, ob der Benutzer das Dokument löschen darf. Folgende Parameter werden übergeben:

Ereignis 2: "Nach dem Löschen eines Dokuments oder einer Akte"

Das Ereignis wird aufgerufen, nachdem ein Benutzer ein Dokument oder eine Akte gelöscht hat. Der Prozess ist bei diesem Ereignis bereits abgeschlossen. Folgende Parameter werden übergeben:

Elemente verknüpfen

Ereignisse vom Typ "Elemente verknüpfen" werden ausgelöst, wenn zwei Elemente miteinander verknüpft werden. Das Ereignis wird bei folgenden Verknüpfungen ausgelöst:

• Ein Dokument wird mit einer Akte verknüpft.
• Ein Dokument wird mit einem anderen Dokument verknüpft.
• Eine Akte wird mit einer anderen Akte verknüpft.

Ereignis 1: "Vor dem Verknüpfen von Elementen"

Das Ereignis wird aufgerufen, bevor zwei Elemente verknüpft werden. Folgende Parameter werden übergeben:

Ereignis 2 "Nach dem Verknüpfen von Elementen"

Das Ereignis wird aufgerufen, nachdem zwei Elemente verknüpft wurden. Der Prozess ist bei diesem Ereignis bereits abgeschlossen. Folgende Parameter werden übergeben:

Status ändern

Diese Ereignisse werden ausgelöst, wenn der Status eines Dokuments geändert wird.

Ereignis 1: "Vor dem Ändern des Status"

Das Ereignis wird aufgerufen, bevor der Dokumentstatus geändert wird. Folgende Parameter werden übergeben:

Ereignis 2: "Nach dem Ändern des Status"

Das Ereignis wird aufgerufen, nachdem der Dokumentstatus geändert wurde. Der Prozess ist bei diesem Ereignis bereits abgeschlossen. Folgende Parameter werden übergeben:

Generiertes Dokument erstellen

Diese Ereignisse werden ausgelöst, wenn zu einem Dokument eine neue, abhängige Datei gespeichert wird. In einem d.3ecm-Cloud-Repository wird dieses Ereignis insbesondere durch die automatische Generierung eines langzeitstabilen PDF-Abbilds des Dokuments ausgelöst.

Ist ein generiertes PDF-Abbild binäridentisch mit dem Dokument, so wird dieses Abbild nicht als abhängige Datei gespeichert und diese Ereignisse werden nicht aufgerufen!

Ereignis 1: "Vor dem Erstellen eines generierten Dokuments"

Das Ereignis wird aufgerufen, bevor eine neue abhängige Datei gespeichert wird. Folgende Parameter werden übergeben:

Ereignis 2: "Nach dem Erstellen eines generierten Dokuments"

Das Ereignis wird aufgerufen, nachdem eine neue abhängige Datei gespeichert wurde. Der Prozess ist bei diesem Ereignis bereits abgeschlossen. Folgende Parameter werden übergeben:

Dokument freigeben

Diese Ereignisse werden ausgelöst, wenn ein Dokument in den Status Freigabe überführt wird.

Ereignis 1: "Vor der Freigabe eines Dokuments"

Das Ereignis wird aufgerufen, bevor ein Dokument in den Status Freigabe überführt wird. Folgende Parameter werden übergeben:

Ereignis 2: "Nach der Freigabe eines Dokuments"

Das Ereignis wird aufgerufen, nachdem ein Dokument in den Status Freigabe überführt wurde. Der Prozess ist bei diesem Ereignis bereits abgeschlossen. Folgende Parameter werden übergeben:

Ereignis zum Abfragen einer dynamischen Wertemenge

Das Ereignis wird ausgelöst, wenn die Werte für eine dynamische Wertemenge angefordert werden. Mit der values-Eigenschaft des dataset-Objekts kannst du in deinem Webhook die gewünschten Werte zurückgeben. Folgende Parameter werden übergeben:

Definition der JSON-Objekte, die im Request übergeben werden können

Abhängig vom Ereignis kannst du die nachfolgenden Objekte an den Webhook übergeben:

• User
• UserOrGroup
• Category
• Document
• Dataset

User

Ein User-Objekt enthält den Namen sowie die IDs eines Benutzers. Das JSON-Objekt sieht beispielsweise so aus:

{
  "id": "e82fa1b5-2fa8-50f6-85eb-a0ae440774c9",
  "name": "dvelop"
}

Hinweise zu den Eigenschaften:

UserOrGroup

Ein UserOrGroup-Objekt repräsentiert einen Benutzer oder eine Benutzergruppe. Das JSON-Objekt sieht beispielsweise so aus:

{
  "id": "e82fa1b5-2fa8-50f6-85eb-a0ae440774c9",
  "name": "dvelop",
  "isUser": true
}

Hinweise zu den Eigenschaften:

Category

Ein Category-Objekt enthält die ID sowie den Namen einer Kategorie. Das JSON-Objekt sieht beispielsweise so aus:

{
  "id": "b3d0a717-d564-4caa-a348-cb8ac1ab7cf6",
  "name": "Document type 1",
  "type": "DOCUMENT_TYPE"
}

Hinweise zu den Eigenschaften:

Document

Ein Document-Objekt enthält die Eigenschaften des Dokuments, auf das sich das Ereignis bezieht. Die allgemeinen Eigenschaften werden jeweils als Schlüssel-Wert-Paar beschrieben. Es sind nur die allgemeinen Eigenschaften enthalten, die in dem Aufrufkontext zugewiesen sind und einen Wert besitzen. Die physischen Versionen des Dokuments sind als Liste von Document.Version-Objekten enthalten. Die erweiterten Eigenschaften des Dokuments sind als Liste von Document.Property-Objekten enthalten. Das JSON-Objekt sieht beispielsweise so aus:

{
  "id": "P000012345",
  "categoryId": "b3d0a717-d564-4caa-a348-cb8ac1ab7cf6",
  "number": "P000012345",
  "status": "B",
  "dateCreated": "2020-01-19T13:14:16.696+01:00",
  "fileName": "MyFile",
  "fileExtension": "txt",
  "size": 54321,
  "versions": [],
  "properties": []
}

Hinweise zu den Eigenschaften:

Document.Version

Die Beschreibung einer Dokumentversion. Das JSON-Objekt sieht beispielsweise so aus:

{
  "id": 1,
  "status": "B",
  "dateCreated": "2020-01-19T13:14:16.696+01:00",
  "fileName": "MyFile",
  "fileExtension": "txt",
  "size": 54321
}

Hinweise zu den Eigenschaften

Document.Property

Die Beschreibung einer erweiterten Dokumenteigenschaft. Das JSON-Objekt sieht beispielsweise so aus:

{
  "id": "a2bc6985-aaac-4ff9-b9f6-ef5a9a1c25fa",
  "name": "Field Alpha 1",
  "dataType": "STRING",
  "isMultiValue": false,
  "value": "a value for field 1"
}

Die Beschreibung einer erweiterten Dokumenteigenschaft, wenn es sich um ein Mehrfacheigenschaftsfeld handelt. Das JSON-Objekt sieht beispielsweise so aus:

{
  "id": "a2bc6985-aaac-4ff9-b9f6-ef5a9a1c25fa",
  "name": "Field Alpha 1",
  "dataType": "STRING",
  "isMultiValue": true,
  "values": []
}

Hinweise zu den Eigenschaften

Document.Property.MultiValue

Ein Wert eines Mehrfacheigenschaftsfeldes. Das JSON-Objekt sieht beispielsweise so aus:

{
  "row": 1,
  "value": "multi value 1"
}

Hinweise zu den Eigenschaften

Dataset

Repräsentiert eine dynamische Wertemenge innerhalb eines d.3-Repositorys. Du kannst in der Response eines Webhooks mit der values-Eigenschaft eine Liste von Werten zurückgegeben. Das JSON-Objekt sieht beispielsweise so aus:

{
  "dataSet": {
    "id": "2851a93e-2d72-48dd-b6bc-b8eafc",
    "propertyId": "73ba9a65-4d47-413c-x78c-32183d7fecae",
    "dataType": "STRING",
    "values": ["Webhook value 1", "Webhook value 2"]
  }
}

Hinweise zu den Eigenschaften

Exemplarische JSON-Repräsentation eines Request-Bodys

Eine mögliche JSON-Repräsentation für ein Ereignis mit drei Parametern mit den Typen User, Category und Document sieht wie folgt aus:

Request

{
  "user": {
    "id": "e82fa1b5-2fa8-50f6-85eb-a0ae440774c9",
    "name": "dvelop"
  },
  "docType": {
    "id": "b3d0a717-d564-4caa-a348-cb8ac1ab7cf6",
    "name": "Document type 1",
    "type": "DOCUMENT_TYPE"
  },
  "doc": {
    "categoryId": "b3d0a717-d564-4caa-a348-cb8ac1ab7cf6",
    "status": "B",
    "properties": [
      {
        "id": "52ba9a68-4d47-413c-a78c-60183d7ffcfe",
        "name": "Field Alpha 2",
        "dataType": "STRING",
        "isMultiValue": false,
        "value": "Value 2"
      },
      {
        "id": "8cbeff43-44af-4c13-9f9f-6e8134e5013d",
        "name": "Field Date 50",
        "dataType": "DATE",
        "isMultiValue": false,
        "value": "2019-10-10"
      },
      {
        "id": "aa2291e1-de76-4ffe-bdb4-801855dea431",
        "name": "Field Alpha 60",
        "dataType": "STRING",
        "isMultiValue": true,
        "values": [
          {
            "row": 1,
            "value": "multi value 1"
          },
          {
            "row": 2,
            "value": "multi value 2"
          },
          {
            "row": 3,
            "value": "multi value 3"
          }
        ]
      },
      {
        "id": "98d7ff8e-03f0-4a9a-81a4-4d8bd8a9342b",
        "name": "Field Money 70",
        "dataType": "NUMERIC",
        "isMultiValue": false,
        "value": 10.5
      },
      {
        "id": "ddb2d1ec-bb48-47d2-ba-a4482a18bf15",
        "name": "Field Num 80",
        "dataType": "NUMERIC",
        "isMultiValue": false,
        "value": 42
      }
    ]
  }
}

Exemplarische JSON-Repräsentation eines Response-Bodys zur Änderung von erweiterten Eigenschaften

Bei einigen Ereignissen kannst du die erweiterten Eigenschaften des übergebenen Dokuments ändern. Ob du die erweiterten Eigenschaften ändern kannst, ist in der Beschreibung des Document-Parameters dieser Ereignisse angegeben.

Zum Ändern von erweiterten Eigenschaften kannst du in deinem Webhook die Werte für die value-Schlüssel der gewünschten erweiterten Eigenschaften ändern. Bei Mehrfacheigenschaftsfeldern kannst du auch neue Werte hinzufügen. Die Antwort eines Webhooks zur Änderung von Eigenschaftswerten sieht beispielsweise so aus:

Response

{
  "doc": {
    "categoryId": "b3d0a717-d564-4caa-a348-cb8ac1ab7cf6",
    "status": "B",
    "properties": [
      {
        "id": "52ba9a68-4d47-413c-a78c-60183d7ffcfe",
        "name": "Field Alpha 2",
        "dataType": "STRING",
        "isMultiValue": false,
        "value": "Webhook value"
      },
      {
        "id": "8cbeff43-44af-4c13-9f9f-6e8134e5013d",
        "name": "Field Date 50",
        "dataType": "DATE",
        "isMultiValue": false,
        "value": "2019-11-11"
      },
      {
        "id": "aa2291e1-de76-4ffe-bdb4-801855dea431",
        "name": "Field Alpha 60",
        "dataType": "STRING",
        "isMultiValue": true,
        "values": [
          {
            "row": 1,
            "value": "Webhook value 1"
          },
          {
            "row": 2,
            "value": "Webhook value 2"
          },
          {
            "row": 3,
            "value": "Webhook value 3"
          },
          {
            "row": 4,
            "value": "Webhook value 4"
          }
        ]
      },
      {
        "id": "42d636c3-5280-4ff2-b856-33d0d7edb758",
        "name": "Field Date 61",
        "dataType": "DATE",
        "isMultiValue": true,
        "values": [
          {
            "row": 1,
            "value": "2021-02-24"
          },
          {
            "row": 2,
            "value": "2022-02-25"
          },
          {
            "row": 3,
            "value": "2070-02-21T00:00:00.000+01:00"
          }
        ]
      },
      {
        "id": "98d7ff8e-03f0-4a9a-81a4-4d8bd8a9342b",
        "name": "Field Money 70",
        "dataType": "NUMERIC",
        "isMultiValue": false,
        "value": 12.99
      }
    ]
  }
}

Exemplarische JSON-Repräsentation zur Bildung einer dynamischen Wertemenge

Du kannst Webhooks konfigurieren, um beispielsweise Werte für eine Wertemenge dynamisch zu ermitteln. Die Webhooks kannst du in der d.velop documents-Repositorykonfiguration im Menüeintrag Wertemengen eintragen. Ein Payload für den Aufruf einer dynamischen Wertemenge sieht beispielsweise so aus:

{
  "dataSet": {
    "id": "2851a93e-2d72-48dd-b6bc-b8eafc",
    "propertyId": "b9cd1834-e88a-4ecb-8869-c77e397b019e",
    "dataType": "STRING",
    "values": []
  },
  "user": {
    "id": "e82fa1b5-2fa8-50f6-85eb-a0ae440774c9",
    "name": "dvelop"
  },
  "docType": {
    "id": "792d97ed-b66f-40c2-baf3-082ac5342a67",
    "name": "Dokuart 2",
    "type": "DOCUMENT_TYPE"
  },
  "rowNo": 0,
  "validate": 0,
  "attribContext": {
    "status": "B",
    "categoryId": "792d97ed-b66f-40c2-baf3-082ac5342a67",
    "properties": [
      {
        "id": "52ba9a68-4d47-413c-a78c-60183d7ffcfe",
        "name": "Field Alpha 2",
        "dataType": "STRING",
        "isMultiValue": false,
        "value": "value 2"
      },
      {
        "id": "6d01c601-c58a-4f9b-aa8d-87c66ca6717b",
        "name": "Field Alpha 4",
        "dataType": "STRING",
        "isMultiValue": false,
        "value": "value 4"
      }
    ]
  }
}

In der Antwort des Webhooks sind die Rückgabewerte für die dynamische Wertemenge enthalten. Eine Antwort mit den Werten "Webhook value 1" bis "Webhook value 5" für eine dynamische Wertemenge sieht beispielsweise so aus:

{
  "dataSet": {
    "id": "2851a93e-2d72-48dd-b6bc-b8eafc",
    "propertyId": "b9cd1834-e88a-4ecb-8869-c77e397b019e",
    "dataType": "STRING",
    "values": [
      "Webhook value 1",
      "Webhook value 2",
      "Webhook value 3",
      "Webhook value 4",
      "Webhook value 5"
    ]
  }
}