Über die DMSApp-API
Funktionsumfang von DMSApp
Voraussetzungen
Menü der Dokumentation
Anbinden von externen Systemen (DMSApp)
In diesem Kapitel erfahren Sie, wie Sie externe Systeme (Drittanbieteranwendungen) an die DMSApp anbinden können, um Zuordnungen (Mappings) in der DMSApp zu erstellen. Ein externes System stellt aus Sicht der DMSApp ein Quellsystem dar. Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern.
Definieren eines Quellsystems
Freigegeben: Erweiterungspunkt
Wenn Sie ein System haben, das Ausgangsdaten bereitstellt (z.B. eine E-Mail-Anwendung oder ein ERP-System), müssen Sie für das Erstellen einer Zuordnung (Mapping) die Elemente des Quellsystems für ein d.3-Repository vorbereiten. Ein Element eines Quellsystems wird Quelle genannt. Eine Quelle enthält Quelleigenschaften und Quellkategorien. Indem Sie eine Quelle definieren, geben Sie der DMSApp die Möglichkeit, die Bezeichner für die Metadaten der Quelle mit den Bezeichnern für die Metadaten des d.3-Repositorys zu verbinden.
Vorbereiten Ihrer App
Damit Quellsysteme von der DMSApp gefunden werden, muss Ihre App diese Schnittstelle bereitstellen. Die DMSApp nutzt zum Auffinden von Apps, die als Quellsysteme dienen, das Konzept einer HTTP GET-Anforderung für die Rootressource (systemBaseUri-Pfad mit dem App-Namen) der Apps. Es werden alle Apps abgefragt, die an d.ecs http gateway registriert sind. Stellen Sie sicher, dass der Administrator Ihre App nicht aktiv ausgeschlossen hat.
Bereitstellen der URL zu den Quellen
Die Rootressourcen der Apps werden zyklisch abgerufen (Request). Die Antwort (Response) einer App wird daraufhin geprüft, ob eine Linkrelation namens sources enthalten ist. Diese Linkrelation gilt als Signal, dass die App als Quellsystem mindestens eine Quelle für die DMSApp anbietet. Die DMSApp führt eine HTTP GET-Anforderung auf den angegeben Link aus und erwartet von der antwortenden App ein genormtes JSON-Objekt mit dem HTTP-Statuscode 200.
Request
GET https://host/myapp/ HTTP/1.1 Accept: application/hal+json
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
{
"_links" : {
"sources" : {
"href" : "/myapp/sources"
}
}
}Anmerkung
Die Abfrage der Rootressourcen erfolgt anonym (ohne Authentifizierung) und wird als asynchroner Hintergrundprozess innerhalb der DMSApp ausgeführt.
Bereitstellen der Quellen
Nachdem die URLs der Quellen (sources) ermittelt wurden, werden die Quellen der Apps mit HTTP GET von der DMSApp abgerufen.
Das Beispiel zeigt, wie Sie die HTTP-Antwort der Linkrelation sources gestalten, um Quellen der DMSApp bekannt zu machen.
Request
GET https://host/myapp/sources HTTP/1.1 Accept: application/hal+json
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
{
"sources" : [{
"id" : "/myapp/sources/mysource",
"displayName" : "My Source",
"categories": [{
"key": "mycategory1_ID",
"displayName": "My category 1"
},
{
"key": "mycategory2_ID",
"displayName": "My category 2"
}],
"properties" : [{
"key" : "myprop1_ID",
"displayName" : "My property 1"
},
{
"key" : "myprop2_ID",
"displayName" : "My property 2"
},
{
"key" : "myprop3_ID",
"displayName" : "My property 3"
}]
}]
}Struktur einer Quelle
Eigenschaft | Eigenschaft eines enthaltenen Objekts | Beschreibung |
|---|---|---|
sources | - | Das Quellsystem kann in diesem Array mehrere Quellen ausliefern (z.B. E-Mail, Anlagen etc.), um verschiedene Zuordnungsarten zu unterscheiden. |
id | Gibt den eindeutigen Bezeichner der Quelle an. Die ID muss eine relative URI sein. Die relative URI sollte mit dem Namen der App beginnen, die das Quellsystem bereitstellt, damit eine Eindeutigkeit gewährleistet ist (z.B. /myapp/sources/mysource). | |
displayName | Gibt den Anzeigenamen an, wie er in der Administrationsoberfläche Zuordnungen im Feld Quelle angezeigt wird. Mit Blick auf die Internationalisierung arbeitet die DMSApp mit dem HTTP-Header Accept-Language. Dieser HTTP-Header muss vom Quellsystem ausgewertet und der Anzeigename der Quelle sprachspezifisch ausgegeben werden. | |
categories | Gibt das Array der Kategorien der Quelle an, die für die Zuordnungsverwaltung und Zuordnungsverarbeitung zur Verfügung gestellt werden. | |
properties | Gibt das Array der Eigenschaften der Quelle an, die für die Zuordnungsverwaltung und Zuordnungsverarbeitung zur Verfügung gestellt werden. |
Struktur einer Quellkategorie
Eigenschaft | Beschreibung |
|---|---|
key | Gibt den eindeutigen Bezeichner der Kategorie der Quelle an. |
displayName | Gibt den Anzeigenamen an, wie er in der Administrationsoberfläche Zuordnungen im Bereich Kategorien im Feld Quelle angezeigt wird. Mit Blick auf die Internationalisierung arbeitet die DMSApp mit dem HTTP-Header Accept-Language. Dieser HTTP-Header muss vom Quellsystem ausgewertet und der Anzeigename der Kategorie sprachspezifisch ausgegeben werden. |
Struktur einer Quelleigenschaft
Eigenschaft | Beschreibung |
|---|---|
key | Gibt den eindeutigen Bezeichner der Eigenschaft der Quelle an. |
displayName | Gibt den Anzeigenamen an, wie er in der Administrationsoberfläche Zuordnungen im Bereich Eigenschaften im Feld Quelle angezeigt wird. Die DMSApp arbeitet zur Internationalisierung mit dem HTTP-Header Accept-Language. Dieser HTTP-Header muss vom Quellsystem ausgewertet und der Anzeigename der Eigenschaft sprachspezifisch ausgegeben werden. |
Anmerkung
Stellen Sie Folgendes sicher: Die Quellen müssen performant abgerufen werden können, damit die Antwortzeit des Features Zuordnungen nicht negativ beeinflusst wird.
Abrufen des Standardquellsystems zu einem d.3-Repository
Freigegeben: JSON-Repräsentation
Das Standardquellsystem ist ein vordefiniertes Quellsystem pro d.3-Repository, das standardmäßig von der DMSApp bereitgestellt wird. Wenn Sie eine Erweiterung zu DMS-Funktionalitäten bereitstellen und kein eigenes Quellsystem definieren möchten, können Sie mit dem Standardquellsystem die Eigenschaften und Kategorien des d.3-Repositorys verwenden.
Die Definition eines Standardquellsystems und die zugehörigen Zuordnungen werden von der DMSApp festgelegt. Sie können Zuordnungen zu einem Standardquellsystem nicht ändern.
In diesem Kapitel erfahren Sie, wie Sie die Quellsystemdefinition je d.3-Repository abrufen können.
Um die Quellsystemdefinition eines d.3-Repositorys abzurufen, müssen Sie folgende Schritte durchführen:
Ermitteln der URL zu einem Repository
Ermitteln der Linkrelation zum Abrufen der Quellsystemdefinition eines d.3-Repositorys
Aufrufen der URL für die Quellsystemdefinition eines d.3-Repositorys
Ermitteln der URL zu einem Repository
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Ermitteln der Linkrelation zum Abrufen der Quellsystemdefinition eines d.3-Repositorys
Das JSON-Objekt zu einem d.3-Repository enthält die Linkrelation source, mit deren Hilfe Sie die Quellsystemdefinition des d.3-Repositorys abrufen können.
Response
{
"_links": {
"source": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source"
}
},
"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}Aufrufen der URL für die Quellsystemdefinition eines d.3-Repositorys
Sie müssen sicherstellen, dass Sie sich für das d.3-Repository authentifizieren können. Nur dann können Sie die URL abrufen. Das Standardquellsystem enthält alle Kategorien und Eigenschaften des d.3-Repositorys unabhängig von den Berechtigungen des Benutzers.
Rufen Sie die Quellsystemdefinition des d.3-Repositorys mit der zuvor ermittelten URL wie folgt ab:
Request
GET https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source HTTP/1.1 Accept: application/hal+json
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
{
"id": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source",
"displayName": "D3RepositoryName",
"properties": [
{
"key": "Key0",
"type": "String",
"displayName": "Sample property1"
}
],
"categories":[
{
"key": "mycategory1_ID",
"displayName": "Sample category1"
}
]
}Struktur einer Quelle
Eigenschaft | Beschreibung |
|---|---|
id | Gibt den eindeutigen Bezeichner des Standardquellsystems an. Diese ID verwenden Sie als Wert zum Parameter sourceId bei weiteren API-Funktionen. |
displayName | Gibt den Anzeigenamen eines d.3-Repositorys an. |
categories | Gibt das Array der Kategorien des abgefragten Quellsystems an. |
properties | Gibt das Array der Eigenschaften des abgefragten Quellsystems an. |
Struktur einer Kategorie
Eigenschaft | Beschreibung |
|---|---|
key | Gibt den eindeutigen Bezeichner der Kategorie im Quellsystem an. |
displayName | Gibt den Anzeigenamen der Kategorie an. Mit Blick auf die Internationalisierung arbeitet die DMSApp mit dem HTTP-Header Accept-Language. Dieser HTTP-Header sorgt dafür, dass der Anzeigename der Kategorie sprachspezifisch ausgegeben wird. |
Struktur einer Eigenschaft
Eigenschaft | Beschreibung |
|---|---|
key | Gibt den eindeutigen Bezeichner der Eigenschaft im Quellsystem an. |
type | Gibt den Typ der Eigenschaft zurück. Der Typ der Eigenschaft wird vom Administrator beim Erstellen der Eigenschaft definiert. Mögliche Werte sind: String, ColorCode, Date, DateTime, Double, Money. |
displayName | Gibt den Anzeigenamen der Eigenschaft an. Die DMSApp arbeitet zur Internationalisierung mit dem HTTP-Header Accept-Language. Dieser HTTP-Header sorgt dafür, dass der Anzeigename der Eigenschaft sprachspezifisch ausgegeben wird. |
Abrufen und Anzeigen der Ergebnisse eines Suchvorgangs
Freigegeben: JSON-Repräsentation, HTML-Seite
Sie können beim Abrufen oder Anzeigen von Ergebnissen eines Suchvorgangs durch Angeben einer bestimmten Quelle sowie zugehörigen Quellkategorien und Quelleigenschaften die Ergebnismenge eingrenzen. Auch ein Volltextsuchbegriff kann zur Einschränkung des Suchergebnisses angegeben werden. Im Kapitel Definition eines Quellsystems erfahren Sie, wie Sie eine Quelle für eine Zuordnung bereitstellen können.
Um die Ergebnisse eines Suchvorgangs abzurufen oder anzuzeigen, müssen Sie folgende Schritte durchführen:
Ermitteln der URL zu einem Repository
Ermitteln der Linkrelation zum Abrufen der Ergebnisse eines Suchvorgangs
Angeben von verhaltenssteuernden Parametern
Aufrufen der URL für die Ergebnisse eines Suchvorgangs
Ermitteln der URL zu einem Repository
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Ermitteln der Linkrelation zum Abrufen oder Anzeigen der Ergebnisse eines Suchvorgangs
Rufen Sie die URL zu einem Repository wie folgt auf:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27 Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation searchresultwithmapping mit Platzhaltern für die Werte, mit deren Hilfe das Abrufen oder Anzeigen der Ergebnisse eines Suchvorgangs durchgeführt wird.
Response
{
_links: {
searchresultwithmapping: {
href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm{?sourceid,sourceproperties,sourcecategories,sourcepropertysort,ascending,fulltext,page,pagesize}",
templated: true
}
},
id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}Angeben von verhaltenssteuernden Parametern
Das Verhalten beim Abrufen oder Anzeigen von Suchergebnissen zu einem Suchvorgang steuern Sie mit folgenden Parametern. Sie müssen die Parameter der URL encodieren (z.B. Leerzeichen in %20). Die Länge des encodierten Abfrageparameters darf 2000 Zeichen nicht überschreiten.
Parameter | Beschreibung |
|---|---|
sourceid | Legt fest, zu welcher Quelle die Zuordnung gehört, die für das Abrufen der Ergebnisse eines Suchvorgangs angewendet werden soll. Für die einzelnen Elemente des Ergebnisses werden nur die Eigenschaften und Kategorien der Quelle verwendet, die zu d.3-Eigenschaften und d.3-Kategorien zugeordnet wurden. Wird keine Quelle angegeben, werden für die einzelnen Elemente des Ergebnisses nur die ID und die Linkrelationen des DMS-Objektes zurückgegeben. |
sourceproperties | Gibt eine Sucheinschränkung nach Eigenschaften der Dokumente und Akten aus Sicht der Quelle an. Geben Sie die ID der zugeordneten Quelleigenschaften an, um einen Suchvorgang auf bestimmte Kriterien zu beschränken. Der Suchvorgang wird basierend auf der Zuordnung ausgeführt. Reguläre Ausdrücke, die vom Administrator bei einer Zuordnung angegeben wurden, werden nicht berücksichtigt. Die Sucheinschränkungen geben Sie als JSON-Objekt an. Sie können je Eigenschaft mindestens einen Wert definieren. Beispiele (nicht encodiert):
Einschränkung in Bezug auf die Definition eines Suchvorgangs: Sie können zu einem Parameter mehrere Werte definieren, sofern für die zugeordnete d.3-Eigenschaft Facetten konfiguriert wurden. Falls keine Facetten für die d.3-Eigenschaft zum Anzeigen konfiguriert wurden, wird immer der letzte Wert für den Suchvorgang übernommen. Quelleigenschaften, die den allgemeinen Eigenschaften für die Bemerkungsfelder (Bemerkung 1 - 4) zugeordnet sind, können Sie nicht für die Suche verwenden, da eine Suche nach einzelnen Bemerkungsfeldern im d.3-Repository nicht unterstützt wird. Sie können auch mehrere Eigenschaften gleichzeitig als Sucheinschränkung verwenden: Beispiel (nicht encodiert):
|
sourcecategories | Legt fest, auf welche Kategorien sich die Suche bezieht. Sie können mindestens eine Kategorie definieren. Geben Sie die ID der Quellkategorie an, andernfalls erfolgt die Suche in allen Kategorien eines d.3-Repositorys. Legt fest, auf welche Quellkategorien sich die Suche bezieht. Geben Sie die ID der Quellkategorie an. Der Suchvorgang wird basierend auf der Zuordnung ausgeführt. Sie geben die Sucheinschränkungen als JSON-Array an. Sie können eine Quellkategorie oder mehrere Quellkategorien angeben. Geben Sie keine Quellkategorie an, erfolgt die Suche in allen Kategorien eines d.3-Repositorys. Beispiele (nicht encodiert):
|
sourcepropertysort | Gibt die ID der zugeordneten Quelleigenschaft an, nach der sortiert wird. Ist keine Sortiereigenschaft angegeben, erfolgt die Sortierung gemäß Standardsortierung anhand des Sortierkriteriums Geändert am. |
ascending | Gibt die Richtung der Sortierreihenfolge an.
Wird der ascending-Parameter nicht explizit angegeben, wird eine aufsteigende Sortierung vorgenommen. Davon ausgenommen ist die Standardsortierung: Wird nach dem Kriterium Geändert am sortiert und ist die Sortierreihenfolge nicht angegeben, wird in diesem Fall absteigend sortiert. Außerdem werden in der Ergebnisliste zunächst die Akten und dann die Dokumente angezeigt. Innerhalb von Dokumenten und Akten wird nach dem angegebenen Sortierkriterium sortiert. |
fulltext | Gibt einen Volltextsuchbegriff an. |
page | Gibt an, welche Seite der Ergebnisliste angefordert werden. Wird der Parameter nicht übergeben, wird die Seite 1 angefordert. |
pagesize | Gibt an, wie viele Elemente pro Seite angezeigt werden. Wird der Parameter nicht übergeben, werden 25 Elemente pro Seite angefordert. |
Anmerkung
Spezielle Angaben für den sourceproperties-Parameter in Bezug auf verschiedene Einschränkungsmöglichkeiten, um gezielt zum Ergebnis zu gelangen:
Suche nach einem numerischen Wert oder einem Geldwert:
Geben Sie den Wert ohne Tausendertrennzeichen an. Als Dezimaltrennzeichen gilt der Punkt (.). Beispiel: Für den Wert 1.000,20 EUR geben Sie 1000.20 an.
Suche nach einem Datum und Uhrzeit:
Geben Sie das Datum im Format YYYY-MM-DD an. Beispiel: Für den 05.12.2014 (DD.MM.YYYY) geben Sie 2014-12-05 an.
Zeitangaben werden nach dem Format YYYY-MM-DDTHH:mm:ss+01:00 durchführt. Das Pluszeichen (+) müssen Sie mit %2b encodieren. Beispiel: 2015-02-18T23:59:59%2b01:00 für den 18.02.2015 um 23:59 Uhr und 59 Sekunden in der Zeitzone UTC+1 für Winterzeit in Deutschland.
Suche nach Elementen, die sich in einem bestimmten Bereich befinden:
Für die Bereichssuche verwenden Sie als Trennzeichen eine Kombination aus einem Pipe- und Minuszeichen (|-). Beispiele für ein numerisches Feld mit der ID "231":
Werte größer oder gleich 100: {"231":["100|-"]}
Werte kleiner oder gleich 100: {"231":["|-100"]}
Werte zwischen 100 und 200: {"231":["100|-200"]}
Aufrufen der URL für die Ergebnisse eines Suchvorgangs (JSON-Repräsentation)
Wenn Sie eine URL erzeugt haben, dann können Sie die Ergebnisse des Suchvorgangs wie folgt abrufen:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?sourceid=/myapp/sources/mysource&sourceproperties={"myprop1_ID":["Test E-Mail 1"]}&sourcecategories=["mycategory1_ID"]&sourcepropertysort=myprop1_ID&ascending=true&fulltext=test&page=1&pagesize=50
Accept: application/jsonAls Ergebnis wird dann folgendes JSON-Objekt zurückgegeben:
Response
{
"_links": {
"next": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?...page=2"
},
"self": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?...page=1"
}
},
"page": 1,
"items": [
{
"_links": {
"self": { "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123" },
"previewReadonly": { href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/preview?isReadonly=true" }
},
"id": "D000000123",
"sourceProperties": [
{
"key": "myprop1_ID",
"value": "Test E-Mail 1",
"isMultiValue": false
},
{
"key": "myprop2_ID",
"value": "Max Mustermann",
"isMultiValue": true
},
"..."
],
"sourceCategories": [ "mycategory1_ID" ]
},
"..."
]
}Eigenschaft | Beschreibung |
|---|---|
_links | Enthält die Linkrelationen zum Element. self: Self-Link. previewReadonly: Relative URL zum Abrufen der Vorschau im Lesemodus. Verwenden Sie die Linkrelation, wenn die Vorschau im Inner Supply ( InnerSupply ) des Bedienkonzepts angezeigt wird. next: Relative URL zum Abrufen der nächsten Seite der Ergebnisliste. Wird nur angegeben, wenn es weitere Ergebnisse gibt. prev: Relative URL zum Abrufen der vorherigen Seite der Ergebnisliste. Wird nur angegeben, wenn es vorherige Ergebnisse gibt. |
page | Gibt die Seitennummer der Ergebnisliste an. |
items | Gibt das Array mit Elementen der Ergebnisse für den Suchvorgang für die angeforderte Seite an. |
Struktur eines Elementes der Ergebnisliste
Eigenschaft | Beschreibung |
|---|---|
_links | Enthält die Linkrelationen zu dem Element. self: Self-Link. delete oder deleteWithReason: Falls vorhanden, kann das Element mit einem HTTP DELETE-Anforderung (Request) gelöscht werden. Weitere Informationen finden Sie unter Löschen der aktuellen Version eines DMS-Objektes ohne Benutzerinteraktion. update oder updateWithContent: Falls vorhanden, kann das Element mit einem HTTP PUT-Anforderung (Request) aktualisiert werden. Weitere Informationen finden Sie unter Speichern einer neuen Version ohne Benutzerinterkation. |
id | Gibt die Dokument-ID des Elements an. |
sourceProperties | Gibt das Array mit Quelleigenschaften an, die für das Element vorhanden sind. Wurde dieselbe Quelleigenschaft mehreren d.3-Eigenschaften zugeordnet, die das Element besitzt, wird die Quelleigenschaft mehrfach mit den jeweiligen Werten der d.3-Eigenschaft zurückgegeben. Reguläre Ausdrücke, die vom Administrator bei einer Zuordnung angegeben wurden, werden nicht berücksichtigt. |
sourceCategories | Gibt das Array mit den IDs der Quellkategorien an, die für das Element zur Verfügung stehen. Es werden nur dann mehrere Kategorien zurückgegeben, wenn mehrere Quellkategorien der d.3-Kategorie zugeordnet wurden, in der sich das Element befindet. |
Struktur einer Quelleigenschaft
Eigenschaft | Beschreibung |
|---|---|
key | Gibt den eindeutigen Bezeichner der Quelleigenschaft an. |
value | Gibt den Wert der zugeordneten d.3-Eigenschaft an. |
displayValue | Gibt den Anzeigewert der zugeordneten d.3-Eigenschaft an. Wird nur zurückgegeben, wenn der Wert ( value ) und der Anzeigewert ( displayValue ) unterschiedlich sind. |
isMultiValue | Gibt an, ob die zugeordnete d.3-Eigenschaft eine Mehrfacheigenschaft ist. Handelt es sich bei der d.3-Eigenschaft um eine Mehrfacheigenschaft, wird bei value der erste oder der erste gefüllte Wert der Eigenschaft zurückgegeben (abhängig von der d.3-Repositorykonfiguration). Um alle Mehrfachwerte abzurufen, verwenden Sie die Anforderung (Request) zum Abrufen der Details eines DMS-Objektes. |
Aufrufen der URL für die Ergebnisse eines Suchvorgangs (HTML-Seite)
Wenn Sie die HTML-Darstellung der Ergebnisse aufrufen möchten, erzeugen Sie die URL in derselben Weise, wie beim Abfragen der JSON-Repräsentation beschrieben. Geben Sie die URL im Browser ein, um die HTML-Seite anzuzeigen. Diese HTML-Seite enthält die Bezeichner der d.3-Eigenschaften und d.3-Kategorien.
Beispiel (nicht encodiert):
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?sourceid=/myapp/sources/mysource&sourceproperties={"myprop1_ID":["Test E-Mail 1"]}&sourcecategories=["mycategory1_ID"]&sourcepropertysort=myprop1_ID&ascending=true&fulltext=test&page=1&pagesize=50
Accept: text/htmlAbrufen und Anzeigen von Details eines DMS-Objektes
Freigegeben: JSON-Repräsentation, HTML-Seite
Sie können die Details zu einem DMS-Objekt als JSON-Repräsentation abrufen oder die Detailansicht zu einem DMS-Objekt anzeigen. Beim Abrufen der Details als JSON-Repräsentation können Sie durch Angeben einer bestimmten Quelle eines Quellsystems festlegen, welche Quelleigenschaften und Quellkategorien ermittelt werden. Geben Sie keine Quelle an, werden nur die ID und die Linkrelationen zu dem DMS-Objekt zurückgegeben. Im Kapitel Definieren eines Quellsystems erfahren Sie, wie Sie eine Quelle anlegen können.
Um die Details eines DMS-Objektes abzurufen oder anzuzeigen, müssen Sie folgende Schritte durchführen:
Ermitteln der URL zu einem Repository
Ermitteln der Linkrelation zum Abrufen der Details eines DMS-Objektes
Angeben von verhaltenssteuernden Parametern
Aufrufen der URL für die Details eines DMS-Objektes
Ermitteln der URL zu einem Repository
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Ermitteln der Linkrelation zum Abrufen oder Anzeigen der Details eines DMS-Objektes
Rufen Sie die URL zu einem Repository wie folgt auf:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27 Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation dmsobjectwithmapping mit Platzhaltern für die Werte, mit deren Hilfe das Abrufen oder Anzeigen der Details eines DMS-Objektes durchgeführt wird.
Response
{
_links: {
dmsobjectwithmapping: {
href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/{dmsobjectid}{?sourceid}",
templated: true
}
},
id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}Angeben von verhaltenssteuernden Parametern
Das Verhalten beim Abrufen oder Anzeigen von Details eines DMS-Objektes steuern Sie mit folgenden Parametern:
Parameter | Beschreibung |
|---|---|
dmsobjectid | Gibt die Dokument-ID des DMS-Objektes an, dessen Details abgerufen (Request) oder angezeigt werden sollen. |
sourceid | Legt fest, zu welcher Quelle die Zuordnung gehört, die für das Abrufen der Details des DMS-Objektes verwendet wird. Wie Sie ein Quellsystem für Zuordnungen bereitstellen, erfahren Sie unter Definieren eines Quellsystems. Wenn Sie das Standardquellsystem verwenden möchten, finden Sie weitere Informationen unter Abrufen des Standardquellsystems zu einem d.3-Repository. Abrufen (JSON-Repräsentation): Es werden nur die Eigenschaften der Quelle zurückgegeben, die den d.3-Eigenschaften zugeordnet wurden. Wird keine Quelle angegeben, werden nur die ID und die Linkrelationen zum DMS-Objekt zurückgegeben. Anzeigen (HTML-Seite): Wenn Sie die Details eines DMS-Objektes anzeigen möchten, ist das Angeben dieses Parameters nicht erforderlich. Der Parameter wird nicht ausgewertet. |
Aufrufen der URL für die Details eines DMS-Objektes (JSON-Repräsentation)
Wenn Sie eine URL erzeugt haben, dann können Sie die Details des DMS-Objektes wie folgt abrufen:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123?sourceid=/myapp/sources/mysource Accept: application/json
Als Ergebnis wird dann folgendes JSON-Objekt zurückgegeben:
Response
{
"_links": {
"self": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123"
},
"mainblobcontent": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/current/b/main/c"
},
"editinoffice": {
"href": "{ms-word:ofe|u|{+clientOrigin}/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/dav/D000000123%20(D000000123).DOCX}",
"templated": true
},
"pdfblobcontent": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/current/b/p1/c"
},
"notes":{
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n"
},
"children":{
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm/?children_of=D000000123"
},
"versions":{
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/"
}
},
"id": "D000000123",
"sourceProperties": [
{
"key": "myprop1_ID",
"value": "value of property 1"
},
{
"key": "myprop2_ID",
"value": "value of property 2 in row 2",
"values": {
"2": "value of property 2 in row 2",
"4": "value of property 2 in row 4"
}
}
],
"sourceCategories": ["mycategory2_ID"]
}Eigenschaft | Beschreibung |
|---|---|
_links | Enthält die Linkrelationen zum DMS-Objekt. mainblobcontent: Relative Download-URL für das Hauptdokument der aktuellen Version des DMS-Objektes. editinoffice: URL mit Platzhaltern, um das Dokument in Microsoft Office zu bearbeiten. Diese URL erhalten Sie nur, wenn der Administrator die Funktion zum Bearbeiten von Microsoft Office-Dokumenten aktiviert hat. Die URL existiert nicht, wenn Sie mit Microsoft Office 365 in der Cloud arbeiten. pdfblobcontent: Relative Download-URL für das generierte ("abhängige") PDF-Dokument der aktuellen Version des DMS-Objektes. Diese URL erhalten Sie nur, wenn ein generiertes PDF-Dokument für das DMS-Objekt erzeugt wurde. notes: Relative URL zum Abrufen der Notizen des DMS-Objektes. Diese URL erhalten Sie nur, wenn zum DMS-Objekt bereits Notizen gespeichert wurden. children: Relative URL für die untergeordneten DMS-Objekte. Diese URL erhalten Sie nur, wenn das DMS-Objekt untergeordnete Elemente hat. versions: Relative URL zum Abrufen und Anzeigen der Versionen eines DMS-Objektes. self: Self-Link. |
id | Gibt die Dokument-ID des DMS-Objektes an. |
sourceProperties | Gibt das Array mit Quelleigenschaften an, die für das angeforderte DMS-Objekt vorhanden sind. Wurde dieselbe Quelleigenschaft verschiedenen d.3-Eigenschaften zugeordnet, die das angeforderte DMS-Objekt besitzt, wird diese Quelleigenschaft mehrfach mit den jeweiligen Werten der d.3-Eigenschaft zurückgegeben. |
sourceCategories | Gibt das Array mit den IDs der Quellkategorien an, die für das angeforderte DMS-Objekt in Frage kommen. Es werden nur dann mehrere Kategorien zurückgegeben, wenn mehrere Quellkategorien der d.3-Kategorie zugeordnet wurden, in der sich das angeforderte DMS-Objekt befindet. |
Struktur einer Quelleigenschaft
Eigenschaft | Beschreibung |
|---|---|
key | Gibt den eindeutigen Bezeichner der Quelleigenschaft an. |
value | Gibt den Wert der zugeordneten d.3-Eigenschaft an. Handelt es sich bei der d.3-Eigenschaft um eine Mehrfacheigenschaft, wird bei value der erste oder der erste gefüllte Wert der Eigenschaft zurückgegeben (abhängig von der d.3-Repositorykonfiguration). |
values | Gibt die Werte der zugeordneten d.3-Eigenschaft an. Wird nur zurückgegeben, wenn die d.3-Eigenschaft eine Mehrfacheigenschaft ist. values ist ein Objekt, das aus Name-Wert-Paaren (Key-Value) besteht: Name: Zeilennummer (beginnend bei 1). Wert: Wert der Eigenschaft in der entsprechenden Zeile. |
displayValue | Gibt den Anzeigewert der zugeordneten d.3-Eigenschaft an. Wird nur zurückgegeben, wenn der Wert (value) und der Anzeigewert (displayValue) unterschiedlich sind. |
Aufrufen der URL für die Details eines DMS-Objektes (HTML-Seite)
Wenn Sie die HTML-Darstellung der Ergebnisse aufrufen möchten, erzeugen Sie die URL in derselben Weise wie beim Abfragen der JSON-Repräsentation beschrieben. Geben Sie die URL im Browser ein, um die HTML-Seite anzuzeigen. Diese HTML-Seite enthält die Bezeichner der d.3-Eigenschaften und d.3-Kategorien.
Beispiel:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123 Accept: text/html
Speichern von DMS-Objekten
Sie können beim Speichern von DMS-Objekten durch Angeben einer bestimmten Quelle sowie zugehörigen Quellkategorien und Quelleigenschaften die Metadaten der Ablage bestimmen. Im Kapitel Definieren eines Quellsystems erfahren Sie, wie Sie eine Quelle für eine Zuordnung bereitstellen können. Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern.
In diesem Thema erfahren Sie, wie Sie Daten aus einer Quelle mithilfe der DMSApp speichern können.
Beachten Sie folgende Begrenzungen (betrifft nur das Cloudangebot d.velop documents):
max. 3000 Aktualisierungen von DMS-Objekten je Mandant (Client-IP) im Zeitraum von 5 Minuten
max. 8000 Speicherungen neuer DMS-Objekte je Mandant (Client-IP) im Zeitraum von 5 Minuten
Speichern eines neuen DMS-Objektes ohne Benutzerinteraktion
Sie können ein neues DMS-Objekt automatisiert im d.3-Repository speichern, ohne dass ein Anwender eine Aktion durchführen muss. Beim Speichern ohne Benutzerinteraktion werden keine Validate-Hooks in d.3 server ausgeführt. Grundvoraussetzung für das Durchführen der Aktion sind die Zuordnungen (Mappings). Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern.
Um ein neues DMS-Objekt zu speichern, müssen Sie folgende Schritte durchführen:
Ermitteln der URL zu einem Repository
Ermitteln der Linkrelation für die Ablage eines neuen eines DMS-Objektes
Bereitstellen der zu speichernden Datei (optional)
Aufrufen der URL zur Ablage eines neuen DMS-Objektes
Ermitteln der URL zu einem Repository
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Ermitteln der Linkrelation für die Ablage eines neuen DMS-Objektes
Rufen Sie die URL zu einem Repository wie folgt auf:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27 Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation dmsobjectwithmapping.
Response
{
"_links": {
"dmsobjectwithmapping": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/{dmsobjectid}{?sourceid}",
"templated":true
}
},
"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}Die Werte dmsobjectid und sourceid sind für das Speichern nicht relevant. Daher füllen Sie diese beim Ausführen des Templates nicht aus.
Bereitstellen der zu speichernden Datei (optional)
Im Kapitel Bereitstellen von Dateien erfahren Sie, wie Sie contentUri oder contentLocationUri erhalten. Diese Parameter benötigen Sie zum Speichern eines neuen DMS-Objektes.
Wenn Sie eine Akte erstellen möchten, ist das Bereitstellen der Datei nicht erforderlich.
Aufrufen der URL zur Ablage eines neuen DMS-Objektes
Führen Sie eine HTTP POST-Anforderung mit den benötigten Eigenschaften als Body auf diese URL aus.
Request
POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json
{
"filename": "myfile.txt",
"sourceCategory": "mycategory1_ID",
"sourceId": "/myapp/sources/mysource",
"contentLocationUri": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43",
"sourceProperties": {
"properties": [{
"key": "myprop1_ID",
"values": ["Please verify the XYZ invoice"]
},
{
"key": "myprop2_ID",
"values": ["Name1@contoso.com","Name2@samplecompany.de"]
}
],
}
}Informationen zu den Parametern des JSON-Objektes finden Sie unter Definieren der Parameter zum Speichern.
Ist für den d.3-Dokumentstatus keine Zuordnung konfiguriert, wird für das DMS-Objekt standardmäßig der Dokumentstatus Freigabe (Release) verwendet. Möchten Sie einen anderen Dokumentstatus beim Speichern anwenden, muss der Administrator die Eigenschaft Status zugeordnet haben.
Ist der Aufruf erfolgreich, wird die URL zum DMS-Objekt im Header Location zurückgegeben.
Wenn Sie ein Element mit einer Akte (parentId) verknüpfen möchten und diese Aktion fehlschlägt, erhalten Sie als Antwort (Response) die URL zum DMS-Objekt im Header Location und eine zusätzliche Meldung, dass die Verknüpfung nicht erfolgreich war.
Response
HTTP/1.1 201 Created
Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D0001234?sourceId=%2Fmyapp%2Fsources%2Fmysourc
{
"reason": "You do not have the right to link the document with the dossier manually.
Nevertheless, the document was successfully saved. The document may be automatically linked on the server."
"severity": 1
}Wenn der Aufruf erfolgreich war und es Detailinformationen zum Verarbeitungsergebnis des Ablagevorgangs gibt, werden die Detailinformationen in der Antwort (Response) zurückgeliefert. Mithilfe der Informationen können Sie entscheiden, ob weitere Verarbeitungsschritte zum DMS-Objekt notwendig sind. Weitere Informationen finden Sie unter Format der Antwort für erfolgreiche Anforderungen (Requests) mit Detailinformationen.
Schlägt das Speichern des DMS-Objektes fehl, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen finden Sie unter Format der Antwort bei Fehlern.
Aktualisieren eines DMS-Objektes ohne Benutzerinteraktion
Sie können ein bestehendes DMS-Objekt in einem d.3-Repository aktualisieren, ohne dass ein Anwender eine Aktion ausführen muss. Beim Aktualisieren eines DMS-Objektes ohne Benutzerinteraktion werden keine Validate-Hooks in d.3 server ausgeführt. Grundvoraussetzung für das Durchführen der Aktion sind die Zuordnungen (Mappings). Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern.
Um ein DMS-Objekt zu aktualisieren, müssen Sie folgende Schritte durchführen:
Ermitteln der URL zu einem Repository
Ermitteln der Linkrelationen zum bestehenden DMS-Objekt
Bereitstellen der zu speichernden Datei (optional)
Aufrufen der URL zum Aktualisieren des DMS-Objektes
Ermitteln der URL zu einem Repository
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Ermitteln der Linkrelationen zum bestehenden DMS-Objekt
Um eine URL zu einem bestehendem DMS-Objekt zu ermitteln, führen Sie eine Suche aus und werten Sie die Linkrelation update oder updateWithContent zu einem Element der Ergebnisliste aus. Im Kapitel Abrufen und Anzeigen der Ergebnisse eines Suchvorgangs finden Sie weitere Informationen zum Ausführen einer Suche und die Beschreibung eines Elements der Ergebnisliste. Hat das bereits vorhandene DMS-Objekt den d.3-Dokumentstatus Processing muss der authentifizierte Benutzer der Bearbeiter des DMS-Objektes sein.
Bereitstellen der zu speichernden Datei (optional)
Haben Sie eine Linkrelation updateWithContent ermittelt, dann können Sie eine Datei mit den Parametern contentUri oder contentLocationUri bereitstellen. Im Kapitel Bereitstellen von Dateien können Sie nachlesen, wie Sie eine Datei bereitstellen können.
Wenn Sie nur Eigenschaften mit der Linkrelation update aktualisieren möchten, ist die Bereitstellung einer Datei nicht notwendig.
Haben Sie ausschließlich eine Linkrelation update erhalten, dann ist keine Aktualisierung mit Datei möglich.
Aufrufen der URL zum Aktualisieren des DMS-Objektes
Führen Sie eine HTTP PUT-Anforderung mit den benötigten Eigenschaften als Body auf die URL des bestehenden DMS-Objektes aus, die Sie in der Linkrelation update oder updateWithContent erhalten haben. Wenn Sie nur Eigenschaften ändern möchten, geben Sie die Parameter contentLocationUri und filename nicht an.
Request
PUT /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json
{
"filename": "myfile.txt",
"alterationText": "updated file",
"sourceCategory": "mycategory1_ID",
"sourceId": "/myapp/sources/mysource",
"contentLocationUri": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43",
"sourceProperties": {
"properties": [{
"key": "myprop1_ID",
"values": ["Please verify the XYZ invoice"]
},
{
"key": "myprop2_ID",
"values": ["Name1@contoso.com","Name2@samplecompany.de"]
}
]
}
}Informationen zu den Parametern des JSON-Objektes finden Sie unter Definieren der Parameter zum Speichern.
Ist der Aufruf erfolgreich, wird HTTP 200 OK zurückgegeben:
Response
HTTP/1.1 200 OK
Wenn der Aufruf erfolgreich war und es Detailinformationen zum Verarbeitungsergebnis des Ablagevorgangs gibt, werden die Detailinformationen in der Antwort (Response) zurückgeliefert. Mithilfe der Informationen können Sie entscheiden, ob weitere Verarbeitungsschritte zum DMS-Objekt notwendig sind. Weitere Informationen finden Sie unter Format der Antwort für erfolgreiche Anforderungen (Requests) mit Detailinformationen.
Schlägt das Speichern der Version fehl, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen finden Sie unter Format der Antwort bei Fehlern.
Wenn der Aufruf erfolgreich war und es Detailinformationen zum Verarbeitungsergebnis des Ablagevorgangs gibt, so werden diese Detailinformationen in der Antwort (Response) zurückgeliefert. Diese Informationen können Sie z.B. dazu verwenden, um Entscheidungen darüber zu treffen, ob weitere Verarbeitungsschritte zu dem DMS-Objekt nötig sind. Weitere Informationen finden Sie unter dem Kapitel Format der Antwort für erfolgreiche Anforderungen.
Speichern neuer DMS-Objekte mit Benutzerinteraktion
Freigegeben: HTML-Seite
Sie können das Feature Ablage zum Speichern von neuen DMS-Objekten mit Eigenschaften und Dateien aufrufen. Grundvoraussetzung für das Durchführen der Aktion sind die Zuordnungen (Mappings). Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern.
Um neue DMS-Objekte zu speichern, müssen Sie folgende Schritte durchführen:
Ermitteln der Linkrelation für den Ablagedialog
Bereitstellen der zu speichernden Datei (optional)
Erstellen eines Ablagedialogs mit definierten Eigenschaften und Dateien
Anzeigen des Ablagedialogs mit definierten Eigenschaften und Dateien
Ausführen weiterer Aktionen nach dem Speichern (optional)
Ermitteln der Linkrelation für den Ablagedialog
Für das Feature Ablage gibt es zwei Linkrelationen:
Linkrelation ohne Bezug zu einem d.3-Repository: Beim Ablegen ohne Bezug zu einem d.3-Repository kann der Anwender das d.3-Repository auswählen. Jedoch können Sie in diesem Fall die Datei nicht temporär hochladen. Weitere Informationen zum Bereitstellen finden Sie unter Bereitstellen von Dateien.
Linkrelation mit Bezug zu einem d.3-Repository: Beim Ablegen mit Bezug zu einem d.3-Repository kann der Anwender das d.3-Repository nicht mehr ändern.
Um die Linkrelation ohne Bezug zu einem d.3-Repository zu ermitteln, führen Sie eine HTTP GET-Anforderung für die REST-Ressource /dms aus.
Request
GET /dms Accept: application/hal+json
Das JSON-Objekt enthält die Linkrelation new.
Response
{
"_links": {
"new": {
"href": "/dms/new/"
}
}
}Um die Linkrelation mit Bezug zu einem d.3-Repository zu ermitteln, müssen Sie zunächst die URL zu einem Repository kennen. Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln. Führen Sie dann eine HTTP Get-Anforderung auf die URL zu einem Repository wie folgt aus:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27 Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation new.
Response
{
"_links": {
"new": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/"
}
},
"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}Bereitstellen der zu speichernden Datei (optional)
Im Kapitel Bereitstellen von Dateien erfahren Sie, wie Sie contentUri oder contentLocationUri erhalten. Diese Parameter benötigen Sie zum Erstellen eines Ablagedialogs für ein neues DMS-Objekt.
Wenn Sie eine Akte erstellen möchten, ist das Bereitstellen der Datei nicht erforderlich.
Erstellen eines Ablagedialogs mit definierten Eigenschaften und Dateien
Führen Sie eine HTTP POST-Anforderung mit den benötigten Eigenschaften als Body auf die URL aus, die Sie in der Linkrelation new erhalten haben.
Request
POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json
{
"storeObjects": [{
"displayValue": "Please verify the XYZ invoice",
"filename": "myfile.txt",
"contentLocationUri": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43",
"sourceId": "/myapp/sources/mysourcel",
"sourceCategory": "mycategory1",
"sourcePropertiesUri": "/myapp/sources/mysourcel/properties/myfile.haljson",
"successCallbackUri": "/myapp/sources/mysourcel/success/myfile"
},
{
...
}]
}Das JSON-Objekt, das beim POST übergeben wird, ist wie folgt beschrieben:
Eigenschaft | Beschreibung |
|---|---|
storeObjects | Gibt das Array der Elementeigenschaften und Dateien an, mit denen der Ablagedialog definiert werden soll. Informationen zu einem Element des Arrays finden Sie unter Definieren der Parameter zum Speichern. |
Wenn Sie nur ein einzelnes DMS-Objekt speichern möchten, dann können Sie das JSON-Objekt der Elementeigenschaften auch ohne übergeordnetes Array storeObjects angeben.
Ist der Aufruf erfolgreich, wird die URL zum Ablagedialog im Header Location zurückgegeben:
Response
HTTP/1.1 201 Created Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/a09dd457-5a21-4b90-8134-e562092b50ea
Schlägt das Erstellen des Ablagedialogs fehl, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen finden Sie unter Format der Antwort bei Fehlern.
Anzeigen des Ablagedialogs mit definierten Eigenschaften und Dateien
Rufen Sie die URL, die Sie im Header Location erhalten haben, im Browser auf, um dem Anwender den erstellten Ablagedialog anzuzeigen. Der Anwender kann die Eigenschaften bearbeiten und das Speichern der DMS-Objekte abschließen.
Ausführen weiterer Aktionen nach dem Speichern (optional)
Wenn Sie beim Erstellen des Ablagedialogs den Parameter successCallbackUri angeben und der Anwender das Speichern erfolgreich abgeschlossen hat, wird die URL aufgerufen. Sie können nach dieser Aktion weitere Schritte ausführen. Weitere Informationen finden Sie unter Feedback mithilfe von "SuccessCallback" und "Userdata".
Aktualisieren von DMS-Objekten mit Benutzerinteraktion
Freigegeben: HTML-Seite
Sie können das Feature Ablage zum Aktualisieren der Eigenschaften und der Datei eines DMS-Objektes aufrufen. Grundvoraussetzung für das Durchführen der Aktion sind die Zuordnungen (Mappings). Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern.
Um ein DMS-Objekt zu aktualisieren, müssen Sie folgende Schritte durchführen:
Ermitteln der ID zum bestehenden DMS-Objekt
Bereitstellen der zu speichernden Datei (optional)
Ermitteln der Linkrelation für den Ablagedialog
Erstellen eines Ablagedialogs mit definierten Eigenschaften und Dateien
Anzeigen des Ablagedialogs mit definierten Eigenschaften und Dateien
Ausführen weiterer Aktionen nach dem Speichern (optional)
Ermitteln der ID zum bestehenden DMS-Objekt
Im Kapitel Suchen von DMS-Objekten wird beschrieben, wie Sie die ID zu einem bestehenden DMS-Objekt ermitteln können. Hat das bereits vorhandene DMS-Objekt den d.3-Dokumentstatus Processing muss der authentifizierte Benutzer der Bearbeiter des DMS-Objektes sein.
Bereitstellen der zu speichernden Datei (optional)
Im Kapitel Bereitstellen von Dateien können Sie nachlesen, wie Sie eine Datei bereitstellen können.
Ermitteln der Linkrelation für den Ablagedialog
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln. Danach führen Sie eine HTTP Get-Anforderung auf die URL zu einem Repository wie folgt aus:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27 Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation new .
Response
{
"_links": {
"new": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/"
}
},
"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}Erstellen eines Ablagedialogs mit definierten Eigenschaften und Dateien
Führen Sie eine HTTP POST-Anforderung mit den benötigten Eigenschaften als Body auf die URL aus, die Sie in der Linkrelation new erhalten haben.
Request
POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json
{
"storeObjects": [{
"dmsObjectId": "D123456789",
"displayValue": "Please verify the XYZ invoice",
"filename": "myfile.txt",
"contentLocationUri": "/dms/blob/chunk/2016-May-24-14-20-26-393-1720.part",
"sourceId": "/myapp/sources/mysourcel",
"sourcePropertiesUri": "/myapp/sources/mysourcel/properties/myfile.haljson",
"successCallbackUri": "/myapp/sources/mysourcel/success/myfile"
},
{
...
}]
}Das JSON-Objekt, das beim POST übergeben wird, ist wie folgt beschrieben:
Eigenschaft | Beschreibung |
|---|---|
storeObjects | Gibt das Array der Elementeigenschaften und Dateien an, mit denen der Ablagedialog definiert werden soll. Informationen zu einem Element des Arrays finden Sie unter Definieren der Parameter zum Speichern. |
Wenn Sie nur ein einzelnes DMS-Objekt aktualisieren möchten, dann können Sie das JSON-Objekt der Elementeigenschaften ohne das übergeordnete Array storeObjects angeben.
Ist der Aufruf erfolgreich, wird die URL zum Ablagedialog im Header Location zurückgegeben:
Response
HTTP/1.1 201 Created Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/a09dd457-5a21-4b90-8134-e562092b50ea
Schlägt das Erstellen des Ablagedialogs fehl, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen finden Sie unter Format der Antwort bei Fehlern.
Anzeigen des Ablagedialogs mit definierten Eigenschaften und Dateien
Rufen Sie die URL zum Ablagedialog, die Sie im Header Location erhalten haben, im Browser auf, um dem Anwender den Ablagedialog anzuzeigen. Der Anwender kann die Eigenschaften bearbeiten und das Aktualisieren der DMS-Objekte abschließen.
Ausführen weiterer Aktionen nach dem Speichern (optional)
Wenn Sie beim Erstellen des Ablagedialogs den Parameter successCallbackUri angeben und der Anwender das Speichern erfolgreich abgeschlossen hat, wird die URL aufgerufen. Sie können nach dieser Aktion weitere Schritte ausführen. Weitere Informationen finden Sie unter Feedback mithilfe von "SuccessCallback" und "Userdata".
Ändern des aktuellen Bearbeiters und Dokumentenstatus
Sie können den Bearbeiter und den Dokumentstatus eines bestehenden DMS-Objekts in einem d.3-Repository aktualisieren, ohne dass ein Anwender eine Aktion ausführen muss. Voraussetzung für das Durchführen der Aktion sind die Zuordnungen (Mappings). Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern.
Um den Bearbeiter oder den Dokumentstatus eines DMS-Objekts zu ändern, müssen Sie folgende Schritte durchführen:
Ermitteln der URL zu einem Repository
Ermitteln der Linkrelationen zum bestehenden DMS-Objekt
Aufrufen der URL zum Ändern des Bearbeiters oder Dokumentstatus eines DMS-Objekts
Ermitteln der URL zu einem Repository
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Ermitteln der Linkrelationen zum bestehenden DMS-Objekt
Um eine URL zu einem bestehendem DMS-Objekt zu ermitteln, führen Sie eine Suche aus und werten Sie die Linkrelation displayVersion zu einem Element der Ergebnisliste aus. Im Kapitel Abrufen und Anzeigen der Ergebnisse eines Suchvorgangs finden Sie weitere Informationen zum Ausführen einer Suche und die Beschreibung eines Elements der Ergebnisliste.
Aufrufen der URL zum Ändern des DMS-Objektstatus und des Bearbeiters
Führen Sie eine HTTP PUT-Anforderung mit den benötigten Eigenschaften als Body auf die URL der bestehenden aktuellen Version des DMS-Objekts aus , die Sie in der Linkrelation displayVersion erhalten haben.
Im Folgenden finden Sie Beschreibungen zum JSON-Objekt, das bei der PUT -Anforderung übergeben wird:
Eigenschaft | Beschreibung |
|---|---|
property_state | Zielstatus des Dokuments. Mögliche Werte:
|
property_editor | Pflichtfeld beim Zielstatus Bearbeitung (Processing) und optional beim Zielstatus Prüfung (Verification). In anderen Zielstatus wird der Parameter ignoriert. Mögliche Werte:
Sie können sowohl die IDs von d.ecs identity provider als auch vom DMS-System verwenden. |
alterationText | Pflichtfeld beim Zielstatus Freigabe (Release). Text (maximal 120 Bytes), der bei der Statusänderung zur Dokumentversion gespeichert wird. Sie können z.B. einen Hinweis zum Änderungsgrad bereitstellen. |
Beispiel 1: Dokument in Status "Bearbeitung" überführen oder den Bearbeiter ändern mit eigener Zuordnung
Stellen Sie sicher, dass eine Zuordnung existiert, in der die Werte myprop1_ID auf property_state und myprop2_ID auf property_editor festgelegt sind.
Request
PUT/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001/v/current
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json
{
"sourceId": "/myapp/sources/mysource",
"sourceProperties": {
"properties": [
{
"key": "myprop1_ID",
"values": [
"Processing"
]
},
{
"key": "myprop2_ID",
"values": [
"97273358-d124-497c-97ce-977f72b32a33"
]
}
]
}
}Wenn der Aufruf erfolgreich ist, wird HTTP 200 OK zurückgegeben:
Response
HTTP/1.1 200 OK
Beispiel 2: Dokument in Status "Bearbeitung" überführen oder den Bearbeiter ändern mit Standardzuordnung
Request
PUT/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001/v/current
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json
{
"sourceId": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source",
"sourceProperties": {
"properties": [
{
"key": "property_state",
"values": [
"Processing"
]
},
{
"key": " property_editor",
"values": [
"97273358-d124-497c-97ce-977f72b32a33"
]
}
]
}
}Wenn der Aufruf erfolgreich ist, wird HTTP 200 OK zurückgegeben:
Response
HTTP/1.1 200 OK
Beispiel 3: Dokument in Status "Freigabe" überführen mit Standardzuordnung
Request
PUT/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001/v/current
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json
{
"sourceId": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source",
"alterationText": "updated file",
"sourceProperties": {
"properties": [
{
"key": "property_state",
"values": [
"Release"
]
}
]
}
}Wenn der Aufruf erfolgreich ist, wird HTTP 200 OK zurückgegeben:
Response
HTTP/1.1 200 OK
Wenn das Ändern des Bearbeiters oder Dokumentstatus fehlschlägt, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen finden Sie unter Format der Antwort bei Fehlern .
Allgemeines zum Ablagevorgang
In diesem Thema erfahren Sie mehr zu den Details zum Speichern von DMS-Objekten. Bevor Sie jedoch mit diesem Thema beginnen, ist es erforderlich, sich mit den Kapiteln zum Speichern und Aktualisieren von DMS-Objekten auseinanderzusetzen.
Definieren der Parameter zum Speichern
In diesem Kapitel erfahren Sie mehr zu den Parametern, die Sie zum Speichern von DMS-Objekten angeben können. Die Parameter gelten wahlweise für das Speichern mit oder ohne Benutzeraktion.
Festlegen eines JSON-Objektes zum Speichern
Das JSON-Objekt, das mit den HTTP-Anforderungen zum Speichern eines DMS-Objektes gesendet wird, enthält folgende Parameter:
Eigenschaft | Beschreibung |
|---|---|
displayValue | Gibt den Anzeigenamen des Elements an, das gespeichert wird. Der Anzeigename wird im Ablagedialog für den Anwender sichtbar. Dieser Parameter ist optional. |
filename | Gibt den Namen der zu speichernden Datei mit der Dateierweiterung an. Wenn Sie diesen Parameter festlegen, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Dokumentart zuordnen. Geben Sie diese Eigenschaft nicht an, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Aktenart zuordnen.
|
dmsObjectId | Gibt die ID des zu aktualisierenden DMS-Objektes an. Dieser Parameter wird nur beim Aktualisieren eines DMS-Objektes mit Benutzerinteraktion berücksichtigt. |
alterationText | Gibt den Änderungsgrund für die Aktualisierung eines DMS-Objektes an. In d.3 admin legen Sie fest, ob das Angeben des Parameters verpflichtend ist. Dieser Parameter wird nur beim Aktualisieren eines DMS-Objektes berücksichtigt. |
sourceCategory | Gibt an, welche Kategorie für die Zuordnungsverarbeitung beim Speichern verwendet werden soll. Geben Sie die ID der Quellkategorie an. Das Angeben dieser Eigenschaft ist verpflichtend, außer unter folgenden Bedingungen:
Wenn Sie mehrere DMS-Objekte mit Benutzerinteraktion speichern, dann wird nur die Quellkategorie des ersten Elements im Array storeObjects im Ablagedialog berücksichtigt. Diese Quellkategorie wird für alle weiteren Dateien, die Sie ablegen möchten, dem Anwender angezeigt. |
sourceId | Legt fest, zu welcher Quelle die Zuordnung gehört, die zum Speichern verwendet werden soll. Die Quelle muss existieren und das Quellsystem muss bei d.ecs http gateway registriert sein, damit die Eigenschaften unter sourcePropertiesUri oder sourceProperties angewendet werden. Weitere Informationen zum Bereitstellen einer Quelle finden Sie unter Definieren eines Quellsystems. Wenn Sie kein eigenes Quellsystem haben, können Sie auch das Standardquellsystem des d.3-Repositorys verwenden. Informationen über das Standardquellsystem finden sie unter Abrufen des Standardquellsystems zu einem d.3-Repository. |
sourcePropertiesUri | Gibt die URL an, unter der die DMSApp die Elementeigenschaften für die Zuordnungsverarbeitung und Duplikatsprüfung herunterladen soll. Vor dem Speichern des DMS-Objektes sendet die DMSApp eine HTTP GET-Anforderung an die URL, um die Quelleigenschaften für den Ablagevorgang zu ermitteln. Wenn es sich bei sourcePropertiesUri um eine relative URL handelt, werden die Benutzerinformationen des angemeldeten Benutzers in der HTTP-Anforderung ebenfalls übertragen (AuthSessionID). Dadurch haben Sie die Möglichkeit, z.B. eine Berechtigungsprüfung durchzuführen oder den aktuellen Benutzernamen zu berücksichtigen. Bei einer absoluten URL werden die Quelleigenschaften anonym angefordert (request). Unter "Festlegen der Quelleigenschaften" ist das bereitzustellende JSON-Objekt beschrieben. Alternativ zu dieser Eigenschaft können Sie die Eigenschaft sourceProperties verwenden. |
sourceProperties | Gibt ein JSON-Array mit Quelleigenschaften an, die für die Zuordnungsverarbeitung und Duplikatsprüfung verwendet werden. Unter "Festlegen der Quelleigenschaften" ist das bereitzustellende JSON-Objekt beschrieben. Alternativ zu dieser Eigenschaft können Sie die Eigenschaft sourcePropertiesUri verwenden. |
contentLocationUri | Gibt die URL zur temporär hochgeladenen Datei an. Weitere Informationen finden Sie unter Bereitstellung über temporäres Hochladen. Alternativ können Sie die Eigenschaft contentUri verwenden. Legen Sie diesen Parameter fest, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Dokumentart zuordnen. Geben Sie weder die contentLocationUri- noch die contentUri-Eigenschaft an, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Aktenart zuordnen. Diese Eigenschaft ist optional, wenn Sie ein DMS-Objekt aktualisieren oder eine Akte erstellen möchten. |
contentUri | Gibt die relative URL an, unter der die DMSApp die abzulegende Datei herunterlädt. Weitere Informationen finden Sie unter Bereitstellung über temporäres Hochladen. Alternativ können Sie die Eigenschaft contentLocationUri verwenden. Legen Sie diesen Parameter fest, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Dokumentart zuordnen. Geben Sie weder die contentLocationUri- noch die contentUri-Eigenschaft an, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Aktenart zuordnen. Diese Eigenschaft ist optional, wenn Sie ein DMS-Objekt aktualisieren oder eine Akte erstellen möchten. |
parentId | Gibt die DMS-Objekt-ID der Akte an, mit der das abzulegende Element verknüpft werden soll. Ist der Ablagevorgang erfolgreich, wird das abgelegte Element mit der entsprechenden Akte verknüpft. Wurde das abzulegende Element als Duplikat erkannt, wird das bereits vorhandene Element mit der Akte verknüpft. Wenn Sie eine Akte mit einer anderen Akte verknüpfen möchten, wird jedoch keine Duplikatsprüfung vorgenommen. Diese Eigenschaft wird ignoriert, wenn Sie ein DMS-Objekt aktualisieren. |
successCallbackUri | Gibt die URL an, die über HTTP POST aufgerufen wird, wenn der Ablagevorgang erfolgreich durchgeführt wurde. Die URL muss relativ sein. Weitere Informationen finden Sie unter Feedback mithilfe von "SuccessCallback" und "Userdata". Diese Eigenschaft ist optional. Sie können die Eigenschaft nur beim Speichern mit Benutzerinteraktion verwenden. |
Festlegen der Quelleigenschaften
Sie können die Quelleigenschaften direkt mithilfe des Parameters sourceProperties definieren oder mit der URL in sourcePropertiesUri bereitstellen.
Das JSON-Objekt ist wie folgt beschrieben:
Eigenschaft | Beschreibung |
|---|---|
properties | Gibt ein Array der Quelleigenschaften an, die für die Zuordnungsverarbeitung bereitgestellt werden. Es werden nur diejenigen Eigenschaften beim Speichern berücksichtigt, die vom Administrator in der Zuordnung konfiguriert wurden. |
uniqueTag | Gibt einen eindeutigen Hashcode an, der von der Quelle für das abzulegende Element festgelegt und von d.3 server zur Duplikatserkennung verwendet wird. Das Festlegen dieser Eigenschaft ist optional. |
userdata | Gibt ein Array von Optionen an, die zusätzlich im Ablagedialog angezeigt werden sollen. Das Angeben dieser Eigenschaft ist optional. Sie können die Eigenschaft nur beim Speichern mit Benutzerinteraktion verwenden. Weitere Informationen finden Sie unter Feedback mithilfe von "SuccessCallback" und "Userdata". |
checkHash | Gibt den Hash der zu speichernden Datei an. Der Hash der zu speichernden Datei hilft Ihnen sicherzustellen, dass Sie das Speichern einer Datei in einem d.3-Repository überprüfen können. Sobald die Hashes nicht übereinstimmen, wird das Speichern des Dokuments mit einer Fehlermeldung abgebrochen. Während des Speicherns wird serverseitig ein Hash von der zu speichernden Datei gebildet und mit dem Hash, den Sie generieren, verglichen und überprüft. Der Parameter muss dabei dem folgenden Aufbau entsprechen: HASHALGORITHM:base64encode(hashfunction(PAYLOAD)) Beispiel für eine Datei mit dem Inhalt "Example": SHA512:xrCRnH/mKK6QVpksSpF+XcA1qWFdSX9usr0UBj6q0+ZQjvyGgv7IKCPKPz3jEYaKcpkJRhZkKfAbOPnzPZymEA== Folgende Hashalgorithmen werden unterstützt:
Dieser Parameter ist optional. Führen Sie die Base64-Encodierung immer auf Byte-Ebene aus. Die Encodierung einer textuellen Repräsentation führt zu invaliden Hashwerten. Beispiele für das Erzeugen eines checkHash-Wertes unter Verwendung der Klassen aus System.Security.Cryptography in C#: private string CreateM5Hash(string filename)
{
using (var md5 = MD5.Create())
{
using (var stream = File.OpenRead(filename))
{
var retVal = md5.ComputeHash(stream);
//Bytes in retVal für eine Datei mit dem Inhalt "Example":
//45 155 209 108 21 173 26 160 179 111 217 119 62 110 20 172
return $"MD5:{Convert.ToBase64String(retVal)}";
//Hash base64-encodiert:
//MD5:ClJzBZf7T/oB/BF9nnHjqQ==
}
}
}
private string CreateSHA256Hash(string filename)
{
using (var sha256 = SHA256.Create())
{
using (var stream = File.OpenRead(filename))
{
var retVal = sha256.ComputeHash(stream);
//Bytes in retVal für eine Datei mit dem Inhalt "Example":
//53 239 154 101 221 213 246 176 70 65 37 206 150 167 54 152
//63 65 154 140 96 227 200 169 71 112 149 213 153 156 17 27
return $"SHA256:{Convert.ToBase64String(retVal)}";
//Hash base64-encodiert:
//SHA256:0Cn4fj2A+P2bG+Z8dCa0zB/0e0qdCoRhyCalnYxets0=
}
}
}
private string CreateSHA512Hash(string filename)
{
using (var sha512 = SHA512.Create())
{
using (var stream = File.OpenRead(filename))
{
var retVal = sha512.ComputeHash(stream);
//Bytes in retVal für eine Datei mit dem Inhalt "Example":
//72 237 177 122 242 252 39 57 63 98 44 167 119 228 162 20 106
//147 201 76 246 223 209 126 97 224 198 30 40 137 121 216 147
//21 15 16 1 103 84 101 60 241 95 82 14 126 211 137 170 235 180
//206 18 112 247 228 229 185 208 62 192 244 131 41
return $"SHA512:{Convert.ToBase64String(retVal)}";
//Hash base64-encodiert:
//SHA512:xrCRnH/mKK6QVpksSpF+XcA1qWFdSX9usr0UBj6q0+ZQjvyGgv7IKCPKPz3jEYaKcpkJRhZkKfAbOPnzPZymEA==
}
}
} |
Struktur eines Objekts im Array "properties"
Eigenschaft | Beschreibung |
|---|---|
key | Gibt die ID der Quelleigenschaft an. Es werden nur diejenigen Eigenschaften berücksichtigt, die von Ihnen angegeben und die vom Administrator in der Zuordnung konfiguriert wurden. Beim Aktualisieren eines DMS-Objektes werden nur die von Ihnen angegebenen Eigenschaften aktualisiert. Alle weiteren Werte der Eigenschaften des bereits vorhandenen DMS-Objektes bleiben bestehen. Wenn Sie das Erstellungsdatum (property_creation_date) des DMS-Objektes festlegen möchten, dann wird das Festlegen der Eigenschaft nur beim Speichern eines neuen DMS-Objektes ohne Benutzerinteraktion berücksichtigt. Weitere Informationen finden Sie unter Speichern eines neuen DMS-Objektes ohne Benutzerinteraktion. |
values | Gibt ein Array mit den zugehörigen Werten der Elementeigenschaft an. Auch wenn Sie nur einen Wert übergeben möchten, müssen Sie diesen Wert als JSON-Array übergeben. Sie können den d.3-Dokumentstatus für ein DMS-Objekt beim Speichern eines neuen DMS-Objektes festlegen. Mögliche Werte sind Processing, Verification und Release. Beim Aktualisieren eines DMS-Objektes werden Zuordnungen zu d.3-Dokumentstatus, d.3-Variantennummer, d.3-Dokument-ID und d.3-Dokumentnummer ignoriert. Eigenschaften mit der Kennzeichnung "nur lesend" werden beim Speichern nicht berücksichtigt. Beim Aktualisieren ohne Benutzerinteraktion muss der authentifizierte Benutzer der Bearbeiter des DMS-Objektes sein, wenn das bestehende DMS-Objekt den d.3-Dokumentstatus Processing hat. Geben Sie numerische Werte ohne Tausendertrennzeichen an. Als Dezimaltrennzeichen gilt der Punkt (.). Beispiel: Für den Wert 1.000,20 EUR geben Sie 1000.20 an. Geben Sie Datumswerte im Format YYYY-MM-DD an. Beispiel: Für den 05.12.2014 (DD.MM.YYYY) geben Sie 2014-12-05 an. Geben Sie Datumszeitwerte im Format YYYY-MM-DDTHH:mm:ss+01:00. Beispiel: 2015-02-18T23:59:59+01:00 für den 18.02.2015 um 23:59 Uhr und 59 Sekunden in der Zeitzone UTC+1 für Winterzeit in Deutschland. |
Beispiel 1: Bereitstellen der Datei und der Eigenschaften durch eine URL
Ein einfaches JSON-Objekt könnte wie folgt aussehen:
{
"filename": "myfile.txt",
"alterationText": "updated file",
"sourceCategory": "mycategory1_ID",
"sourceId": "/myapp/sources/mysource",
"contentUri": "/myapp/sources/mysource/myfile.txt",
"sourcePropertiesUri": "/myapp/sources/mysource/myfile.haljson"
}Beispiel 2: Direktes Angeben der Eigenschaften, inklusive der Parameter "userdata" und "successCallbackUri"
Das folgende JSON-Objekt enthält userdata und die Eigenschaften (properties). Zugleich wird uniqueTag für die Duplikatsprüfung festgelegt. Die ID der Akte wird in dem Parameter parentId festgelegt, um das neu zu erstellende DMS-Objekt zu verlinken:
{
"displayValue": "Please verify the XYZ invoice",
"filename": "myfile.txt",
"alterationText": "updated file",
"sourceCategory": "mycategory1_ID",
"sourceId": "/myapp/sources/mysource",
"parentId": "P123456789",
"contentLocationUri": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43",
"successCallbackUri": "/myapp/sources/mysource/myfile/success",
"sourceProperties": {
"properties": [{
"key": "myprop1_ID",
"values": ["Please verify the XYZ invoice"]
},
{
"key": "myprop2_ID",
"values": ["Name1@contoso.com","Name2@samplecompany.de"]
}
],
"userdata": [{
"key": "postProcessingOption",
"display": "My post processing options",
"values": [
{"value":"1", "display": "Action 1", "default":"false"},
{"value":"2", "display": "Default action 2", "default":"true"},
{"value":"3", "display": "Action 3", "default":"false"}
]
}
],
"uniqueTag": "123456789",
"checkHash": "MD5:ClJzBZf7T/oB/BF9nnHjqQ=="
}
}Bereitstellen von Dateien
Beim Speichern von DMS-Objekten werden deren Eigenschaften und Kategorien gespeichert. Um Dateien speichern zu können, müssen diese der DMSApp bereitgestellt werden und die Quellkategorie muss in der Zuordnungsverarbeitung einer Dokumentart zugeordnet werden. Sie haben zwei Möglichkeiten für die Bereitstellung der Dateien:
Bereitstellen einer Datei mit einer URL
In diesem Kapitel erfahren Sie, wie Sie eine Datei mithilfe einer URL bereitstellen. Beim Speichern von DMS-Objekten geben Sie die URL zu einer Datei in der Eigenschaft contentUri an. Vor dem Speichern des DMS-Objekts lädt die DMSApp die Datei von der angegebenen URL (contentUri) herunter. Bei der URL muss es sich um eine relative URL handeln. Beim Herunterladen werden die Benutzerinformationen des angemeldeten Anwenders in der HTTP-Anforderung ebenfalls übertragen (AuthSessionID). Mithilfe von AuthSessionID haben Sie die Möglichkeit, den Anwender zu identifizieren, um z.B. eine Berechtigungsprüfung durchzuführen.
Da die Datei in einer Anforderung (Request) heruntergeladen wird, eignet sich dieses Verfahren nicht für größere Dateien. Für größere Dateien verwenden Sie das Verfahren zum temporären Hochladen von Dateien. Weitere Informationen finden Sie unter Bereitstellen einer Datei durch temporäres Hochladen.
Downloaden der bereitgestellten Datei
Die DMSApp führt eine HTTP GET-Anforderung auf die im Parameter contentUri angegebene URL aus. Ein Beispiel für die HTTP GET-Anforderung der DMSApp für Ihr Quellsystem sieht wie folgt aus, wenn contentUri folgender URL /myapp/sources/mysource/myfile.txt entspricht:
Request
GET /myapp/sources/mysource/myfile.txt Accept: application/octet-stream, */* AuthSessionID: SampleAuthsessionId
Die Antwort Ihres Quellsystems muss wie folgt aussehen:
Response
HTTP/1.1 200 OK Content-Length: 3495 <binary content>
Bereitstellen einer Datei durch temporäres Hochladen
In diesem Kapitel erfahren Sie, wie Sie eine Datei vorläufig bereitstellen, indem Sie die Datei temporär hochladen. Das temporäre Hochladen ist besonders bei großen Dateien sinnvoll. Mit der URL (contentLocationUri) zur temporär hochgeladenen Datei können Sie anschließend das DMS-Objekt speichern.
Um eine Datei temporär hochzuladen, müssen Sie folgende Schritte durchführen:
Ermitteln der URL zu einem Repository
Ermitteln der Linkrelation zum temporären Hochladen der Datei
Aufrufen der URL zum temporären Hochladen der Datei
Weitere Aufrufe der URL zum temporären Hochladen der Datei (optional)
Ein temporäres Hochladen einer Datei ohne die Angabe einer ID zu einem Repository ist nicht möglich.
Ermitteln der URL zu einem Repository
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Ermitteln der Linkrelation zum temporären Hochladen der Datei
Rufen Sie die URL zu einem Repository wie folgt auf:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27 Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation chunkedupload.
Response
{
"_links": {
"chunkedupload": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/"
}
},
"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}Aufrufen der URL zum temporären Hochladen der Datei
Führen Sie eine HTTP POST-Anforderung mit den Binärdaten als Body auf die URL aus, die Sie in der Linkrelation chunkedupload erhalten haben. Wenn der Vorgang erfolgreich war, erhalten Sie den HTTP-Statuscode 201 und die URL (contentLocationUri) im HTTP-Header Location.
Request
POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/ Origin: https://baseuri Content-Type: application/octet-stream <binary content>
Response
HTTP/1.1 201 Created Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43
Bei der HTTP Post-Anforderung wird der komplette Body als Binärdaten der hochzuladenden Datei behandelt. Ein Upload mittels multipart/form-data ist derzeit nicht möglich.
Die maximale Größe des Bodys ist auf 100 MB begrenzt. Wir empfehlen eine Bodygröße von 25 MB. Wenn Sie größere Dateien hochladen möchten, können Sie die Datei in verschiedene Teilstücke (Chunks) unterteilen. Weitere Informationen finden Sie im folgenden Abschnitt.
Weitere Aufrufe der URL zum temporären Hochladen der Datei (optional)
Sie haben die Möglichkeit, das Hochladen auf mehrere HTTP-Anforderungen aufzuteilen, um bei größeren Dateien einen Timeout zu vermeiden.
Gehen Sie dazu wie folgt vor:
Teilen Sie die hochzuladende Datei in verschiedene Teilstücke (Chunks).
Laden Sie das erste Teilstück hoch, so wie es unter "Aufrufen der URL zum temporären Hochladen der Datei" beschrieben ist.
Laden Sie das nächste Teilstück hoch, indem Sie eine HTTP POST-Anforderung auf die URL ausführen, die Sie im Header der Antwort zum ersten Teilstück unter Location erhalten haben.
Wiederholen Sie den vorherigen Schritt nacheinander für alle Teilstücke in der richtigen Reihenfolge.
Request
POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43 Content-Type: application/octet-stream <binary content for chunk>
Response
HTTP/1.1 200 OK
Beachten Sie beim Hochladen mehrerer Teilstücke Folgendes:
Die Teilstücke dürfen nur sequenziell hochgeladen werden.
Die Reihenfolge der HTTP POST-Anforderung der Teilstücke ist strikt einzuhalten.
Sollte es bei einer HTTP POST-Anforderung zu einem Fehler kommen (z.B. HTTP-Statuscode ist nicht 200), müssen Sie die Datei in allen Teilstücken erneut hochladen. Das erneute Hochladen einzelner Teilstücke ist nicht möglich.
Sie erhalten auf die Anforderungen folgende mögliche Antworten:
Statuscode | Beschreibung |
|---|---|
200 OK | Ein Teilstück wurde erfolgreich hochgeladen. |
201 Created | Das erste Teilstück wurde erfolgreich hochgeladen. |
404 Not Found | Die Ressource wurde nicht gefunden. Es wurde z.B. eine unbekannte Repository-ID angegeben. |
500 Internal Server Error | Es trat ein interner Fehler bei der Verarbeitung auf. |
Format der Antwort bei Fehlern
Freigegeben: JSON-Repräsentation
In diesem Kapitel erfahren Sie, in welchem Format Fehler ausgegeben werden. Abhängig vom Verarbeitungsergebnis des Ablagevorgangs wird die HTTP-Anforderung mit verschiedenen HTTP-Statuscodes beantwortet. Optional werden beschreibende Informationen zurückgeliefert.
Beispiel für eine Antwort für eine fehlgeschlagene Anforderung (Request):
Response
HTTP/1.1 400 BadRequest
{
"reason": "10019: Missing value for a mandatory property.",
"severity": 1,
"errorCode": 10019
}Beschreibung der Parameter zu der Antwort auf die fehlerhafte Anforderung:
Eigenschaft | Beschreibung |
|---|---|
reason | Ein optionaler kurzer Beschreibungstext, weshalb der Fehler aufgetreten ist. Dieser Text wird als Titel der Fehlermeldung verwendet. |
hint | Ein optionaler Hinweistext für den Anwender mit Tipps für die Fehlerbehebung. |
details | Optionale Detailinformationen zum Fehler. |
severity | Optionaler Schweregrad des Fehlers. Folgende Werte sind möglich: Success = 0, Information = 1, Warning = 2, Error = 3 |
errorCode | Ein optionaler Fehlercode, den d.3 server zurückgegeben hat. |
requestId | ID der zugehörigen Anforderung. Die ID wird bei weiteren Anforderungen an andere Apps übergeben und dient der Nachverfolgung bei der Verarbeitung einer Aktion. |
Zusätzliche Parameter, wenn das abzulegende DMS-Objekt als Duplikat erkannt wird:
Eigenschaft | Beschreibung |
|---|---|
dmsObjectId | Enthält die ID des bereits existierenden DMS-Objektes. |
_links | Enthält die Linkrelation dmsobject, die auf das bereits existierende DMS-Objekt verweist. |
Die Bearbeitung eines Elements durch Anwender in Microsoft Office 365 erfordert die exklusive Bearbeitung eines DMS-Objektes. Falls die Verarbeitung durch Office 365 noch nicht abgeschlossen ist, schlägt die Anforderung fehl und Sie erhalten als Antwort den Statuscode 403 Forbidden mit entsprechenden Fehlerinformation. Bitte wiederholen Sie die Anforderung zu einem späteren Zeitpunkt.
Format der Antwort für erfolgreiche Anforderungen (Requests) mit Detailinformationen
Freigegeben: JSON-Repräsentation
In diesem Kapitel erfahren Sie, in welchem Format Detailinformationen zu erfolgreichen Anforderungen (Requests) ausgegeben werden. Abhängig vom Verarbeitungsergebnis wird die HTTP-Anforderung mit beschreibenden Detailinformationen zurückgeliefert.
Beschreibung der Parameter zur Antwort auf die erfolgreiche Anforderung mit Detailinformationen:
Eigenschaft | Beschreibung |
|---|---|
responseDetails | Array mit Detailinformationen zur Anforderung |
Beschreibung der Parameter eines responseDetails-Objekts:
Eigenschaft | Beschreibung |
|---|---|
code | Code vom Typ String, der definiert, um welche Detailinformation es sich handelt:
|
title | Titel, der kurz benennt, um welche Detailinformation es sich handelt. |
detail | Detaillierte Beschreibung zur Detailinformation. |
hint | Optionaler weiterführender Hinweis mit möglichen Handlungsinformationen. |
data | Optionaler Parameter, der weitere Daten zu der Detailinformation enthält, um die Daten z.B. programmatisch auszuwerten. |
Beschreibung der Parameter eines ResponseDetailData-Objekts:
Eigenschaft | Beschreibung |
|---|---|
destinationItemValue | Aktueller Wert des Zielelements. |
sourceItemId | ID des Quellelements, auf das sich die Detailinformationen bezieht (z.B. Quelle, Quelleigenschaft, Quellkategorie). |
destinationItemId | ID des Zielelements, das dem Quellelement zugeordnet ist (z.B. Zieleigenschaft, Zielkategorie). |
sourceItemValue | Wert des Quellelements, der in das Zielelement geschrieben werden soll. |
Beispiele für eine Antwort für eine erfolgreiche Anforderung (Request) mit Detailinformationen zu den jeweiligen ResponseDetail-Codes:
Beispiel 1: DmsApp-Mapping-IgnoredNotModifiableDestinationProperty
HTTP/1.1 200 OK
{
"responseDetails": [
{
"code": "DmsApp-Mapping-IgnoredNotModifiableDestinationProperty",
"title": "Ignored source property",
"detail": "The source property with the ID 'myprop1_ID' was ignored because the mapped destination property with the ID '5' ('Name') is not modifiable. The current value for the property is 'Value of Name' and is not overwritten by the given value 'Value for myprop1'.",
"hint": "Please adjust the d.3 configuration if you still want to write the values or contact your administrator.",
"data": {
"sourceItemId": "myprop1_ID",
"sourceItemValue": "Value for myprop1",
"destinationItemId": "5",
"destinationItemValue": "Value of Name"
}
}
]
}Beispiel 2: DmsApp-Mapping-NoMappingFoundForSourceCategory
HTTP/1.1 200 OK
{
"responseDetails": [
{
"code": "DmsApp-Mapping-NoMappingFoundForSourceCategory",
"title": "Ignored source category",
"detail": "The source category with the ID 'CAT1' was ignored because no mapping to a destination category was found.",
"hint": "Please configure a mapping for the given source category or contact your administrator.",
"data": {
"sourceItemId": "CAT1"
}
}
]
}Beispiel 3: DmsApp-Mapping-IgnoredDestinationSystemPropertyDueToUpdateMode
HTTP/1.1 200 OK
{
"responseDetails": [
{
"code": "DmsApp-Mapping-IgnoredDestinationSystemPropertyDueToUpdateMode",
"title": "Ignored source property",
"detail": "The source property with the ID 'PROP2' was ignored because the mapped destination property with the ID 'property_document_number', which is a system property, cannot be changed in update mode.",
"data": {
"sourceItemId": "PROP2",
"destinationItemId": "property_document_number"
}
}
]
}Beispiel 4: DmsApp-Mapping-MappingForSourceNotFound
HTTP/1.1 200 OK
{
"responseDetails": [
{
"code": "DmsApp-Mapping-MappingForSourceNotFound",
"title": "Mapping configuration not found",
"detail": "No mapping configuration was found for the source with the ID '/myapp/sources/mysourcex'. For this reason, no mapping is applied and any given values for properties or categories are ignored.",
"hint": "Please configure a mapping for the given source or contact your administrator.",
"data": {
"sourceItemId": "/myapp/sources/mysourcex"
}
}
]
}Beispiel 5: DmsApp-Mapping-NoDestinationCategoryFoundWithDestinationProperty
HTTP/1.1 200 OK
{
"responseDetails": [
{
"code": "DmsApp-Mapping-NoDestinationCategoryFoundWithDestinationProperty",
"title": "Ignored source property",
"detail": "The source property with the ID 'myprop1_ID' was ignored because the mapped destination property with the ID '5' was not found in any destination category.",
"data": {
"sourceItemId": "myprop1_ID",
"destinationItemId": "5"
}
}
]
}Beispiel 6: DmsApp-Mapping-NoMappingFoundForSourceProperty
HTTP/1.1 200 OK
{
"responseDetails": [
{
"code": "DmsApp-Mapping-NoMappingFoundForSourceProperty",
"title": "Ignored source property",
"detail": "The source property with the ID 'PROP3' was ignored because no mapping to a destination property was found.",
"hint": "Please configure a mapping for the given source property or contact your administrator.",
"data": {
"sourceItemId": "PROP3"
}
}
]
}Beispiel 7: DmsApp-Mapping-NoSourceProperties
HTTP/1.1 200 OK
{
"responseDetails": [
{
"code": "DmsApp-Mapping-NoSourceProperties",
"title": "No source properties given",
"detail": "No source properties were given that could be mapped."
}
]
}Beispiel 8: DmsApp-Mapping-NoValuesGivenForSourceProperty
HTTP/1.1 200 OK
{
"responseDetails": [
{
"code": "DmsApp-Mapping-NoValuesGivenForSourceProperty",
"title": "Ignored source property",
"detail": "The source property with the ID 'myprop1_ID' was ignored because no values were given.",
"data": {
"sourceItemId": "myprop1_ID"
}
}
]
}Beispiel 9: DmsApp-Mapping-PropertyStatusIgnored
HTTP/1.1 200 OK
{
"responseDetails": [
{
"code": "DmsApp-Mapping-PropertyStatusIgnored",
"title": "Ignored source property",
"detail": "The source property with the ID 'myprop1_ID' was ignored because it is mapped to the destination property 'status' (ID: 'property_state') and other source properties were given. A status transfer is only possible if no other properties are changed.",
"hint": "For a status transfer please send only the property ‘status’. Change the other properties in another request.",
"data": {
"sourceItemId": "myprop1_ID",
"destinationItemId": "property_state"
}
}
]
}Beispiel 10: DmsApp-Mapping-UnknownDestinationCategory
HTTP/1.1 200 OK
{
"responseDetails": [
{
"code": "DmsApp-Mapping-UnknownDestinationCategory",
"title": "Ignored source category",
"detail": "The source category with the ID 'mycat1_ID' was ignored because the mapped destination category with the id 'destcat1_ID' is unknown or the user does not have permission for the category.",
"data": {
"sourceItemId": "mycat1_ID",
"destinationItemId": "destcat1_ID"
}
}
]
}Feedback mithilfe von "SuccessCallback" und "Userdata"
In diesem Kapitel erfahren Sie, wie Sie Feedback zum Speichervorgang erhalten. Zusätzlich können Sie dem Anwender eigene Optionen im Ablagedialog bereitstellen. Die Optionen, die ein Anwender ausgewählt hat, können Sie in Ihrem Quellsystem auswerten, wenn der Speichervorgang erfolgreich war. Sie können aber auch Feedback erhalten, ohne dem Anwender eigene Optionen zur Verfügung zu stellen.
Bereitstellen von Optionen für den Anwender im Ablagedialog
Neben den Daten zur Zuordnungsverarbeitung können Sie in dem Ablagedialog Ihren Anwendern eigene Optionen anzeigen. Der Anwender kann eine der Optionen auswählen. Um diese Optionen bereitzustellen, fügen Sie dem JSON-Objekt sourceProperties das Array userdata hinzu. Weitere Informationen finden Sie unter Definieren der Parameter zum Speichern.
Sie können dem Anwender eine Auswahlmöglichkeit vorschlagen. Falls Sie keine Option vorschlagen, muss der Anwender selbst vor dem Speichern des DMS-Objektes eine Option auswählen. Nach dem erfolgreichen Speichern wird die vom Anwender ausgewählte Option an die URL (successCallbackUri) übergeben.
Das JSON-Objekt sourceProperties mit dem Array userdata sieht wie folgt aus:
{
"properties": [
...
],
"userdata": [{
"key": "postProcessingOption",
"display": "My post processing options",
"values": [
{"value":"1", "display": "Action 1", "default":"false"},
{"value":"2", "display": "Default action 2", "default":"true"},
{"value":"3", "display": "Action 3", "default":"false"}
]
}]
}
Feedback nach erfolgreichem Speichern
Möchten Sie Feedback erhalten, sobald das DMS-Objekt erfolgreich gespeichert wurde, geben Sie den Parameter successCallbackUri an. Sie erhalten eine HTTP POST-Anforderung für diese URL mit einem JSON-Objekt in der Anforderung.
Die Anforderung, die die DMSApp sendet, könnte wie folgt aussehen:
Request
POST /myapp/sources/mysource/myfile/success
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json
{
"_links": {
"dmsobjectwithmapping": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000001234?sourceId=%2Fmyapp%2Fsources%2Fmysourc"
}
},
"userdata": [
{
"postProcessingOption": ["2"]
}
]
}
Beschreibung des JSON-Objektes, das beim POST übergeben wird:
Eigenschaft | Beschreibung |
|---|---|
_links | Enthält die Linkrelation dmsobjectwithmapping. Die Linkrelation ist eine relative URL zu den Details des gespeicherten DMS-Objektes. |
userdata | Gibt das Array mit den Ergebnissen, welche Optionen ein Anwender ausgewählt hat, als Name-Wert-Paare (Key-Value) an. Die Eigenschaft userdata existiert nur, wenn Sie dem Anwender Optionen bereitgestellt haben. |
Geben Sie als Antwort auf die Anforderung der DMSApp einen entsprechenden HTTP-Statuscode zurück. Anhand Ihres Statuscodes zeigt der Ablagedialog eine entsprechende Erfolgs- oder Fehlermeldung an. Sie können weitere Informationen in Ihrer Antwort als JSON-Objekt übergeben.
Beispiel für Ihre Antwort für eine Anforderung (Request):
Response
HTTP/1.1 400 BadRequest
{
"reason": "My error message",
"severity": 3
}Beschreibung der Parameter zu der Antwort auf die Anforderung:
Eigenschaft | Beschreibung |
|---|---|
reason | Ein optionaler kurzer Beschreibungstext, weshalb der Fehler aufgetreten ist. Dieser Text wird als Titel der Fehlermeldung verwendet. |
hint | Ein optionaler Hinweistext für den Anwender mit Tipps für die Fehlerbehebung. |
details | Optionale Detailinformationen zum Fehler. |
severity | Optionaler Schweregrad des Fehlers. Folgende Werte sind möglich: Success = 0, Information = 1, Warning = 2, Error = 3 |
Löschen der aktuellen Version eines DMS-Objektes ohne Benutzerinteraktion
Freigegeben: JSON-Repräsentation
Sie können die aktuelle Version eines bestehenden DMS-Objektes in einem d.3-Repository löschen, ohne dass ein Anwender eine Aktion ausführen muss.
Um die aktuelle Version eines DMS-Objektes zu löschen, müssen Sie folgende Schritte durchführen:
Ermitteln der URL zu einem Repository
Ermitteln der Linkrelation zum bestehenden DMS-Objekt
Ermitteln der Linkrelation zum Löschen der aktuellen Version eines bestehenden DMS-Objektes
Aufrufen der URL zum Löschen der aktuellen Version des DMS-Objektes
Ermitteln der URL zu einem Repository
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Ermitteln der Linkrelation zum bestehenden DMS-Objekt
Um eine URL zu einem bestehendem DMS-Objekt zu ermitteln, führen Sie eine Suche aus und werten Sie die Linkrelation self zu einem Element der Ergebnisliste aus. Im Kapitel Abrufen und Anzeigen der Ergebnisse eines Suchvorgangs finden Sie weitere Informationen zum Ausführen einer Suche und die Beschreibung eines Elements der Ergebnisliste.
Ermitteln der Linkrelation zum Löschen der aktuellen Version des bestehenden DMS-Objektes
Um die URL zum Löschen der aktuellen Version des DMS-Objektes zu ermitteln, werten Sie die Linkrelationen delete und deleteWithReason zu einem Element der Ergebnisliste aus. Wenn ein Löschgrund z.B. beim Löschen einer bereits freigegebenen Version zwingend angegeben werden muss, ist die Linkrelelation deleteWithReason vorhanden. Ansonsten enthält die Linkrelation delete die URL zum Löschen. Fehlen beide Linkrelationen, überprüfen Sie bitte die Berechtigungen zum Löschen der Version des DMS-Objektes. Wenn das vorhandene DMS-Objekt sich in Bearbeitung befindet, muss der authentifizierte Benutzer der Bearbeiter des DMS-Objektes sein.
Aufrufen der URL zum Löschen der aktuellen Version des DMS-Objektes
Führen Sie eine HTTP DELETE-Anforderung auf die ermittelten Linkrelationen delete oder deleteWithReason zum bestehenden DMS-Objektes aus. Wenn Sie einen Löschgrund übermittelt möchten, muss dieser im Body der Anforderung angegeben werden. Der Löschgrund muss mindestens 3 Zeichen und darf maximal 80 Zeichen umfassen.
Request
DELETE /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json
{"reason":"Created accidentally."}Ist der Aufruf erfolgreich, wird HTTP 200 OK zurückgegeben. Ist der Body leer, wurde das komplette DMS-Objekt gelöscht. Enthält das DMS-Objekt weitere Versionen, enthält der Body weitere Linkrelationen. Ist die Linkrelation self enthalten, existieren weitere Versionen zum DMS-Objekt und Sie können mit dieser URL weitere Details zum DMS-Objekt abrufen. Mit den Linkrelationen delete oder deleteWithReason können Sie die nächste Version des DMS-Objektes löschen. Sind diese Linkrelationen nicht vorhanden, fehlen dem Benutzer die Berechtigungen, die nächste Version zu löschen.
Response
HTTP/1.1 200 OK
{
"_links": {
"self": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001"
},
"delete": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001"
}
}
}Schlägt das Löschen der Version fehl, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen finden Sie unter Übersicht über Formate bei Fehlern.
Die Bearbeitung eines Elements durch Anwender in Microsoft Office 365 erfordert die exklusive Bearbeitung eines DMS-Objektes. Falls die Verarbeitung durch Office 365 noch nicht abgeschlossen ist, schlägt die Anforderung fehl und Sie erhalten als Antwort den Statuscode 403 Forbidden mit entsprechenden Fehlerinformation. Bitte wiederholen Sie die Anforderung zu einem späteren Zeitpunkt.
Abrufen, Speichern und Bearbeiten von Zuordnungen
Freigegeben: JSON-Repräsentation
In diesem Kapitel erfahren Sie, wie Sie Zuordnungen sowohl für Eigenschaften als auch für Kategorien von einem Quellsystem (z.B. einer E-Mail-Anwendung) zu einem d.3-Repository erstellen und verwalten können. Diese Zuordnungen werden bei der Ablage, beim Abrufen von Details eines Elementes und beim Abrufen und Anzeigen von Ergebnissen eines Suchvorgangs innerhalb von d.3one-Integrationen verwendet. Beim Speichern von Zuordnungen legen Sie fest, welche externen Daten (z.B. die Eigenschaften einer E-Mail) welcher d.3-Dokumenteigenschaft zugewiesen werden.
Pro Quelle eines Quellsystems kann es ausschließlich eine einzige Zuordnung geben.
Im Kapitel Definieren eines Quellsystems erfahren Sie, wie Sie eine Quelle für eine Zuordnung bereitstellen können. Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern. Wissenswertes zu schreibenden Zugriffen finden Sie unter Grundlegendes zu schreibenden Zugriffen.
Ermitteln der Linkrelation für das Verwalten von Zuordnungen
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln. Danach führen Sie eine HTTP Get-Anforderung für die REST-Ressource zu einem Repository wie folgt aus:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27 Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation mappingconfig.
Response
{
"_links": {
"mappingconfig": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/"
}
},
"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}Speichern von Zuordnungen
Führen Sie eine HTTP POST-Anforderung mit den Zuordnungen für Ihr Quellsystem als Body für die URL aus, die Sie in der Linkrelation mappingconfig erhalten haben. Nach dem erfolgreichen Speichern erhalten Sie den HTTP-Statuscode 201 Created.
Request
POST https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m HTTP/1.1
Origin: https://host
Accept: application/hal+json
Content-Type: application/hal+json
{
name: "My Source",
sourceId: "/myapp/sources/mysource",
mappingItems: [{
destination: "RECH",
source: "mycategory1_ID",
type: 1
},
{
destination: "3",
source: "myprop1_ID",
type: 0
},
{
destination: "property_caption",
source: "myprop2_ID",
type: 0
}]
}Das JSON-Objekt, das beim POST übergeben wird, ist wie folgt beschrieben:
Eigenschaft | Eigenschaft eines enthaltenen Objekts | Beschreibung |
|---|---|---|
name | - | Gibt den Namen der Zuordnung an. |
sourceId | - | Gibt den eindeutigen Bezeichner der Quelle an. Die ID muss eine relative URI sein. Die relative URI sollte mit dem Namen der App beginnen, die das Quellsystem bereitstellt, damit eine Eindeutigkeit gewährleistet ist (z.B. /myapp/sources/mysource). |
mappingItems | - | Gibt das Array mit den Elementen der Zuordnung an. Dieses Array ordnet die Eigenschaften und Kategorien des Quellsystems zu den Eigenschaften und Kategorien des d.3-Repositorys zu. |
type | Gibt den Typ des Zuordnungselements an. Folgende Werte sind möglich: Bei Wert 0 bezieht sich das Zuordnungselement auf eine Eigenschaft. Bei Wert 1 bezieht sich das Zuordnungselement auf eine Kategorie. | |
source | Gibt die ID der Eigenschaft im Quellsystem an. | |
destination | Wenn Sie eine Kategorie zuordnen, dann gibt destination die ID der Kategorie im d.3-Repository an. Wenn Sie eine Eigenschaft zuordnen, dann kann destination einen der folgenden Werte enthalten:
Wenn Sie das Erstellungsdatum (property_creation_date) des DMS-Objektes festlegen möchten, dann wird das Festlegen der Eigenschaft nur beim Speichern eines neuen DMS-Objektes ohne Benutzerinteraktion berücksichtigt. Weitere Informationen finden Sie unter Speichern eines neuen DMS-Objektes ohne Benutzerinteraktion. Bitte beachten Sie, dass Sie nur d.3-Eigenschaften als Ziel angeben können, die mindestens einer d.3-Kategorie als Eigenschaft zugewiesen sind. |
Abrufen der gespeicherten Zuordnungen
Führen Sie eine HTTP GET-Anforderung für die URL /dms/r/<RepositoryID>/m?sourceId=<SourceID> aus, um die Zuordnungen abzurufen. Der Wert der Eigenschaft sourceID gibt den eindeutigen Bezeichner der Quelle an (z.B. /myapp/sources/mysource).
Request
GET https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m?sourceId=%2Fmyapp%2Fsources%2Fmysource HTTP/1.1 Accept: application/hal+json
Sie erhalten als Antwort das Objekt mit den gespeicherten Zuordnungen.
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
{
mappings: [{
_links: {
self: {
href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID>"
}
}
name: "My Source",
sourceId: "/myapp/sources/mysource",
mappingItems: [{
destination: "RECH",
source: "mycategory1_ID",
type: 1
},
{
destination: "3",
source: "myprop1_ID",
type: 0
},
{
destination: "property_caption",
source: "myprop2_ID",
type: 0
}]
}]
}Die Eigenschaften der Objekte sind die gleichen Eigenschaften wie beim Speichern von Zuordnungen.
Löschen einer gespeicherten Zuordnung
Wenn Sie die Zuordnungen für Ihre Quelle abrufen, erhalten Sie pro Zuordnung eine Linkrelation zu dieser gespeicherten Zuordnung (_links.self.href). Für diese URL können Sie eine HTTP Delete-Anforderung ausführen, um die Zuordnung zu löschen.
Request
DELETE https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID> HTTP/1.1 Origin: https://host Accept: application/hal+json
Bearbeiten einer gespeicherten Zuordnung
Wenn Sie die Zuordnungen für Ihre Quelle abrufen, erhalten Sie pro Zuordnung eine Linkrelation zu dieser gespeicherten Zuordnung (_links.self.href). Für diese URL können Sie eine HTTP PUT-Anforderung zum Aktualisieren der Zuordnung ausführen. Das Objekt, das Sie übergeben, entspricht dem Objekt zum Speichern einer Zuordnung.
Request
PUT https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID> HTTP/1.1
Origin: https://host
Accept: application/hal+json
Content-Type: application/hal+json
{
name: "My Source",
sourceId: "/myapp/sources/mysource",
mappingItems: [{
destination: "RECH",
source: "mycategory1_ID",
type: 1
},
{
destination: "3",
source: "myprop1_ID",
type: 0
},
{
destination: "property_caption",
source: "myprop2_ID",
type: 0
}]
}Abrufen und Speichern der Notizen eines DMS-Objektes
Freigegeben: JSON-Repräsentation
In diesem Kapitel erfahren Sie, wie Sie die Notizen eines DMS-Objektes abrufen und speichern können.
Um die Notizen eines DMS-Objektes abzurufen oder zu speichern, müssen Sie folgende Schritte durchführen:
Ermitteln der URL zu einem Repository
Ermitteln und Aufrufen der Linkrelation zum Abrufen der Details eines DMS-Objektes
Ermitteln der Linkrelation zum Abrufen der Notizen eines DMS-Objektes
Aufrufen der URL für die Notizen eines DMS-Objektes
Ermitteln der URL zu einem Repository
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Ermitteln und Aufrufen der Linkrelation zum Abrufen der Details eines DMS-Objektes
Im Kapitel Abrufen und Anzeigen von Details eines DMS-Objektes können Sie nachlesen, wie Sie die URL zum Abrufen der Details eines DMS-Objektes ermitteln und aufrufen.
Ermitteln der Linkrelation zum Abrufen der Notizen eines DMS-Objektes
Das JSON-Objekt zu den Details eines DMS-Objektes enthält die Linkrelation notes , mit deren Hilfe Sie die Notizen des DMS-Objektes abrufen können.
Response
{
"_links": {
"notes":{
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n"
}
},
"id": "D000000123"
}Abrufen der Notizen eines DMS-Objektes
Rufen Sie die Notizen des DMS-Objektes mit der zuvor ermittelten URL wie folgt ab:
Request
GET https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n HTTP/1.1 Accept: application/hal+json
Sie erhalten als Antwort das Objekt mit den Notizen des DMS-Objektes:
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
{
"_links": {
"self": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n"
}
},
"notes":[{
"creator" : {
"id": "MargaS"
"displayName": "Marga Schilling"
},
"text": "This is a sample text."
"created": "2019-09-03T09:09:09.453+02:00"
}
]
}Eigenschaft | Beschreibung |
|---|---|
_links | self: selbstverweisender Link (Self-Link) |
notes | Gibt das Array mit den Notizelementen des DMS-Objektes an. |
Struktur eines Notizelementes
Eigenschaft | Beschreibung |
|---|---|
creator | Gibt ein Objekt mit den Informationen zum Benutzer zurück, der die Notiz verfasst hat. |
text | Enthält den Inhalt der Notiz. |
created | Gibt den eindeutigen Zeitstempel des Verfassungszeitpunkts der Notiz an. Der Zeitstempel wird im ISO-Format zurückgegeben. |
Struktur eines Erstellerobjektes
Eigenschaft | Beschreibung |
|---|---|
id | Gibt die eindeutige ID des d.3-Benutzers zurück. |
displayName | Gibt den Anzeigenamen des d.3-Benutzers zurück. |
Speichern der Notizen eines DMS-Objektes
Mit einer HTTP POST -Anforderung für die zuvor ermittelte URL können Sie eine Notiz zu einem DMS-Objekt erstellen. Wenn Sie mehrere Notizen erstellen möchten, wiederholen Sie den Vorgang. Speichern Sie eine Notiz wie folgt ab:
Request
POST https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n HTTP/1.1
Content-Type: application/json
Content-Length: 42
{
"text": "This is a sample text."
}Response
HTTP/1.1 200 OK
Struktur des Notizelementes
Eigenschaft | Beschreibung |
|---|---|
text | Enthält den Inhalt der Notiz. |
Abrufen und Anzeigen der Versionen eines DMS-Objektes
Freigegeben: JSON-Repräsentation, HTML-Seite
Sie können die Versionen zu einem DMS-Objekt als JSON-Repräsentation abrufen oder die Versionen zu einem DMS-Objekt anzeigen.
Um die Versionen eines DMS-Objektes abzurufen oder anzuzeigen, müssen Sie die folgenden Schritte durchführen:
Ermitteln der Linkrelation zum Abrufen und Anzeigen der Versionen eines DMS-Objektes
Aufrufen der URL für die Versionen eines DMS-Objektes
Ermitteln der Linkrelation zum Abrufen und Anzeigen der Versionen eines DMS-Objektes
Im Kapitel Abrufen und Anzeigen von Details eines DMS-Objektes können Sie nachlesen, wie Sie die Linkrelation für die Versionen eines DMS-Objektes ermitteln.
Abrufen und Anzeigen der Versionen eines DMS-Objektes (JSON-Repräsentation)
Wenn Sie die URL zu den Versionen aus der Linkrelation haben, dann können Sie die Versionen eines DMS-Objektes wie folgt aufrufen:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/ Accept: application/json Accept-Language: en
Als Ergebnis wird dann folgendes JSON-Objekt zurückgegeben:
Response
{
"_links": {
"self": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/"
}
},
"versions": [{
"_links": {
"mainblobcontent": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/6_3/b/main/c"
},
"pdfblobcontent": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/6_3/b/p1/c"
},
"self": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/6_3"
}
},
"alterationText": "",
"caption": "3 Processing",
"creationDate":"2019-10-25T12:22:56.000+02:00",
"id": "6_3",
"mimeType":"application/msword",
"state":"Processing"
},
{
"_links": {
"mainblobcontent": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/3_2/b/main/c"
},
"pdfblobcontent": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/3_2/b/p1/c"
},
"self": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/3_2"
}
},
"alterationText": "Reasons for changes",
"caption": "2 Release",
"creationDate":"2019-10-22T16:29:32.000+02:00",
"id": "3_2",
"mimeType":"application/msword",
"state":"Released"
},
{
"_links": {
"mainblobcontent": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/1_1/b/main/c"
},
"pdfblobcontent": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/1_1/b/p1/c"
},
"self": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/1_1"
}
},
"alterationText": "Reasons for changes",
"caption": "1 Archive",
"creationDate":"2019-10-12T11:49:41.000+02:00",
"id": "1_1",
"mimeType":"application/msword",
"state":"Archived"
}
]
}Eigenschaft | Beschreibung |
|---|---|
_links | Enthält die Linkrelationen: self: Self-Link |
versions | Gibt das Array mit Versionen an. |
Struktur einer Version
Eigenschaft | Beschreibung |
|---|---|
_links | Enthält die Linkrelationen zu der Version eines DMS-Objektes. mainblobcontent: Relative Download-URL für das Hauptdokument der Version des DMS-Objektes. pdfblobcontent: Relative Download-URL für das abhängige PDF-Dokument der Version des DMS-Objektes. Diese URL erhalten Sie nur, wenn ein abhängiges PDF-Dokument für das DMS-Objekt erzeugt wurde. self: Self-Link. |
alterationText | Gibt den Änderungtext bei der Freigabe der Version an. |
caption | Gibt den Anzeigenamen der Version an. Dieser Wert wird sprachspezifisch ausgegeben, indem der HTTP-Header Accept-Language ausgewertet wird. |
creationDate | Gibt das Erzeugungsdatum der Version an. |
id | Gibt die ID der Version an. |
mimeType | Gibt den Typ des Hauptdokumentes an. |
state | Gibt den Status der Version an. Mögliche Werte sind Processing, Verification, Released und Archived. |
Abrufen und Anzeigen der Versionen eines DMS-Objektes (HTML-Seite)
Wenn Sie die HTML-Darstellung der Versionen aufrufen möchten, ermitteln Sie die Linkrelation zu den Versionen eines DMS-Objektes. Geben Sie die URL im Browser ein, um die HTML-Seite anzuzeigen. Diese HTML-Seite enthält die Liste der Versionen eines DMS-Objektes.
Beispiel:
Request
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/ Accept: text/html
Verknüpfen von DMS-Objekten
Freigegeben: JSON-Repräsentation
In diesem Kapitel erfahren Sie, wie Sie DMS-Objekte mit anderen DMS-Objekten unabhängig vom Typ hierarchisch verknüpfen können.
Um DMS-Objekte miteinander zu verknüpfen, müssen Sie folgende Schritte durchführen:
Ermitteln der URL zu einem Repository
Ermitteln und Aufrufen der Linkrelation zum Abrufen der Details eines DMS-Objektes
Ermitteln der Linkrelation zum Verknüpfen von DMS-Objekten
Verknüpfen von DMS-Objekten
Ermitteln der URL zu einem Repository
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Ermitteln und Aufrufen der Linkrelation zum Abrufen der Details eines DMS-Objektes
Im Kapitel Abrufen und Anzeigen von Details eines DMS-Objektes können Sie nachlesen, wie Sie die URL zum Abrufen der Details eines DMS-Objektes ermitteln und aufrufen.
Ermitteln der Linkrelation zum Verknüpfen von DMS-Objekten
Das JSON-Objekt zu den Details eines DMS-Objektes enthält die Linkrelation linkDmsObjects, mit deren Hilfe Sie DMS-Objekte verknüpfen können.
Response
{
"_links": {
"linkDmsObjects":{
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/children"
}
},
"id": "D000000123"
}Verknüpfen von DMS-Objekten
Führen Sie eine HTTP POST-Anforderung mit der Liste der IDs der zu verknüpfenden DMS-Objekte als Body auf die zuvor ermittelte URL wie folgt aus, um ein DMS-Objekt mit den übergebenen DMS-Objekten zu verknüpfen:
Request
POST https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/children HTTP/1.1
Accept: application/hal+json
Content-Type: application/hal+json
{
"dmsObjectIds": [
"D000000089",
"D000000127",
"D000004567",
]
}Das JSON-Objekt, das beim POST übergeben wird, ist wie folgt beschrieben:
Eigenschaft | Beschreibung |
|---|---|
dmsObjectIds | Gibt das Array mit den IDs der DMS-Objekte (vom Typ String) an, die mit dem DMS-Objekt verknüpft werden sollen. |
Sie erhalten als Antwort den HTTP-Statuscode 200 (OK), wenn das Verknüpfen erfolgreich war. War das Verknüpfen nicht erfolgreich oder nur für einzelne DMS-Objekte erfolgreich, erhalten Sie den HTTP-Statuscode 207 (Multi-Status) und eine Liste mit detaillierten Informationen zu den einzelnen Verknüpfungsvorgängen.
Beispiel für eine Antwort für eine teilweise fehlgeschlagene Anforderung (Request):
Response
HTTP/1.1 207 Multi-Status
Content-Type: application/hal+json
{
"requestId": "XyErwIKPhyGaMg9dxcGksgAAA@A",
"linkDocumentErrorPageModels": [
{
"dmsObjectId": "D000000089",
"errorPageModel": {
"reason": "These documents are already linked to each other! [0000071] ",
"severity": 1,
"errorCode": 71
}
},
{
"dmsObjectId": "D000000127",
"errorPageModel": {
"reason": "These documents are already linked to each other! [0000071] ",
"severity": 1,
"errorCode": 71
}
},
{
"dmsObjectId": "D000004567",
"errorPageModel": {
"reason": "These documents are already linked to each other! [0000071] ",
"severity": 1,
"errorCode": 71
}
}
]
}Beschreibung der Parameter zu der Antwort auf die fehlerhafte Anforderung:
Eigenschaft | Beschreibung |
|---|---|
requestId | ID der zugehörigen Anforderung. Die ID wird bei weiteren Anforderungen an andere Apps übergeben und dient der Nachverfolgung bei der Verarbeitung einer Aktion. |
linkDocumentErrorPageModels | Ein Array mit Fehlermeldungen zu einem Verknüpfungsvorgang. |
Struktur eines Antwortobjektes zu einem Verknüpfungsvorgang
Eigenschaft | Beschreibung |
|---|---|
dmsObjectId | Die ID des DMS-Objektes, das verknüpft werden soll. |
errorPageModel | Ein Objekt mit einer Beschreibung, ob die Verknüpfung erfolgreich war. |
Format der Antwort bei Fehlern
Eigenschaft | Beschreibung |
|---|---|
errorCode | Ein optionaler Fehlercode, den d.3 server zurückgegeben hat. |
reason | Ein optionaler kurzer Beschreibungstext, weshalb der Fehler aufgetreten ist. Dieser Text wird als Titel der Fehlermeldung verwendet. |
severity | Optionaler Schweregrad des Fehlers. Folgende Werte sind möglich: Success = 0, Information = 1, Warning = 2, Error = 3 |
Aufheben der Verknüpfung eines DMS-Objektes
Diese Funktion steht Ihnen aktuell nur für On-Premises-Installationen zur Verfügung.
Freigegeben: JSON-Repräsentation
In diesem Kapitel erfahren Sie, wie Sie die Verknüpfung zwischen zwei DMS-Objekten aufheben können. Sie können Verknüpfungen von DMS-Objekten nur einzeln aufheben.
Um die Verknüpfung zwischen zwei DMS-Objekten aufzuheben, müssen Sie folgende Schritte durchführen:
Ermitteln der URL zu einem Repository
Ermitteln und Aufrufen der Linkrelation zum Abrufen der Details eines DMS-Objektes
Ermitteln der Linkrelation zum Aufheben der Verknüpfung zwischen zwei DMS-Objekten
Aufrufen der URL zum Aufheben der Verknüpfung zwischen zwei DMS-Objekten
Ermitteln der URL zu einem Repository
Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Ermitteln und Aufrufen der Linkrelation zum Abrufen der Details eines DMS-Objektes
Im Kapitel Abrufen und Anzeigen von Details eines DMS-Objektes können Sie nachlesen, wie Sie die URL zum Abrufen der Details eines DMS-Objektes ermitteln und aufrufen.
Ermitteln der Linkrelation zum Aufheben der Verknüpfung zwischen zwei DMS-Objekten
Das JSON-Objekt zu den Details eines DMS-Objektes enthält die Linkrelation unlinkDmsObject mit einem Platzhalter für die ID des übergeordneten DMS-Objektes, für das Sie die Verknüpfung aufheben möchten.
Response
{
"_links": {
"unlinkDmsObject": {
"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/{parentDmsObjectId}/children/D000004567"
}
},
"id": "D000000123"
}Aufrufen der URL zum Aufheben der Verknüpfung zwischen zwei DMS-Objekten
Führen Sie eine HTTP DELETE-Anforderung mit der ID des DMS-Objektes als Parameter in der zuvor ermittelten URL wie folgt aus, um die Verknüpfung für das DMS-Objekt aufzuheben:
Request
DELETE https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/children/D000004567 HTTP/1.1 Accept: application/hal+json
Sie erhalten als Antwort den HTTP-Statuscode 200 (OK), wenn das Aufheben der Verknüpfung erfolgreich war. War das Aufheben der Verknüpfung nicht erfolgreich, erhalten Sie den HTTP-Statuscode 400 (Bad Request) und eine detaillierte Information zu dem Fehler.
Beispiel für eine Antwort für eine fehlgeschlagene Anforderung (Request):
Response
HTTP/1.1 400 Bad Request
Content-Type: application/hal+json
{
"reason": "These two documents are not linked with each other. [0000073] ",
"severity": 1,
"errorCode": 73,
"requestId": "XyEWT4KPhyGaMg9dxcGNiAAAA@c"
}Falls Sie mehrere DMS-Objekte lösen möchten, wiederholen Sie diesen Schritt.
Beschreibung der Parameter zu der Antwort auf die fehlerhafte Anforderung:
Format der Antwort bei Fehlern
Eigenschaft | Beschreibung |
|---|---|
reason | Ein optionaler kurzer Beschreibungstext, weshalb der Fehler aufgetreten ist. Dieser Text wird als Titel der Fehlermeldung verwendet. |
severity | Optionaler Schweregrad des Fehlers. Folgende Werte sind möglich: Success = 0, Information = 1, Warning = 2, Error = 3 |
errorCode | Ein optionaler Fehlercode, den d.3 server zurückgegeben hat. |
requestId | ID der zugehörigen Anforderung. Die ID wird bei weiteren Anforderungen an andere Apps übergeben und dient der Nachverfolgung bei der Verarbeitung einer Aktion. |