DMS API zur Konfiguration von d.3-Repositorys

DMS API zur Konfiguration von d.3-Repositorys

 Verwenden der API-Funktionen

Nachfolgend erfährst du, wie du die Programmierschnittstelle der DMS-App zur Konfiguration von d.3-Repositorys für eigene Entwicklungen nutzen kannst.

Diese API ist eine RESTful HTTP-API mit JSON-Repräsentationen. Insbesondere verwenden wir die JSON Hypertext Application Language, um im JSON-Format zwischen verschiedenen Ressourcen zu verlinken.

Den Einstieg zur Konfiguration von Repositorys findest du unter der Route /dms. Über die Linkrelation repoconfig erreichst du die Liste der konfigurierbaren Repositorys. Von dort aus kommst du über weitere Linkrelationen zu den verschiedenen Konfigurationsmöglichkeiten.

 Ermitteln des Links zur Repositorykonfiguration

Rufe die Links zur Repositorykonfiguration mit einer HTTP GET-Anforderung auf.

Request


GET /dms
Accept: application/hal+json

Die Antwort (Response) der HTTP GET-Anforderung enthält unter anderem die Linkrelation zur Konfiguration.

Response


{
  "_links": {
    "repoconfig": {
      "href": "<URI to repository list>"
    },
    ...
  }
}

 Grundlegendes zu allgemeinen Statuscodes

Während du die Funktionen dieser API nutzt, kann es vorkommen, dass dir die App folgende allgemeine Statuscodes mitteilt. Speziellere Statuscodes werden dir in den entsprechenden Abschnitten erläutert.

Statuscode

  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Header Origin fehlt oder der Benutzer ist nicht zur Administration berechtigt. Nur Mandanten-Administratoren sind berechtigt, Konfigurationen am Repository vorzunehmen.
  • 406: Die angeforderte Ressource steht nicht in der gewünschten Form zur Verfügung. Bitte ändere den Header Accept.
  • 500: Serverfehler.

 Grundlegendes zu unterstützten Sprachen

Innerhalb dieser API kannst du bei einigen Ressourcen bestimmte Eigenschaftswerte in verschiedenen Sprachen nach ISO 639-1 und RFC-3066 definieren. Folgende Sprachen werden unterstützt:

SpracheID der Sprache (ISO 639-1 und RFC-3066)Besonderheit
Deutschde
Englischen
Kroatischhr
Tschechischcs
Dänischda
Niederländischnl
Französischfr
Italienischit
Polnischpl
Serbischsr
Spanisches
Slowakischsk
Chinesischzh-CN
Sprachunabhängiger Standardwertx-originalNur bei Wertemengen

Hinweis

Aus Gründen der Abwärtskompatibilität wird außerdem die Sprach-ID de-DE unterstützt. Bei schreibenden HTTP-Anforderungen (POST, PUT) kannst du die Sprach-ID de-DE synonym zur Sprach-ID de (bei Kategorien und Eigenschaften) bzw. x-original (bei Wertemengen) verwenden. Wir empfehlen die Verwendung der IDs de bzw. x-original.

 Grundlegendes zu sequentiellen und parallelen Anfragen an diese API

Verwende für diese API bitte ausschließlich sequentielle Anfragen. Parallele Anfragen an diese API können zu Fehlern führen und werden daher nicht unterstützt.

 Konfigurieren von Ressourcen

Die API zur Konfiguration von d.3-Repositorys enthält die nachfolgenden Ressourcen. In den nachfolgenden Abschnitten werden die Ressourcen und ihre Konfigurationsmöglichkeiten im Detail beschrieben.

 Repositories

Repräsentiert eine Liste von Repository-Ressourcen.

 Anzeigen aller administrierbaren Repositorys

Verwende eine HTTP GET-Anforderung, zum Anzeigen aller administrierbaren Repositorys.

Request


GET <URI to repositories resource>
Accept: application/hal+json

In der Antwort erhältst du innerhalb des Objekts _embedded ein Array von Repositorys.

Response


{
  "_links": { ... },
  "_embedded": {
    "repositories": [ ... ]
  }
}

Statuscode

  • 200: Die Repositorys wurden erfolgreich ermittelt.
  • 404: Die administrierbaren Repositorys konnten nicht ermittelt werden.

 Aufbau einer "Repositories"-Ressource

Die Repositories-Ressource enthält immer folgende Elemente.

 Embedded (Eingebettete Ressourcen)
RelationTypRessource
repositoriesrepository[]Repository

 Repository

Repräsentiert ein d.3-Repository. Um ein Repository zu konfigurieren kannst du den entsprechenden Linkrelationen in den Repository-Ressourcen folgen. Zur Konfiguration benötigst du Administrationsberechtigungen in den jeweiligen Repositorys.

Nachfolgend erfährst du, wie du ein d.3-Repository konfigurieren kannst.

 Anzeigen eines administrierbaren Repositorys

Verwende eine HTTP GET-Anforderung zum Anzeigen eines administrierbaren Repositorys.

Request


GET <URI to repository resource>
Accept: application/hal+json

Nach dem Aufruf der URI erhältst du in der Antwort der HTTP GET-Anforderung die Linkrelationen, welche auf die spezifischen Funktionen des Repositorys verweisen. Diese Funktionen kannst du nun zur Konfiguration des Repositorys verwenden.

Response


{
  "id": "723199c4-4f0c-5993-8b04-d5f72cd37b3d",
  "name": "repository name",
  "_links": {
    "categories": {
      "href": "<URI to category list>"
    },
    "properties": {
      "href": "<URI to property list>"
    },
	"datasets": {
      "href": "<URI to dataset list>"
    },
	"permissions": {
      "href": "<URI to permission list>"
    },
    "structures": {
      "href": "<URI to struturerule list>"
    },
    "events": {
      "href": "<URI to event list>"
    }
  }
}

Statuscode

  • 200: Das Repository wurde erfolgreich ermittelt.
  • 404: Das Repository mit der angegebenen ID konnte nicht ermittelt werden.

 Aufbau einer "Repository"-Ressource

Die Repository-Ressource enthält immer folgende Elemente.

EigenschaftTypBedeutung
idstringDie eindeutige ID des Repositorys.
namestringDer Anzeigename der Repositorys.
RelationOperationenMedia TypeRessource
selfGETapplication/hal+jsonRepository
categoriesGET, POSTapplication/hal+jsonCategories
propertiesGET, POSTapplication/hal+jsonProperties
datasetsGET, POSTapplication/hal+jsonDatasets
permissionsGET, POSTapplication/hal+jsonPermissions
structuresGET, POSTapplication/hal+jsonStructures
eventsGETapplication/hal+jsonEvents

 Categories

Repräsentiert eine Liste von Category-Ressourcen.

 Abrufen einer Liste aller Kategorien

Verwende eine HTTP GET-Anforderung zum Abrufen einer Liste über alle Kategorien.

Request


GET <URI to categories resource>
Accept: application/hal+json

In der Antwort erhältst du innerhalb des Objekts _embedded ein Array von Kategorien.

Response


{
  "_links": { ... },
  "_embedded": {
    "categories": [ ... ]
   }
}

Statuscode

  • 200: Die Kategorien wurden erfolgreich ermittelt.

 Aufbau einer "Categories"-Ressource

Die Categories-Ressource enthält immer folgende Elemente.

 Embedded (Eingebettete Ressourcen)
RelationTypRessource
categoriescategory[]Category

 Erstellen einer Kategorie

Damit du eine neue Kategorie erstellen kannst, benötigst du mindestens eine verfügbare Eigenschaft. Ist für dein Repository noch keine Eigenschaft konfiguriert, hilft dir dieser Abschnitt weiter: Eigenschaft erstellen.

Sind für dein Repository bereits die benötigten Eigenschaften konfiguriert, kannst du eine Kategorie mit der Methode POST erstellen.

Übergib beim Ausführen der POST-Methode als Request-Body eine Category-Ressource.

Request


