Webhook-API

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.

Hinweis

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:

ParameterTypBeschreibung
userUserDer Benutzer, der die Suche ausgeführt hat.
docTypeCategoryDer Dokumenttyp der gesuchten Dokumente, falls er angegeben wurde.
searchContextDocumentDie Suchbegriffe, auf die du mit dem Document-Objekt zugreifen kannst. Die erweiterten Eigenschaften mit den Suchbegriffen kannst du in der Response ändern.

 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:

ParameterTypBeschreibung
userUserDer ausführende Benutzer.
errorCodeNumber0 bei Erfolg, ansonsten ein Fehlercode.
noResultsNumberAnzahl der Treffer.
noRefusedNumberAnzahl verweigerter Treffer.
docTypeCategoryDer Dokumenttyp der gesuchten Dokumente, falls er angegeben wurde.

 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:

ParameterTypBeschreibung
userUserDer ausführende Benutzer.
docTypeCategoryDer Dokumenttyp des zu validierenden Dokuments.
docDocumentDas Dokument, das vor dem Import validiert werden soll. Die erweiterten Eigenschaften des Dokuments kannst du in der Response ändern.
nextcallStringName des Calls, der auf die Validierung folgt. Der Wert ist in diesem Fall ImportDocument.

 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:

ParameterTypBeschreibung
userUserDer ausführende Benutzer.
docTypeCategoryDokumenttyp des Dokuments, das importiert wird.
docDocumentDie Eigenschaften des Dokuments, das importiert wird. Die erweiterten Eigenschaften des Dokuments kannst du in der Response ändern.

 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:

ParameterTypBeschreibung
docDocumentDas neue Dokument.
fileDestinationStringPfad und Name der Zieldatei.
importOkNumber1: Bisher ist kein Fehler aufgetreten.
0: Beim Erstellen des Dokuments ist ein Fehler aufgetreten.
userUserDer ausführende Benutzer.
docTypeCategoryDokumenttyp des neuen Dokuments.

 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:

ParameterTypBeschreibung
doc DocumentDokument, für das eine neue Dateiversion erstellt werden soll. Die erweiterten Eigenschaften des Dokuments kannst du in der Response ändern.
user UserDer ausführende Benutzer.
docType CategoryDokumenttyp der Dateiversion, die importiert werden soll.

 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:

ParameterTypBeschreibung
doc Document Das Document mit den aktualisierten Eigenschaftswerten für das eine neue Dateiversion importiert wurde.
importOkNumber 1: Speichern der neuen Version erfolgreich.
0: Speichern der neuen Version mit einem Fehler abgebrochen.
errorCodeNumber Im Fehlerfall (importOk=0): Fehlercode des zuvor aufgetretenen Fehlers.
userUser Der ausführende Benutzer.
docTypeCategory Dokumenttyp der importierten Dateiversion.
docOldDocumentDas Document vor der Eigenschaftsaktualisierung.

 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:

ParameterTypBeschreibung
userUserDer ausführende Benutzer.
docTypeCategoryDokumenttyp des Dokuments, das aktualisiert werden soll.
docDocumentDas Dokument, dessen Eigenschaften aktualisiert werden sollen. Die erweiterten Eigenschaften des Dokuments kannst du in der Response ändern.
nextcallStringName des Calls, der auf die Validierung folgt. Der Wert ist in diesem Fall UpdateAttributes.

 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:

ParameterTypBeschreibung
docDocumentDas Document-Objekt mit den Eigenschaftswerten, die aktualisiert werden sollen. Die erweiterten Eigenschaften des Dokuments kannst du in der Response ändern.
userUserDer ausführende Benutzer.
docTypeCategoryDokumenttyp vor der Eigenschaftsaktualisierung.
docTypeNewCategoryDokumenttyp nach der Eigenschaftsaktualisierung.

 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:

ParameterTypBeschreibung
docDocumentDas Document-Objekt mit den aktualisierten Eigenschaftswerten.
errorCodeNumber0: Aktualisierung war erfolgreich.
<>0: Interne Fehlernummer oder DB-Fehlercode.
userUserDer ausführende Benutzer.
docTypeCategoryDokumenttyp nach der Eigenschaftsaktualisierung.
docTypeOldCategoryDokumenttyp vor der Eigenschaftsaktualisierung.
docOldDocumentDas Document-Objekt vor der Eigenschaftsaktualisierung.

 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:

ParameterTypBeschreibung
doc DocumentDokument, das gelöscht werden soll.
user UserDer Benutzer, der das Dokument löschen möchte.
docType CategoryDokumenttyp des Dokuments, das gelöscht werden soll.

 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:

