DMSApp-API
DMS API
Einleitung
In diesem Thema finden Sie allgemeine Informationen zur DMSApp-API, dem Funktionsumfang sowie zu den Kenntnissen, die hilfreich beim Programmieren von Funktionen und Anpassungen sind.
Über die DMSApp-API
In dieser Dokumentation erfahren Sie, wie Sie die Programmierschnittstelle der DMSApp für eigene Entwicklungen nutzen können.
Diese Dokumentation richtet sich an Entwickler von Anwendungen, die in der d.ecs architecture-Systemumgebung ausgeführt werden sollen. Die DMSApp ist eine zentrale Komponente in der d.ecs architecture-Systemumgebung und stellt Funktionalitäten rund um das Thema Dokumente und Akten im Rahmen des d.3ecm-Systems bereit.
JSON-Objekte, URLs und Abfrageparameter (Query) können jederzeit erweitert werden, ohne dass die API ihre Gültigkeit verliert. Es sind ausschließlich die in dieser Dokumentation beschriebenen Erweiterungspunkte, Eigenschaften, Objekte und Parameter für die API-Programmierung freigegeben. In jedem Kapitel wird daraufhin gewiesen, ob die URL zum Abrufen der HTML-Seite, die JSON-Repräsentation oder der Erweiterungspunkt freigegeben ist. Die HTML-Seite dient ausschließlich der UI-Integration, darf nicht programmatisch ausgewertet und kann jederzeit ohne vorherige Ankündigung geändert werden. Alle Eigenschaften, die nicht in dieser Dokumentation beschrieben sind, dürfen nicht verwendet werden.
Diese Dokumentation steht Entwicklungspartnern der d.velop AG im Service Portal online bereit. Die Weitergabe dieser Dokumentation oder von Teilen daraus ist nicht gestattet. Bei Anfragen im Rahmen der Entwicklungspartnerschaft gilt stets nur die Onlinedokumentation.
Bitte beachten Sie, dass Ihre Software über diese Schnittstelle auch Zugriff auf die von Ihren Kunden im d.3ecm abgelegten und konfigurierten Daten erhält und Eingriff in die Abläufe im d.3ecm-System nimmt. Gehen Sie daher bitte sorgfältig vor und achten Sie darauf, dass Ihre Anwendung Teil eines bestehenden Zusammenspiels unterschiedlicher Anwendungen ist. Die unsachgemäße Verwendung dieser Schnittstelle kann veränderte Programmabläufe und Datenverlust zur Folge haben.
Funktionsumfang von DMSApp
Die DMS-App ist die zentrale HTTP-Schnittstelle zu wesentlichen Funktionalitäten in Bezug auf das Thema Dokumente und Akten in der d.3ecm-Umgebung. Sie können die DMS-App u.a. für das Erstellen von Zuordnungen, Erstellen, Bearbeiten und Aktualisieren von Dokumenten verwenden. Das Navigieren durch Aktenstrukturen und das Anzeigen von Detailinformationen können Sie ebenfalls mit der DMS-App realisieren. Darüber hinaus bietet Ihnen die DMS API viele Erweiterungspunkte für eigene Funktionen.
Voraussetzungen
Diese Dokumentation richtet sich an Administratoren eines d.3ecm-Systems und an Entwickler von Apps und Erweiterungen.
Sie sollten über folgende Kenntnisse verfügen, um die API nutzen zu können:
- Sie sollten über gute Kenntnisse der d.3ecm-Architektur verfügen.
- Sie sollten mit der Authentifizierung über die d.ecs identity provider-API im d.3ecm-Kontext vertraut sein.
- Sie sollten über Kenntnisse in der Entwicklung webbasierter Apps verfügen und sicher im Umgang mit folgenden Detailthemen sein:
- Hypertext Transfer Protocol (HTTP) (RFC 7230)
- RESTful HTTP-Schnittstellen
- JavaScript Object Notation (JSON) (RFC 7159)
- Hypertext Application Language in Verbindung mit der JavaScript Object Notation (HAL+JSON)
- UriTemplate (RFC 6570)
- Sofern Sie eigene Benutzeroberflächen bereitstellen möchten, sollten Sie über Kenntnisse in HTML, CSS, Responsive Webdesign verfügen. Um ein einheitliches Look&Feel zu ermöglichen, ist es empfehlenswert, über Kenntnisse in der Verwendung des Frameworks Material Design zu verfügen. Weitere Empfehlungen zum Design finden Sie im Developer Portal.
- Zusätzlich sind Kenntnisse in der Administration eines Webservers von Vorteil.
Hinweise zum Support bei der API-Programmierung
Bitte beachten Sie, dass Ihre Software über diese Schnittstelle auch Zugriff auf die von Ihren Kunden im d.3ecm abgelegten und konfigurierten Daten erhält und Eingriff in die Abläufe im d.3ecm-System nimmt. Gehen Sie daher bitte sorgfältig vor und achten Sie darauf, dass Ihre Anwendung Teil eines bestehenden Zusammenspiels unterschiedlicher Anwendungen ist. Die unsachgemäße Verwendung dieser Schnittstelle kann veränderte Programmabläufe und Datenverlust zur Folge haben.
Die Software-Entwicklung mit dieser Programmierschnittstelle ist eine Individualentwicklung. Der von Ihnen erzeugte Programmcode fällt nicht unter die Pflege- und Supportbedingungen der Produkte der d.velop AG. Unser Support unterstützt Sie gerne, Ihre Anfragen sind jedoch kostenpflichtig, sofern sich die Anfrage nicht auf einen Fehler in unseren Produkten zurückführen lässt.
Alle Fragen zu den Voraussetzungen und zur Software-Entwicklung mit d.3ecm beantwortet Ihnen gerne das Technology Partner Management der d.velop AG.
Technische Hintergrundinformationen
Es ist empfehlenswert, die Systemlandschaft, die Interoperabilität und Architektur von d.3ecm zu kennen. Grundlagen und weitere Informationen finden Sie beispielsweise im d.3one-Administrationshandbuch d3one_admin.pdf.
Darüber hinaus spielt der Authentifizierungsmechanismus in der d.3ecm-Systemlandschaft eine wesentliche Rolle. Die Basisinformationen zur Authentifizierung finden Sie unter Basiswissen zur Authentifizierung.
Um die Zuordnungsfunktionalität der DMSApp zu nutzen, finden Sie Basisinformationen unter Grundlegendes zu Zuordnungen (Mappings).
Um schreibende Zugriffe auf die DMSApp durchzuführen, finden Sie Basisinformationen unter Grundlegendes zu schreibenden Zugriffen.
Grundlegendes zu Zuordnungen (Mappings)
Sie haben mit der DMSApp die Möglichkeit, mit der Zuordnungsfunktionalität eine Verbindung zwischen einer beliebigen Drittanbieteranwendung, wie z.B. einer E-Mail-Anwendung oder einem ERP-System, und einem d.3-Repository herzustellen. Diese Zuordnungsfunktionalität (Mapping) bildet die Grundlage für Ihre Erweiterungen und Funktionen, die Ihnen das Programmieren von Funktionen erleichtern, z.B. das Speichern von Elementen, die aus einem anderen ERP-System stammen.
Wenn Sie beispielsweise Ihre E-Mails standardmäßig in einem d.3-Repository speichern möchten, ist es hilfreich, das Element "E-Mail" direkt einer d.3-Kategorie und den zugehörigen d.3-Eigenschaften zuzuordnen. Sie können dem Anwender das manuelle Zuordnen von Eigenschaften und Kategorien ersparen, wenn Sie die Zuordnung administrativ definieren. Ihr Quellsystem ist somit die E-Mail-Anwendung, das Zielsystem ist ein d.3-Repository. Jede E-Mail hat standardmäßig bestimmte Eigenschaften, dazu zählen z.B. der Absender und der Empfänger sowie der Betreff einer E-Mail. Sie können diese für eine E-Mail typischen Eigenschaften einer d.3-Kategorie und den d.3-Eigenschaften zuordnen. Mithilfe dieser Zuordnung wird die E-Mail z.B. automatisch der richtigen Kategorie zugeordnet. Die für eine E-Mail typischen Eigenschaften werden dann automatisch in die d.3-Eigenschaften geschrieben.
Um die Zuordnungsfunktionalität effektiv anzuwenden, können Sie das Datenmodell einer Drittanbieteranwendung als Quelle bereitstellen, um es mit dem Datenmodell des Ziels d.3ecm (DMSApp) zu verbinden. Die Beschreibung des Datenmodells wird als Quelle bezeichnet.
Angenommen, Sie möchten Ihre Daten einer E-Mail-Anwendung (E-Mails, Anlagen) in einem d.3-Repository speichern und Ihren Anwendern das manuelle Zuweisen von d.3-Kategorien und d.3-Eigenschaften ersparen. Die E-Mail-Anwendung ist in diesem Fall Ihr Quellsystem. Die E-Mail ist eine Quelle dieses Quellsystems, die standardmäßig über bestimmte Kategorien und Eigenschaften verfügt. Diese für die Quelle typischen Kategorien und Eigenschaften müssen in das d.3ecm-Datenmodell "übersetzt" werden. Nur auf diese Weise stellen Sie sicher, dass beim Speichern der Elemente aus der E-Mail-Anwendung die Felder korrekt und standardmäßig zugeordnet werden.
Eine E-Mail-Anwendung bietet Ihnen eine Reihe von verschiedenen Metadaten. Das können z.B. der Absender, der Empfänger, die Betreffzeile sein. Diese Metadaten der Quelle können Sie mit den Metadaten in einem d.3-Repository verbinden, in das die Elemente aus der Quelle gespeichert werden. In einem d.3-Repository können Sie beispielsweise eine E-Mail der Dokumentart Schriftverkehr zuordnen und den Betreff (Quelleigenschaft Mail_Subject
) der d.3-Eigenschaft Betreff zuordnen.
Das Verstehen der Beziehung zwischen den möglichen Kategorien und Eigenschaften einer Quelle und den Kategorien und Eigenschaften in d.3ecm ist relevant für die Zuordnungen.
Basiswissen zur Authentifizierung
In der Architektur einer d.3ecm-Umgebung übernimmt die App d.ecs identity provider die Authentifizierung. Fast alle REST-Ressourcen der DMSApp müssen mit Authentifizierung aufgerufen werden. In den folgenden Beschreibungen der API-Funktionen werden Sie immer daraufhin gewiesen, wenn Sie eine REST-Ressource anonym aufrufen können.
Die Funktionsweise der identity provider-App finden Sie in der identity provider API-Dokumentation.
Grundlegendes zu schreibenden Zugriffen
Beim Aufrufen der API mittels der HTTP-Verben POST
, PUT
, DELETE
und PATCH
müssen Sie den Header Origin
festlegen. Der Wert des Headers muss der aufrufenden URL ohne Pfad entsprechen. Bei einem lesenden Aufruf (z.B. GET
) müssen Sie den Header nicht angeben.
Das Festlegen eines Wertes für Origin
ist erforderlich, um CSRF-Angriffe (Cross-site Request Forgery) zu vermeiden.
PUT /dms/sampleuri
Origin: https://samplehost
Sofern der Header fehlt, antwortet die DMSApp mit HTTP 403 Forbidden
.
Verwenden der API-Funktionen
Im Folgenden lernen Sie die unterschiedlichen Möglichkeiten kennen, die Schnittstellen der DMSApp für Ihre Anforderungen zu verwenden.
Grundlegendes zu API-Funktionen (DMSApp)
In diesem Kapitel finden Sie alle Themen, die übergreifend für alle Arten der Verwendung der API-Funktionen der DMSApp gelten.
Ermitteln eines Repositorys
Freigegeben: JSON-Repräsentation
Sie benötigen für die Implementierung eigener Funktionen immer die ID des Repositorys. Mit der DMSApp haben Sie die Möglichkeit, auf unterschiedliche Repositorys zuzugreifen, wenn Sie in Ihrem Unternehmen oder Ihrer Organisation mehrere Repositorys konfiguriert haben.
Wenn Sie beispielsweise, einen Suchvorgang starten möchten, müssen Sie erst ein Repository auswählen. Um das Repository anzugeben, führen Sie eine HTTP GET
-Anforderung für die REST-Ressource /dms
aus.
Das Ermitteln der Repository-ID erfolgt in zwei Schritten:
- Ermitteln der Linkrelation zum Abrufen der Liste der Repositorys
- Abrufen der Liste der Repositorys
Ermitteln der Linkrelation zum Abrufen der Liste der Repositorys
Die URL für ein Repository ist als Linkrelation in der Antwort (Response) der HTTP GET
-Anforderung verfügbar.
GET /dms
Accept: application/hal+json
{
_links: {
repo: {
href: "/dms/r/{repositoryid}",
templated: true
}
}
}
Abrufen der Liste der Repositorys
Um repositoryspezifische Funktionen aufrufen zu können, benötigen Sie die Repository-ID.
Ersetzen Sie den Platzhalter {repositoryid}
in der URL "/dms/r/{repositoyid}"
mit der Repository-ID. Wenn Sie die Repository-ID nicht kennen, rufen Sie die URL /dms/r
wie folgt auf:
GET /dms/r
Accept: application/hal+json
In der Antwort erhalten Sie ein Array von Repositorys, bei dem jeweils die Repository-ID als Eigenschaft id
und der Anzeigename des Repositorys als Eigenschaft name
aufgeführt ist.
{
repositories: [
{
id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27",
name: "Contoso (A)"
},
...
]
}
Wenn Sie die Repository-ID bereits kennen, dann können Sie den Platzhalter {repositoryid}
in der URL /dms/r/{repositoryid}
mit der Repository-ID ersetzen. Wenn Sie URL mit der Repository-ID aufrufen, erhalten Sie folgendes Ergebnis:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json
Das JSON-Objekt in der Antwort ist dasselbe Objekt wie in der Liste der JSON-Objekte aus der Anforderung zur URL /dms/r
.
{
id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27",
name: "Contoso (A)"
}
Übersicht über Formate bei Fehlern
Freigegeben: JSON-Repräsentation
In diesem Kapitel erfahren Sie mehr zu den Grundlagen der Fehlerbehandlung und zum Format, in dem Fehler zurückgegeben werden.
Abhängig vom Verarbeitungsergebnis einer HTTP
-Anforderung wird die Anforderung mit verschiedenen HTTP
-Statuscodes beantwortet. Optional werden beschreibende Informationen als JSON zurückgeliefert.
Beispiel für eine Antwort für eine fehlgeschlagene Anforderung (Request):
HTTP/1.1 400 BadRequest
{
"reason": "10019: Missing value for a mandatory property.",
"severity": 1,
}
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 |
Aufrufen der Weboberfläche mit einer URL (DMSApp)
In diesen Thema können Sie erfahren, wie Sie die HTML-Oberflächen der DMSApp mithilfe von URLs erreichen können. Diese URLs können Sie auch verwenden, um die HTML-Oberflächen in Ihre eigene Anwendung zu integrieren.
Anzeigen des Ablagedialogs
Freigegeben: HTML-Seite
Der Ablagedialog des Features Ablage bietet Ihnen die Möglichkeit, DMS-Objekte zu speichern und zu aktualisieren.
Wenn Sie den Ablagedialog im Browser geöffnet und Werte eingegeben haben, dann wird Ihnen in der URL der Link zum Aufrufen des angezeigten Dialogs inklusive Ihrer eingegebenen Werte angezeigt. Sie können diesen Link z.B. als Lesezeichen im Browser verwenden, um den Ablagedialog immer mit den eingegebenen Werten anzuzeigen. In diesem Kapitel erfahren Sie, wie dieser Link aufgebaut ist.
Möchten Sie ein externes System anbinden, dann finden Sie weitere Informationen zum Speichern neuer DMS-Objekte mithilfe des Ablagedialogs unter Speichern neuer DMS-Objekte mit Benutzerinteraktion. Wie Sie aus einem externem System den Ablagedialog zum Aktualisieren vorbereiten und anzeigen, erfahren Sie im Kapitel Aktualisieren von DMS-Objekten mit Benutzerinteraktion.
Ermitteln der Linkrelation zum Anzeigen des Ablagedialogs
Wenn Sie die Rootressource /dms
aufrufen, erhalten Sie als Antwort ein JSON-Objekt mit der Linkrelation new
, mit der Sie den Ablagedialog anzeigen können.
Der Request zur Rootresource /dms
:
GET /dms
Accept: application/hal+json
Das JSON-Objekt der Rootressource enthält die Linkrelation new
:
{
_links: {
new: {
href: "/dms/new/"
}
}
}
Angeben von verhaltenssteuernden Parametern
Das Verhalten des Ablagedialogs steuern Sie mit den 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 |
---|---|
type | Legt die Kategorie (Ablagetyp) im Ablagedialog fest. Der einzige mögliche Wert ist |
repositoryid | Definiert die Repository-ID. |
objectdefinitionid | Legt fest, welche Kategorie in dem Ablagedialog ausgewählt sein soll. Geben Sie die ID einer Kategorie an. Wird keine Angabe gemacht, wird keine Kategorie ausgewählt. Beispiel (nicht encodiert):
|
properties | Ein JSON Objekt, mit dem Sie folgende Eigenschaften setzen können:
Sie können auch Werte für erweiterte Eigenschaften setzen. Die ID der Eigenschaft entspricht der Kennung (RID) der Eigenschaft. Für erweiterte Eigenschaften setzen Sie einen Wert wie folgt:
Für Mehrfachwerte müssen Sie noch die Zeilennummer setzen:
|
Aufrufen der URL für den Ablagedialog
Sie haben eine URL für den Ablagedialog erzeugt. Wenn Sie die URL im Browser öffnen, wird der Ablagedialog mit den übergebenen Parametern geladen.
Beispiel Anwendungsbeispiele für verschiedene Aufrufe des Ablagedialogs:
|
Anzeigen der Details eines DMS-Objektes
Freigegeben: HTML-Seite
Die Detailansicht bietet Ihnen verschiedene Perspektiven wie Eigenschaften, Anzeige und Notizen für das angeforderte Element.
Wie Sie die Detailansicht für ein Element anzeigen lassen, erfahren Sie im Kapitel Abrufen und Anzeigen von Details eines DMS-Objektes.
Anzeigen der Vorschau eines DMS-Objektes
Freigegeben: HTML-Seite
Die Perspektive Anzeige bietet Ihnen eine Vorschau für das ausgewählte Element. Den Inhalt der Perspektive können Sie für ein Element direkt verwenden, ohne die anderen Perspektiven zu laden.
Um nur die Vorschau eines DMS-Objektes anzuzeigen, müssen Sie folgende Schritte durchführen:
- Ermitteln der URL zu einem Repository
- Ermitteln der Linkrelation zum Anzeigen der Vorschau
- Aufrufen der URL für die Anzeige der Vorschau
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 Anzeigen der Vorschau
Rufen Sie die URL zu einem Repository wie folgt auf:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation dmsobjectpreview
mit dem Platzhalter dmsobjectid
.
{
_links: {
dmsobjectpreview: {
href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/{dmsobjectid}/preview{?isReadonly}",
templated: true
}
},
id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}
Ersetzen Sie den Platzhalter {dmsobjectid}
mit der ID des DMS-Objektes, das Sie direkt in der Vorschau sehen möchten.
Angeben von verhaltenssteuernden Parametern
Parameter | Beschreibung |
---|---|
isReadonly | Legt fest, ob die Vorschau im Lesemodus angezeigt wird (Standardwert: false). Im Lesemodus können auch keine grafischen Markierungen z.B. auf PDF-Dokumenten aufgebracht werden. Verwenden Sie den Parameter isReadonly=true, wenn die Vorschau im Inner Supply (InnerSupply) des Bedienkonzepts angezeigt wird. |
Aufrufen der URL für die Anzeige der Vorschau
Rufen Sie die Vorschau folgendermaßen auf:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/P0123456789/preview
Accept: text/html
Als Ergebnis wird dann die Vorschau des DMS-Objektes geladen.
Suchen von DMS-Objekten
Sie können die HTML-Seiten des Features Suche in Ihre eigene HTML-Oberfläche integrieren, um beispielsweise häufig wiederkehrende Aufgaben bei Anwendern zu vereinfachen.
Folgende Aufgaben können Sie integrieren:
Diejenigen Parameter, die Sie sowohl für die Suchvorgänge als auch für das Anzeigen der Ergebnisliste nutzen können, finden Sie im Kapitel Definieren der Parameter für einen Suchvorgang und eine Ergebnisliste erläutert.
Definieren von Suchvorgängen
Freigegeben: HTML-Seite
Mit dem Feature Suche können Sie die im Repository gespeicherten Elemente finden, vorausgesetzt, Sie verfügen über die entsprechenden Berechtigungen. Aufgrund ihres Aufgabenbereichs suchen Anwender häufig nach denselben Elementen, die sie mithilfe von ausgewählten Eigenschaften und Kategorien schnell finden. Sie können den Suchvorgang vereinfachen, indem Sie den Anwendern die Möglichkeit bieten, einen bereits definierten Suchvorgang zu verwenden. Im Suchvorgang haben Sie bereits die Werte definiert, die ihre Anwender andernfalls immer wieder eingeben müssen.
Um einen definierten Suchvorgang bereitzustellen, übergeben Sie die Parameter der URL.
Sie haben zwei Möglichkeiten, den Suchvorgang aufzurufen:
- Sie rufen den Suchvorgang ohne Angabe eines speziellen Repositorys auf. In diesem Fall wird das zuletzt ausgewählte Repository für den Suchvorgang verwendet, der Anwender kann jedoch das Repository jederzeit wechseln.
- Sie rufen den Suchvorgang speziell für ein Repository auf, sodass der Anwender das Repository nicht mehr wechseln kann.
Suchen, ohne ein Repository anzugeben
Wenn Sie den Suchvorgang ohne Angabe eines Repositorys definieren möchten, müssen Sie wie folgt vorgehen:
Wenn Sie die URL /dms
aufrufen, wird Ihnen mit folgender HTTP-Antwort die URL für den Suchvorgang inklusive verfügbarer Parameter mitgeteilt:
GET /dms
Accept: application/hal+json
Das JSON-Objekt zu der Rootressource enthält die Linkrelation search
mit Platzhaltern für die Werte, mit deren Hilfe die Suche nach DMS-Objekten durchgeführt wird.
{
_links: {
search: {
href: "/dms/s/{?objectdefinitionids,fulltext,properties,showresultlist,repositoryid}"
templated: true
}
}
}
Suchen in einem definierten Repository
Wenn Sie einen Suchvorgang speziell für ein Repository definieren möchten, müssen Sie zunächst die URL zu einem Repository ermitteln. Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.
Wenn Sie die URL zu einem Repository ermittelt haben (beispielsweise: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
) und die URL per HTTP GET
aufrufen, dann erhalten Sie folgendes Ergebnis, das die repositoryspezifische URL für den Suchvorgang enthält:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation search
mit Platzhaltern für die Werte, mit dessen Hilfe die Suche nach DMS-Objekten durchgeführt wird.
{
_links: {
search: {
href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/s/{?objectdefinitionids,fulltext,properties,showresultlist}"
templated: true
}
},
id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}
Angeben von verhaltenssteuernden Parametern
Das Verhalten beim Suchen und Anzeigen steuern Sie mit den folgenden Parametern:
Parameter | Beschreibung |
---|---|
| Legt fest, wenn Werte für einen Suchvorgang vorhanden sind, ob der Suchvorgang direkt ausgeführt wird und die Ergebnisse der Suchanfrage angezeigt werden (Standardwert: false ). |
| Definiert die Repository-ID. |
Die Beschreibungen zu den Parametern objectdefinitionids
, fulltext
und properties
finden Sie im Kapitel Definieren der Parameter für einen Suchvorgang und eine Ergebnisliste.
Hinweis Sie können zu einem Parameter auch mehrere Werte definieren, sofern für die zugehörige Eigenschaft Facetten angezeigt werden. Falls keine Facetten für die Eigenschaft zum Anzeigen definiert wurden, wird immer der letzte Wert für den Suchvorgang übernommen. |
Aufrufen der URL für den Suchvorgang
Wenn Sie eine URL für den Suchvorgang erzeugt haben, dann können Sie die Ergebnisse mit den entsprechenden Anforderungen aufrufen.
Anforderung ohne Repository-ID:
GET /dms/s/?objectdefinitionids=["RECH"]&fulltext=Mustermann&properties={"227":["KND001"]}&repoid=dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: text/html
Anforderung mit Repository-ID:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/s/?objectdefinitionids=["RECH"]&fulltext=Mustermann&properties={"227":["KND001"]}
Accept: text/html
Als Ergebnis wird dann der Suchvorgang im Feature Suche mit den übergebenen Parametern geladen.
Beispiel Sie müssen die Parameter der URL encodieren (z.B. Leerzeichen in Anwendungsbeispiele für verschiedene Suchanfragen (nicht encodiert):
|
Anzeigen der Ergebnisse eines Suchvorgangs
Freigegeben: HTML-Seite
Sie können beim Definieren von Suchvorgängen festlegen, dass nur die Ergebnisliste angezeigt wird. Ihre Anwender können dann direkt die Ergebnisse einer Suche sehen und müssen nicht mehr die einzelnen Eigenschaften angeben. Mit der Ergebnisliste können Ihre Anwender einfach weiterarbeiten. Die Anwender können jedoch die Suchkriterien, die zum Ergebnis geführt haben, nicht mehr ändern.
Um nur die Ergebnisse eines Suchvorgangs 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
Wenn Sie eine Zuordnung für eine Quelle erstellt haben, können Sie die Ergebnisse eines Suchvorgangs auch auf andere Weise anzeigen. Weitere Informationen finden Sie im Kapitel Abrufen und Anzeigen der 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 der Ergebnisse eines Suchvorgangs
Rufen Sie die URL zu einem Repository wie folgt auf:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation searchresult
mit Platzhaltern für die Werte, mit deren Hilfe die Suche nach DMS-Objekten durchgeführt wird.
{
_links: {
searchresult: {
href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/sr/{?objectdefinitionids,fulltext,properties,propertysort,ascending,showdetails}"
templated: true
}
},
id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}
Angeben von verhaltenssteuernden Parametern
Das Verhalten beim Anzeigen der Ergebnisse steuern Sie mit folgenden Parametern:
Parameter | Beschreibung |
---|---|
| Legt fest, wenn der Suchvorgang ein einzelnes Dokument findet, ob dieses Dokument direkt in der Detailansicht angezeigt wird (Standardwert: false ). |
propertysort | Gibt die ID der Eigenschaft an, nach der sortiert wird. Ist keine Sortiereigenschaft angegeben, erfolgt die Sortierung gemäß Standardsortierung anhand des Sortierungskriteriums Geändert am.
Sie können die Ergebnisliste auch anhand einer erweiterten Eigenschaft sortieren. Die ID der Eigenschaft entspricht der Kennung (RID) einer Eigenschaft, die Sie in d.3 admin für jede erweiterte Eigenschaft ermitteln können. Weitere Informationen zur Kennung einer Eigenschaft (RID) finden Sie in der Dokumentation zu d.3 admin ( |
ascending | Gibt die Richtung der Sortierreihenfolge an.
Wird der Außerdem werden in der Ergebnisliste zunächst die Akten und dann die Dokumente angezeigt. Innerhalb von Dokumenten und Akten wird nach dem Sortierkriterium sortiert. |
children_of | Gibt die Dokument-ID an, zu der die verknüpften direkten untergeordneten Elemente gesucht werden. |
Die Beschreibungen zu den Parametern objectdefinitionids
, fulltext
und properties
finden Sie im Kapitel Definieren der Parameter für einen Suchvorgang und eine Ergebnisliste.
Aufrufen der URL für die Ergebnisse
Wenn Sie eine URL erzeugt haben, dann können Sie die Ergebnisse wie folgt aufrufen:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/sr/?objectdefinitionids=["RECH"]&fulltext=Mustermann&properties={"227":["KND001"]}
Accept: text/html
Als Ergebnis wird dann das Ergebnis des Suchvorgangs geladen.
Beispiel Sie müssen die Parameter der URL encodieren (z.B. Leerzeichen in Anwendungsbeispiele für verschiedene Ergebnislisten (nicht encodiert):
|
Sie erhalten als Antwort (Response) die HTML-Seite mit der Ergebnisliste. Im Fehlerfall erhalten Sie eine HTML-Seite, die den Fehler genauer beschreibt. Wenn Fehler auftreten, müssen Sie die fehlerhafte Anforderung (Request) korrigieren.
Definieren der Parameter für einen Suchvorgang und eine Ergebnisliste
Wenn Sie beispielsweise Ihren Anwendern einen definierten Suchvorgang oder eine Ergebnisliste bereitstellen möchten, können Sie verschiedene Parameter angeben. In der Regel ist die Volltextsuche in einem d.3-Repository zu unspezifisch. Deshalb können Sie die Suchanfrage mithilfe von Abfrageparametern einschränken.
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 |
---|---|
| Legt fest, auf welche Kategorien sich die Suche beziehen soll. Sie können mindestens eine Kategorie definieren. Geben Sie die ID einer Kategorie an. Wird keine Angabe gemacht, erfolgt die Suche in allen Kategorien eines d.3-Repositorys. Beispiele (nicht encodiert):
|
| Gibt einen Volltextsuchbegriff an. |
| Gibt eine Sucheinschränkung nach Eigenschaften der Dokumente und Akten an. Mit folgenden Kriterien können Sie einen Suchvorgang einschränken:
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 zugehörige Eigenschaft Facetten konfiguriert wurden. Falls keine Facetten für die Eigenschaft zum Anzeigen konfiguriert wurden, wird immer der letzte Wert für den Suchvorgang übernommen. Sie können die Ergebnisliste und den Suchvorgang auch anhand einer erweiterten Eigenschaft einschränken. Die ID der Eigenschaft entspricht der Kennung (RID) einer Eigenschaft, die Sie in d.3 admin für jede erweiterte Eigenschaft ermitteln können. Weitere Informationen zur Kennung einer Eigenschaft (RID) finden Sie in der Dokumentation zu d.3 admin ( Beispiele (nicht encodiert):
Sie können auch mehrere Eigenschaften gleichzeitig als Sucheinschränkung verwenden: Beispiele (nicht encodiert):
|
Hinweis Spezielle Angaben für den
|
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
- Abrufen des Standardquellsystems zu einem d.3-Repository
- Abrufen und Anzeigen der Ergebnisse eines Suchvorgangs
- Abrufen und Anzeigen von Details eines DMS-Objektes
- Speichern von DMS-Objekten
- Löschen der aktuellen Version eines DMS-Objektes ohne Benutzerinteraktion
- Abrufen, Speichern und Bearbeiten von Zuordnungen
- Abrufen und Speichern der Notizen eines DMS-Objektes
- Abrufen und Anzeigen der Versionen eines DMS-Objektes
- Verknüpfen von DMS-Objekten
- Aufheben der Verknüpfung eines DMS-Objektes
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.
GET https://host/myapp/ HTTP/1.1
Accept: application/hal+json
HTTP/1.1 200 OK
Content-Type: application/hal+json
{
"_links" : {
"sources" : {
"href" : "/myapp/sources"
}
}
}
Hinweis 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.
GET https://host/myapp/sources HTTP/1.1
Accept: application/hal+json
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. | |
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 | |
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 |
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 |
Hinweis 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.
{
"_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:
GET https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source HTTP/1.1
Accept: application/hal+json
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 |
---|---|
| Gibt den eindeutigen Bezeichner der Kategorie im Quellsystem an. |
| Gibt den Anzeigenamen der Kategorie an. Mit Blick auf die Internationalisierung arbeitet die DMSApp mit dem HTTP-Header |
Struktur einer Eigenschaft
Eigenschaft | Beschreibung |
---|---|
| 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. |
| Gibt den Anzeigenamen der Eigenschaft an. Die DMSApp arbeitet zur Internationalisierung mit dem HTTP-Header |
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 Definieren 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:
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.
{
_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 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. |
Hinweis Spezielle Angaben für den
|
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:
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/json
Als Ergebnis wird dann folgendes JSON-Objekt zurückgegeben:
{
"_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.
|
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.
|
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 |
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):
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/html
Abrufen 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:
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.
{
_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:
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:
{
"_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.
|
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 |
values | Gibt die Werte der zugeordneten d.3-Eigenschaft an. Wird nur zurückgegeben, wenn die d.3-Eigenschaft eine Mehrfacheigenschaft ist.
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 ( |
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:
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.
- Speichern eines neuen DMS-Objektes ohne Benutzerinteraktion
- Aktualisieren eines DMS-Objektes ohne Benutzerinteraktion
- Speichern neuer DMS-Objekte mit Benutzerinteraktion
- Aktualisieren von DMS-Objekten mit Benutzerinteraktion
- Ändern des aktuellen Bearbeiters und Dokumentenstatus
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:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation dmsobjectwithmapping
.
{
"_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.
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.
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.
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:
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.
GET /dms
Accept: application/hal+json
Das JSON-Objekt enthält die Linkrelation new
.
{
"_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:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation new
.
{
"_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.
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:
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:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation new
.
{
"_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.
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:
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 ( 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.
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:
HTTP/1.1 200 OK
Beispiel 2: Dokument in Status "Bearbeitung" überführen oder den Bearbeiter ändern mit Standardzuordnung
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:
HTTP/1.1 200 OK
Beispiel 3: Dokument in Status "Freigabe" überführen mit Standardzuordnung
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:
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 |
---|---|
| 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
|
| 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. |
| 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 |
| 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 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. |
| 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 Alternativ zu dieser Eigenschaft können Sie die Eigenschaft |
| 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 |
| 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 Legen Sie diesen Parameter fest, dann müssen Sie die unter Diese Eigenschaft ist optional, wenn Sie ein DMS-Objekt aktualisieren oder eine Akte erstellen möchten. |
| 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 Legen Sie diesen Parameter fest, dann müssen Sie die unter Diese Eigenschaft ist optional, wenn Sie ein DMS-Objekt aktualisieren oder eine Akte erstellen möchten. |
| 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. |
| Gibt die URL an, die über 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:
Beispiel für eine Datei mit dem Inhalt "Example":
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#:
|
Struktur eines Objekts im Array "properties"
Eigenschaft | Beschreibung |
---|---|
| 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 ( |
| 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 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 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:
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:
GET /myapp/sources/mysource/myfile.txt
Accept: application/octet-stream, */*
AuthSessionID: SampleAuthsessionId
Die Antwort Ihres Quellsystems muss wie folgt aussehen:
HTTP/1.1 200 OK
Content-Length: 3495
<binary content>
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:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation chunkedupload
.
{
"_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
.
POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/
Origin: https://baseuri
Content-Type: application/octet-stream
<binary content>
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 unterLocation
erhalten haben.- Wiederholen Sie den vorherigen Schritt nacheinander für alle Teilstücke in der richtigen Reihenfolge.
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>
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 nicht200
), 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):
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 |
---|---|
| Enthält die ID des bereits existierenden DMS-Objektes. |
| Enthält die Linkrelation |
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
|
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:
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 |
userdata | Gibt das Array mit den Ergebnissen, welche Optionen ein Anwender ausgewählt hat, als Name-Wert-Paare (Key-Value) an. Die Eigenschaft |
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):
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.
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.
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:
GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json
Das JSON-Objekt zu einem Repository enthält die Linkrelation mappingconfig
.
{
"_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
.
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. |
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 Wenn Sie eine Eigenschaft zuordnen, dann kann
Wenn Sie das Erstellungsdatum ( 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
).
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.
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.
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.
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.
{
"_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:
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:
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:
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."
}
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:
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:
{
"_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:
|
versions | Gibt das Array mit Versionen an. |
Struktur einer Version
Eigenschaft | Beschreibung |
---|---|
_links | Enthält die Linkrelationen zu der Version eines DMS-Objektes.
|
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:
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.
{
"_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:
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):
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.
{
"_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:
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):
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. |
Erweiterung um eigene Funktionen (DMSApp)
In diesem Thema lernen Sie, wie Sie die DMSApp um eigene Funktionen erweitern können.
Verwenden von Erweiterungspunkten
Mit Erweiterungspunkten haben Sie die Möglichkeit, die DMSApp um Ihre eigenen Funktionen zu erweitern. An folgenden Stellen bietet die DMSApp Erweiterungspunkte:
- Ersetzen des Inhalts der Perspektive "Anzeige" in der Detailansicht
- Hinzufügen von Kontextaktionen zu Listen
- Hinzufügen von Kontextaktionen zur Detailansicht
Es gibt zwei Arten, wie Sie die Erweiterungspunkte in der DMSApp erweitern können:
- Bereitstellen per URL
- Über die API in der DMSApp anlegen
Vorbereiten Ihrer App
Damit Erweiterungen zu Kontextaktionen oder der Anzeige von Dokumenten von der DMSApp gefunden werden, muss Ihre App diese Schnittstelle bereitstellen. Die DMSApp nutzt zum Auffinden von Apps, die Erweiterungen bereitstellen, 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 Erweiterungspunkten
Die Rootressourcen dieser Apps werden zyklisch abgefragt (Request). Die Antwort (Response) einer App wird daraufhin geprüft, ob eine Linkrelation namens dmsobjectextensions
enthalten ist. Diese Linkrelation gilt als Signal, dass die App Erweiterungen für die DMSApp anbietet. Die DMSApp führt ein HTTP GET
auf den angegeben Link aus und erwartet von der antwortenden App ein genormtes JSON-Objekt mit dem HTTP-Statuscode 200.
GET https://host/myapp/ HTTP/1.1
Accept: application/hal+json
HTTP/1.1 200 OK
Content-Type: application/hal+json
{
"_links" : {
"dmsobjectextensions" : {
"href" : "/myapp/dmsobjectextensions"
}
}
}
Hinweis Die Abfrage der Rootressourcen erfolgt anonym (ohne Authentifizierung) und wird als asynchroner Hintergrundprozess innerhalb der DMSApp ausgeführt. |
Über die API in der DMSApp erstellen
Mit einer HTTP POST
-Anforderung für die URL /dms/extensions
können Sie eine Erweiterung bei der DMSApp erstellen. Wenn Sie mehrere Erweiterungen erstellen möchten, wiederholen Sie den Vorgang. Die Anforderung darf nur von einem Benutzer mit Administrationsrechten gestellt werden. Ist die Antwort der Anforderung erfolgreich, wird die Erweiterung in der DMSApp gespeichert und Sie erhalten eine Location
-URL im Header der Antwort. Der Aufbau des genormten JSON-Objektes ist in den folgenden Seiten beschrieben.
POST /dms/extensions
Origin: https://baseuri
Content-Type: application/json
Content-Length: 619
{
"id": "myapp.openExternalApp",
"activationConditions": [{
"propertyId": "repository.id",
"operator": "or",
"values": ["e632f767-5cfa-538d-ab55-6756c36a74c9"]
}
],
"captions": [{
"culture": "de",
"caption": "Externe Applikation öffnen"
}, {
"culture": "en",
"caption": "Open external application"
}
],
"context": "DmsObjectDetailsContextAction",
"uriTemplate": "/myapp/dosomething?id={dmsobject.property_document_id}",
"iconUri": "/myapp/images/goto.svg"
}
HTTP/1.1 201 Created
Location: /dms/extensions/dmsapp-custom-myapp.openExternalApp
Über die Location
-URL kann ein Benutzer mit Administrationsrechten die Erweiterung in der DMSApp auch wieder löschen. Dazu muss eine HTTP DELETE
-Anforderung an den Wert der Location
-URL gesendet werden.
DELETE /dms/extensions/dmsapp-custom-myapp.openExternalApp
Origin: https://baseuri
HTTP/1.1 200 OK
Anzeigen von Erweiterungspunkten
Freigegeben: HTML-Seite
Sie können die bei der DMSApp registrierten Erweiterungspunkte anzeigen. Geben Sie einfach die URL /dms/extensions
im Browser ein.
GET /dms/extensions
Accept: text/html
Hinzufügen von Kontextaktionen zu Listen
Freigegeben: Erweiterungspunkt
Wenn Sie Kontextaktionen zu Listen mit Elementen (z.B. Dokumenten und Akten) hinzufügen, werden diese in folgenden Sektionen angezeigt:
- Ergebnisse im Feature Suche
- Inhalt einer Akte
- Ihre Favoritenlisten und die Liste der beobachteten Elemente im Feature Persönlicher Bereich
Klickt der Anwender auf eine Kontextaktion einer Liste, wechselt die Liste immer zunächst in den Auswahlmodus. Im Auswahlmodus kann der Anwender die gewünschten Elemente auswählen und die Kontextaktion ausführen.
Die App, die solche Erweiterungen bereitstellen möchte, muss unter der Linkrelation dmsobjectextensions
eine HTTP-Antwort (Response) im JSON-Format zurückgeben, in der zu jeder Kontextaktion folgende Informationen bereitgestellt werden:
- Kontext des Erweiterungspunkts:
DmsObjectListContextAction
- Aktivierungsbedingungen zum Anzeigen der Kontextaktion.
- Anzeigename der Kontextaktion in den verfügbaren Übersetzungen.
- Link zum Symbol der Kontextaktion.
- Die Aktion, die ausgeführt werden soll, wenn die Auswahl vom Anwender abgeschlossen wurde. Geben Sie einen relativen Link an, der per
HTTP GET
von der DMSApp aufgerufen wird.
Jede Kontextaktion kann auch per HTTP POST
-Anforderung für die URL /dms/extensions
in der DMSApp erstellt werden. Die Anforderung darf nur von einem Benutzer mit Administrationsrechten gestellt werden. Wenn die Antwort der Anforderung erfolgreich ist, wird die Erweiterung in der DMSApp gespeichert und Sie erhalten eine Location
-URL im Header der Antwort. Über die Location
-URL kann ein Benutzer mit Administrationsrechten die Erweiterung in der DMSApp auch wieder löschen. Dazu muss eine HTTP DELETE
-Anforderung an den Wert der Location
-URL gesendet werden.
Beispiel
Das Beispiel zeigt, wie Sie die HTTP-Antwort der Linkrelation dmsobjectextensions
gestalten, um eine Kontextaktion mithilfe eines Erweiterungspunkts DmsObjectListContextAction
hinzuzufügen. Je Kontextaktion definieren Sie verschiedene Eigenschaften.
{
"extensions": [
{
"id": "myapp.exportList",
"activationConditions": [{
"propertyId": "repository.id",
"operator": "or",
"values": ["e632f767-5cfa-538d-ab55-6756c36a74c9"]
}],
"captions": [{
"culture": "de",
"caption": "Exportieren"
},
{
"culture": "en",
"caption": "Export"
},
{
"culture": "en-GB",
"caption": "Exportin Great Britain"
}],
"descriptions": [{
"culture": "de",
"description": "Liste als CSV exportieren"
},
{
"culture": "en",
"description": "Export list as CSV"
},
{
"culture": "en-GB",
"description": "Export list as CSV in Great Britain"
}],
"context": "DmsObjectListContextAction",
"uriTemplate": "/myapp/dosomething?url={dmsobjectlist.url}",
"iconUri": "/myapp/images/export-list.svg",
"target": "dapi_navigate"
}]
}
Eigenschaft | Eigenschaften eines enthaltenen Objekts | Beschreibung | |
---|---|---|---|
id | - | Legt den eindeutigen technischen Namen fest, der verwendet wird, um die Erweiterung von anderen Erweiterungen zu unterscheiden. | |
activationConditions | Pro Erweiterung teilt die Anwendung mit, unter welchen Aktivierungsbedingungen die Kontextaktion angezeigt werden soll. Diese Aktivierungsbedingungen werden vorab von der Anwendung mitgeteilt. Würden die Aktivierungsbedingungen nicht vorab mitgeteilt, müsste die DMSApp zu einem späteren Zeitpunkt, an dem der Anwender sich ein Element ansieht, andere Apps mit einer Netzwerkanforderung (Request) abfragen. Die Wartezeit für den Anwender würde dann stark steigen, wenn eine App nur verzögert auf diese Anfrage reagiert. Eine Kontextaktion wird dann angezeigt, wenn alle Einzelbedingungen zutreffen. Enthält die Liste der Aktivierungsbedingungen keinen Eintrag, ist die Erweiterung generell aktiv. Sie geben die Aktivierungsbedingungen als Array an. | ||
propertyId | Gibt die ID der Eigenschaft an, die für die Aktivierungsbedingung geprüft wird. Mögliche Werte werden weiter unten beschrieben. | ||
operator | Der Operator gibt an, auf welche Art und Weise eine Einzelbedingung ausgewertet wird. Folgender Operator steht zur Verfügung: or: Eine notOr: Eine | ||
values | Gibt die Werte in Form eines Arrays an, die mit dem Wert der propertyId -Eigenschaft verglichen werden. | ||
captions | Jede Kontextaktion teilt mit, unter welchem Namen sie angezeigt wird. Sie können auch verschiedene Sprachen berücksichtigen, wobei Sie die sprachabhängigen Namen als Array angeben. Für eine vollständige Kompatibilität von Sprachpaketen geben Sie die Sprachen für folgende
Wird vom Anwender eine Sprache angefordert, für die die erweiternde App keine Angabe zum lokalisierten (sprachspezifischen) Namen angegeben hat, wird nach folgenden Regeln eine alternative Sprache für die Anzeige bestimmt:
| ||
culture | Gibt die Sprachkennung an, zu der der Name der Kontextaktion definiert wird. Die Angabe enthält den Sprachcode (z.B. en) und optional einen zusätzlichen Regionscode (z.B. en-GB). | ||
caption | Gibt den sprachabhängigen Namen der Kontextaktion an. | ||
descriptions | (Optional) Jede Kontextaktion kann mitteilen, welche Beschreibung für die jeweilige Kontextaktion angezeigt wird. Diese Beschreibung wird als Tooltipp bei der Kontextaktion angezeigt. Verschiedene Sprachen werden wie in der Eigenschaft captions angegeben. | ||
culture | Gibt die Sprachkennung an, zu der die Beschreibung der Kontextaktion definiert wird. Die Angabe enthält den Sprachcode (z.B. en) und optional einen zusätzlichen Regionscode (z.B. en-GB). | ||
description | Gibt die sprachabhängige Beschreibung der Kontextaktion an. | ||
context | - | Gibt den gewünschten Erweiterungspunkt an, zu dem die Kontextaktion hinzugefügt werden soll. Geben Sie für Kontextaktionen zur Detailansicht folgenden Wert an:
| |
uriTemplate | - | Sie definieren in der Eigenschaft
| |
iconUri | - | Gibt den Link zum Symbol an, das für die Kontextaktion angezeigt wird. Die Datei für das Symbol muss im SVG-Format vorhanden sein. Die Füllfarbe des SVGs darf nicht festgelegt sein, damit die Füllfarbe über das Theming angepasst werden kann. Wenn Sie eine eigene SVG-Datei als Symbol verwenden möchten, ist es empfehlenswert, die SVG-Datei im Ordner des Installationsverzeichnisses | |
target | - | (Optional) Gibt an, wo der Inhalt der Kontextaktion angezeigt werden soll. Mögliche Werte:
|
Verwenden Sie beim Definieren von Aktivierungsbedingungen bei Kontextaktionen zu Listen folgende Werte für die propertyId
-Eigenschaft:
Bedingungskontext | propertyId | Beschreibung |
---|---|---|
Repository | repository.id | ID des Repositorys, wie in der d.ecs repo-App angegeben. Die Repository-ID finden Sie in der Detailsektion des Features d.3 Repositorys ( Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die ID zu einem Repository programmatisch ermitteln. |
Benutzer | user.d3.group_id | Aktivierungsbedingung: ID einer d.3-Benutzergruppe (maximal acht Zeichen), in der der aktuell angemeldete Anwender Mitglied ist. |
user.idp.group_id | Aktivierungsbedingung: GUID einer Benutzergruppe der identity provider-App, in der der aktuell angemeldete Anwender Mitglied ist. |
Für eine Kontextaktion vom Typ DmsObjectListContextAction
können Sie folgende Eigenschaften als Platzhalter in der uriTemplate
-Eigenschaft verwenden:
Eigenschaft | Beschreibung |
---|---|
dmsobjectlist.url | Eine URL-codierte URL, unter der die Liste der vom Anwender ausgewählten Elemente (Dokumente und Akten) abgefragt werden kann. Als HTTP-Antwort erhalten Sie diese URL als JSON-Array
Beispiel:
selectionList
|
repository.id | ID des Repositorys, wie in der d.ecs repo-App angegeben. Die Repository-ID finden Sie in der Detailsektion des Features d.3 Repositorys ( Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die ID zu einem Repository programmatisch ermitteln. |
user.d3.group_id | Platzhalter uriTemplate : Liste der IDs der d.3-Benutzergruppen (jeweils maximal acht Zeichen) als Array im JSON-Format, in denen der aktuell angemeldete Anwender Mitglied ist. |
user.idp.group_id | Platzhalter uriTemplate : Liste der GUIDs der Benutzergruppen der identity provider-App als Array im JSON-Format, in denen der aktuell angemeldete Anwender Mitglied ist. |
Hinzufügen von Kontextaktionen zur Detailansicht
Freigegeben: Erweiterungspunkt
Sie können Kontextaktionen zur Detailansicht für ein Element (DMS-Objekt, Dokument oder Akte) hinzufügen. Diese Kontextaktionen werden auch im Menü für Kontextaktionen (drei übereinander liegende Pünktchen) für ein Element zusammengefasst. Die App, die eine solche Erweiterung bereitstellen möchte, muss unter der Linkrelation dmsobjectextensions
eine HTTP-Antwort im JSON-Format zurückgeben, in der zu jeder Kontextaktion folgende Informationen bereitgestellt werden:
- Kontext des Erweiterungspunkts:
DmsObjectDetailsContextAction
- Aktivierungsbedingungen zum Anzeigen der Kontextaktion.
- Anzeigename der Kontextaktion in den verfügbaren Übersetzungen.
- Link zum Symbol der Kontextaktion.
- Die Aktion, die ausgeführt werden soll, wenn der Anwender auf die Kontextaktion geklickt hat. Geben Sie einen relativen Link an, der per
HTTP GET
von der DMSApp aufgerufen wird.
Jede Kontextaktion kann auch per HTTP POST
-Anforderung für die URL /dms/extensions
in der DMSApp erstellt werden. Die Anforderung darf nur von einem Benutzer mit Administrationsrechten gestellt werden. Wenn die Antwort der Anforderung erfolgreich ist, wird die Erweiterung in der DMSApp gespeichert und Sie erhalten eine Location
-URL im Header der Antwort. Über die Location
-URL kann ein Benutzer mit Administrationsrechten die Erweiterung in der DMSApp auch wieder löschen. Dazu muss eine HTTP DELETE
-Anforderung an den Wert der Location
-URL gesendet werden.
Beispiel
Das Beispiel zeigt, wie Sie die HTTP-Antwort der Linkrelation dmsobjectextensions
gestalten, um eine Kontextaktion mithilfe eines Erweiterungspunkts DmsObjectDetailsContextAction
hinzuzufügen. Je Kontextaktion definieren Sie verschiedene Eigenschaften.
{
"extensions": [
{
"id": "myapp.openExternalApp",
"activationConditions": [{
"propertyId": "repository.id",
"operator": "or",
"values": ["e632f767-5cfa-538d-ab55-6756c36a74c9"]
}],
"captions": [{
"culture": "de",
"caption": "Externe Applikation öffnen"
},
{
"culture": "en",
"caption": "Open external application"
}],
"context": "DmsObjectDetailsContextAction",
"uriTemplate": "/myapp/dosomething?id={dmsobject.property_document_id}",
"iconUri": "/myapp/images/goto.svg",
"target": "dapi_navigate"
}]
}
Eigenschaft | Eigenschaften eines enthaltenen Objekts | Beschreibung | |
---|---|---|---|
id | - | Legt den eindeutigen technischen Namen fest, der verwendet wird, um die Erweiterung von anderen Erweiterungen zu unterscheiden. | |
activationConditions | Pro Erweiterung teilt die Anwendung mit, unter welchen Aktivierungsbedingungen die Kontextaktion angezeigt werden soll. Diese Aktivierungsbedingungen werden vorab von der Anwendung mitgeteilt. Würden die Aktivierungsbedingungen nicht vorab mitgeteilt, müsste die DMSApp zu einem späteren Zeitpunkt, an dem der Anwender sich ein Dokument ansieht, andere Apps mit einer Netzwerkanforderung (Request) abfragen. Die Wartezeit für den Anwender würde dann stark steigen, wenn eine App nur verzögert auf diese Anfrage reagiert. Eine Kontextaktion wird dann angezeigt, wenn alle Einzelbedingungen zutreffen. Enthält die Liste der Aktivierungsbedingungen keinen Eintrag, ist die Erweiterung generell aktiv. Sie geben die Aktivierungsbedingungen als Array an. | ||
propertyId | Gibt die ID der Eigenschaft an, die für die Aktivierungsbedingung geprüft wird. Mögliche Werte werden weiter unten beschrieben. | ||
operator | Der Operator gibt an, auf welche Art und Weise eine Einzelbedingung ausgewertet wird. Folgender Operator steht zur Verfügung: or: Eine notOr: Eine | ||
values | Gibt die Werte in Form eines Arrays an, die mit dem Wert der propertyId -Eigenschaft verglichen werden. | ||
captions | Jede Kontextaktion teilt mit, unter welchem Namen sie angezeigt wird. Sie können auch verschiedene Sprachen berücksichtigen, wobei Sie die sprachabhängigen Namen als Array angeben. Für eine vollständige Kompatibilität von Sprachpaketen geben Sie die Sprachen für folgende
Wird vom Anwender eine Sprache angefordert, für die die erweiternde App keine Angabe zum lokalisierten (sprachspezifischen) Namen angegeben hat, wird nach folgenden Regeln eine alternative Sprache für die Anzeige bestimmt:
| ||
culture | Gibt die Sprachkennung an, zu der der Name der Kontextaktion definiert wird. Die Angabe enthält den Sprachcode (z.B. en) und optional einen zusätzlichen Regionscode (z.B. en-GB). | ||
caption | Gibt den sprachabhängigen Namen der Kontextaktion an. | ||
context | - | Gibt den gewünschten Erweiterungspunkt an, zu dem die Kontextaktion hinzugefügt werden soll. Geben Sie für Kontextaktionen zur Detailansicht folgenden Wert an:
| |
uriTemplate | - | Sie definieren in der Eigenschaft
| |
iconUri | - | Gibt den Link zum Symbol an, das für die Kontextaktion angezeigt wird. Die Datei für das Symbol muss im SVG-Format vorhanden sein. Die Füllfarbe des SVGs darf nicht gesetzt sein, damit diese über das Theming angepasst werden kann. Wenn Sie eine eigene SVG-Datei als Symbol verwenden möchten, ist es empfehlenswert, die SVG-Datei im Ordner des Installationsverzeichnisses | |
target | - | (Optional) Gibt an, wo der Inhalt der Kontextaktion angezeigt werden soll. Mögliche Werte:
|
Die nachfolgenden Werte können Sie bei der Definition von Kontextaktionen zur Detailansicht in folgenden Bereichen nutzen:
- Definition von Aktivierungsbedingungen für die Eigenschaft
propertyId
- Festlegen von Platzhaltern in der Eigenschaft
uriTemplate
Thema | Wert | Beschreibung |
---|---|---|
Repository | repository.id | ID des Repositorys, wie in der d.ecs repo-App angegeben. Die Repository-ID finden Sie in der Detailsektion des Features d.3 Repositorys (https://<Basisadresse>/repo/repositories/ ). Sie erhalten diese ID, indem Sie entweder die URL verwenden oder im Startmenü auf Alle Programme > d.velop > d.3one > Repository-Konfiguration klicken. |
Benutzer | user.d3.group_id | Aktivierungsbedingung: ID einer d.3-Benutzergruppe (maximal acht Zeichen), in der der aktuell angemeldete Anwender Mitglied ist. Platzhalter |
user.idp.group_id | Aktivierungsbedingung: GUID einer Benutzergruppe der identity provider-App, in der der aktuell angemeldete Anwender Mitglied ist. Platzhalter | |
Eigenschaften zum Element | dmsobject.property_editor | Bearbeiter des Elements. |
dmsobject.property_owner | Besitzer des Elements. | |
dmsobject.property_filename | Dateiname des Elements. | |
dmsobject.property_filetype | Dateityp des Elements. | |
dmsobject.property_document_number | Dokumentnummer des Elements. | |
dmsobject.property_creation_date | Erstellungsdatum des Elements. | |
dmsobject.property_size | Dateigröße des Elements. | |
dmsobject.property_state | Dokumentstatus des Elements. Mögliche Werte:
| |
dmsobject.property_variant_number | Variantennummer des Elements. | |
dmsobject.property_access_date | Zugriffsdatum des Elements. | |
dmsobject.property_remark | Bemerkungen zum Element. | |
dmsobject.property_last_alteration_date | Änderungsdatum des Elements. | |
dmsobject.property_caption | Titel des Elements. | |
dmsobject.property_category | ID der Kategorie des Elements. | |
dmsobject.property_category_uuid | UUID der Kategorie des Elements. | |
dmsobject.property_colorcode | Farbmarkierung des Elements. | |
dmsobject.property_document_class | Aktivierungsbedingung: Kürzel einer Dokumentklasse des Elements. Platzhalter | |
dmsobject.property_document_id | Dokument-ID des Elements. | |
dmsobject.property_display_version_id | Eindeutige ID der Anzeigeversion seitens der DMSApp. | |
dmsobject.type | Typ des Elements. Mögliche Werte:
| |
| Geben Sie für den Platzhalter Handelt es sich bei der d.3-Eigenschaft um eine Mehrfacheigenschaft, wird der Platzhalter durch den ersten oder den ersten gefüllten Wert der Eigenschaft ersetzt (abhängig von der d.3-Repositorykonfiguration). Sind mehrere Werte für die Mehrfacheigenschaft vorhanden, wird der zurückgegebene Wert um drei Punkte (...) ergänzt. | |
dmsobject.fieldposition.<NUMBER> | Geben Sie für den Platzhalter
Handelt es sich bei der d.3-Eigenschaft um eine Mehrfacheigenschaft, wird der Platzhalter durch den ersten oder den ersten gefüllten Wert der Eigenschaft ersetzt (abhängig von der d.3-Repositorykonfiguration). Sind mehrere Werte für die Mehrfacheigenschaft vorhanden, wird der zurückgegebene Wert um drei Punkte (...) ergänzt. | |
dmsobject.self_url_relative | Relative URL des Elements. | |
Originaldatei des Elements | dmsobject.mainblob.content_type | MIME-Typ der Originaldatei (z.B. text\plain oder image\jpeg ). |
dmsobject.mainblob.content_url | (Veraltet) Absolute URL der Originaldatei. Wenn der Benutzer keine Berechtigung hat, das Dokument zu exportieren, dann ist dieser Parameter leer. | |
dmsobject.mainblob.content_url_relative | Relative URL der Originaldatei. Wenn der Benutzer keine Berechtigung hat, das Dokument zu exportieren, dann ist dieser Parameter leer. | |
dmsobject.mainblob.id | ID der Originaldatei, falls der Anwender das Recht besitzt, die Originaldatei zu exportieren. | |
Abhängige Dateien zum Element | dmsobject.dependentblobs | Liste der IDs der abhängigen Dateien, falls der Anwender das Recht besitzt, die abhängige Datei zu exportieren. |
dmsobject.dependentblob.ID.content_url | (Veraltet) Absolute URL der abhängigen Datei mit der ID aus dmsobject.dependentblobs . | |
dmsobject.dependentblob.ID.content_url_relative | Relative URL der abhängigen Datei mit der ID aus dmsobject.dependentblobs . |
Ersetzen des Inhalts der Perspektive "Anzeige" in der Detailansicht
Freigegeben: Erweiterungspunkt
Sie können den Inhalt der Perspektive Anzeige zur Detailansicht zu einem Element (z.B. Dokument oder Akte) ersetzen, damit Sie unter bestimmten Bedingungen eine eigene Vorschau darstellen können.
Die App, die eine solche Erweiterung bereitstellen möchte, muss unter der Linkrelation dmsobjectextensions
eine HTTP-Antwort im JSON-Format zurückgeben, in der zu jedem Erweiterungspunkt der Anzeige-Perspektive folgende Informationen bereitgestellt werden:
- Kontext des Erweiterungspunkts:
DmsObjectDetailsPreview
- Aktivierungsbedingungen zum Anzeigen Ihrer Vorschau.
- Die URL für die Vorschau, die angezeigt werden soll, wenn der Anwender die Perspektive Anzeige der Detailansicht öffnet und Ihre definierten Aktivierungsbedingungen zutreffen. Geben Sie einen relativen Link an, der per
HTTP GET
von der DMSApp aufgerufen wird.
Jede Kontextaktion kann auch per HTTP POST
-Anforderung für die URL /dms/extensions
in der DMSApp erstellt werden. Die Anforderung darf nur von einem Benutzer mit Administrationsrechten gestellt werden. Wenn die Antwort der Anforderung erfolgreich ist, wird die Erweiterung in der DMSApp gespeichert und Sie erhalten eine Location
-URL im Header der Antwort. Über die Location
-URL kann ein Benutzer mit Administrationsrechten die Erweiterung in der DMSApp auch wieder löschen. Dazu muss eine HTTP DELETE
-Anforderung an den Wert der Location
-URL gesendet werden.
Beispiel
Das Beispiel zeigt, wie Sie die HTTP-Antwort der Linkrelation dmsobjectextensions
gestalten, um eine Erweiterung zum Erweiterungspunkt DmsObjectDetailsPreview
hinzuzufügen. Je Erweiterung definieren Sie verschiedene Eigenschaften.
{
"extensions": [
{
"id": "myapp.viewer",
"activationConditions": [{
"propertyId": "dmsobject.mainblob.content_type",
"operator": "or",
"values": [
"text/plain",
"application/pdf"
]
}],
"context": "DmsObjectDetailsPreview",
"uriTemplate": "/myapp/preview?layer0={dmsobject.mainblob.content_url}"
}]
}
Eigenschaft | Eigenschaften eines enthaltenen Objekts | Beschreibung | |
---|---|---|---|
id | - | Legt den eindeutigen technischen Namen fest, der verwendet wird, um die Erweiterung von anderen Erweiterungen zu unterscheiden. | |
activationConditions | Pro Erweiterung teilt die Anwendung mit, unter welchen Aktivierungsbedingungen die Erweiterung der Anzeige-Perspektive angezeigt werden soll. Diese Aktivierungsbedingungen werden vorab von der Anwendung mitgeteilt. Würden die Aktivierungsbedingungen nicht vorab mitgeteilt, müsste die DMSApp zu einem späteren Zeitpunkt, an dem der Anwender sich ein Element ansieht, andere Apps mit einer Netzwerkanforderung (Request) abfragen. Die Wartezeit für den Anwender würde dann stark steigen, wenn eine App nur verzögert auf diese Anforderung reagiert. Eine Erweiterung wird dann angezeigt, wenn alle Einzelbedingungen zutreffen. Enthält die Liste der Aktivierungsbedingungen keinen Eintrag, ist die Erweiterung generell aktiv. Sie geben die Aktivierungsbedingungen als Array an. | ||
propertyId | Gibt die ID der Eigenschaft an, die für die Aktivierungsbedingung geprüft wird. Mögliche Werte werden weiter unten beschrieben. | ||
operator | Der Operator gibt an, auf welche Art und Weise eine Einzelbedingung ausgewertet wird. Folgender Operator steht zur Verfügung: or: Eine notOr: Eine | ||
values | Gibt die Werte in Form eines Arrays an, die mit dem Wert der propertyId -Eigenschaft verglichen werden. | ||
context | - | Gibt den gewünschten Erweiterungspunkt an, zu dem die Erweiterung hinzugefügt werden soll. Geben Sie für Erweiterungen der Anzeige-Perspektive der Detailansicht folgenden Wert an:
| |
uriTemplate | - | Sie definieren in der Eigenschaft
|
Die nachfolgenden Werte können Sie bei der Definition von Erweiterungen, die den Inhalt der Anzeige-Perspektive ersetzen, in folgenden Bereichen nutzen:
- Definieren von Aktivierungsbedingungen für die Eigenschaft
propertyId
- Festlegen von Platzhaltern in der Eigenschaft
uriTemplate
Thema | Wert | Beschreibung |
---|---|---|
Repository | repository.id | ID des Repositorys, wie in der d.ecs repo-App angegeben. Die Repository-ID finden Sie in der Detailsektion des Features d.3 Repositorys ( Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die ID zu einem Repository programmatisch ermitteln. |
Benutzer | user.d3.group_id | Aktivierungsbedingung: ID einer d.3-Benutzergruppe (maximal acht Zeichen), in der der aktuell angemeldete Anwender Mitglied ist. Platzhalter |
user.idp.group_id | Aktivierungsbedingung: GUID einer Benutzergruppe der identity provider-App, in der der aktuell angemeldete Anwender Mitglied ist. Platzhalter | |
Eigenschaften zum Element | dmsobject.property_editor | Bearbeiter des Elements. |
dmsobject.property_owner | Besitzer des Elements. | |
dmsobject.property_filename | Dateiname des Elements. | |
dmsobject.property_filetype | Dateityp des Elements. | |
dmsobject.property_document_number | Dokumentnummer des Elements. | |
dmsobject.property_creation_date | Erstellungsdatum des Elements. | |
dmsobject.property_size | Dateigröße des Elements. | |
dmsobject.property_state | Dokumentstatus des Elements. Mögliche Werte:
| |
dmsobject.property_variant_number | Variantennummer des Elements. | |
dmsobject.property_access_date | Zugriffsdatum des Elements. | |
dmsobject.property_remark | Bemerkungen zum Element. | |
dmsobject.property_last_alteration_date | Änderungsdatum des Elements. | |
dmsobject.property_caption | Titel des Elements. | |
dmsobject.property_category | ID der Kategorie des Elements. | |
dmsobject.property_category_uuid | UUID der Kategorie des Elements. | |
dmsobject.property_colorcode | Farbmarkierung des Elements. | |
dmsobject.property_document_class | Aktivierungsbedingung: ID einer Dokumentklasse des Elements. Platzhalter | |
dmsobject.property_document_id | Dokument ID des Elements. | |
dmsobject.property_display_version_id | Eindeutige ID der Anzeigeversion seitens der DMSApp. | |
dmsobject.property_version_id | Eindeutige ID der aktuellen Version seitens der DMSApp. | |
dmsobject.type | Typ des Elements. Mögliche Werte:
| |
dmsobject.<NUMBER|UUID> | Geben Sie für den Platzhalter Handelt es sich bei der d.3-Eigenschaft um eine Mehrfacheigenschaft, wird der Platzhalter durch den ersten oder den ersten gefüllten Wert der Eigenschaft ersetzt (abhängig von der d.3-Repositorykonfiguration). Sind mehrere Werte für die Mehrfacheigenschaft vorhanden, wird der zurückgegebene Wert um drei Punkte (...) ergänzt. | |
dmsobject.fieldposition.<NUMBER> | Geben Sie für den Platzhalter
Handelt es sich bei der d.3-Eigenschaft um eine Mehrfacheigenschaft, wird der Platzhalter durch den ersten oder den ersten gefüllten Wert der Eigenschaft ersetzt (abhängig von der d.3-Repositorykonfiguration). Sind mehrere Werte für die Mehrfacheigenschaft vorhanden, wird der zurückgegebene Wert um drei Punkte (...) ergänzt. | |
| Relative URL des Elements. | |
Originaldatei des Elements | dmsobject.mainblob.content_type | MIME-Typ der Originaldatei (z.B. text\plain oder image\jpeg ). |
dmsobject.mainblob.content_url | (Veraltet) Absolute URL der Originaldatei. Wenn der Benutzer keine Berechtigung hat, das Dokument zu exportieren, dann ist dieser Parameter leer. | |
dmsobject.mainblob.content_url_relative | Relative URL der Originaldatei. Wenn der Benutzer keine Berechtigung hat, das Dokument zu exportieren, dann ist dieser Parameter leer. | |
dmsobject.mainblob.id | ID der Originaldatei, falls der Anwender das Recht besitzt, die Originaldatei zu exportieren. | |
Abhängige Dateien zum Element | dmsobject.dependentblobs | Liste der IDs der abhängigen Dateien, falls der Anwender das Recht besitzt, die abhängige Datei zu exportieren. |
dmsobject.dependentblob.ID.content_url | (Veraltet) Absolute URL der abhängigen Datei mit der ID aus dmsobject.dependentblobs . | |
dmsobject.dependentblob.ID.content_url_relative | Relative URL der abhängigen Datei mit der ID aus dmsobject.dependentblobs . |