POST <URI to categories resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
 "name": {
	"en": "Bill"
  },
  "type": "DOCUMENT_TYPE",
  "readOnly": false,
  "retention": {
    "period": 50,
    "unit": "YEARS"
  },
  "propertyRefs": [
    {
      "propertyId": "1",
      "required": false,
      "showInFacets": true,
      "showInSearch": true,
      "showInImport": true,
      "showInResult": true
    }
  ],
  "titleRefs": [
    {
      "propertyId": "1"
    }
  ],
  "protection": {
    "preventDeletion": true,
    "preventDeletionChangeReason": ""
  }
}

Beim Erstellen einer Kategorie kannst du keine ID angeben. Diese wird vom System automatisch generiert. Nachdem eine Kategorie erstellt wurde, kannst du die URI der neuen Kategorie dem Header Location entnehmen.

Response


location: <URI of the created category resource>

Statuscode

  • 201: Die Kategorie wurde erfolgreich erstellt.
  • 400: Es wurden ungültige Daten übergeben oder die Kategorie existiert bereits im Repository.

 Category

Repräsentiert eine Kategorie innerhalb eines d.3-Repositorys. Eine Kategorie umfasst die Elemente Aktenart und Dokumentart. Jede Kategorie kannst du mit unterschiedlichen Eigenschaften ausstatten, um diesen Typ genauer zu beschreiben. So kannst du beispielsweise deine Dokumente in verschiedene Dokumentarten ablegen und gezielt in einer bestimmten Akte oder nach einer gewünschten Dokumentart suchen.

Nachfolgend erfährst du, wie du eine Kategorie konfigurieren kannst.

 Abrufen einer Kategorie

Wenn du dir die Konfiguration einer bestehenden Kategorie anzeigen lassen möchtest, kannst du die Methode GET auf die URI der Category-Ressource anwenden.

Request


GET <URI to category resource>
Accept: application/hal+json

In der Antwort (Response) der HTTP GET-Anforderung erhältst du schließlich die Detailinformationen zur angegebenen Kategorie:

Response


{
  "id": "BILL",
  "name": {
    "en": "Bill"
  },
  "type": "DOCUMENT_TYPE",
  "readOnly": false,
  "retention": {
    "period": 50,
    "unit": "YEARS"
  },
  "propertyRefs": [{
    "propertyId": "1",
    "required": false,
    "showInFacets": true,
    "showInSearch": true,
    "showInImport": true,
    "showInResult": true
  },
  {
    "propertyId": "DOCUMENT_ID"
  },
  ...
  ],
  "titleRefs": [{
    "propertyId": "1",
    "delimiter": ""
  },
  {
    "propertyId": "DOCUMENT_ID",
    "delimiter": "-"
  }],
  "protection": {
    "preventDeletion": true,
    "preventDeletionChangeReason": ""
  },
  "_links": { ... },
  "_embedded": { ... }
}

Statuscode

  • 200: Die Kategorie wurde erfolgreich ermittelt.
  • 404: Die Kategorie mit der angegebenen ID konnte nicht ermittelt werden.

 Aufbau einer "Category"-Ressource

Die Category-Ressource enthält immer folgende Elemente.

EigenschaftTypBedeutungErforderlich
idstringDie eindeutige ID der Kategorie.ja
namedictionary<string,string>Der Anzeigename der Kategorie. Schlüsselpaare aus der ID der Sprache (ISO 639-1 und RFC-3066) und dem Anzeigenamen in der entsprechenden Sprache. Siehe Grundlegendes zu unterstützten Sprachen.ja
typestringDer Typ der Kategorie.
  • Aktenart: DOSSIER_TYPE
  • Dokumentart: DOCUMENT_TYPE
ja
readOnlybooleanEine rein lesende Eigenschaft, die angibt, ob eine Kategorie vom System vorgegeben wurde und unveränderbar ist.nur lesend
retentionretentionDie Einstellungen zur Aufbewahrung von Dokumenten dieses Typs.nein
propertyRefspropertyRef[]Referenzen auf Eigenschaften, die einer Kategorie zugeordnet sind. Besteht aus einem Array von Referenzobjekten. Mit der Angabe der propertyId wird der Kategorie die jeweilige Eigenschaft zugeordnet.ja
titleRefstitleRef[]Der Titel eines Dokuments dieser Kategorie. Er setzt sich aus einem Array von Objekten zusammen.nein
protectionprotectionDie Einstellung gibt an, ob für die Elemente der Kategorie ein erweiterter Schutz verwendet wird.nein
 PropertyRef

Ein PropertyRef-Objekt beschreibt die Referenz von dieser Kategorie auf eine ihr zugewiesene Eigenschaft. Mithilfe der Eigenschaft propertyId wird der Kategorie die Eigenschaft zugeordnet.

Die übrigen Parameter des PropertyRef-Objektes beschreiben, wie sich die zugewiesene Eigenschaft innerhalb genau dieser Kategorie verhält. Beispielsweise kann die Eigenschaft mit dem required-Parameter als Pflichtfeld für diese Kategorie definiert werden.

EigenschaftTypBedeutungErforderlich
propertyIdstringDie eindeutige ID einer Eigenschaft.ja
requiredbooleanKennzeichnet die Eigenschaft innerhalb der Kategorie als verpflichtend.

Standardwert: false
nein
showInFacetsbooleanDiese Eigenschaft wird bei der Suche nach dieser Kategorie als Facette angeboten.

Standardwert: false
nein
showInSearchbooleanDiese Eigenschaft wird bei der Suche nach dieser Kategorie angeboten.

Standardwert: false
nein
showInImportbooleanDiese Eigenschaft wird bei der Ablage dieser Kategorie angeboten.

Standardwert: false
nein
showInResultbooleanDiese Eigenschaft wird nach der Suche dieser Kategorie in der Ergebnisliste dargestellt.

Standardwert: false
nein
 TitleRef

Ein TitleRef-Objekt beschreibt eine Eigenschaft, die in dieser Kategorie als Titelfeld verwendet wird. Der Titel eines Dokumentes wird anhand der TitleRef-Konfiguration seiner Kategorie automatisch gebildet und beispielsweise in der Suchtrefferliste angezeigt.

EigenschaftTypBedeutungErforderlich
propertyIdstringDie eindeutige ID einer Eigenschaft.ja
delimiterstringTrennzeichen, das vor dieser Eigenschaft eingefügt wird.

Standardwert: Leerzeichen
nein
 Retention

Ein Retention-Objekt beschreibt, wie lange Dokumente dieser Kategorie im d.3-Repository aufbewahrt werden sollen.

EigenschaftTypBedeutungErforderlich
periodnumberDie Aufbewahrungsdauer von Dokumenten dieses Typs.

Standardwert: 0 (0 entspricht ewig)
nein
unitstringDie Einheit in der die Aufbewahrungsdauer angegeben ist.
  • Jahre: YEARS
  • Monate: MONTHS


Standardwert: YEARS
nein
 Protection

Ein Protection-Objekt steuert den erweiterten Schutz von Elementen dieses Typs.

EigenschaftTypBedeutungErforderlich
preventDeletionbooleanVerhindert das Löschen von Elementen im Status Freigabe und Archiv. Die Eigenschaft übersteuert alle Löschen-Rechte. Wenn du eine Aufbewahrungsdauer für Elemente dieser Kategorie festgelegt hast, werden die Elemente nach Ablauf des Zeitraums dennoch gelöscht.

Standardwert: false
nein
preventDeletionChangeReasonstringGrund zur Änderung der Eigenschaft preventDeletion.nein, nur wenn du den Wert für preventDeletion von true auf false änderst.
 Links
RelationOperationenMedia TypeRessource
selfGET, PUT, DELETEapplication/hal+jsonCategory
propertiesGET, POSTapplication/hal+jsonProperties
 Embedded (Eingebettete Ressourcen)
RelationTypRessource
propertiespropertiesProperties

 Ändern einer Kategorie