ParameterTypBeschreibung
docDocumentDas Dokument, das gelöscht werden soll.
userUserBenutzer, der das Dokument gelöscht hat.
errorCodeNumber0: Dokument wurde erfolgreich gelöscht.
Ansonsten: Löschen fehlgeschlagen; Fehlercode.
docTypeCategoryDokumenttyp des Dokuments, das gelöscht werden soll.

 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:

ParameterTypBeschreibung
parentDocumentDie übergeordnete Akte bzw. das übergeordnete Dokument.
childDocumentDas untergeordnete Dokument bzw. die untergeordnete Akte.

 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:

ParameterTypBeschreibung
parentDocumentDas übergeordnete Dokument, bzw. die übergeordnete Akte.
childDocumentDas untergeordnete Dokument bzw. die untergeordnete Akte.
linkErrorNumber0: Verknüpfung war erfolgreich.
1: Das übergeordnete und untergeordnete Element ist identisch bzw. eins der beiden Elemente existiert nicht.
2: Die beiden Dokumente sind bereits verknüpft.
3: Die beiden Dokumente sind bereits in umgekehrter Hierarchie miteinander verknüpft.
4: Beim Eintragen der Verknüpfung in die Datenbank ist ein Datenbankfehler aufgetreten (siehe errorCode).
Ansonsten: Datenbankfehlernummer beim Eintragen der Verknüpfung in die Datenbank.
errorCodeNumber0 = Ok.
Ansonten Datenbank- oder Webhook-Fehler.

 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:

ParameterTypBeschreibung
userUserBenutzer, der den Dokumentstatus ändert.
docDocumentDas Dokument, dessen Status geändert werden soll.
fileIdNumberFile-ID der Dokumentversion.
sourceStatusStringQuellstatus des Dokuments ("B", "P", "F", "A").
destStatusStringZielstatus des Dokuments ("B", "P", "A").
destEditorUserOrGroupBei Zielstatus "B" ("Bearbeitung"): Der Benutzer- oder der Gruppenname. Bei Zielstatus "P" (" Prüfung"): Der Gruppenname. Ansonsten leer.

 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:

ParameterTypBeschreibung
userUserDer ausführende Benutzer.
docDocumentDas Dokument, dessen Status geändert wurde.
fileIdNumberFile-ID der Dokumentversion.
sourceStatusStringQuellstatus des Dokumentes ("B", "P", "F", "A").
destStatusStringZielstatus des Dokumentes ("B", "P", "A").
destEditorUserOrGroupBei Zielstatus "B" ("Bearbeitung"): Der Benutzer- oder der Gruppenname. Bei Zielstatus "P" ("Prüfung"): Der Gruppenname. Ansonsten leer.
errorCodeNumber0 = Statustransfer erfolgreich.
Ansonsten Fehlercode.

 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.

 Ereignis 1: "Vor dem Erstellen eines generierten Dokuments"

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

ParameterTypBeschreibung
docDocumentDas Dokument, zu dem die abhängige Datei gehört.
statusStringAktueller Status des Dokuments.
fileIdNumberVersion des Dokuments.
editorUserOrGroupBearbeiter oder Prüfergruppe des Dokuments bei Status "Bearbeitung" bzw. "Prüfung".
depExtStringDateierweiterung der abhängigen Datei.
transferNumber1: Aufruf während eines Statustransfers.

 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:

ParameterTypBeschreibung
docDocumentDas Dokument, zu dem die abhängige Datei abgelegt wurde.
statusStringAktueller Status des Dokuments.
fileIDNumberVersion des Dokuments.
editorUserOrGroupBearbeiter oder Prüfergruppe des Dokuments bei Status "Bearbeitung" bzw. "Prüfung".
depExtStringDateierweiterung der abhängigen Datei.
transferNumber1: Aufruf während eines Statustransfers.

 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:

ParameterTypBeschreibung
docDocumentDas freizugebene Dokument.
userUserBenutzer, der das Dokument freigeben möchte.
docTypeCategoryDer Dokumenttyp des freizugebenden Dokuments.
unblockString(veraltet)
"1" = Dokument wird entsperrt
"" = normale Freigabe

 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:

ParameterTypBeschreibung
docDocumentDas freigegebene Dokument.
userUserBenutzer, der das Dokument freigegeben hat.
docTypeCategoryDer Dokumenttyp des freigegebenden Dokuments.
unblockString(veraltet)
"1" = Dokument wurde entsperrt
"" = normale Freigabe
errorCodeNumber0 = Statustransfer war erfolgreich.
Ansonsten Fehlercode.

 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:

ParameterTypBeschreibung
dataSetDatasetDie dynamische Wertemenge.
userUserDer aufrufende Benutzer.
docTypeCategoryDer Dokumenttyp, dem die Wertemenge zugeordnet ist.
rowNoNumberZeilennummer für Mehrfacheigenschaften.
validateBooleanAufruf zur Wertvalidierung (true/false).
attribContextDocumentDocument-Objekt mit dem Attributkontext. Dieses Objekt enthält bei der Suche die Suchkriterien. Beim Import und Update enthält das Objekt die bereits gefüllten Attribute.

 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

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:

EigenschaftTypBeschreibung
idStringDie ID des Benutzers.
nameStringName des Benutzers.

 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:

EigenschaftTypBeschreibung
idStringDie ID des Benutzers bzw. der Benutzergruppe.
nameStringName des Benutzers bzw. der Benutzergruppe.
isUserBooleanLiefert den Wert true, wenn es sich um einen Benutzer handelt.

 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:

EigenschaftTypBeschreibung
idStringDie eindeutige ID der Kategorie.
nameStringDer Anzeigename der Kategorie.
typeStringDer Typ der Kategorie. Aktenart: DOSSIER_TYPE, Dokumentart: DOCUMENT_TYPE.

 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:

EigenschaftTypBeschreibung
idStringDie ID des Dokuments.
categoryIdStringID der Kategorie, zu der das Dokument gehört.
numberStringDie Nummer des Dokuments.
statusStringDer Status des Dokuments: "B" = "Bearbeitung", "P" = "Prüfung", "F" = "Freigabe" und "A" = "Archiv".
captionStringDer Titel des Dokuments.
dateCreatedStringDer Zeitstempel des Neuimports des Dokuments.
dateUpdatedStringDer Zeitstempel der letzten Änderung des Dokuments. Die letzte Änderung umfasst Änderungen des Dokumentinhalts und Änderungen an den Dokumenteigenschaften.
dateUpdatedFileStringDer Zeitstempel des letzten Imports einer neuen Dokumentversion.
dateLastAccessStringDer Zeitstempel des letzten Zugriffs.
fileNameStringDer Dateiname des Dokuments.
fileExtensionStringDie Dateierweiterung des Dokuments.
sizeNumberDateigröße in Bytes.
fileFormatStringDas Format der Datei wie z.B. "PDF".
retentionDateStringDie Aufbewahrungszeit des Dokuments.
versionsVersion[]Die erweiterten Eigenschaften des Dokuments werden als Liste von Version-Objekten geliefert.
propertiesProperty[]Die erweiterten Eigenschaften des Dokuments werden als Liste von Property-Objekten geliefert.

 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

EigenschaftTypBeschreibung
idStringDie ID der Dokumentversion.
statusStringDer Status der Dokumentversion: "B" = "Bearbeitung", "P" = "Prüfung", "F" = "Freigabe" und "A" = "Archiv".
dateCreatedStringDer Zeitstempel des Neuimports der Dokumentversion.
fileNameStringDer Dateiname der Dokumentversion.
fileExtensionStringDie Dateierweiterung der Dokumentversion.
sizeNumberDateigröße der Dokumentversion in Bytes.

 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

EigenschaftTypBeschreibung
idStringDie eindeutige ID der Eigenschaft.
nameStringDer Name der erweiterten Dokumenteigenschaft
dataTypeStringDer Datentyp der Eigenschaft.
Text: STRING
Währung: CURRENCY
Zahl: NUMERIC
Datum: DATE
Datum und Zeit: DATETIME.
isMultiValueBooleanZeigt an, ob es sich um ein Mehrfacheigenschaftsfeld handelt.
valueString/NumberDer Wert der Dokumenteigenschaft.
valuesMultiValue[]Falls es sich um ein Mehrfacheigenschaftsfeld handelt, werden die Werte als Array von MultiValue-Objekten geliefert

 Document.Property.MultiValue

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


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

Hinweise zu den Eigenschaften

EigenschaftTypBeschreibung
rowStringZeilennummer der Mehrfacheigenschaft.
valueStringWert dieser Zeile des Mehrfacheigenschaftsfeldes.

 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:


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

Hinweise zu den Eigenschaften

EigenschaftTypBeschreibung
idStringDie ID der dynamischen Wertemenge.
propertyIdStringDie eindeutige ID der Dokumenteigenschaft, der die dynamische Wertemenge zugewiesen ist.
dataTypeStringDer Datentyp der Wertemenge.
Text: STRING
Währung: CURRENCY
Zahl: NUMERIC
Datum: DATE
Datum und Zeit: DATETIME
valuesString[]/
Number[]
Die Liste der Werte für die Wertemenge. Ein Webhook füllt in seiner Response das Array mit den gewünschten Werten.

 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"
    ]
  }
}