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:
Sprache | ID der Sprache (ISO 639-1 und RFC-3066) | Besonderheit |
---|---|---|
Deutsch | de | |
Englisch | en | |
Kroatisch | hr | |
Tschechisch | cs | |
Dänisch | da | |
Niederländisch | nl | |
Französisch | fr | |
Italienisch | it | |
Polnisch | pl | |
Serbisch | sr | |
Spanisch | es | |
Slowakisch | sk | |
Chinesisch | zh-CN | |
Sprachunabhängiger Standardwert | x-original | Nur 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)
Relation | Typ | Ressource |
---|---|---|
repositories | repository[] | 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.
Eigenschaft | Typ | Bedeutung |
---|---|---|
id | string | Die eindeutige ID des Repositorys. |
name | string | Der Anzeigename der Repositorys. |
Links
Relation | Operationen | Media Type | Ressource |
---|---|---|---|
self | GET | application/hal+json | Repository |
categories | GET, POST | application/hal+json | Categories |
properties | GET, POST | application/hal+json | Properties |
datasets | GET, POST | application/hal+json | Datasets |
permissions | GET, POST | application/hal+json | Permissions |
structures | GET, POST | application/hal+json | Structures |
events | GET | application/hal+json | Events |
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)
Relation | Typ | Ressource |
---|---|---|
categories | category[] | 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
id | string | Die eindeutige ID der Kategorie. | ja |
name | dictionary<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 |
type | string | Der Typ der Kategorie.
| ja |
readOnly | boolean | Eine rein lesende Eigenschaft, die angibt, ob eine Kategorie vom System vorgegeben wurde und unveränderbar ist. | nur lesend |
retention | retention | Die Einstellungen zur Aufbewahrung von Dokumenten dieses Typs. | nein |
propertyRefs | propertyRef[] | 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 |
titleRefs | titleRef[] | Der Titel eines Dokuments dieser Kategorie. Er setzt sich aus einem Array von Objekten zusammen. | nein |
protection | protection | Die 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
propertyId | string | Die eindeutige ID einer Eigenschaft. | ja |
required | boolean | Kennzeichnet die Eigenschaft innerhalb der Kategorie als verpflichtend. Standardwert: false | nein |
showInFacets | boolean | Diese Eigenschaft wird bei der Suche nach dieser Kategorie als Facette angeboten. Standardwert: false | nein |
showInSearch | boolean | Diese Eigenschaft wird bei der Suche nach dieser Kategorie angeboten. Standardwert: false | nein |
showInImport | boolean | Diese Eigenschaft wird bei der Ablage dieser Kategorie angeboten. Standardwert: false | nein |
showInResult | boolean | Diese 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
propertyId | string | Die eindeutige ID einer Eigenschaft. | ja |
delimiter | string | Trennzeichen, 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
period | number | Die Aufbewahrungsdauer von Dokumenten dieses Typs. Standardwert: 0 (0 entspricht ewig) | nein |
unit | string | Die Einheit in der die Aufbewahrungsdauer angegeben ist.
Standardwert: YEARS | nein |
Protection
Ein Protection-Objekt steuert den erweiterten Schutz von Elementen dieses Typs.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
preventDeletion | boolean | Verhindert 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 |
preventDeletionChangeReason | string | Grund zur Änderung der Eigenschaft preventDeletion. | nein, nur wenn du den Wert für preventDeletion von true auf false änderst. |
Links
Relation | Operationen | Media Type | Ressource |
---|---|---|---|
self | GET, PUT, DELETE | application/hal+json | Category |
properties | GET, POST | application/hal+json | Properties |
Embedded (Eingebettete Ressourcen)
Relation | Typ | Ressource |
---|---|---|
properties | properties | Properties |
Ä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)
Relation | Typ | Ressource |
---|---|---|
properties | property[] | 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
id | string | Die eindeutige ID der Eigenschaft. | ja |
name | dictionary<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 |
dataType | string | Der Datentyp der Eigenschaft.
| ja |
isSystemProperty | boolean | Zeigt an, ob es sich um eine vom System erstellte Eigenschaft handelt. | nur lesend |
readOnly | boolean | Eine rein lesende Eigenschaft, die angibt, ob eine Eigenschaft vom System vorgegeben wurde und unveränderbar ist. | nur lesend |
isMultiValue | boolean | Zeigt an, ob es sich um eine Eigenschaft mit einem oder mehreren Werten handelt. Standardwert: false | ja |
validationRegEx | string | Regulärer Ausdruck zur Validierung der Eingaben (POSIX Basic Regular Expression Syntax). Gültige Datentypen: STRING | nein |
dataSetId | string | Die ID einer verknüpften Wertemenge. Gültige Datentypen: STRING, NUMERIC, CURRENCY, DATE | nein |
minValue | number | Der kleinste Wert, den diese Eigenschaft annehmen kann. Gültige Datentypen: NUMERIC, CURRENCY | nein |
maxValue | number | Der größte Wert, den diese Eigenschaft annehmen kann. Gültige Datentypen: NUMERIC, CURRENCY | nein |
Links
Relation | Operationen | Media Type | Ressource |
---|---|---|---|
self | GET, PUT, DELETE | application/hal+json | Property |
dataset | GET, PUT, DELETE | application/hal+json | Dataset |
Embedded (Eingebettete Ressourcen)
Relation | Typ | Ressource |
---|---|---|
dataset | dataset | Dataset |
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.
ID | Name | Bedeutung |
---|---|---|
DOCUMENT_ID | Dokument ID | Die eindeutige ID des Dokumentes. |
CATEGORY | Kategoriename | Der Name der Kategorie. |
FILE_EXTENSION | Dateityp | Der Dateityp des Dokumentes. |
FILE_NAME | Dateiname | Der Dateiname des Dokumentes. |
STATUS | Status | Der aktuelle Status des Dokumentes. |
EDITOR | Bearbeiter | Der aktuelle Bearbeiter des Dokumentes. |
OWNER | Besitzer | Der 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)
Relation | Typ | Ressource |
---|---|---|
datasets | dataset[] | 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
id | string | Die eindeutige ID der Wertemenge. | ja |
name | string | Der interne Name der Wertemenge. | ja |
dataType | string | Der Datentyp der Wertemenge.
| ja |
readOnly | boolean | Eine rein lesende Eigenschaft, die angibt, ob eine Wertemenge vom System vorgegeben wurde und unveränderbar ist. | nur lesend |
values | value[] | 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:
Datentyp | Typ | Bedeutung | Beispiel |
---|---|---|---|
STRING | dictionary<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, NUMERIC | number[] | Wird als Array von Numbers angegeben (Ein Punkt entspricht dem Tausendertrennzeichen). | "values": [10.3, -4.99] |
DATE | string[] | Wird als Array von Strings angegeben (ISO 8601). | "values": ["2004-07-11"] |
URI | string[] | 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
Relation | Operationen | Media Type | Ressource |
---|---|---|---|
self | GET, PUT, DELETE | application/hal+json | Dataset |
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.
ID | Datentyp | Bedeutung |
---|---|---|
USERS | STRING | Enthält alle Benutzer im Repository. |
GROUPS | STRING | Enthält alle Gruppen im Repository. |
USERS_AND_GROUPS | STRING | Enthält alle Benutzer und Gruppen im Repository. |
EXISTING_VALUES | STRING | Enthä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)
Relation | Typ | Ressource |
---|---|---|
permissions | permission[] | 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
id | string | Die eindeutige ID der Berechtigung. | ja |
name | string | Name, nur für den Administrator zur Unterscheidung relevant. | ja |
restrictions | restriction[] | 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 |
assignments | assignment[] | Die Gruppen, die Berechtigungen erhalten. | nein |
Restriction
Das Restriction-Objekt beschreibt einen Filter, der festlegt, für welche Dokumente und Akten diese Berechtigung gilt.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
key | string | Entweder CATEGORY, um auf eine Kategorie zu filtern (darf maximal einmal vorkommen), oder die ID einer Objekteigenschaft. | ja |
value | string | Bei einer Kategorie die ID der Kategorie, sonst ein Filtertext. Operatoren:
| ja |
Assignment
Ein Assignment-Objekt beschreibt eine Gruppe, die Berechtigungen erhält, mit den dazugehörigen Rechten.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
subject | string | Die ID einer Gruppe aus der identity provider-App | ja |
read | string | Berechtigt die Gruppenmitglieder, Objekte zu lesen. Standardwert: INHERITED | nein |
write | string | Berechtigt die Gruppenmitglieder, Objekte zu bearbeiten oder anzulegen. Standardwert: INHERITED | nein |
delete | string | Berechtigt 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:
Recht | Bedeutung |
---|---|
ALLOWED | Recht wird explizit erlaubt. |
INHERITED | Recht wird nicht erteilt. Wenn für ein Objekt mehrere Berechtigungen für die Gruppe zutreffen, gelten die anderen. Ansonsten wie DENIED |
DENIED | Recht 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
Relation | Operationen | Media Type | Ressource |
---|---|---|---|
self | GET, PUT, DELETE | application/hal+json | Permission |
Ä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)
Relation | Typ | Ressource |
---|---|---|
structures | structurerule[] | 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
id | string | Die eindeutige ID der Strukturregel. | ja |
parent | string | Die übergeordnete Kategorie, mit der ein Dokument oder eine Akte verknüpft werden soll. Diese Kategorie muss zwingend vom Typ Akte sein. | ja |
child | string | Die untergeordnete Kategorie, dessen Elemente unter parent verknüpft werden sollen. Es dürfen keine Zirkelreferenzen definiert werden. | ja |
createSiblingDossiers | boolean | Alle untergeordneten Akten, die dieselbe parent-Akte besitzen, werden bei Erstellung der ausgewählten child-Akte ebenfalls automatisch erstellt. | nein |
recognition | Recognition[] | 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 |
inheritance | Inheritance[] | 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
propertyId | string | Die 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
propertyId | string | Die 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 |
type | string | Gibt die Art der Vererbung an.
| ja |
Links
Relation | Operationen | Media Type | Ressource |
---|---|---|---|
self | GET, PUT, DELETE | application/hal+json | Structurerule |
Ä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)
Relation | Typ | Ressource |
---|---|---|
events | event[] | 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.
Eigenschaft | Typ | Bedeutung |
---|---|---|
order | string[] | Enthält die IDs der zugeordneten Webhooks. Definiert die Reihenfolge, in der die Webhooks ausgeführt werden. |
Links
Relation | Operationen | Media Type | Ressource |
---|---|---|---|
self | GET, PUT, POST | application/hal+json | Event |
Embedded (Eingebettete Ressourcen)
Relation | Typ | Ressource |
---|---|---|
webhooks | webhook[] | 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
id | string | Die eindeutige ID des Webhooks. | ja |
uri | string | URI die beim Ausführen des Webhooks angesteuert werden soll. Muss eine gültige HTTP(S)-URI sein. Relative URIs beginnen mit einem Slash. | ja |
description | string | Eine frei wählbare Beschreibung des Webhooks. Dient lediglich zur Übersicht und Beschreibung. | ja |
enabled | boolean | Gibt an, ob ein Webhook ausgeführt werden soll. Webhooks, die nicht ausgeführt werden, bleiben im System gespeichert. Standardwert: false | nein |
handleResponse | string | Gibt an, wie die vom Webhook zurückgegebene HTTP-Response verarbeitet wird.
| ja |
timeout | number | Zeit in Millisekunden, nach der von einem Timeout ausgegangen wird. Standardwert: 300 | nein |
retry | boolean | Gibt an, ob ein Webhook bei einem Timeout oder einer fehlerhaften Antwort bis zu drei Mal erneut ausgeführt werden soll. Standardwert: true | nein |
apiKey | string | Authentifizierungsschlüssel, der dem Webhook übermittelt werden kann. | nein |
restrictions | restriction[] | 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.
Eigenschaft | Typ | Bedeutung | Erforderlich |
---|---|---|---|
key | string | Als Key kann derzeit nur CATEGORY angegeben werden, um auf eine oder mehrere Kategorien zu filtern. | ja |
value | string | Die ID der Kategorie. | ja |
Links
Relation | Operationen | Media Type | Ressource |
---|---|---|---|
self | GET, PUT, DELETE | application/hal+json | Webhook |
Ä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
Relation | Operationen | Media Type | Ressource |
---|---|---|---|
self | GET | application/hal+json | Packages |
import | GET | application/octet-stream | binary |
Embedded (Eingebettete Ressourcen)
Relation | Typ | Ressource |
---|---|---|
packages | package[] | 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.
Eigenschaft | Typ | Bedeutung |
---|---|---|
id | string | Die eindeutige ID des Pakets. |
name | string | Der interne Name des Pakets. |
description | string | Die Beschreibung des Pakets. |
readOnly | boolean | Gibt an, ob das Paket selbst erstellt oder installiert wurde. |
systemPackage | boolean | Gibt an, ob das Paket ein von d.velop erstelltes Systempaket ist. Dieser Status kann nicht verändert werden. |
Links
Relation | Operationen | Media Type | Ressource |
---|---|---|---|
self | GET | application/hal+json | Package |
export | GET | application/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.
Parameter | Typ | Bedeutung | Erforderlich |
---|---|---|---|
version | string | Die 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.