Wenn du Änderungen an einer bestehenden Kategorie vornehmen möchtest, kannst du die Methode PUT auf die URI der Category-Ressource anwenden.

Request


PUT <URI to category resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
 "name": {
	"en": "Bill"
  },
  "type": "DOCUMENT_TYPE",
  "readOnly": false,
  "retention": {
    "period": 50,
    "unit": "YEARS"
  },
  "propertyRefs": [
    {
      "propertyId": "1",
      "required": false,
      "showInFacets": true,
      "showInSearch": true,
      "showInImport": true,
      "showInResult": true
    },
    {
      "propertyId": "2",
      "required": true,
      "showInFacets": true,
      "showInSearch": true,
      "showInImport": true,
      "showInResult": true
    }
  ],
  "titleRefs": [
    {
      "propertyId": "1"
    }
  ]
}

Response


location: <URI of the changed category resource>

Statuscode

  • 200: Die Kategorie wurde erfolgreich geändert.
  • 400: Es wurden ungültige Daten übergeben.
  • 404: Die Kategorie mit der angegebenen ID konnte nicht ermittelt werden.

 Löschen einer Kategorie

Eine nicht mehr benötigte Kategorie kannst du wieder aus dem Repository löschen, indem du die Methode DELETE auf die URI der Category-Ressource anwendest. Eine Kategorie kann nur gelöscht werden, wenn sie keiner Berechtigung mehr zugeordnet ist und wenn sie nicht vom System vordefiniert wurde (readOnly=true).

Request


DELETE <URI to category resource>
Origin: <Base-URI of the tenant>

Statuscode

  • 204: Die Kategorie wurde erfolgreich gelöscht.
  • 404: Die Kategorie mit der angegebenen ID konnte nicht ermittelt werden.

 Properties

Repräsentiert eine Liste von Property-Ressourcen.

 Abrufen einer Liste aller Eigenschaften

Verwende eine HTTP GET-Anforderung zum Abrufen einer Liste über alle Eigenschaften.

Request


GET <URI to properties resource>
Accept: application/hal+json

In der Antwort erhältst du in der Sektion _embedded ein Array von Eigenschaften.

Response


{
  "_links": { ... },
  "_embedded": {
    "properties": [ ... ]
   }
}

Statuscode

  • 200: Die Eigenschaften wurden erfolgreich ermittelt.

 Aufbau einer "Properties"-Ressource

Die Properties-Ressource enthält immer folgende Elemente.

 Embedded (Eingebettete Ressourcen)
RelationTypRessource
propertiesproperty[]Property

 Erstellen einer Eigenschaft

Verwende die Methode POST zum Erstellen einer Eigenschaft.

Optional kannst du eine Eigenschaft mit einer Wertemenge verknüpfen, damit der DMS-Benutzer aus einer vorgegebenen Menge an Werten auswählen kann. Sofern du eine Eigenschaft mit einer Wertemenge erstellen möchtest, die noch nicht im Repository enthalten ist, musst du diese vor der Eigenschaft erstellen. Dazu hilft dir dieses Kapitel weiter: Wertemenge erstellen.

Übergib beim Ausführen der POST-Methode als Request-Body eine Property-Ressource.

Request


POST <URI to properties resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": {
	"en": "Supplier"
  },
  "dataType": "STRING",
  "isSystemProperty": false,
  "isMultiValue": false,
  "validationRegEx": "(?<=\s)\d{13}(?=\s)",
  "dataSetId": "1"
}

Beim Erstellen einer Eigenschaft kannst du keine ID angeben. Diese wird vom System automatisch generiert. Nachdem eine Eigenschaft erstellt wurde, kannst du die URI der neuen Eigenschaft dem Header Location entnehmen.

Response


location: <URI of the created property resource>

Statuscode

  • 201: Die Eigenschaft wurde erfolgreich erstellt.
  • 400: Es wurden ungültige Daten übergeben oder die Eigenschaft existiert bereits im Repository.

 Property

Repräsentiert eine Eigenschaft innerhalb eines d.3-Repositorys. Eine Eigenschaft ist ein Merkmal, das ein Dokument oder eine Akte kompakt beschreibt. Die verfügbaren Eigenschaften kannst du beim Erstellen oder Ändern einer Kategorie zuordnen.

Nachfolgend erfährst du, wie du eine Eigenschaft konfigurieren kannst.

 Anzeigen der Konfiguration einer Eigenschaft

Wenn du dir die Konfiguration einer bestehenden Eigenschaft anzeigen lassen möchtest, kannst du die Methode GET auf die URI der Property-Ressource anwenden.

Request


GET <URI to property resource>
Accept: application/hal+json

In der Antwort (Response) der HTTP GET-Anforderung erhältst du schließlich die Detailinformationen zur angegebenen Eigenschaft:

Response


{
  "id": "1",
  "name": {
	"en": "Supplier"
  },
  "dataType": "STRING",
  "isSystemProperty": false,
  "readOnly": false,
  "isMultiValue": false,
  "validationRegEx": "",
  "dataSetId": "1",
  "_links": { ... }
}

Statuscode

  • 200: Die Eigenschaft wurde erfolgreich ermittelt.
  • 404: Die Eigenschaft mit der angegebenen ID konnte nicht ermittelt werden.

 Aufbau einer Property-Ressource

Die Property-Ressource enthält immer folgende Elemente.

EigenschaftTypBedeutungErforderlich
idstringDie eindeutige ID der Eigenschaft.ja
namedictionary<string,string>Der Anzeigename der Eigenschaft. Schlüsselpaare aus der ID der Sprache (ISO 639-1 und RFC-3066) und dem Anzeigenamen in der entsprechenden Sprache. Siehe Grundlegendes zu unterstützten Sprachen.ja
dataTypestringDer Datentyp der Eigenschaft.
  • Text: STRING
  • Währung: CURRENCY
  • Zahl: NUMERIC
  • Datum: DATE
  • Datum und Zeit: DATETIME
ja
isSystemPropertybooleanZeigt an, ob es sich um eine vom System erstellte Eigenschaft handelt.nur lesend
readOnlybooleanEine rein lesende Eigenschaft, die angibt, ob eine Eigenschaft vom System vorgegeben wurde und unveränderbar ist.nur lesend
isMultiValuebooleanZeigt an, ob es sich um eine Eigenschaft mit einem oder mehreren Werten handelt.

Standardwert: false
ja
validationRegExstringRegulärer Ausdruck zur Validierung der Eingaben (POSIX Basic Regular Expression Syntax).

Gültige Datentypen: STRING
nein
dataSetIdstringDie ID einer verknüpften Wertemenge.

Gültige Datentypen: STRING, NUMERIC, CURRENCY, DATE
nein
minValuenumberDer kleinste Wert, den diese Eigenschaft annehmen kann.

Gültige Datentypen: NUMERIC, CURRENCY
nein
maxValuenumberDer größte Wert, den diese Eigenschaft annehmen kann.

Gültige Datentypen: NUMERIC, CURRENCY
nein
 Links
RelationOperationenMedia TypeRessource
selfGET, PUT, DELETEapplication/hal+jsonProperty
datasetGET, PUT, DELETEapplication/hal+jsonDataset
 Embedded (Eingebettete Ressourcen)
RelationTypRessource
datasetdatasetDataset

 Verwenden von vordefinierten Eigenschaften

Einige Eigenschaften existieren bereits im Repository, auch ohne dass du diese angelegt hast. Diese Eigenschaften können keiner Kategorie zugeordnet werden, da sie automatisch Bestandteil einer jeden Kategorie sind. Du kannst diese Eigenschaften jedoch für die Vergabe von Berechtigungen und für die Vergabe des Titels einer Kategorie nutzen. Diese Art von Eigenschaften kannst du nicht verändern. Das heißt, du kannst ihre Werte nicht ändern oder löschen. Alle diese Eigenschaften sind mit der Eigenschaft isSystemProperty=true gekennzeichnet.

IDNameBedeutung
DOCUMENT_IDDokument IDDie eindeutige ID des Dokumentes.
CATEGORYKategorienameDer Name der Kategorie.
FILE_EXTENSIONDateitypDer Dateityp des Dokumentes.
FILE_NAMEDateinameDer Dateiname des Dokumentes.
STATUSStatusDer aktuelle Status des Dokumentes.
EDITORBearbeiterDer aktuelle Bearbeiter des Dokumentes.
OWNERBesitzerDer Besitzer des Dokumentes.

 Ändern einer Eigenschaft

Wenn du Änderungen an einer bestehenden Eigenschaft vornehmen möchtest, kannst du die Methode PUT auf die URI der Property-Ressource anwenden.

Request


PUT <URI to property resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": {
	"en": "Supplier"
  },
  "dataType": "STRING",
  "isSystemProperty": "false",
  "isMultiValue": false,
  "validationRegEx": "",
  "dataSetId": "2"
}

Response


location: <URI of the changed property resource>

Statuscode

  • 200: Die Eigenschaft wurde erfolgreich geändert.
  • 400: Es wurden ungültige Daten übergeben.
  • 404: Die Eigenschaft mit der angegebenen ID konnte nicht ermittelt werden.

 Löschen einer Eigenschaft

Eine nicht mehr benötigte Eigenschaft kannst du wieder aus dem Repository löschen, indem du die Methode DELETE auf die URI der Property-Ressource anwendest. Eine Eigenschaft kann nur gelöscht werden, wenn sie keiner Kategorie mehr zugeordnet ist und wenn sie nicht vom System vordefiniert wurde (readOnly=true).

Request


DELETE <URI to property resource>
Origin: <Base-URI of the tenant>

Statuscode

  • 204: Die Eigenschaft wurde erfolgreich gelöscht.
  • 400: Die Eigenschaft ist noch mindestens einer Kategorie zugeordnet oder wurde vom System vordefiniert.
  • 404: Die Eigenschaft mit der angegebenen ID konnte nicht ermittelt werden.

 Datasets

Repräsentiert eine Liste von Dataset-Ressourcen.

 Abrufen einer Liste aller Wertemengen

Verwende eine HTTP GET-Anforderung zum Abrufen einer Liste über alle Wertemengen.

Request


GET <URI to datasets resource>
Accept: application/hal+json

In der Antwort erhältst du innerhalb des Objektes _embedded ein Array von Wertemengen.

Response


{
  "_links": { ... },
  "_embedded": {
    "datasets": [ ... ]
   }
}

Statuscode

  • 200: Die Wertemengen wurden erfolgreich ermittelt.

 Aufbau einer "Datasets"-Ressource

Die Datasets-Ressource enthält immer folgende Elemente.

 Embedded (Eingebettete Ressourcen)
RelationTypRessource
datasetsdataset[]Dataset

 Erstellen einer Wertemenge

Du kannst eine Wertemenge mit der Methode POST erstellen.

Übergib beim Ausführen der POST-Methode als Request-Body eine Dataset-Ressource.

Request


POST <URI to datasets resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": "Supplier names",
  "dataType": "STRING",
  "values": [
    {
      "x-original": "SUPPLIER_1",
      "en": "Supplier 1"
    },
    {
      "x-original": "SUPPLIER_2",
      "en": "Supplier 2"
    }
  ]
}

Beim Erstellen einer Wertemenge kannst du keine ID angeben. Diese wird vom System automatisch generiert. Nachdem eine Wertemenge erfolgreich erstellt wurde, kannst du die URI der neuen Wertemenge dem Header Location entnehmen.

Response


location: <URI of the created dataset resource>

Statuscode

  • 201: Die Wertemenge wurde erfolgreich erstellt.
  • 400: Es wurden ungültige Daten übergeben oder die Wertemenge existiert bereits im Repository.

 Dataset

Repräsentiert eine Wertemenge innerhalb eines d.3-Repositorys. Eine Wertemenge ist ein Vorrat von Werten, die ein Benutzer als Eigenschaft für eine Kategorie auswählen kann. Das gilt sowohl für die Suche, als auch für die Ablage neuer Dokumente.

Nachfolgend erfährst du, wie du eine Wertemenge konfigurieren kannst.

 Anzeigen der Konfiguration einer Wertemenge

Wenn du dir die Konfiguration einer bestehenden Wertemenge anzeigen lassen möchtest, kannst du die Methode GET auf die URI der Dataset-Ressource anwenden.

Request


GET <URI to dataset resource>
Accept: application/hal+json

In der Antwort (Response) der HTTP GET-Anforderung erhältst du schließlich die Detailinformationen zur angegebenen Wertemenge:

Response


{
  "id": "1",
  "name": "Supplier names",
  "dataType": "STRING",
  "readOnly": false,
  "values": [
      {
        "x-original": "SUPPLIER_1",
        "en": "Supplier 1"
      },
      {
        "x-original": "SUPPLIER_2",
        "en": "Supplier 2"
      }
    ],
  "_links": { ... }
}

Statuscode

  • 200: Die Wertemenge wurde erfolgreich ermittelt.
  • 404: Die Wertemenge mit der angegebenen ID konnte nicht ermittelt werden.

 Aufbau einer "Dataset"-Ressource

Die Dataset-Ressource enthält immer folgende Elemente.

EigenschaftTypBedeutungErforderlich
idstringDie eindeutige ID der Wertemenge.ja
namestringDer interne Name der Wertemenge.ja
dataTypestringDer Datentyp der Wertemenge.
  • Text: STRING
  • Währung: CURRENCY
  • Zahl: NUMERIC
  • Datum: DATE
  • Dynamisch: URI
ja
readOnlybooleanEine rein lesende Eigenschaft, die angibt, ob eine Wertemenge vom System vorgegeben wurde und unveränderbar ist.nur lesend
valuesvalue[]Die Werte, die dem DMS-Benutzer zur Auswahl stehen. Wird als Array von Werten angegeben, die abhängig vom Datentypen der Wertemenge sind.nein
 Value

Ein Value-Objekt beschreibt einen Wert, der dem DMS-Benutzer bei dieser Wertemenge zur Auswahl steht. Je nach Datentyp der Wertemenge ist ein Value-Objekt unterschiedlich aufgebaut:

DatentypTypBedeutungBeispiel
STRINGdictionary<string,string>[]Wird als Array von Dictionarys angegeben. Schlüsselpaare aus der ID der Sprache (ISO 639-1 und RFC-3066) und dem Anzeigenamen in der entsprechenden Sprache. In jedem Value des Arrays muss ein sprachunabhängiger Standardwert vorhanden sein (x-original). Dieser Wert wird beispielsweise innerhalb von Webhooks verwendet und dient als Standardwert, wenn keine passende Übersetzung in einer anderen Sprache existiert. Werte in anderen Sprachen sind optional. Siehe Grundlegendes zu unterstützten Sprachen."values": [{ "x-original": "SUPPLIER_1"}]
CURRENCY, NUMERICnumber[]Wird als Array von Numbers angegeben (Ein Punkt entspricht dem Tausendertrennzeichen)."values": [10.3, -4.99]
DATEstring[]Wird als Array von Strings angegeben (ISO 8601)."values": ["2004-07-11"]
URIstring[]Wird als Array von Strings angegeben. Angabe einer Uri eines Webhooks zur dynamischen Ermittlung von Werten. Muss eine gültige HTTP(S)-URI sein. Relative URIs beginnen mit einem Slash. Derzeit kann nur eine Uri angegeben werden.
In diesem Fall kannst du eine zusätzliche Eigenschaft "apiKey" konfigurieren. Mit dieser Eigenschaft kann dem Webhook ein Authentifizierungsschlüssel übermittelt werden. Außerdem kannst du eine zusätzliche Eigenschaft "timeout" konfigurieren. Mit dieser Eigenschaft wird die Zeit in Millisekunden angegeben, nach der von einem Timeout ausgegangen wird (Standardwert: 1000).
"values": ["https://webhook.d-velop.cloud/"],
"apiKey": "securid-key",
"timeout": 1000
 Links
RelationOperationenMedia TypeRessource
selfGET, PUT, DELETEapplication/hal+jsonDataset

 Verwenden von vordefinierten Wertemengen

Einige Wertemengen existieren bereits im Repository, auch ohne dass du diese angelegt hast. Diese Wertemengen können dynamische Werte enthalten und setzen sich aus dem Datenbestand im Repository zusammen. Diese Wertemengen kannst du mit den folgenden IDs einer Eigenschaft zuweisen. Diese Art von Wertemengen kannst du nicht verändern. Das heißt, du kannst ihr keine Werte hinzufügen oder ihren Namen und Datentypen ändern. Alle diese Wertemengen sind mit der Eigenschaft readOnly=true gekennzeichnet.

IDDatentypBedeutung
USERSSTRINGEnthält alle Benutzer im Repository.
GROUPSSTRINGEnthält alle Gruppen im Repository.
USERS_AND_GROUPSSTRINGEnthält alle Benutzer und Gruppen im Repository.
EXISTING_VALUESSTRINGEnthält alle Werte, die für die verknüpfte Eigenschaft eingegeben wurden.

 Ändern einer Wertemenge

Wenn du Änderungen an einer bestehenden Wertemenge vornehmen möchtest, kannst du die Methode PUT auf die URI der Dataset-Ressource anwenden.

Request


PUT <URI to dataset resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": "Supplier names",
  "dataType": "STRING",
  "values": [
    {
      "x-original": "SUPPLIER_1",
      "en": "Supplier 1"
    },
    {
      "x-original": "SUPPLIER_2",
      "en": "Supplier 2"
    },
    {
      "x-original": "SUPPLIER_3",
      "en": "Supplier 3"
    }
  ]
}

Response


location: <URI of the changed dataset resource>

Statuscode

  • 200: Die Wertemenge wurde erfolgreich geändert.
  • 400: Es wurden ungültige Daten übergeben.
  • 404: Die Wertemenge mit der angegebenen ID konnte nicht ermittelt werden.

 Löschen einer Wertemenge

Eine nicht mehr benötigte Wertemenge kannst du wieder aus dem Repository löschen, indem du die Methode DELETE auf die URI der Dataset-Ressource anwendest. Eine Wertemenge kann nur gelöscht werden, wenn sie keiner Eigenschaft mehr zugeordnet ist und wenn sie nicht vom System vordefiniert wurde (readOnly=true).

Request


DELETE <URI to dataset resource>
Origin: <Base-URI of the tenant>

Statuscode

  • 204: Die Wertemenge wurde erfolgreich gelöscht.
  • 400: Die Wertemenge ist noch mindestens einer Eigenschaft zugeordnet oder wurde vom System vordefiniert.
  • 404: Die Wertemenge mit der angegebenen ID konnte nicht ermittelt werden.

 Permissions

Repräsentiert eine Liste von Permission-Ressourcen.

 Abrufen einer Liste aller Berechtigungen

Verwende eine HTTP GET-Anforderung zum Abrufen einer Liste über alle Berechtigungen.

Request


GET <URI to permissions resource>
Accept: application/hal+json

In der Antwort erhältst du innerhalb des Objekts _embedded ein Array von Berechtigungen.

Response


{
  "_links": { ... },
  "_embedded": {
    "permissions": [ ... ]
   }
}

Statuscode

  • 200: Die Berechtigungen wurden erfolgreich ermittelt.

 Aufbau einer "Permissions"-Ressource

Die Permissions-Ressource enthält immer folgende Elemente.

 Embedded (Eingebettete Ressourcen)
RelationTypRessource
permissionspermission[]Permission

 Erstellen einer Berechtigung

Erstelle eine Berechtigung mit der Methode POST.

Übergib beim Ausführen der POST-Methode als Request-Body eine Permission-Ressource.

Request


POST <URI to permissions resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": "All bills",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    },
    {
      "key": "9",
      "value": "|-1000"
    }
  ],
  "assignments": [
    {
      "subject": "89e6cbd9-af7f-46c8-9c86-2c12602476fe",
      "read": "INHERITED",
      "write": "DENIED",
      "delete": "DENIED"
    }
  ]
}

Beim Erstellen einer Berechtigung kannst du keine ID angeben. Diese wird vom System automatisch generiert. Nachdem die Berechtigung erfolgreich erstellt wurde, kannst du die URI der neuen Berechtigung dem Header Location entnehmen.

Response


location: <URI of the created permission resource>

Statuscode

  • 201: Die Berechtigung wurde erfolgreich erstellt.
  • 400: Es wurden ungültige Daten übergeben oder eine Berechtigung mit dem Namen existiert bereits.

 Permission

Repräsentiert eine Berechtigung innerhalb eines d.3-Repositorys. Innerhalb eines d.3-Repositorys kannst du für deine angelegten Kategorien verschiedene Berechtigungen vergeben. Damit kannst du die Sichtbarkeit und Zugriffsmöglichkeiten verschiedener Benutzergruppen einschränken. Die Konfiguration von Berechtigungen erfolgt immer auf Basis eines Repositorys.

Nachfolgend erfährst du, wie du eine Berechtigung konfigurieren kannst.

 Anzeigen der Konfiguration einer Berechtigung

Wenn du dir die Konfiguration einer bestehenden Berechtigung anzeigen lassen möchtest, kannst du die Methode GET auf die URI der Permission-Ressource anwenden.

Request


GET <URI to permission resource>
Accept: application/hal+json

In der Antwort (Response) der HTTP GET-Anforderung erhältst du schließlich die Detailinformationen zur angegebenen Berechtigung:

Response


{
  "id": "1",
  "name": "All bills",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    },
    {
      "key": "9",
      "value": "|-1000"
    },
    ...
  ],
  "assignments": [
    {
      "subject": "89e6cbd9-af7f-46c8-9c86-2c12602476fe",
      "read": "INHERITED",
      "write": "DENIED",
      "delete": "DENIED"
    },
    ...
  ],
  "_links": { ... }
}

Statuscode

  • 200: Die Berechtigung wurde erfolgreich ermittelt.
  • 404: Es konnte keine Berechtigung mit der angegebenen ID ermittelt werden.

 Aufbau einer "Permission"-Ressource

Die Permission-Ressource enthält immer folgende Elemente.

EigenschaftTypBedeutungErforderlich
idstringDie eindeutige ID der Berechtigung.ja
namestringName, nur für den Administrator zur Unterscheidung relevant.ja
restrictionsrestriction[]Die Filter, die festlegen, für welche Dokumente und Akten diese Berechtigung gilt. Es muss mindestens ein Objekt restriction mit dem Key category geben.ja
assignmentsassignment[]Die Gruppen, die Berechtigungen erhalten.nein
 Restriction

Das Restriction-Objekt beschreibt einen Filter, der festlegt, für welche Dokumente und Akten diese Berechtigung gilt.

EigenschaftTypBedeutungErforderlich
keystringEntweder CATEGORY, um auf eine Kategorie zu filtern (darf maximal einmal vorkommen), oder die ID einer Objekteigenschaft.ja
valuestringBei einer Kategorie die ID der Kategorie, sonst ein Filtertext.

Operatoren:
  • Bereich: |-
  • Platzhalter für eine unbekannte Anzahl von Zeichen: *
  • Platzhalter für genau ein unbekanntes Zeichen: ?
  • Platzhalter für die ID des angemeldeten Benutzers: @CURRENT_USER
  • Platzhalter für die ID einer Gruppe, in welcher der angemeldete Benutzer Mitglied ist: @CURRENT_USER_IN_GROUP
ja
 Assignment

Ein Assignment-Objekt beschreibt eine Gruppe, die Berechtigungen erhält, mit den dazugehörigen Rechten.

EigenschaftTypBedeutungErforderlich
subjectstringDie ID einer Gruppe aus der identity provider-Appja
readstringBerechtigt die Gruppenmitglieder, Objekte zu lesen.

Standardwert: INHERITED
nein
writestringBerechtigt die Gruppenmitglieder, Objekte zu bearbeiten oder anzulegen.

Standardwert: INHERITED
nein
deletestringBerechtigt die Gruppenmitglieder, Objekte zu löschen.

Standardwert: INHERITED
nein

Hinweise zu den Eigenschaften "read", "write" und "delete"

Die drei Eigenschaften können jeweils einen dieser Werte annehmen:

RechtBedeutung
ALLOWEDRecht wird explizit erlaubt.
INHERITEDRecht wird nicht erteilt. Wenn für ein Objekt mehrere Berechtigungen für die Gruppe zutreffen, gelten die anderen. Ansonsten wie DENIED
DENIEDRecht wird explizit verweigert. Wenn für ein Objekt mehrere Berechtigungen für die Gruppe zutreffen, gilt immer DENIED.

Wenn die Eigenschaft read den Wert DENIED enthält, müssen die Eigenschaften write und delete auch den Wert DENIED enthalten. Enthalten die Eigenschaften write oder delete den Wert ALLOWED, muss die Eigenschaft read zwingend auch den Wert ALLOWED enthalten.

 Links
RelationOperationenMedia TypeRessource
selfGET, PUT, DELETEapplication/hal+jsonPermission

 Ändern einer Berechtigung

Wenn du Änderungen an einer bestehenden Berechtigung vornehmen möchtest, kannst du die Methode PUT auf die URI der Permission-Ressource anwenden.

Request


PUT <URI to permission resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": "All bills",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    },
    {
      "key": "9",
      "value": "|-1000"
    }
  ],
  "assignments": [
    {
      "subject": "89e6cbd9-af7f-46c8-9c86-2c12602476fe",
      "read": "INHERITED",
      "write": "DENIED",
      "delete": "DENIED"
    }
  ]
}

Response


location: <URI of the changed permission resource>

Statuscode

  • 200: Die Berechtigung wurde erfolgreich aktualisiert.
  • 400: Es wurden ungültige Daten übergeben oder eine andere Berechtigung mit dem Namen existiert bereits.

 Löschen einer Berechtigung

Eine nicht mehr benötigte Berechtigung kannst du wieder aus dem Repository löschen, indem du die Methode DELETE auf die URI der Permission-Ressource anwendest.

Request


DELETE <URI to permission resource>
Origin: <Base-URI of the tenant>

Statuscode

  • 204: Die Berechtigung wurde erfolgreich gelöscht.
  • 404: Eine Berechtigung mit der angegebenen ID konnte nicht ermittelt werden.

 Structures

Repräsentiert eine Liste von Structurerule-Ressourcen.

 Abrufen einer Liste aller Strukturregeln

Verwende eine HTTP GET-Anforderung zum Abrufen einer Liste über alle Strukturregeln.

Request


GET <URI to structures resource>
Accept: application/hal+json

In der Antwort erhälst du innerhalb des Objekts _embedded ein Array von einzelnen Strukturregeln.

Response


{
  "_links": { ... },
  "_embedded": {
    "structures": [ ... ]
  }
}

Statuscode

  • 200: Die Strukturregeln wurden erfolgreich ermittelt.

 Aufbau einer "Structures"-Ressource

Die Structures-Ressource enthält immer folgende Elemente.

 Embedded (Eingebettete Ressourcen)
RelationTypRessource
structuresstructurerule[]Structurerule

 Erstellen einer Strukturregel

Erstelle eine Strukturregel mit der Methode POST.

Eine Strukturregel kannst du mit der nachfolgenden Funktion erstellen. Übergib beim Ausführen der POST-Methode als Request-Body eine Structurerule-Ressource.

Request


POST <URI to structures resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "parent": "CUST",
  "child": "BILL",
  "createSiblingDossiers": true,
  "recognition": [
    {
      "propertyId": "1"
    }
  ],
  "inheritance": [
    {
      "propertyId": "2"
    }
  ]
}

Beim Erstellen einer Strukturregel kannst du keine ID angeben. Diese wird vom System automatisch generiert. Nachdem die Strukturregel erfolgreich erstellt wurde, kannst du die URI der neuen Strukturregel dem Header Location entnehmen.

Response


location: <URI of the created structurerule resource>

Statuscode

  • 201: Die Strukturregel wurde erfolgreich erstellt.
  • 400: Es wurden ungültige Daten übergeben oder eine Strukturregel mit dem angegebenen parent und child existiert bereits.

 Structurerule

Repräsentiert eine Strukturregel innerhalb eines d.3-Repositorys. Innerhalb eines d.3-Repositorys kannst du deinen Anwendern mithilfe von Strukturregeln einen bereits konfigurierten Aktenaufbau bereitstellen. Mithilfe der Strukturregeln werden Elemente, die deine Anwender speichern, automatisch in Akten verknüpft. Du kannst festlegen, anhand welcher Eigenschaften die übergeordnete Akte erkannt werden soll. Außerdem kannst du Eigenschaften definieren, die von der Akte automatisch für das untergeordnete Dokument übernommen werden. Durch die Konfiguration von Strukturen kannst du festlegen, welche Kategorien, unter welchen Voraussetzungen, miteinander verknüpft werden.

Nachfolgend erfährst du, wie du eine Strukturregel konfigurieren kannst.

 Anzeigen der Konfiguration einer Strukturregel

Wenn du dir die Konfiguration einer bestehenden Strukturregel anzeigen lassen möchtest, kannst du die Methode GET auf der URI der Structurerule-Ressource anwenden.

Request


GET <URI to structurerule resource>
Accept: application/hal+json

In der Antwort (Response) der HTTP GET-Anforderung erhältst du schließlich die Detailinformationen zu der angegebenen Strukturregel:

Response


{
  "id": "1",
  "parent": "CUST",
  "child": "BILL",
  "createSiblingDossiers": true,
  "recognition": [
    {
      "propertyId": "1"
    }
  ],
  "inheritance": [
    {
      "propertyId": "2"
    }
  ],
  "_links": { ... }
}

Status Code

  • 200: Die Strukturregel wurde erfolgreich ermittelt.
  • 404: Es konnte keine Strukturregel mit der angegebenen ID ermittelt werden.

 Aufbau einer "Structurerule"-Ressource

Die Structurerule-Ressource enthält immer folgende Elemente.

EigenschaftTypBedeutungErforderlich
idstringDie eindeutige ID der Strukturregel.ja
parentstringDie übergeordnete Kategorie, mit der ein Dokument oder eine Akte verknüpft werden soll. Diese Kategorie muss zwingend vom Typ Akte sein.ja
childstringDie untergeordnete Kategorie, dessen Elemente unter parent verknüpft werden sollen. Es dürfen keine Zirkelreferenzen definiert werden.ja
createSiblingDossiersbooleanAlle untergeordneten Akten, die dieselbe parent-Akte besitzen, werden bei Erstellung der ausgewählten child-Akte ebenfalls automatisch erstellt.nein
recognitionRecognition[]Eine Liste von Identifizierungseigenschaften. Wenn diese Eigenschaften in einer parent-Akte und einem child-Element gleich sind, werden diese miteinander verknüpft. An dieser Stelle können keine Eigenschaften mit mehreren Werten definiert werden.ja
inheritanceInheritance[]Eine Liste von Eigenschaften, deren Werte aus der parent-Akte in das child-Element übernommen werden. Sofern eine Eigenschaft im child-Element bereits einen Wert für die Eigenschaft besitzt, wird dieser nicht aus der Akte übernommen.nein
 Recognition

Ein Recognition-Objekt beschreibt eine Eigenschaft, mit der die Verknüpfung zwischen parent und child vorgenommen wird. Diese Eigenschaft muss sowohl in der parent- als auch in der child-Kategorie vorhanden sein. Ist der Wert dieser Eigenschaft in beiden Objekten identisch, wird eine entsprechende Struktur im System angelegt.

EigenschaftTypBedeutungErforderlich
propertyIdstringDie ID einer Eigenschaft. Diese Eigenschaft muss sowohl in der parent-Kategorie als auch in der child-Kategorie definiert sein.ja
 Inheritance

Ein Inheritance-Objekt beschreibt eine Eigenschaft, die während einer Verknüpfung vererbt wird. Erfolgt eine Verknüpfung anhand einer Recognition-Eigenschaft, werden die Werte der unter Inheritance festgelegten Eigenschaften vom parent-Objekt, an das child-Objekt vererbt.

EigenschaftTypBedeutungErforderlich
propertyIdstringDie ID einer Eigenschaft. Diese Eigenschaft muss sowohl in der parent-Kategorie als auch in der child-Kategorie definiert sein. Diese Eigenschaft darf außerdem noch nicht unter recognition definiert worden sein.ja
typestringGibt die Art der Vererbung an.
  • Eigenschaften der parent-Kategorie werden in neu erstellte Elemente der child-Kategorie übernommen: FROM_CHILD_TO_PARENT
  • Beim automatischen Erstellen einer Akte der parent-Kategorie werden die Eigenschaften des Elements der child-Kategorie übernommen: FROM_PARENT_TO_CHILD
ja
 Links
RelationOperationenMedia TypeRessource
selfGET, PUT, DELETEapplication/hal+jsonStructurerule

 Ändern einer Strukturregel

Wenn du Änderungen an einer bestehenden Strukturregel vornehmen möchtest, kannst du die Methode PUT auf die URI der Structurerule-Ressource anwenden.

Request


PUT <URI to structurerule resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "parent": "CUST",
  "child": "BILL",
  "createSiblingDossiers": true,
  "recognition": [
    {
      "propertyId": "1"
    }
  ],
  "inheritance": [
    {
      "propertyId": "2"
    }
  ]
}

Response


location: <URI of the changed structurerule resource>

Statuscode

  • 201: Die Strukturregel wurde erfolgreich aktualisiert.
  • 400: Es wurden ungültige Daten übergeben.

 Löschen einer Strukturregel

Eine nicht mehr benötigte Strukturregel kannst du wieder aus dem Repository löschen, indem du die Methode DELETE auf der URI der Structurerule-Ressource anwendest.

Request


DELETE <URI to structurerule resource>
Origin: <Base-URI of the tenant>

Statuscode

  • 204: Die Strukturregel wurde erfolgreich gelöscht.
  • 404: Eine Strukturregel mit der angegebenen ID konnte nicht ermittelt werden.

 Events

Repräsentiert eine Liste von Event-Ressourcen.

 Abrufen einer Liste aller Ereignisse

Verwende eine HTTP GET-Anforderung zum Abrufen einer Liste aller Ereignisse.

Request


GET <URI to events resource>
Accept: application/hal+json

In der Antwort erhältst du innerhalb des Objekts _links eine Liste aller verfügbaren Events und innerhalb des Objekts _embedded die einzelnen Ereignisse.

Response


{
  "_links": {
    "presearch": { ... },
    "postsearch": { ... },
  },
  "_embedded": {
    "presearch": { ... },
    "postsearch": { ... },
    ...
  }
}

Statuscode

  • 200: Die Ereignisse wurden erfolgreich ermittelt.

 Aufbau einer "Events"-Ressource

Die Events-Ressource enthält immer folgende Elemente.

 Embedded (Eingebettete Ressourcen)
RelationTypRessource
eventsevent[]Event

 Event

Repräsentiert ein Ereignis des d.3-Repositorys. Ereignisse werden während bestimmter Prozesse durchlaufen. Alle angegebenen Webhooks in einem Ereignis werden dann in der angegebenen Reihenfolge angesteuert. Details zu den einzelnen Ereignissen, wie zum Beispiel Ausführungszeitpunkte, findest du in der Webhook-Dokumentation.

 Anzeigen der Konfiguration eines Ereignisses

Wenn du die Konfiguration eines Ereignisses anzeigen möchtest, kannst du die Methode GET auf der URI der Event-Ressource anwenden.

Request


GET <URI to event resource>
Accept: application/hal+json

In der Antwort (Response) der HTTP GET-Anforderung erhältst du schließlich die Detailinformationen zum angegebenen Ereignis:

Response


{
  "order": [
    "05F3AC34-EF06-43CE-81B6-11CA7E5E4C9E",
    "1D7341B4-547C-4FFD-A309-68B871959CD8",
    "E5FE04F2-6432-469F-9191-8C1DCCEE3752"
  ],
  "_links": { ... },
  "_embedded": {
    "webhooks": [ ... ]
  }
}

Statuscode

  • 200: Das Ereignis wurde erfolgreich ermittelt.
  • 404: Das angegebene Ereignis existiert nicht.

 Aufbau einer "Event"-Ressource

Die Event-Ressource enthält immer folgende Elemente.

EigenschaftTypBedeutung
orderstring[]Enthält die IDs der zugeordneten Webhooks. Definiert die Reihenfolge, in der die Webhooks ausgeführt werden.
 Links
RelationOperationenMedia TypeRessource
selfGET, PUT, POSTapplication/hal+jsonEvent
 Embedded (Eingebettete Ressourcen)
RelationTypRessource
webhookswebhook[]Webhook

 Erstellen eines Webhooks

Wenn du einen neuen Webhook für ein Ereignis einrichten möchtest, kannst du die Methode POST verwenden. Übergib beim Ausführen der POST-Methode als Request-Body eine Webhook-Ressource.

Request


POST <URI to event resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "uri": "https://my-company.com/webhooks",
  "description": "This is a description of my webhook.",
  "enabled": true,
  "handleResponse": "STATUS_AND_BODY",
  "timeout": 300,
  "apiKey": "key",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    }
  ]
}

Beim Erstellen eines Webhooks kannst du keine ID angeben. Die ID wird vom System automatisch generiert. Nachdem ein Webhook erstellt wurde, kannst du die URI des neuen Webhooks dem Header Location entnehmen.

Response


location: <URI of the created webhook resource>

Statuscode

  • 201: Der Webhook wurde erfolgreich erstellt.
  • 400: Es wurden ungültige Daten übergeben.

 Ändern der Aufrufreihenfolge innerhalb eines Ereignisses

Wenn du Änderungen an einem Ereignis vornehmen möchtest, kannst du die Methode PUT auf die URI der Event-Ressource anwenden. Du kannst allerdings nur die Reihenfolge der Webhooks verändern. Für Änderungen an einem Webhook musst du die Webhook-Ressource verwenden.

Request


PUT <URI to event resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "order": [
    "E5FE04F2-6432-469F-9191-8C1DCCEE3752",
    "05F3AC34-EF06-43CE-81B6-11CA7E5E4C9E",
    "1D7341B4-547C-4FFD-A309-68B871959CD8"
  ]
}

Statuscode

  • 201: Das Ereignis wurde erfolgreich aktualisiert.
  • 400: Es wurden ungültige Daten übergeben.

 Webhook

Repräsentiert eine benutzerdefinierte Funktion, die zu einem Ereignis innerhalb eines d.3-Repositorys definiert wird. Mithilfe eines Webhooks wird mittels URI eine Funktion definiert, die das DMS-Standardverhalten beeinflussen oder weitere anschließende Aktionen auslösen kann.

Nachfolgend erfährst du, wie du einen Webhook konfigurieren kannst.

 Anzeigen der Konfiguration eines Webhooks

Wenn du die Konfiguration eines bestehenden Webhooks anzeigen möchtest, kannst du die Methode GET auf die URI der Webhook-Ressource anwenden.

Request


GET <URI to webhook resource>
Accept: application/hal+json

In der Antwort (Response) der HTTP GET-Anforderung erhältst du Detailinformationen des angegebenen Webhooks:

Response


{
  "id": "05F3AC34-EF06-43CE-81B6-11CA7E5E4C9E",
  "uri": "https://my-company.com/webhooks",
  "description": "Webhook for the validation of invoices.",
  "enabled": true,
  "handleResponse": "STATUS_AND_BODY",
  "timeout": 300,
  "apiKey": "key",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    }
  ]
  "_links": { ... }
}

Statuscode

  • 200: Der Webhook wurde erfolgreich ermittelt.
  • 404: Es konnte kein Webhook mit der angegebenen ID ermittelt werden.

 Aufbau einer "Webhook"-Ressource

Die Webhook-Ressource enthält immer folgende Elemente.

EigenschaftTypBedeutungErforderlich
idstringDie eindeutige ID des Webhooks.ja
uristringURI die beim Ausführen des Webhooks angesteuert werden soll. Muss eine gültige HTTP(S)-URI sein. Relative URIs beginnen mit einem Slash.ja
descriptionstringEine frei wählbare Beschreibung des Webhooks. Dient lediglich zur Übersicht und Beschreibung.ja
enabledbooleanGibt an, ob ein Webhook ausgeführt werden soll. Webhooks, die nicht ausgeführt werden, bleiben im System gespeichert.

Standardwert: false
nein
handleResponsestringGibt an, wie die vom Webhook zurückgegebene HTTP-Response verarbeitet wird.
  • Anwort wird nicht verarbeitet: NONE
  • Nur der Statuscode der HTTP-Response wird ausgewertet: STATUS
  • Der Statuscode und der Responsebody werden ausgewertet: STATUS_AND_BODY
ja
timeoutnumberZeit in Millisekunden, nach der von einem Timeout ausgegangen wird.

Standardwert: 300
nein
retrybooleanGibt an, ob ein Webhook bei einem Timeout oder einer fehlerhaften Antwort bis zu drei Mal erneut ausgeführt werden soll.

Standardwert: true
nein
apiKeystringAuthentifizierungsschlüssel, der dem Webhook übermittelt werden kann.nein
restrictionsrestriction[]Filter, mit denen du festlegen kannst, für welche Kategorien dieser Webhook ausgeführt werden soll. Wenn du keine Angabe machst, wird der Webhook für alle Kategorien ausgeführt.nein
 Restriction

Das Restriction-Objekt beschreibt einen Filter, der festlegt, für welche Dokumente und Akten dieser Webhook ausgeführt werden soll.

EigenschaftTypBedeutungErforderlich
keystringAls Key kann derzeit nur CATEGORY angegeben werden, um auf eine oder mehrere Kategorien zu filtern.ja
valuestringDie ID der Kategorie.ja
 Links
RelationOperationenMedia TypeRessource
selfGET, PUT, DELETEapplication/hal+jsonWebhook

 Ändern eines Webhooks

Wenn du Änderungen an einem bestehenden Webhook vornehmen möchtest, kannst du die Methode PUT auf die URI der Webhook-Ressource anwenden.

Request


PUT <URI to webhook resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "uri": "https://my-company.com/webhooks",
  "description": "Webhook for the validation of invoices.",
  "enabled": true,
  "handleResponse": "STATUS_AND_BODY",
  "timeout": 300,
  "apiKey": "key",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    }
  ]
}

Response


location: <URI of the changed webhook resource>

Statuscode

  • 201: Der Webhook wurde erfolgreich aktualisiert.
  • 400: Es wurden ungültige Daten übergeben.

 Löschen eines Webhooks

Einen nicht mehr benötigten Webhook kannst du wieder aus dem Repository löschen, indem du die Methode DELETE auf der URI der Webhook-Ressource anwendest.

Request


DELETE <URI to webhook resource>
Origin: <Base-URI of the tenant>

Statuscode

  • 204: Der Webhook wurde erfolgreich gelöscht.
  • 404: Ein Webhook mit der angegebenen ID konnte nicht ermittelt werden.

 Packages

Repräsentiert eine Liste von Package-Ressourcen.

 Abrufen einer Liste aller Pakete

Verwende eine HTTP GET-Anforderung zum Abrufen einer Liste über alle Pakete.

Request


GET <URI to packages resource>
Accept: application/hal+json

In der Antwort erhältst du innerhalb des Objekts _embedded ein Array von Paketen.

Response


{
  "_links": { ... },
  "_embedded": {
    "packages": [ ... ]
   }
}

Statuscode

  • 200: Die Pakete wurden erfolgreich ermittelt.

 Aufbau einer "Packages"-Ressource

Die Packages-Ressource enthält immer folgende Elemente.

 Links
RelationOperationenMedia TypeRessource
selfGETapplication/hal+jsonPackages
importGETapplication/octet-streambinary
 Embedded (Eingebettete Ressourcen)
RelationTypRessource
packagespackage[]Package

 Installieren eines Pakets

Wenn du ein Paket aus einer Paketdatei installieren möchtest, kannst du die Methode POST auf die URI in der Linkrelation import anwenden.

Request


POST <URI to import package resource>
Content-Type: application/octet-stream

<Package file stream>

Statuscode

  • 204: Das Paket wurde erfolgreich installiert.

 Package

Repräsentiert ein Paket innerhalb eines d.3-Repositorys. Mit Paketen kannst du dein d.3-Repository mit vordefinierten Repository-Konfigurationen erweitern. Diese Konfigurationen können von dir selbst erstellt oder aber auch für dich bereitgestellt worden sein. Ein Paket kann Metadaten (Kategorien, Eigenschaften, Wertemengen), Strukturen, Berechtigungen und Webhooks enthalten.

 Abrufen eines Pakets

Wenn du dir Informationen zu einem bestehenden Paket anzeigen lassen möchtest, kannst du die Methode GET auf die URI der Package-Ressource anwenden.

Request


GET <URI to category resource>
Accept: application/hal+json

In der Antwort (Response) der HTTP GET-Anforderung erhältst du schließlich die Detailinformationen zum angegebenen Paket:

Response


{
  "id": "3933ca77-ee0d-4594-bae7-8f9b3a2c190e",
  "name": "Package name",
  "description": "Package description",
  "readOnly": "false",
  "systemPackage": "false",
  "_links": { ... }
}

Statuscode

  • 200: Das Paket wurde erfolgreich ermittelt.
  • 404: Das Paket mit der angegebenen ID konnte nicht ermittelt werden.

 Aufbau einer "Package"-Ressource

Die Package-Ressource enthält immer folgende Elemente.

EigenschaftTypBedeutung
idstringDie eindeutige ID des Pakets.
namestringDer interne Name des Pakets.
descriptionstringDie Beschreibung des Pakets.
readOnlybooleanGibt an, ob das Paket selbst erstellt oder installiert wurde.
systemPackagebooleanGibt an, ob das Paket ein von d.velop erstelltes Systempaket ist. Dieser Status kann nicht verändert werden.
 Links
RelationOperationenMedia TypeRessource
selfGETapplication/hal+jsonPackage
exportGETapplication/hal+json-

 Exportieren eines Pakets

Wenn du ein Paket in eine Paketdatei exportieren möchtest, kannst du die Methode GET auf die URI in der Linkrelation export eine Pakets anwenden. Anschließend kannst du die Paketdatei mit der URI aus dem Location-Header herunterladen. Du kannst immer nur die Pakete exportieren, die du selbst erstellt hast.

Angeben von Queryparametern

Beim Aufrufen der Ressource musst du in deiner HTTP-Anforderung Queryparameter angeben. Du kannst folgende Queryparameter übermitteln.

ParameterTypBedeutungErforderlich
versionstringDie Version des zu exportieren Pakets. Du kannst die Version frei vergeben.ja

Request


GET <URI to export package resource>?<Query parameter>
Content-Type: application/hal+json

Response


location: <URI of the package file>

Statuscode

  • 201: Die Paketdatei wurde erfolgreich erstellt.
  • 403: Das Paket kann nicht exportiert werden, da es sich um ein bereits installiertes Paket handelt.
  • 404: Das Paket mit der angegebenen ID konnte nicht ermittelt werden.