DMS-APP

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 DUX (d.velop user experience) zu verfügen.
  • 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.

Request
   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.

Request
   GET /dms
Accept: application/hal+json
Response
   {
	_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:

Request
   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.

Response
   {
	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:

Request
   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.

Response
   {
	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):

Response
   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:

EigenschaftBeschreibung
reason

Ein optionaler kurzer Beschreibungstext, weshalb der Fehler aufgetreten ist. Dieser Text wird als Titel der Fehlermeldung verwendet.

hintEin optionaler Hinweistext für den Anwender mit Tipps für die Fehlerbehebung.
detailsOptionale 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 bietet Ihnen die Möglichkeit, DMS-Objekte zu speichern und zu aktualisieren.

Weitere Informationen zum Speichern neuer DMS-Objekte mithilfe des Ablagedialogs finden Sie unter Speichern neuer DMS-Objekte mit Benutzerinteraktion. Wie Sie den Ablagedialog zum Aktualisieren vorbereiten und anzeigen finden Sie in dem Kapitel Aktualisieren eines DMS-Objektes mit Benutzerinteraktion.

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:

Request
   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.

Response
   {
	_links: {
		dmsobjectpreview: {
			href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/{dmsobjectid}/preview",
			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.

Aufrufen der URL für die Anzeige der Vorschau

Rufen Sie die Vorschau folgendermaßen auf:

Request
   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:

Request
   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.

Response
   {
	_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:

Request
   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.

Response
   {
	_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:

ParameterBeschreibung

showresultlist

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).

repositoryid

Definiert die Repository-ID.

Die Beschreibungen zu den Parametern objectdefinitionidsfulltext und properties finden Sie im Kapitel Definieren der Parameter für einen Suchvorgang und eine Ergebnisliste.

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:

Request
   GET /dms/s/?objectdefinitionids=["RECH"]&fulltext=Mustermann&properties={"227":["KND001"]}&repoid=dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: text/html

Anforderung mit Repository-ID:

Request
   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.

Anwendungsbeispiele für verschiedene Suchanfragen:

  • Suchen in einer Dokumentart: Ergänzen Sie die URL um den Teil objectdefinitionids=["<Dokumentartname kurz>"].

https://<Basisadresse>/dms/r/<RepositoryID>/s/?fulltext=5353&objectdefinitionids=["RECH"]

  • Suchen in mehreren Dokumentarten: Ergänzen Sie die URL um den Teil objectdefinitionids=["<Dokumentartname kurz>","<Dokumentartname kurz>"].

https://<Basisadresse>/dms/r/<RepositoryID>/s/?fulltext=5353&objectdefinitionids=["RECH","AUFT"]

  • Suchen nach PDF-Dokumenten mit Einschränkungen auf den Dateityp: Ergänzen Sie die URL um den Teil properties={"property_filetype":["<Dateierweiterung>"]}.

https://<Basisadresse>/dms/r/<RepositoryID>/s/?fulltext=test&properties={"property_filetype":["pdf"]}

  • Suchen nach einer alphanumerischen Eigenschaft: Ergänzen Sie den properties-Parameter in der URL um properties={"227":["KND001"]} (nicht encodiert), um das Eigenschaftsfeld mit der RID 227 (Kundennummer) und dem Wert "KND001" als Kundennummer zu suchen.

https://<Basisadresse>/dms/r/<RepositoryID>/s/?objectdefinitionids=["RECH"]&fulltext=&properties={"227":["KND001"]}

  • Suchen nach mehreren Eigenschaften: Ergänzen Sie den properties-Parameter in der URL um properties={"227":["KND001"],"231":["|-100"]} (nicht encodiert), um das Eigenschaftsfeld mit der RID 227 (Kundennummer) mit dem Wert "KND001" und das Eigenschaftsfeld mit der RID 231 (Rechnungsbetrag) mit dem Wert kleiner oder gleich 100 zu suchen.

https://<Basisadresse>/dms/r/<RepositoryID>/s/?objectdefinitionids=["RECH"]&fulltext=&properties={"227":["KND001"],"231":["|-100"]}

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:

Request
   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.

Response
   {
	_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:

ParameterBeschreibung

showdetails

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.

  • Caption/Titel: property_caption
  • Besitzer: property_owner
  • Dateiendung: property_filetype
  • Bemerkung: property_remark
  • Zugriffsdatum: property_access_date
  • Bearbeiter: property_editor
  • Dokument-ID: property_document_id
  • Dokumentnummer: property_document_number
  • Dateigröße: property_size
  • Dokumentstatus: property_state
  • Geändert am: property_last_modified_date
  • Datei geändert am: property_last_alteration_date

  • Farbmarkierung: property_colorcode

  • Kategorie: property_category

  • Erstellt am: property_creation_date

  • Zugriffsdatum: property_access_date

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 (d3admin.pdf).

ascending

Gibt die Richtung der Sortierreihenfolge an.

  • ascending=true: führt zu einer aufsteigenden Sortierung (von klein nach groß (A-Z) und von alt nach jung).
  • ascending=false: führt zu absteigenden Sortierung (von groß nach klein (Z-A) und von jung nach alt).

Wird der ascending-Parameter nicht explizit angegeben, wird eine aufsteigende Sortierung vorgenommen. Davon ausgenommen ist die Standardsortierung: Wird nach dem Kriterium Geändert am sortiert und ist die Sortierreihenfolge nicht angegeben, wird in diesem Fall absteigend sortiert.

Außerdem werden in der Ergebnisliste zunächst die Akten und dann die Dokumente angezeigt. Innerhalb von Dokumenten und Akten wird nach dem Sortierkriterium sortiert.

children_ofGibt die Dokument-ID an, zu der die verknüpften direkten untergeordneten Elemente gesucht werden.

Die Beschreibungen zu den Parametern objectdefinitionidsfulltext 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:

Request
   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.

Anwendungsbeispiele für verschiedene Ergebnislisten:

  • Suchen in einer Dokumentart: Ergänzen Sie die URL um den Teil objectdefinitionids=["<Dokumentartname kurz>"].

https://<Basisadresse> /dms/r/ <RepositoryID>/sr/?fulltext=5353&objectdefinitionids=["RECH"]

  • Suchen in mehreren Dokumentarten: Ergänzen Sie die URL um den Teil objectdefinitionids=["<Dokumentartname kurz>","<Dokumentartname kurz>"].

https://<Basisadresse> /dms/r/<RepositoryID>/sr/?fulltext=5353&objectdefinitionids=["RECH","AUFT"]

  • Suchen nach PDF-Dokumenten mit Einschränkungen auf den Dateityp: Ergänzen Sie die URL um den Teil properties={"property_filetype":["<Dateierweiterung>"]}.

https://<Basisadresse> /dms/r/ <RepositoryID>/sr/?fulltext=test&properties={"property_filetype":["pdf"]}

  • Suchen nach einer alphanumerischen Eigenschaft: Ergänzen Sie den properties-Parameter in der URL um properties={"227":["KND001"]} (nicht encodiert), um das Eigenschaftsfeld mit der RID 227 (Kundennummer) und dem Wert "KND001" als Kundennummer zu suchen.

https://<Basisadresse> /dms/r/ <RepositoryID>/sr/?objectdefinitionids=["RECH"]&fulltext=&properties={"227":["KND001"]}

  • Suchen nach mehreren Eigenschaften: Ergänzen Sie den properties-Parameter in der URL um properties={"227":["KND001"],"231":["|-100"]} (nicht encodiert), um das Eigenschaftsfeld mit der RID 227 (Kundennummer) mit dem Wert "KND001" und das Eigenschaftsfeld mit der RID 231 (Rechnungsbetrag) mit dem Wert kleiner oder gleich 100 zu suchen.

https://<Basisadresse> /dms/r/ <RepositoryID>/sr/?objectdefinitionids=["RECH"]&fulltext=&properties={"227":["KND001"],"231":["|-100"]}

  • Definieren der Sortierung der Ergebnisliste nach Titel: Ergänzen Sie die URL um den Teil propertysort=property_caption.

https://<Basisadresse> /dms/r/<RepositoryID>/sr/?fulltext=&objectdefinitionids=["RECH"]&propertysort=property_caption

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.

ParameterBeschreibung

objectdefinitionids

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):

  • objectdefinitionids=["RECH"]: für die Suche in der Dokumentart Rechnung ("RECH").
  • objectdefinitionids=["RECH","AUFT"]: für die Suche in den Dokumentarten Rechnung ("RECH") und Aufträge ("AUFT"). 

fulltext

Gibt einen Volltextsuchbegriff an.

properties

Gibt eine Sucheinschränkung nach Eigenschaften der Dokumente und Akten an. Mit folgenden Kriterien können Sie einen Suchvorgang einschränken:

  • Dokument-ID: property_document_id
  • Dateityp: property_filetype
  • Dokumentnummer: property_document_number
  • Dokumentstatus: property_state (Mögliche Werte sind Be für Bearbeitung, Pr für Prüfung, Fr für Freigabe und Ar für Archiv)
  • Bearbeiter: property_editor (d.3-Benutzerkennung)

  • Dateiname: property_filename

  • Importdatum: property_creation_date

  • Dateigröße: property_size (Bei der Suche nach der Dateigröße muss die Größe in Bytes als Ganzzahl angegeben werden. Bereichssuchen mit dem Trennzeichen Pipe- und Minus-Zeichen (|-) sind ebenfalls möglich: Mit dem Ausdruck {"property_size ":["|-1024"]} suchen Sie nach Dokumenten, deren Nutzdatei kleiner oder gleich 1024 Bytes ist.

  • Geändert am: property_last_modified_date

  • Datei geändert am: property_last_alteration_date

  • Zugriff am: property_access_date

  • Bemerkung: property_remark

  • Farbmarkierung: property_colorcode (Ist eine Ganzzahl zwischen 1 und 24, die der Nummer des gewünschten Farbcodes entspricht).

  • Variantennummer: property_variant_number

Sie können je Eigenschaft mindestens einen Wert definieren.

Beispiele (nicht encodiert):

  • properties={"property_filetype"=["docx"]}: für die Suche nach dem Dateityp "docx".
  • properties={"property_filetype"=["docx","pdf"]}: für die Suche nach Elementen mit dem Dateityp "docx" oder "pdf".

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 (d3admin.pdf). 

Beispiele (nicht encodiert):

  • properties={"227"=["KND001"]}: für die Suche nach Elementen, die die erweiterte Eigenschaft mit der ID "227" besitzen und diese Eigenschaft den Wert "KND001" hat.
  • properties={"227"=["KND001","KND002"]}: für die Suche nach Elementen, die die erweiterte Eigenschaft mit der ID "227" besitzen und diese Eigenschaft den Wert "KND001" oder "KND002" hat.


Sie können auch mehrere Eigenschaften gleichzeitig als Sucheinschränkung verwenden:

Beispiele (nicht encodiert):

  • properties={"227"=["KND001"],"231":["|-100"]}: für die Suche nach Elementen mit der Kundennummer (erweiterte Eigenschaft mit der ID "227") "KND001" und einem Rechnungsbetrag (erweiterte Eigenschaft mit der ID "231") kleiner oder gleich 100.
  • properties={"227"=["KND001"],"property_filetype":["pdf"]}: für die Suche nach Elementen mit der Kundennummer (erweiterte Eigenschaft mit der ID "227") "KND001" und dem Dateityp "pdf".

Spezielle Angaben für den properties-Parameter in Bezug auf verschiedene Einschränkungsmöglichkeiten, um gezielt zum Ergebnis zu gelangen:

  1. Suche nach einem numerischen Wert oder einem Geldwert:
    Geben Sie den Wert ohne Tausendertrennzeichen an. Als Dezimaltrennzeichen gilt der Punkt (.). Beispiel: Für den Wert 1.000,20 EUR geben Sie 1000.20 an.
  2. Suche nach einem Datum und Uhrzeit:
    Geben Sie das Datum im Format YYYY-MM-DD an. Beispiel: Für den 05.12.2014 (DD.MM.YYYY) geben Sie 2014-12-05 an.
    Zeitangaben werden nach dem Format YYYY-MM-DDTHH:MM:SS.ZZZ+01:00 durchführt. Das Pluszeichen (+) müssen Sie mit %2b encodieren. Beispiel: 2015-02-18T23:59:59.999%2b01:00 für den 18.02.2014 um 23:59 Uhr und 59.999 Millisekunden in der Zeitzone UTC+1 für Winterzeit in Deutschland.
  3. Suche nach Elementen, die sich in einem bestimmten Bereich befinden:
    Für die Bereichssuche verwenden Sie als Trennzeichen eine Kombination aus einem Pipe- und Minuszeichen (|-). Beispiele für ein numerisches Feld mit der ID "231":
  • Werte größer oder gleich 100:  {"231":["100|-"]}
  • Werte kleiner oder gleich 100: {"231":["|-100"]}
  • Werte zwischen 100 und 200: {"231":["100|-200"]}

Anbinden von externen Systemen (DMSApp)

In diesem Kapitel erfahren Sie, wie Sie externe Systeme (Drittanbieteranwendungen) an die DMSApp anbinden können, um Zuordnungen (Mappings) in der DMSApp zu erstellen. Ein externes System stellt aus Sicht der DMSApp ein Quellsystem dar. Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern.



Definieren eines Quellsystems

Freigegeben: Erweiterungspunkt

Wenn Sie ein System haben, das Ausgangsdaten bereitstellt (z.B. eine E-Mail-Anwendung oder ein ERP-System), müssen Sie für das Erstellen einer Zuordnung (Mapping) die Elemente des Quellsystems für ein d.3-Repository vorbereiten. Ein Element eines Quellsystems wird Quelle genannt. Eine Quelle enthält Quelleigenschaften und Quellkategorien. Indem Sie eine Quelle definieren, geben Sie der DMSApp die Möglichkeit, die Bezeichner für die Metadaten der Quelle mit den Bezeichnern für die Metadaten des d.3-Repositorys zu verbinden.

Vorbereiten Ihrer App

Damit Quellsysteme von der DMSApp gefunden werden, muss Ihre App diese Schnittstelle bereitstellen. Die DMSApp nutzt zum Auffinden von Apps, die als Quellsysteme dienen, das Konzept einer HTTP GET-Anforderung für die Rootressource (systemBaseUri-Pfad mit dem App-Namen) der Apps. Es werden alle Apps abgefragt, die an d.ecs http gateway registriert sind. Stellen Sie sicher, dass der Administrator Ihre App nicht aktiv ausgeschlossen hat.

Bereitstellen der URL zu den Quellen

Die Rootressourcen der Apps werden zyklisch abgerufen (Request). Die Antwort (Response) einer App wird daraufhin geprüft, ob eine Linkrelation namens sources enthalten ist. Diese Linkrelation gilt als Signal, dass die App als Quellsystem mindestens eine Quelle für die DMSApp anbietet. Die DMSApp führt eine HTTP GET-Anforderung auf den angegeben Link aus und erwartet von der antwortenden App ein genormtes JSON-Objekt mit dem HTTP-Statuscode 200. 

Request
   GET https://host/myapp/ HTTP/1.1
Accept: application/hal+json


Response
   HTTP/1.1 200 OK
Content-Type: application/hal+json

{
    "_links" : {
        "sources" : {
            "href" : "/myapp/sources"
        }
    }
}

Die Abfrage der Rootressourcen erfolgt anonym (ohne Authentifizierung) und wird als asynchroner Hintergrundprozess innerhalb der DMSApp ausgeführt.

Bereitstellen der Quellen

Nachdem die URLs der Quellen (sources) ermittelt wurden, werden die Quellen der Apps mit HTTP GET von der DMSApp abgerufen.

Das Beispiel zeigt, wie Sie die HTTP-Antwort der Linkrelation sources gestalten, um Quellen der DMSApp bekannt zu machen.

Request
   GET https://host/myapp/sources HTTP/1.1
Accept: application/hal+json


Response
   HTTP/1.1 200 OK
Content-Type: application/hal+json

{
	"sources" : [{
		"id" : "/myapp/sources/mysource",
		"displayName" : "My Source",
		"categories": [{
			"key": "mycategory1", 
			"displayName": "My category 1"
		}, 
		{
			"key": "mycategory2", 
			"displayName": "My category 2"
		}],
		"properties" : [{
			"key" : "myprop1",
			"displayName" : "My property 1"
		}, 
		{
			"key" : "myprop2",
			"displayName" : "My property 2"
		},
		{
			"key" : "myprop3",
			"displayName" : "My property 3"
		}]
	}]
}

 Struktur einer Quelle

EigenschaftEigenschaft eines enthaltenen ObjektsBeschreibung
sources
          
-Das Quellsystem kann in diesem Array mehrere Quellen ausliefern (z.B. E-Mail, Anlagen etc.), um verschiedene Zuordnungsarten zu unterscheiden.
id

Gibt den eindeutigen Bezeichner der Quelle an.

Die ID muss eine relative URI sein. Die relative URI sollte mit dem Namen der App beginnen, die das Quellsystem bereitstellt, damit eine Eindeutigkeit gewährleistet ist (z.B. /myapp/sources/mysource).

displayName

Gibt den Anzeigenamen an, wie er in der Administrationsoberfläche Zuordnungen im Feld Quelle angezeigt wird.

Mit Blick auf die Internationalisierung arbeitet die DMSApp mit dem HTTP-Header Accept-Language. Dieser HTTP-Header muss vom Quellsystem ausgewertet und der Anzeigename der Quelle sprachspezifisch ausgegeben werden.

categoriesGibt 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

EigenschaftBeschreibung
key
Gibt den eindeutigen Bezeichner der Kategorie der Quelle an.
displayName

Gibt den Anzeigenamen an, wie er in der Administrationsoberfläche Zuordnungen im Bereich Kategorien im Feld Quelle angezeigt wird.

Mit Blick auf die Internationalisierung arbeitet die DMSApp mit dem HTTP-Header Accept-Language. Dieser HTTP-Header muss vom Quellsystem ausgewertet und der Anzeigename der Kategorie sprachspezifisch ausgegeben werden.


Struktur einer Quelleigenschaft

EigenschaftBeschreibung
key
Gibt den eindeutigen Bezeichner der Eigenschaft der Quelle an.
displayName

Gibt den Anzeigenamen an, wie er in der Administrationsoberfläche Zuordnungen im Bereich Eigenschaften im Feld Quelle angezeigt wird.

Die DMSApp arbeitet zur Internationalisierung mit dem HTTP-Header Accept-Language. Dieser HTTP-Header muss vom Quellsystem ausgewertet und der Anzeigename der Eigenschaft sprachspezifisch ausgegeben werden.

Stellen Sie Folgendes sicher: Die Quellen müssen performant abgerufen werden können, damit die Antwortzeit des Features Zuordnungen nicht negativ beeinflusst wird.

Abrufen des Standardquellsystems zu einem d.3-Repository

Freigegeben: JSON-Repräsentation

Das Standardquellsystem ist ein vordefiniertes Quellsystem pro d.3-Repository, das standardmäßig von der DMSApp bereitgestellt wird. Wenn Sie eine Erweiterung zu DMS-Funktionalitäten bereitstellen und kein eigenes Quellsystem definieren möchten, können Sie mit dem Standardquellsystem die Eigenschaften und Kategorien des d.3-Repositorys verwenden.

Die Definition eines Standardquellsystems und die zugehörigen Zuordnungen werden von der DMSApp festgelegt. Sie können Zuordnungen zu einem Standardquellsystem nicht ändern.

In diesem Kapitel erfahren Sie, wie Sie die Quellsystemdefinition je d.3-Repository abrufen können.

Um die Quellsystemdefinition eines d.3-Repositorys abzurufen, müssen Sie folgende Schritte durchführen:

  • Ermitteln der URL zu einem Repository
  • Ermitteln der Linkrelation zum Abrufen der Quellsystemdefinition eines d.3-Repositorys
  • Aufrufen der URL für die Quellsystemdefinition eines d.3-Repositorys

Ermitteln der URL zu einem Repository

Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.

Ermitteln der Linkrelation zum Abrufen der Quellsystemdefinition eines d.3-Repositorys

Das JSON-Objekt zu einem d.3-Repository enthält die Linkrelation source, mit deren Hilfe Sie die Quellsystemdefinition des d.3-Repositorys abrufen können.

Response
   {
	"_links": {
		"source": {
			"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source"
		}
	},
	"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

Aufrufen der URL für die Quellsystemdefinition eines d.3-Repositorys

Sie müssen sicherstellen, dass Sie sich für das d.3-Repository authentifizieren können. Nur dann können Sie die URL abrufen. Das Standardquellsystem enthält alle Kategorien und Eigenschaften des d.3-Repositorys unabhängig von den Berechtigungen des Benutzers.

Rufen Sie die Quellsystemdefinition des d.3-Repositorys mit der zuvor ermittelten URL wie folgt ab:

Request
   GET https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source HTTP/1.1
Accept: application/hal+json


Response
   HTTP/1.1 200 OK
Content-Type: application/hal+json

{
	"id": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source",
	"displayName": "D3RepositoryName",
	"properties": [
		{
			"key": "Key0",
			"type": "String",
			"displayName": "Sample property1"
		}
	],
	"categories":[
		{
			"key": "mycategory1",
			"displayName": "Sample category1"
		}
	]
}


 Struktur einer Quelle

EigenschaftBeschreibung
idGibt den eindeutigen Bezeichner des Standardquellsystems an. Diese ID verwenden Sie als Wert zum Parameter sourceId bei weiteren API-Funktionen.
displayNameGibt den Anzeigenamen eines d.3-Repositorys an.
categoriesGibt das Array der Kategorien des abgefragten Quellsystems an.
propertiesGibt das Array der Eigenschaften des abgefragten Quellsystems an.

Struktur einer Kategorie

EigenschaftBeschreibung

key

Gibt den eindeutigen Bezeichner der Kategorie im Quellsystem an.

displayName

Gibt den Anzeigenamen der Kategorie an.

Mit Blick auf die Internationalisierung arbeitet die DMSApp mit dem HTTP-Header Accept-Language. Dieser HTTP-Header sorgt dafür, dass der Anzeigename der Kategorie sprachspezifisch ausgegeben wird.

 

Struktur einer Eigenschaft

EigenschaftBeschreibung

key

Gibt den eindeutigen Bezeichner der Eigenschaft im Quellsystem an.
type

Gibt den Typ der Eigenschaft zurück.

Der Typ der Eigenschaft wird vom Administrator beim Erstellen der Eigenschaft definiert. Mögliche Werte sind: String, ColorCode, DateTime, Date, Double, Money.

displayName

Gibt den Anzeigenamen der Eigenschaft an.

Die DMSApp arbeitet zur Internationalisierung mit dem HTTP-Header Accept-Language. Dieser HTTP-Header sorgt dafür, dass der Anzeigename der Eigenschaft sprachspezifisch ausgegeben wird.

Abrufen und Anzeigen der Ergebnisse eines Suchvorgangs

Freigegeben: JSON-Repräsentation, HTML-Seite

Sie können beim Abrufen oder Anzeigen von Ergebnissen eines Suchvorgangs durch Angeben einer bestimmten Quelle sowie zugehörigen Quellkategorien und Quelleigenschaften die Ergebnismenge eingrenzen. Auch ein Volltextsuchbegriff kann zur Einschränkung des Suchergebnisses angegeben werden. Im Kapitel 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:

Request
   GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

Das JSON-Objekt zu einem Repository enthält die Linkrelation searchresultwithmapping mit Platzhaltern für die Werte, mit deren Hilfe das Abrufen oder Anzeigen der Ergebnisse eines Suchvorgangs durchgeführt wird.

Response
   {
	_links: {
		searchresultwithmapping: {
			href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm{?sourceid,sourceproperties,sourcecategories,sourcepropertysort,ascending,fulltext,page,pagesize}",
			templated: true
		}
	},
	id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

Angeben von verhaltenssteuernden Parametern

Das Verhalten beim Abrufen oder Anzeigen von Suchergebnissen zu einem Suchvorgang steuern Sie mit folgenden Parametern. Sie müssen die Parameter der URL encodieren (z.B. Leerzeichen in %20). Die Länge des encodierten Abfrageparameters darf 2000 Zeichen nicht überschreiten.

ParameterBeschreibung
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):

  • sourceproperties={"myprop1":["Test E-Mail 1"]}: für die Suche nach Elementen mit der d.3-Eigenschaft mit dem Wert "Test E-Mail 1", die der Quelleigenschaft mit der ID "myprop1" zugeordnet wurde.
  • sourceproperties={"myprop1":["Test E-Mail 1", "Test E-Mail 2"]}: für die Suche nach Elementen mit der d.3-Eigenschaft mit dem Wert "Test E-Mail 1" oder "Test E-Mail 2", die der Quelleigenschaft mit der ID "myprop1" zugeordnet wurde.

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):

  • sourceproperties={"myprop1":["Test E-Mail 1"],"myprop2":["Max Mustermann"]}: für die Suche nach Elementen mit der d.3-Eigenschaft mit dem Wert "Test E-Mail 1", die der Quelleigenschaft mit der ID "myprop1" zugeordnet wurde und der d.3-Eigenschaft mit dem Wert "Max Mustermann", die der Quelleigenschaft mit der ID "myprop2" zugeordnet wurde.
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):

  • sourcecategories=["mycategory1"]: für die Suche in der d.3-Kategorie, die der Quellkategorie mit der ID "mycategory1" zugeordnet wurde.
  • sourcecategories=["mycategory1","mycategory2"]: für die Suche in den d.3-Kategorien, die der Quellkategorie mit der ID "mycategory1" oder "mycategory2" zugeordnet wurden. 
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.

  • ascending=true: führt zu einer aufsteigenden Sortierung (von klein nach groß (A-Z) und von alt nach jung).
  • ascending=false: führt zu absteigenden Sortierung (von groß nach klein (Z-A) und von jung nach alt).

Wird der ascending-Parameter nicht explizit angegeben, wird eine aufsteigende Sortierung vorgenommen. Davon ausgenommen ist die Standardsortierung: Wird nach dem Kriterium Geändert am sortiert und ist die Sortierreihenfolge nicht angegeben, wird in diesem Fall absteigend sortiert.

Außerdem werden in der Ergebnisliste zunächst die Akten und dann die Dokumente angezeigt. Innerhalb von Dokumenten und Akten wird nach dem angegebenen Sortierkriterium sortiert.

fulltextGibt 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.

Spezielle Angaben für den sourceproperties-Parameter in Bezug auf verschiedene Einschränkungsmöglichkeiten, um gezielt zum Ergebnis zu gelangen:

  1. Suche nach einem numerischen Wert oder einem Geldwert:
    Geben Sie den Wert ohne Tausendertrennzeichen an. Als Dezimaltrennzeichen gilt der Punkt (.). Beispiel: Für den Wert 1.000,20 EUR geben Sie 1000.20 an.
  2. Suche nach einem Datum und Uhrzeit:
    Geben Sie das Datum im Format YYYY-MM-DD an. Beispiel: Für den 05.12.2014 (DD.MM.YYYY) geben Sie 2014-12-05 an.
    Zeitangaben werden nach dem Format YYYY-MM-DDTHH:MM:SS.ZZZ+01:00 durchführt. Das Pluszeichen (+) müssen Sie mit %2b encodieren. Beispiel: 2015-02-18T23:59:59.999%2b01:00 für den 18.02.2014 um 23:59 Uhr und 59.999 Millisekunden in der Zeitzone UTC+1 für Winterzeit in Deutschland.
  3. Suche nach Elementen, die sich in einem bestimmten Bereich befinden:
    Für die Bereichssuche verwenden Sie als Trennzeichen eine Kombination aus einem Pipe- und Minuszeichen (|-). Beispiele für ein numerisches Feld mit der ID "231":
  • Werte größer oder gleich 100:  {"231":["100|-"]}
  • Werte kleiner oder gleich 100: {"231":["|-100"]}
  • Werte zwischen 100 und 200: {"231":["100|-200"]}

Aufrufen der URL für die Ergebnisse eines Suchvorgangs (JSON-Repräsentation)

Wenn Sie eine URL erzeugt haben, dann können Sie die Ergebnisse des Suchvorgangs wie folgt abrufen:

Request
   GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?sourceid=/myapp/sources/mysource&sourceproperties={"myprop1":["Test E-Mail 1"]}&sourcecategories=["mycategory1"]&sourcepropertysort=myprop1&ascending=true&fulltext=test&page=1&pagesize=50
Accept: application/json

Als Ergebnis wird dann folgendes JSON-Objekt zurückgegeben:

Response
   {
  "_links": {
    "next": {
      "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?...page=2"
    },
    "self": {
      "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?...page=1"
    }
  },
  "page": 1,
  "items": [
    {
      "_links": {
        "self": { "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123" }
      },
      "id": "D000000123",
      "sourceProperties": [
        {
          "key": "myprop1",
          "value": "Test E-Mail 1",
          "isMultiValue": false
        },
        {
          "key": "myprop2",
          "value": "Max Mustermann",
          "isMultiValue": true
        },
        "..."
      ],
      "sourceCategories": [ "mycategory1" ]
    },
    "..."
  ]
}

EigenschaftBeschreibung
_links

Enthält die Linkrelationen zum Element.

self: Self-Link.

next: Relative URL zum Abrufen der nächsten Seite der Ergebnisliste. Wird nur angegeben, wenn es weitere Ergebnisse gibt.

prev: Relative URL zum Abrufen der vorherigen Seite der Ergebnisliste. Wird nur angegeben, wenn es vorherige Ergebnisse gibt.

pageGibt die Seitennummer der Ergebnisliste an.
itemsGibt das Array mit Elementen der Ergebnisse für den Suchvorgang für die angeforderte Seite an.


Struktur eines Elementes der Ergebnisliste

EigenschaftBeschreibung
_links

Enthält die Linkrelationen zu dem Element.

self: Self-Link.

delete oder deleteWithReason: Falls vorhanden, kann das Element mit einem HTTP DELETE-Anforderung (Request) gelöscht werden. Weitere Informationen finden Sie unter Löschen der aktuellen Version eines DMS-Objektes ohne Benutzerinteraktion.

update oder updateWithContent: Falls vorhanden, kann das Element mit einem HTTP PUT-Anforderung (Request) aktualisiert werden. Weitere Informationen finden Sie unter Speichern einer neuen Version ohne Benutzerinterkation.

idGibt 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

EigenschaftBeschreibung
keyGibt den eindeutigen Bezeichner der Quelleigenschaft an.
value

Gibt den Wert der zugeordneten d.3-Eigenschaft an.

isMultiValue

Gibt an, ob die zugeordnete d.3-Eigenschaft eine Mehrfacheigenschaft ist.

Handelt es sich bei der d.3-Eigenschaft um eine Mehrfacheigenschaft, wird bei value der erste oder der erste gefüllte Wert der Eigenschaft zurückgegeben (abhängig von der d.3-Repositorykonfiguration). Um alle Mehrfachwerte abzurufen, verwenden Sie die Anforderung (Request) zum Abrufen der Details eines DMS-Objektes.

Aufrufen der URL für die Ergebnisse eines Suchvorgangs (HTML-Seite)

Wenn Sie die HTML-Darstellung der Ergebnisse aufrufen möchten, erzeugen Sie die URL in derselben Weise, wie beim Abfragen der JSON-Repräsentation beschrieben. Geben Sie die URL im Browser ein, um die HTML-Seite anzuzeigen. Diese HTML-Seite enthält die Bezeichner der d.3-Eigenschaften und d.3-Kategorien.

Beispiel (nicht encodiert):

Request
   GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?sourceid=/myapp/sources/mysource&sourceproperties={"myprop1":["Test E-Mail 1"]}&sourcecategories=["mycategory1"]&sourcepropertysort=myprop1&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:

Request
   GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

Das JSON-Objekt zu einem Repository enthält die Linkrelation dmsobjectwithmapping mit Platzhaltern für die Werte, mit deren Hilfe das Abrufen oder Anzeigen der Details eines DMS-Objektes durchgeführt wird.

Response
   {
	_links: {
		dmsobjectwithmapping: {
			href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/{dmsobjectid}{?sourceid}",
			templated: true
		}
	},
	id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

Angeben von verhaltenssteuernden Parametern

Das Verhalten beim Abrufen oder Anzeigen von Details eines DMS-Objektes steuern Sie mit folgenden Parametern:

ParameterBeschreibung
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, finden Sie unter Definieren eines Quellsystems.

Wenn Sie das Standardquellsystem verwenden möchten, finden Sie weitere Informationen unter Abrufen des Standardquellsystems zu einem d.3-Repository.

Abrufen (JSON-Repräsentation):

Es werden nur die Eigenschaften der Quelle zurückgegeben, die den d.3-Eigenschaften zugeordnet wurden. Wird keine Quelle angegeben, werden nur die ID und die Linkrelationen zum DMS-Objekt zurückgegeben.

Anzeigen (HTML-Seite):

Wenn Sie die Details eines DMS-Objektes anzeigen möchten, ist das Angeben dieses Parameters nicht erforderlich. Der Parameter wird nicht ausgewertet.

Aufrufen der URL für die Details eines DMS-Objektes (JSON-Repräsentation)

Wenn Sie eine URL erzeugt haben, dann können Sie die Details des DMS-Objektes wie folgt abrufen:

Request
   GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123?sourceid=/myapp/sources/mysource
Accept: application/json

Als Ergebnis wird dann folgendes JSON-Objekt zurückgegeben:

Response
   {
  "_links": {
    "self": { 
		"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123"
     },
    "mainblobcontent": {
        "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/current/b/main/c"
     },
     "editinoffice": {
	   "href": "{ms-word:ofe|u|{+clientOrigin}/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/dav/D000000123%20(D000000123).DOCX}",
       "templated": true
     },
	 "pdfblobcontent": {
       "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/current/b/p1/c"
     },
	 "notes":{
	   "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n"
	 },
	 "children":{
	   "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm/?children_of=D000000123"
	 }
  },
  "id": "D000000123",
  "sourceProperties": [
    {
      "key": "myprop1",
      "value": "value of property 1"
    },
    {
      "key": "myprop2",
      "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"]
}

EigenschaftBeschreibung
_links

Enthält die Linkrelationen zum DMS-Objekt.

mainblobcontent: Relative Download-URL für das Hauptdokument der aktuellen Version des DMS-Objektes.

editinoffice: URL mit Platzhaltern, um das Dokument in Microsoft Office zu bearbeiten. Diese URL erhalten Sie nur, wenn der Administrator die Funktion zum Bearbeiten von Microsoft Office-Dokumenten aktiviert hat.

pdfblobcontent: Relative Download-URL für das abhängige PDF-Dokument der aktuellen Version des DMS-Objektes. Diese URL erhalten Sie nur, wenn ein abhängiges PDF-Dokument für das DMS-Objekt erzeugt wurde.

notes: Relative URL zum Abrufen der Notizen des DMS-Objektes. Diese URL erhalten Sie nur, wenn zum DMS-Objekt bereits Notizen gespeichert wurden.

children: Relative URL für die untergeordneten DMS-Objekte. Diese URL erhalten Sie nur, wenn das DMS-Objekt untergeordnete Elemente hat.

self: Self-Link.

idGibt 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

EigenschaftBeschreibung
keyGibt den eindeutigen Bezeichner der Quelleigenschaft an.
value

Gibt den Wert der zugeordneten d.3-Eigenschaft an.

Handelt es sich bei der d.3-Eigenschaft um eine Mehrfacheigenschaft, wird bei value der erste oder der erste gefüllte Wert der Eigenschaft zurückgegeben (abhängig von der d.3-Repositorykonfiguration).

values

Gibt die Werte der zugeordneten d.3-Eigenschaft an. Wird nur zurückgegeben, wenn die d.3-Eigenschaft eine Mehrfacheigenschaft ist.

values ist ein Objekt, das aus Name-Wert-Paaren (Key-Value) besteht:

Name: Zeilennummer (beginnend bei 1).

Wert: Wert der Eigenschaft in der entsprechenden Zeile.

Aufrufen der URL für die Details eines DMS-Objektes (HTML-Seite)

Wenn Sie die HTML-Darstellung der Ergebnisse aufrufen möchten, erzeugen Sie die URL in derselben Weise, wie beim Abfragen der JSON-Repräsentation beschrieben. Geben Sie die URL im Browser ein, um die HTML-Seite anzuzeigen. Diese HTML-Seite enthält die Bezeichner der d.3-Eigenschaften und d.3-Kategorien.

Beispiel:

Request
   GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123
Accept: text/html

Speichern von DMS-Objekten

Sie können beim Speichern von DMS-Objekten durch Angeben einer bestimmten Quelle sowie zugehörigen Quellkategorien und Quelleigenschaften die Metadaten der Ablage bestimmen. Im Kapitel Definieren eines Quellsystems erfahren Sie, wie Sie eine Quelle für eine Zuordnung bereitstellen können. Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern.

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
  • Aufrufen der URL zur Ablage eines neuen DMS-Objektes


Ermitteln der URL zu einem Repository

Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.

Ermitteln der Linkrelation für die Ablage eines neuen DMS-Objektes

Rufen Sie die URL zu einem Repository wie folgt auf:

Request
   GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

Das JSON-Objekt zu einem Repository enthält die Linkrelation dmsobjectwithmapping.

Response
   {
	"_links": {
		"dmsobjectwithmapping": {
			"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/{dmsobjectid}{?sourceid}",
			"templated":true
		}
	},
	"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

Die Werte dmsobjectid und sourceid sind für das Speichern nicht relevant. Daher füllen Sie diese beim Ausführen des Templates nicht aus.


Bereitstellen der zu speichernden Datei

Im Kapitel Bereitstellen von Dateien erfahren Sie, wie Sie contentUri oder contentLocationUri erhalten. Diese Parameter benötigen Sie zum Speichern eines neuen DMS-Objektes.


Aufrufen der URL zur Ablage eines neuen DMS-Objektes

Führen Sie eine HTTP POST-Anforderung mit den benötigten Eigenschaften als Body auf diese URL aus. 

Request
   POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
	"filename": "myfile.txt",
	"sourceCategory": "mycategory1",
	"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",
				"values": ["Please verify the XYZ invoice"]
			},
			{
				"key": "myprop2",
				"values": ["Name1@contoso.com","Name2@samplecompany.de"]
			}
		],
	}
}

Informationen zu den Parametern des JSON-Objektes finden Sie unter Definieren der Parameter für eine Ablage.

Ist für den d.3-Dokumentstatus keine Zuordnung konfiguriert, wird für das DMS-Objekt standardmäßig der Dokumentstatus Freigabe (Release) verwendet. Möchten Sie einen anderen Dokumentstatus beim Speichern anwenden, muss der Administrator die Eigenschaft Status zugeordnet haben.

Ist der Aufruf erfolgreich, wird die URL zum DMS-Objekt im Header Location zurückgegeben.

Wenn Sie ein Element mit einer Akte (parentId) verknüpfen möchten und diese Aktion fehlschlägt, erhalten Sie als Antwort (Response) die URL zum DMS-Objekt im Header Location und eine zusätzliche Meldung, dass die Verknüpfung nicht erfolgreich war.

Response
   HTTP/1.1 201 Created
Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D0001234?sourceId=%2Fmyapp%2Fsources%2Fmysourc

{
	"reason": "You do not have the right to link the document with the dossier manually.
Nevertheless, the document was successfully saved. The document may be automatically linked on the server."
	"severity": 1
}

Schlägt das Speichern des DMS-Objektes fehl, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen finden Sie unter Format der Antwort bei Fehlern.

Aktualisieren eines DMS-Objektes ohne Benutzerinteraktion

Sie können ein bestehendes DMS-Objekt in einem d.3-Repository aktualisieren, ohne dass ein Anwender eine Aktion ausführen muss. Beim Aktualisieren eines DMS-Objektes ohne Benutzerinteraktion werden keine Validate-Hooks in d.3 server ausgeführt. Grundvoraussetzung für das Durchführen der Aktion sind die Zuordnungen (Mappings). Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern.

Um ein DMS-Objekt zu aktualisieren, müssen Sie folgende Schritte durchführen:

  • Ermitteln der URL zu einem Repository
  • Ermitteln der Linkrelationen zum bestehenden DMS-Objekt
  • Bereitstellen der zu speichernden Datei (optional)
  • Aufrufen der URL zum Aktualisieren des DMS-Objektes

Ermitteln der URL zu einem Repository

Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.

Ermitteln der Linkrelationen zum bestehenden DMS-Objekt

Um eine URL zu einem bestehendem DMS-Objekt zu ermitteln, führen Sie eine Suche aus und werten Sie die Linkrelation update oder updateWithContent zu einem Element der Ergebnisliste aus. Im Kapitel Abrufen und Anzeigen der Ergebnisse eines Suchvorgangs finden Sie weitere Informationen zum Ausführen einer Suche und die Beschreibung eines Elements der Ergebnisliste. Hat das bereits vorhandene DMS-Objekt den d.3-Dokumentstatus Processing muss der authentifizierte Benutzer der Bearbeiter des DMS-Objektes sein.

Bereitstellen der zu speichernden Datei (optional)

Haben Sie eine Linkrelation updateWithContent ermittelt, dann können Sie eine Datei mit den Parametern contentUri oder contentLocationUri bereitstellen. Im Kapitel Bereitstellen von Dateien können Sie nachlesen, wie Sie eine Datei bereitstellen können.

Wenn Sie nur Eigenschaften mit der Linkrelation update aktualisieren möchten, ist die Bereitstellung einer Datei nicht notwendig.

Haben Sie ausschließlich eine Linkrelation update erhalten, dann ist keine Aktualisierung mit Datei möglich.


Aufrufen der URL zum Aktualisieren des DMS-Objektes

Führen Sie eine HTTP PUT-Anforderung mit den benötigten Eigenschaften als Body auf die URL des bestehenden DMS-Objektes aus, die Sie in der Linkrelation update oder updateWithContent erhalten haben. Wenn Sie nur Eigenschaften ändern möchten, geben Sie die Parameter contentLocationUri und filename nicht an.

Request
   PUT /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
	"filename": "myfile.txt",
	"alterationText": "updated file",
	"sourceCategory": "mycategory1",
	"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",
				"values": ["Please verify the XYZ invoice"]
			},
			{
				"key": "myprop2",
				"values": ["Name1@contoso.com","Name2@samplecompany.de"]
			}
		]
	}
}

Informationen zu den Parametern des JSON-Objektes finden Sie unter Definieren der Parameter für eine Ablage.

Ist der Aufruf erfolgreich, wird HTTP 200 OK zurückgegeben:

Response
   HTTP/1.1 200 OK

Schlägt das Speichern der Version fehl, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen finden Sie unter Format der Antwort bei Fehlern.

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
  • Erstellen eines Ablagedialogs mit definierten Eigenschaften und Dateien
  • Anzeigen des Ablagedialogs mit definierten Eigenschaften und Dateien
  • Ausführen weiterer Aktionen nach dem Speichern (optional)


Ermitteln der Linkrelation für den Ablagedialog

Für das Feature Ablage gibt es zwei Linkrelationen:

  • Linkrelation ohne Bezug zu einem d.3-Repository: Beim Ablegen ohne Bezug zu einem d.3-Repository kann der Anwender das d.3-Repository auswählen. Jedoch können Sie in diesem Fall die Datei nicht temporär hochladen. Weitere Informationen zum Bereitstellen finden Sie unter Bereitstellen von Dateien.
  • Linkrelation mit Bezug zu einem d.3-Repository: Beim Ablegen mit Bezug zu einem d.3-Repository kann der Anwender das d.3-Repository nicht mehr ändern.

Um die Linkrelation ohne Bezug zu einem d.3-Repository zu ermitteln, führen Sie eine HTTP GET-Anforderung für die REST-Ressource /dms aus.

Request
   GET /dms
Accept: application/hal+json

Das JSON-Objekt enthält die Linkrelation new.

Response
   {
    "_links": {
        "new": {
            "href": "/dms/new/"
        }
    }
}

Um die Linkrelation mit Bezug zu einem d.3-Repository zu ermitteln, müssen Sie zunächst die URL zu einem Repository kennen. Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln. Führen Sie dann eine HTTP Get-Anforderung auf die URL zu einem Repository wie folgt aus:

Request
   GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

Das JSON-Objekt zu einem Repository enthält die Linkrelation new.

Response
   {
	"_links": {
		"new": {
			"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/"
		}
	},
	"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}


Bereitstellen der zu speichernden Datei

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.


Erstellen eines Ablagedialogs mit definierten Eigenschaften und Dateien

Führen Sie eine HTTP POST-Anforderung mit den benötigten Eigenschaften als Body auf die URL aus, die Sie in der Linkrelation new erhalten haben. 

Request
   POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "storeObjects": [{
        "displayValue": "Please verify the XYZ invoice",
        "filename": "myfile.txt",
        "contentLocationUri": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43",
        "sourceId": "/myapp/sources/mysourcel",
		"sourceCategory": "mycategory1",
		"sourcePropertiesUri": "/myapp/sources/mysourcel/properties/myfile.haljson",
		"successCallbackUri": "/myapp/sources/mysourcel/success/myfile"
    },
    {
        ...
    }]
}

Das JSON-Objekt, das beim POST übergeben wird, ist wie folgt beschrieben:

EigenschaftBeschreibung
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 für eine Ablage.

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.

Wenn Sie mehrere DMS-Objekte speichern möchten, dann wird nur die Quellkategorie (sourceCategory) des ersten Elements im Array storeObjects im Ablagedialog berücksichtigt. Diese Quellkategorie wird für alle weiteren Dateien, die Sie ablegen möchten, dem Anwender angezeigt.

Ist der Aufruf erfolgreich, wird die URL zum Ablagedialog im Header Location zurückgegeben:

Response
   HTTP/1.1 201 Created
Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/a09dd457-5a21-4b90-8134-e562092b50ea

Schlägt das Erstellen des Ablagedialogs fehl, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen finden Sie unter Format der Antwort bei Fehlern.


Anzeigen des Ablagedialogs mit definierten Eigenschaften und Dateien

Rufen Sie die URL, die Sie im Header Location erhalten haben, im Browser auf, um dem Anwender den erstellten Ablagedialog anzuzeigen. Der Anwender kann die Eigenschaften bearbeiten und das Speichern der DMS-Objekte abschließen.

Ausführen weiterer Aktionen nach dem Speichern (optional)

Wenn Sie beim Erstellen des Ablagedialogs den Parameter successCallbackUri angeben und der Anwender das Speichern erfolgreich abgeschlossen hat, wird die URL aufgerufen. Sie können nach dieser Aktion weitere Schritte ausführen. Weitere Informationen finden Sie unter Feedback mithilfe von "SuccessCallback" und "Userdata".

Aktualisieren eines DMS-Objektes 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
  • Ermitteln der Linkrelation für den Ablagedialog
  • Erstellen eines Ablagedialogs mit definierten Eigenschaften und einer Datei
  • Anzeigen des Ablagedialogs mit definierten Eigenschaften und einer Datei
  • 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

Im Kapitel Bereitstellen von Dateien können Sie nachlesen, wie Sie eine Datei bereitstellen können.

Ermitteln der Linkrelation für den Ablagedialog

Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln. Danach führen Sie eine HTTP Get-Anforderung auf die URL zu einem Repository wie folgt aus:

Request
   GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

Das JSON-Objekt zu einem Repository enthält die Linkrelation new .

Response
   {
	"_links": {
		"new": {
			"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/"
		}
	},
	"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}


Erstellen eines Ablagedialogs mit definierten Eigenschaften und einer Datei

Führen Sie eine HTTP POST-Anforderung mit den benötigten Eigenschaften als Body auf die URL aus, die Sie in der Linkrelation new erhalten haben.

Request
   POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "storeObjects": [{
        "dmsObjectId": "D123456789",
        "displayValue": "Please verify the XYZ invoice",
        "filename": "myfile.txt",
        "contentLocationUri": "/dms/blob/chunk/2016-May-24-14-20-26-393-1720.part",
        "sourceId": "/myapp/sources/mysourcel",
        "sourcePropertiesUri": "/myapp/sources/mysourcel/properties/myfile.haljson",
        "successCallbackUri": "/myapp/sources/mysourcel/success/myfile"
    }]
}

Das JSON-Objekt, das beim POST übergeben wird, ist wie folgt beschrieben:

EigenschaftBeschreibung
storeObjectsGibt das Array der Elementeigenschaften und einer Datei an, mit denen der Ablagedialog definiert werden soll. Informationen zu einem Element des Arrays finden Sie unter Definieren der Parameter für eine Ablage. Das Array muss genau ein Element enthalten.

Alternativ können Sie das JSON-Objekt der Elementeigenschaften ohne das übergeordnete Array storeObjects angeben.

Ist der Aufruf erfolgreich, wird die URL zum Ablagedialog im Header Location zurückgegeben:

Response
   HTTP/1.1 201 Created
Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/a09dd457-5a21-4b90-8134-e562092b50ea

Schlägt das Erstellen des Ablagedialogs fehl, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen finden Sie unter Format der Antwort bei Fehlern.

Anzeigen des Ablagedialogs mit definierten Eigenschaften und einer Datei

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 des DMS-Objektes 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".


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:

EigenschaftBeschreibung

displayValue

Gibt den Anzeigenamen des Elements an, das gespeichert wird. Der Anzeigename wird im Ablagedialog für den Anwender sichtbar. Dieser Parameter ist optional.

filename

Gibt den Namen der zu speichernden Datei mit der Dateierweiterung an.

Wenn Sie diesen Parameter festlegen, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Dokumentart zuordnen. Geben Sie diese Eigenschaft nicht an, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Aktenart zuordnen.

Diese Eigenschaft wird ignoriert, wenn Sie ein DMS-Objekt aktualisieren. Dieser Parameter ist optional, sofern Sie keine Datei bereitstellen möchten.

dmsObjectId

Gibt die ID des zu aktualisierenden DMS-Objektes an. Dieser Parameter wird nur beim Aktualisieren eines DMS-Objektes mit Benutzerinteraktion berücksichtigt.
alterationTextGibt den Änderungsgrund für die Aktualisierung eines DMS-Objektes an. In d.3 admin legen Sie fest, ob das Angeben des Parameters verpflichtend ist. Dieser Parameter wird nur beim Aktualisieren eines DMS-Objektes berücksichtigt.

sourceCategory

Gibt an, welche Kategorie für die Zuordnungsverarbeitung beim Speichern verwendet werden soll. Geben Sie die ID der Quellkategorie an.

Das Angeben dieser Eigenschaft ist verpflichtend, außer unter folgenden Bedingungen:

  • Die Eigenschaft wird ignoriert, wenn der Parameter parentId festgelegt ist und eine zugehörige Standardkategorie in d.3 admin wurde definiert.
  • Die Eigenschaft wird ignoriert, wenn sie ein DMS-Objekt aktualisieren.
  • Die Eigenschaft ist optional, wenn das Speichern eines Elements mit Benutzeraktion erfolgt.

Wenn Sie mehrere DMS-Objekte mit Benutzerinteraktion speichern, dann wird nur die Quellkategorie des ersten Elements im Array storeObjects im Ablagedialog berücksichtigt. Diese Quellkategorie wird für alle weiteren Dateien, die Sie ablegen möchten, dem Anwender angezeigt.

sourceId

Legt fest, zu welcher Quelle die Zuordnung gehört, die zum Speichern verwendet werden soll. Die Quelle muss existieren und das Quellsystem muss bei d.ecs http gateway registriert sein, damit die Eigenschaften unter sourcePropertiesUri oder sourceProperties angewendet werden.

Weitere Informationen zum Bereitstellen einer Quelle finden Sie unter Definieren eines Quellsystems.

sourcePropertiesUri

Gibt die URL an, unter der die DMSApp die Elementeigenschaften für die Zuordnungsverarbeitung und Duplikatsprüfung herunterladen soll. Vor dem Speichern des DMS-Objektes sendet die DMSApp eine HTTP GET-Anforderung an die URL, um die Quelleigenschaften für den Ablagevorgang zu ermitteln. Wenn es sich bei sourcePropertiesUri um eine relative URL handelt, werden die Benutzerinformationen des angemeldeten Benutzers in der HTTP-Anforderung ebenfalls übertragen (AuthSessionID). Dadurch haben Sie die Möglichkeit, z.B. eine Berechtigungsprüfung durchzuführen oder den aktuellen Benutzernamen zu berücksichtigen. Bei einer absoluten URL werden die Quelleigenschaften anonym angefordert (request). Unter "Festlegen der Quelleigenschaften" ist das bereitzustellende JSON-Objekt beschrieben.

Alternativ zu dieser Eigenschaft können Sie die Eigenschaft sourceProperties verwenden.

sourceProperties

Gibt ein JSON-Array mit Quelleigenschaften an, die für die Zuordnungsverarbeitung und Duplikatsprüfung verwendet werden. Unter "Festlegen der Quelleigenschaften" ist das bereitzustellende JSON-Objekt beschrieben.

Alternativ zu dieser Eigenschaft können Sie die Eigenschaft sourcePropertiesUri verwenden.

contentLocationUri

Gibt die URL zur temporär hochgeladenen Datei an. Weitere Informationen finden Sie unter Bereitstellung über temporäres Hochladen.

Alternativ können Sie die Eigenschaft contentUri verwenden.

Legen Sie diesen Parameter fest, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Dokumentart zuordnen. Geben Sie weder die contentLocationUri- noch die contentUri-Eigenschaft an, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Aktenart zuordnen.

Diese Eigenschaft ist optional, wenn Sie ein DMS-Objekt aktualisieren.

contentUri

Gibt die relative URL an, unter der die DMSApp die abzulegende Datei herunterlädt. Weitere Informationen finden Sie unter Bereitstellung über temporäres Hochladen.

Alternativ können Sie die Eigenschaft contentLocationUri verwenden.

Legen Sie diesen Parameter fest, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Dokumentart zuordnen. Geben Sie weder die contentLocationUri- noch die contentUri-Eigenschaft an, dann müssen Sie die unter sourceCategory angegebene Kategorie in der Zuordnungsverarbeitung einer Aktenart zuordnen.

Diese Eigenschaft ist optional, wenn Sie ein DMS-Objekt aktualisieren.

parentId

Gibt die DMS-Objekt-ID der Akte an, mit der das abzulegende Element verknüpft werden soll. Ist der Ablagevorgang erfolgreich, wird das abgelegte Element mit der entsprechenden Akte verknüpft. Wurde das abzulegende Element als Duplikat erkannt, wird das bereits vorhandene Element mit der Akte verknüpft.

Wenn Sie eine Akte mit einer anderen Akte verknüpfen möchten, wird jedoch keine Duplikatsprüfung vorgenommen.

Diese Eigenschaft wird ignoriert, wenn Sie ein DMS-Objekt aktualisieren.

successCallbackUri

Gibt die URL an, die über HTTP POST aufgerufen wird, wenn der Ablagevorgang erfolgreich durchgeführt wurde. Die URL muss relativ sein. Weitere Informationen finden Sie unter Feedback mithilfe von "SuccessCallback" und "Userdata".

Diese Eigenschaft ist optional. Sie können die Eigenschaft nur beim Speichern mit Benutzerinteraktion verwenden.


Festlegen der Quelleigenschaften

Sie können die Quelleigenschaften direkt mithilfe des Parameters sourceProperties definieren oder mit der URL in sourcePropertiesUri bereitstellen.

Das JSON-Objekt ist wie folgt beschrieben:

EigenschaftBeschreibung
propertiesGibt 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"

Struktur eines Objekts im Array "properties"

EigenschaftBeschreibung

key

Gibt die ID der Quelleigenschaft an. Es werden nur diejenigen Eigenschaften berücksichtigt, die von Ihnen angegeben und die vom Administrator in der Zuordnung konfiguriert wurden.

Beim Aktualisieren eines DMS-Objektes werden nur die von Ihnen angegebenen Eigenschaften aktualisiert. Alle weiteren Werte der Eigenschaften des bereits vorhandenen DMS-Objektes bleiben bestehen.

values

Gibt ein Array mit den zugehörigen Werten der Elementeigenschaft an. Auch wenn Sie nur einen Wert übergeben möchten, müssen Sie diesen Wert als JSON-Array übergeben.

Sie können den d.3-Dokumentstatus für ein DMS-Objekt beim Speichern eines neuen DMS-Objektes festlegen. Mögliche Werte sind Processing, Verification und Release.

Beim Aktualisieren eines DMS-Objektes werden Zuordnungen zu d.3-Dokumentstatus, d.3-Variantennummer, d.3-Dokument-ID und d.3-Dokumentnummer ignoriert.

Eigenschaften mit der Kennzeichnung "nur lesend" werden beim Speichern nicht berücksichtigt.

Beim Aktualisieren ohne Benutzerinteraktion muss der authentifizierte Benutzer der Bearbeiter des DMS-Objektes sein, wenn das bestehende DMS-Objekt den d.3-Dokumentstatus Processing hat.

Geben Sie numerische Werte ohne Tausendertrennzeichen an. Als Dezimaltrennzeichen gilt der Punkt (.). Beispiel: Für den Wert 1.000,20 EUR geben Sie 1000.20 an.

Geben Sie Datumswerte im Format YYYY-MM-DD an. Beispiel: Für den 05.12.2014 (DD.MM.YYYY) geben Sie 2014-12-05 an.


Beispiel 1: Bereitstellen der Datei und der Eigenschaften durch eine URL 

Ein einfaches JSON-Objekt könnte wie folgt aussehen:

JSON object
   {
    "filename": "myfile.txt",
	"alterationText": "updated file",
    "sourceCategory": "mycategory1",
    "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:

JSON object
   {
    "displayValue": "Please verify the XYZ invoice",
    "filename": "myfile.txt",
	"alterationText": "updated file",
    "sourceCategory": "mycategory1",
    "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",
                "values": ["Please verify the XYZ invoice"]
            },
            {
                "key": "myprop2",
                "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"
    }
}


Bereitstellen von Dateien

Beim Speichern von DMS-Objekten werden deren Eigenschaften und Kategorien gespeichert. Um Dateien speichern zu können, müssen diese der DMSApp bereitgestellt werden und die Quellkategorie muss in der Zuordnungsverarbeitung einer Dokumentart zugeordnet werden. Sie haben zwei Möglichkeiten für die Bereitstellung der Dateien:

Bereitstellen einer Datei mit einer URL

In diesem Kapitel erfahren Sie, wie Sie eine Datei mithilfe einer URL bereitstellen. Beim Speichern von DMS-Objekten geben Sie die URL zu einer Datei in der Eigenschaft contentUri an. Vor dem Speichern des DMS-Objekts lädt die DMSApp die Datei von der angegebenen URL (contentUri) herunter. Bei der URL muss es sich um eine relative URL handeln. Beim Herunterladen werden die Benutzerinformationen des angemeldeten Anwenders in der HTTP-Anforderung ebenfalls übertragen (AuthSessionID). Mithilfe von AuthSessionID haben Sie die Möglichkeit, den Anwender zu identifizieren, um z.B. eine Berechtigungsprüfung durchzuführen.

Da die Datei in einer Anforderung (Request) heruntergeladen wird, eignet sich dieses Verfahren nicht für größere Dateien. Für größere Dateien verwenden Sie das Verfahren zum temporären Hochladen von Dateien. Weitere Informationen finden Sie unter Bereitstellen einer Datei durch temporäres Hochladen.

Downloaden der bereitgestellten Datei

Die DMSApp führt eine HTTP GET-Anforderung auf die im Parameter contentUri angegebene URL aus. Ein Beispiel für die HTTP GET-Anforderung der DMSApp für Ihr Quellsystem sieht wie folgt aus, wenn contentUri folgender URL /myapp/sources/mysource/myfile.txt entspricht:

Request
   GET /myapp/sources/mysource/myfile.txt
Accept: application/octet-stream, */*
AuthSessionID: SampleAuthsessionId

Die Antwort Ihres Quellsystems muss wie folgt aussehen:

Response
   HTTP/1.1 200 OK
Content-Length: 3495

<binary content>




Bereitstellen einer Datei durch temporäres Hochladen

In diesem Kapitel erfahren Sie, wie Sie eine Datei vorläufig bereitstellen, indem Sie die Datei temporär hochladen. Das temporäre Hochladen ist besonders bei großen Dateien sinnvoll. Mit der URL (contentLocationUri) zur temporär hochgeladenen Datei können Sie anschließend das DMS-Objekt speichern.

Um eine Datei temporär hochzuladen, müssen Sie folgende Schritte durchführen:

  • Ermitteln der URL zu einem Repository
  • Ermitteln der Linkrelation zum temporären Hochladen der Datei
  • Aufrufen der URL zum temporären Hochladen der Datei
  • Weitere Aufrufe der URL zum temporären Hochladen der Datei (optional)

Ein temporäres Hochladen einer Datei ohne die Angabe einer ID zu einem Repository ist nicht möglich.

Ermitteln der URL zu einem Repository

Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.


Ermitteln der Linkrelation zum temporären Hochladen der Datei

Rufen Sie die URL zu einem Repository wie folgt auf:

Request
   GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

Das JSON-Objekt zu einem Repository enthält die Linkrelation chunkedupload.

Response
   {
	"_links": {
		"chunkedupload": {
			"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/"
		}
	},
	"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}


Aufrufen der URL zum temporären Hochladen der Datei

Führen Sie eine HTTP POST-Anforderung mit den Binärdaten als Body auf die URL aus, die Sie in der Linkrelation chunkedupload erhalten haben. Wenn der Vorgang erfolgreich war, erhalten Sie den HTTP-Statuscode 201 und die URL (contentLocationUri) im HTTP-Header Location.

Request
   POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/
Origin: https://baseuri
Content-Type: application/octet-stream

<binary content>
Response
   HTTP/1.1 201 Created
Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43


Bei der HTTP Post-Anforderung wird der komplette Body als Binärdaten der hochzuladenden Datei behandelt. Ein Upload mittels multipart/form-data ist derzeit nicht möglich.


Weitere Aufrufe der URL zum temporären Hochladen der Datei (optional)

Sie haben die Möglichkeit, das Hochladen auf mehrere HTTP-Anforderungen aufzuteilen, um bei größeren Dateien einen Timeout zu vermeiden.

Gehen Sie dazu wie folgt vor:

  • Teilen Sie die hochzuladende Datei in verschiedene Teilstücke (Chunks).
  • Laden Sie das erste Teilstück hoch, so wie es unter "Aufrufen der URL zum temporären Hochladen der Datei" beschrieben ist.
  • Laden Sie das nächste Teilstück hoch, indem Sie eine HTTP POST-Anforderung auf die URL ausführen, die Sie im Header der Antwort zum ersten Teilstück unter Location erhalten haben.

  • Wiederholen Sie den vorherigen Schritt nacheinander für alle Teilstücke in der richtigen Reihenfolge.

Request
   POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43
Content-Type: application/octet-stream

<binary content for chunk>
Response
   HTTP/1.1 200 OK

Beachten Sie beim Hochladen mehrerer Teilstücke Folgendes:

  • Die Teilstücke dürfen nur sequenziell hochgeladen werden.
  • Die Reihenfolge der HTTP POST-Anforderung der Teilstücke ist strikt einzuhalten.
  • Sollte es bei einer HTTP POST-Anforderung zu einem Fehler kommen (z.B. HTTP-Statuscode ist nicht 200), müssen Sie die Datei in allen Teilstücken erneut hochladen. Das erneute Hochladen einzelner Teilstücke ist nicht möglich. 

Sie erhalten auf die Anforderungen folgende mögliche Antworten:

StatuscodeBeschreibung
200 OKEin Teilstück wurde erfolgreich hochgeladen.
201 CreatedDas erste Teilstück wurde erfolgreich hochgeladen.
404 Not FoundDie Ressource wurde nicht gefunden. Es wurde z.B. eine unbekannte Repository-ID angegeben.
500 Internal Server ErrorEs trat ein interner Fehler bei der Verarbeitung auf.
Format der Antwort bei Fehlern

Freigegeben: JSON-Repräsentation

In diesem Kapitel erfahren Sie, in welchem Format Fehler ausgegeben werden. Abhängig vom Verarbeitungsergebnis des Ablagevorgangs wird die HTTP-Anforderung mit verschiedenen HTTP-Statuscodes beantwortet. Optional werden beschreibende Informationen zurückgeliefert.

Beispiel für eine Antwort für eine fehlgeschlagene Anforderung (Request):

Response
   HTTP/1.1 400 BadRequest
  
{
    "reason": "10019: Missing value for a mandatory property.",
    "severity": 1,
    "errorCode": 10019
}

Beschreibung der Parameter zu der Antwort auf die fehlerhafte Anforderung:

EigenschaftBeschreibung
reason

Ein optionaler kurzer Beschreibungstext, weshalb der Fehler aufgetreten ist. Dieser Text wird als Titel der Fehlermeldung verwendet.

hintEin optionaler Hinweistext für den Anwender mit Tipps für die Fehlerbehebung.
detailsOptionale 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.

Zusätzliche Parameter, wenn das abzulegende DMS-Objekt als Duplikat erkannt wird:

EigenschaftBeschreibung
dmsObjectId
Enthält die ID des bereits existierenden DMS-Objektes.
_links

Enthält die Linkrelation dmsobject, die auf das bereits existierende DMS-Objekt verweist.

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 für eine Ablage.

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:

sourceProperties
   {
    "properties": [ 
       ...
    ],
	"userdata": [{
       "key": "postProcessingOption",
       "display": "My post processing options",
       "values": [
                    {"value":"1", "display": "Action 1", "default":"false"},
                    {"value":"2", "display": "Default action 2", "default":"true"},
                    {"value":"3", "display": "Action 3", "default":"false"}
                 ]
    }]
}



Feedback nach erfolgreichem Speichern

Möchten Sie Feedback erhalten, sobald das DMS-Objekt erfolgreich gespeichert wurde, geben Sie den Parameter successCallbackUri an. Sie erhalten eine HTTP POST-Anforderung für diese URL mit einem JSON-Objekt in der Anforderung.

Die Anforderung, die die DMSApp sendet, könnte wie folgt aussehen:

Request
   POST /myapp/sources/mysource/myfile/success
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "_links": {
        "dmsobjectwithmapping": { 
            "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000001234?sourceId=%2Fmyapp%2Fsources%2Fmysourc" 
        }
    },
	"userdata": [
        {
            "postProcessingOption": ["2"]
        }
    ]
}

Beschreibung des JSON-Objektes, das beim POST übergeben wird:

EigenschaftBeschreibung
_links

Enthält die Linkrelation dmsobjectwithmapping. Die Linkrelation ist eine relative URL zu den Details des gespeicherten DMS-Objektes.

userdata

Gibt das Array mit den Ergebnissen, welche Optionen ein Anwender ausgewählt hat, als Name-Wert-Paare (Key-Value) an. Die Eigenschaft userdata existiert nur, wenn Sie dem Anwender Optionen bereitgestellt haben.

Geben Sie als Antwort auf die Anforderung der DMSApp einen entsprechenden HTTP-Statuscode zurück. Anhand Ihres Statuscodes zeigt der Ablagedialog eine entsprechende Erfolgs- oder Fehlermeldung an. Sie können weitere Informationen in Ihrer Antwort als JSON-Objekt übergeben.

Beispiel für Ihre Antwort für eine Anforderung (Request):

Response
   HTTP/1.1 400 BadRequest
  
{
    "reason": "My error message",
    "severity": 3
}

Beschreibung der Parameter zu der Antwort auf die Anforderung:

EigenschaftBeschreibung
reason

Ein optionaler kurzer Beschreibungstext, weshalb der Fehler aufgetreten ist. Dieser Text wird als Titel der Fehlermeldung verwendet.

hintEin optionaler Hinweistext für den Anwender mit Tipps für die Fehlerbehebung.
detailsOptionale Detailinformationen zum Fehler.
severity

Optionaler Schweregrad des Fehlers. Folgende Werte sind möglich:

Success = 0,
Information = 1,
Warning = 2,
Error = 3

Löschen der aktuellen Version eines DMS-Objektes ohne Benutzerinteraktion

Freigegeben: JSON-Repräsentation

Sie können die aktuelle Version eines bestehenden DMS-Objektes in einem d.3-Repository löschen, ohne dass ein Anwender eine Aktion ausführen muss. 

Um die aktuelle Version eines DMS-Objektes zu löschen, müssen Sie folgende Schritte durchführen:

  • Ermitteln der URL zu einem Repository
  • Ermitteln der Linkrelation zum bestehenden DMS-Objekt
  • Ermitteln der Linkrelation zum Löschen der aktuellen Version eines bestehenden DMS-Objektes
  • Aufrufen der URL zum Löschen der aktuellen Version des DMS-Objektes

Ermitteln der URL zu einem Repository

Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.

Ermitteln der Linkrelation zum bestehenden DMS-Objekt

Um eine URL zu einem bestehendem DMS-Objekt zu ermitteln, führen Sie eine Suche aus und werten Sie die Linkrelation self zu einem Element der Ergebnisliste aus. Im Kapitel Abrufen und Anzeigen der Ergebnisse eines Suchvorgangs finden Sie weitere Informationen zum Ausführen einer Suche und die Beschreibung eines Elements der Ergebnisliste.

Ermitteln der Linkrelation zum Löschen der aktuellen Version des bestehenden DMS-Objektes

Um die URL zum Löschen der aktuellen Version des DMS-Objektes zu ermitteln, werten Sie die Linkrelationen delete und deleteWithReason zu einem Element der Ergebnisliste aus. Wenn ein Löschgrund z.B. beim Löschen einer bereits freigegebenen Version zwingend angegeben werden muss, ist die Linkrelelation deleteWithReason vorhanden. Ansonsten enthält die Linkrelation delete die URL zum Löschen. Fehlen beide Linkrelationen, überprüfen Sie bitte die Berechtigungen zum Löschen der Version des DMS-Objektes. Wenn das vorhandene DMS-Objekt sich in Bearbeitung befindet, muss der authentifizierte Benutzer der Bearbeiter des DMS-Objektes sein.

Aufrufen der URL zum Löschen der aktuellen Version des DMS-Objektes

Führen Sie eine HTTP DELETE-Anforderung auf die ermittelten Linkrelationen delete oder deleteWithReason zum bestehenden DMS-Objektes aus. Wenn Sie einen Löschgrund übermittelt möchten, muss dieser im  Body der Anforderung angegeben werden. Der Löschgrund muss mindestens 3 Zeichen und darf maximal 80 Zeichen umfassen.

Request
   DELETE /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{"reason":"Created accidentally."}


Ist der Aufruf erfolgreich, wird HTTP 200 OK zurückgegeben. Ist der Body leer, wurde das komplette DMS-Objekt gelöscht. Enthält das DMS-Objekt weitere Versionen, enthält der Body weitere Linkrelationen. Ist die Linkrelation self enthalten, existieren weitere Versionen zum DMS-Objekt und Sie können mit dieser URL weitere Details zum DMS-Objekt abrufen. Mit den Linkrelationen delete oder deleteWithReason können Sie die nächste Version des DMS-Objektes löschen. Sind diese Linkrelationen nicht vorhanden, fehlen dem Benutzer die Berechtigungen, die nächste Version zu löschen.

Response
   HTTP/1.1 200 OK

{
	"_links": {
    	"self": {
     		"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001"
    	},
   		"delete": {
      		"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001"
    	}
  	}
}

Schlägt das Löschen der Version fehl, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen finden Sie unter Übersicht über Formate bei Fehlern.

Abrufen, Speichern und Bearbeiten von Zuordnungen

Freigegeben: JSON-Repräsentation

In diesem Kapitel erfahren Sie, wie Sie Zuordnungen sowohl für Eigenschaften als auch für Kategorien von einem Quellsystem (z.B. einer E-Mail-Anwendung) zu einem d.3-Repository erstellen und verwalten können. Diese Zuordnungen werden bei der Ablage, beim Abrufen von Details eines Elementes und beim Abrufen und Anzeigen von Ergebnissen eines Suchvorgangs innerhalb von d.3one-Integrationen verwendet. Beim Speichern von Zuordnungen legen Sie fest, welche externen Daten (z.B. die Eigenschaften einer E-Mail) welcher d.3-Dokumenteigenschaft zugewiesen werden.

Pro Quelle eines Quellsystems kann es ausschließlich eine einzige Zuordnung geben.

Im Kapitel Definieren eines Quellsystems erfahren Sie, wie Sie eine Quelle für eine Zuordnung bereitstellen können. Im Kapitel Grundlegendes zu Zuordnungen (Mappings) finden Sie Basisinformationen, die Ihnen das Erstellen von Zuordnungen erleichtern. Wissenswertes zu schreibenden Zugriffen finden Sie unter Grundlegendes zu schreibenden Zugriffen.

Ermitteln der Linkrelation für das Verwalten von Zuordnungen

Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln. Danach führen Sie eine HTTP Get-Anforderung für die REST-Ressource zu einem Repository wie folgt aus:

Request
   GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

Das JSON-Objekt zu einem Repository enthält die Linkrelation mappingconfig.

Response
   {
	"_links": {
		"mappingconfig": {
			"href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/"
		}
	},
	"id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

Speichern von Zuordnungen

Führen Sie eine HTTP POST-Anforderung mit den Zuordnungen für Ihr Quellsystem als Body für die URL aus, die Sie in der Linkrelation mappingconfig erhalten haben. Nach dem erfolgreichen Speichern erhalten Sie den HTTP-Statuscode 201 Created.

Request
   POST https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m HTTP/1.1
Origin: https://host
Accept: application/hal+json
Content-Type: application/hal+json

{
	name: "My Source",
	sourceId: "/myapp/sources/mysource",
	mappingItems: [{
		destination: "RECH",
		source: "mycategory1",
		type: 1
	},
	{
		destination: "3",
		source: "myprop1",
		type: 0
	},
	{
		destination: "property_caption",
		source: "myprop2",
		type: 0
	}]
}

Das JSON-Objekt, das beim POST übergeben wird, ist wie folgt beschrieben:

EigenschaftEigenschaft eines enthaltenen ObjektsBeschreibung
name-Gibt den Namen der Zuordnung an.
sourceId-

Gibt den eindeutigen Bezeichner der Quelle an.

Die ID muss eine relative URI sein. Die relative URI sollte mit dem Namen der App beginnen, die das Quellsystem bereitstellt, damit eine Eindeutigkeit gewährleistet ist (z.B. /myapp/sources/mysource).

mappingItems-Gibt das Array mit den Elementen der Zuordnung an. Dieses Array ordnet die Eigenschaften und Kategorien des Quellsystems zu den Eigenschaften und Kategorien des d.3-Repositorys zu.

type

Gibt den Typ des Zuordnungselements an. Folgende Werte sind möglich:

Bei Wert 0 bezieht sich das Zuordnungselement auf eine Eigenschaft.

Bei Wert 1 bezieht sich das Zuordnungselement auf eine Kategorie.


sourceGibt die ID der Eigenschaft im Quellsystem an.

destination

Wenn Sie eine Kategorie zuordnen, dann gibt destination die ID der Kategorie im d.3-Repository an.

Wenn Sie eine Eigenschaft zuordnen, dann kann destination einen der folgenden Werte enthalten:

  • Die ID der erweiterten Eigenschaft, wie sie im d.3-Repository definiert ist.
  • property_last_modified_date
  • property_last_alteration_date
  • property_editor
  • property_remark1
  • property_remark2
  • property_remark3
  • property_remark4
  • property_owner
  • property_caption
  • property_filename
  • property_filetype
  • property_document_number
  • property_variant_number
  • property_creation_date
  • property_size
  • property_state
  • property_access_date
  • property_colorcode


Abrufen der gespeicherten Zuordnungen

Führen Sie eine HTTP GET-Anforderung für die URL /dms/r/<RepositoryID>/m?sourceId=<SourceID> aus, um die Zuordnungen abzurufen. Der Wert der Eigenschaft sourceID gibt den eindeutigen Bezeichner der Quelle an (z.B. /myapp/sources/mysource).

Request
   GET https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m?sourceId=%2Fmyapp%2Fsources%2Fmysource HTTP/1.1
Accept: application/hal+json

Sie erhalten als Antwort das Objekt mit den gespeicherten Zuordnungen.

Response
   HTTP/1.1 200 OK
Content-Type: application/hal+json

{
	mappings: [{
		_links: {
			self: {
				href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID>"
			}
		}
		name: "My Source",
		sourceId: "/myapp/sources/mysource",
		mappingItems: [{
			destination: "RECH",
			source: "mycategory1",
			type: 1
		},
		{
			destination: "3",
			source: "myprop1",
			type: 0
		},
		{
			destination: "property_caption",
			source: "myprop2",
			type: 0
		}]
	}]
}

Die Eigenschaften der Objekte sind die gleichen Eigenschaften wie beim Speichern von Zuordnungen.

Löschen einer gespeicherten Zuordnung

Wenn Sie die Zuordnungen für Ihre Quelle abrufen, erhalten Sie pro Zuordnung eine Linkrelation zu dieser gespeicherten Zuordnung (_links.self.href). Für diese URL können Sie eine HTTP Delete-Anforderung ausführen, um die Zuordnung zu löschen.

Request
   DELETE https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID> HTTP/1.1
Origin: https://host
Accept: application/hal+json

Bearbeiten einer gespeicherten Zuordnung

Wenn Sie die Zuordnungen für Ihre Quelle abrufen, erhalten Sie pro Zuordnung eine Linkrelation zu dieser gespeicherten Zuordnung (_links.self.href). Für diese URL können Sie eine HTTP PUT-Anforderung zum Aktualisieren der Zuordnung ausführen. Das Objekt, das Sie übergeben, entspricht dem Objekt zum Speichern einer Zuordnung.

Request
   PUT https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID> HTTP/1.1
Origin: https://host
Accept: application/hal+json
Content-Type: application/hal+json

{
	name: "My Source",
	sourceId: "/myapp/sources/mysource",
	mappingItems: [{
		destination: "RECH",
		source: "mycategory1",
		type: 1
	},
	{
		destination: "3",
		source: "myprop1",
		type: 0
	},
	{
		destination: "property_caption",
		source: "myprop2",
		type: 0
	}]
}

Abrufen der Notizen eines DMS-Objektes

Freigegeben: JSON-Repräsentation

In diesem Kapitel erfahren Sie, wie Sie die Notizen eines DMS-Objektes abrufen können. 

Um die Notizen eines DMS-Objektes abzurufen, müssen Sie folgende Schritte durchführen:

  • Ermitteln der URL zu einem Repository
  • Ermitteln und Aufrufen der Linkrelation zum Abrufen der Details eines DMS-Objektes
  • Ermitteln der Linkrelation zum Abrufen der Notizen eines DMS-Objektes
  • Aufrufen der URL für die Notizen eines DMS-Objektes

Ermitteln der URL zu einem Repository

Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die URL zu einem Repository ermitteln.

Ermitteln und Aufrufen der Linkrelation zum Abrufen der Details eines DMS-Objektes

Im Kapitel Abrufen und Anzeigen von Details eines DMS-Objektes können Sie nachlesen, wie Sie die URL zum Abrufen der Details eines DMS-Objektes ermitteln und aufrufen.

Ermitteln der Linkrelation zum Abrufen der Notizen eines DMS-Objektes

Das JSON-Objekt zu den Details eines DMS-Objektes enthält die Linkrelation notes , mit deren Hilfe Sie die Notizen des DMS-Objektes abrufen können.

Response
   {
  "_links": {    
	 "notes":{
	   "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n"
	 }
  },
  "id": "D000000123"  
}

Abrufen der Notizen eines DMS-Objektes

Rufen Sie die Notizen des DMS-Objektes mit der zuvor ermittelten URL wie folgt ab:

Request
   GET https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n HTTP/1.1
Accept: application/hal+json

Sie erhalten als Antwort das Objekt mit den Notizen des DMS-Objektes:

Response
   HTTP/1.1 200 OK
Content-Type: application/hal+json

{
	_links: {
		self: {
		 href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n"
		}
	},
	"notes":[
	{
      "creator" : {
		"id": "MargaS"
		"displayName": "Marga Schilling"
	  },
	  "text": "This is a sample text."
	  "created": "2019-09-03T09:09:09.453+02:00"
	}
	]
}


EigenschaftBeschreibung
_linksself: Self-Link.
notesGibt das Array mit den Notizelementen des DMS-Objektes an.


Struktur eines Notizelementes

EigenschaftBeschreibung
creatorGibt ein Objekt mit den Informationen zum Benutzer zurück, der die Notiz verfasst hat.
textEnthä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

EigenschaftBeschreibung
idGibt die eindeutige ID des d.3-Benutzers zurück.
displayNameGibt den Anzeigenamen des d.3-Benutzers zurück.

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:

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. 

Request
   GET https://host/myapp/ HTTP/1.1
Accept: application/hal+json

Response
   HTTP/1.1 200 OK
Content-Type: application/hal+json

{
    "_links" : {
        "dmsobjectextensions" : {
            "href" : "/myapp/dmsobjectextensions"
        }
    }
}

Die Abfrage der Rootressourcen erfolgt anonym (ohne Authentifizierung) und wird als asynchroner Hintergrundprozess innerhalb der DMSApp ausgeführt.

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.

Request
   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
  • Liste Ihrer Favoriten im Feature Favoriten 

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.

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": "Liste exportieren"
		},
		{
			"culture": "en",
			"caption": "Export list"
		},
        {
            "culture": "en-GB",
            "caption": "Export list in Great Britain"
        }],
		"context": "DmsObjectListContextAction",
		"uriTemplate": "/myapp/dosomething?url={dmsobjectlist.url}",
		"iconUri": "/myapp/images/export-list-64x64.png"
	}]
}
EigenschaftEigenschaften eines enthaltenen ObjektsBeschreibung
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 or-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft einem der Werte entspricht. Die Groß-/Kleinschreibung wird nicht berücksichtigt.

notOr: Eine notOr-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft keinem der Werte entspricht. Die Groß-/Kleinschreibung wird nicht berücksichtigt.

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 Cultures-Bezeichnungen an:

  • cs (Tschechisch)
  • da (Dänisch)
  • de (Deutsch)
  • en (Englisch)
  • es (Spanisch)
  • fr (Französisch)
  • hr (Kroatisch)
  • it (Italienisch)
  • nl (Niederländisch)
  • pl (Polnisch)
  • sr (Serbisch)

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:

  • Wird die Sprachkennung mit Regionscode (z.B. en-GB) nicht gefunden, wird geprüft, ob die übergeordnete Sprache (Sprache ohne Regionscode) verfügbar ist (en). Im obigen Beispiel wird "Export List" für eine Anfrage der Sprache "en-GB" angezeigt, da "en" als Alternative genutzt wird.
  • Ist auch die übergeordnete Sprache nicht verfügbar, ist immer Englisch "en" ohne Regionscode die verwendete Alternative.
  • Ist auch "en" nicht als Alternative angegeben, wird die erste angegebene Sprache als Alternative angezeigt.

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:

DmsObjectListContextAction

uriTemplate
-

Sie definieren in der Eigenschaft uriTemplate die URL, die aufgerufen werden soll, wenn die Auswahl vom Anwender abgeschlossen wurde. Sie können Platzhalter definieren, um weitere Informationen zum aktuellen Kontext zu erhalten. Die Platzhalter werden beim Aufrufen der Erweiterung durch die tatsächlichen Eigenschaften ersetzt. Die Eigenschaften werden URL-codiert in die URI übernommen. Mögliche Platzhalter finden Sie weiter unten.

Das Verwenden eines Platzhalters im Host-Teil der URL ist aus Sicherheitsgründen nicht erlaubt und führt zu einem Fehler. 

iconUri
-

Gibt den Link zum Symbol an, das für Kontextaktion angezeigt wird. Die Datei für das Symbol muss im PNG-Format vorhanden sein.

Wenn Sie eine eigene PNG-Datei als Symbol verwenden möchten, ist es empfehlenswert, die PNG-Datei im Ordner des Installationsverzeichnisses d.3one/dms/Client/Custom zu speichern.

Verwenden Sie beim Definieren von Aktivierungsbedingungen bei Kontextaktionen zu Listen folgende Werte für die propertyId-Eigenschaft:

BedingungskontextpropertyIdBeschreibung
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 nutzen oder im Startmenü auf Alle Programme > d.velop > d.3one > Repository-Konfiguration klicken.

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:

EigenschaftBeschreibung
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 selectionList, das zu jedem Element folgende Informationen zurückgibt:

  • _links.self.href: Relative URL zum Element, mit der Sie weitere Detailinformationen zum Element abrufen können.
  • id: Dokument-ID des Elements.
  • caption: Titel des Elements.

Beispiel:

selectionList
   {
	"selectionList": 
    [{
		"_links": {
			"self": {
				"href": "/dms/r/e632f767-5cfa-538d-ab55-6756c36a74c9/o2/A0000000001"
			}
		},
		"id": "A0000000001",
		"caption": "Title of the item"
	},
	...
	]
}
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 nutzen oder im Startmenü auf Alle Programme > d.velop > d.3one > Repository-Konfiguration klicken.

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.

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

EigenschaftEigenschaften eines enthaltenen ObjektsBeschreibung
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.

propertyIdGibt 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 or-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft einem der Werte entspricht. Die Groß-/Kleinschreibung wird nicht berücksichtigt.

notOr: Eine notOr-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft keinem der Werte entspricht. Die Groß-/Kleinschreibung wird nicht berücksichtigt.

valuesGibt 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 Cultures-Bezeichnungen an:

  • cs (Tschechisch)
  • da (Dänisch)
  • de (Deutsch)
  • en (Englisch)
  • es (Spanisch)
  • fr (Französisch)
  • hr (Kroatisch)
  • it (Italienisch)
  • nl (Niederländisch)
  • pl (Polnisch)
  • sr (Serbisch)

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:

  • Wird die Sprachkennung mit Regionscode (z.B. en-GB) nicht direkt gefunden, wird geprüft, ob die übergeordnete Sprache (Sprache ohne Regionscode) verfügbar ist (en). Im obigen Beispiel wird "Export List" für eine Anfrage der Sprache "en-GB" angezeigt, da "en" als Alternative genutzt wird.
  • Ist auch die übergeordnete Sprache nicht verfügbar, so ist immer Englisch "en" ohne Regionscode die verwendete Alternative.
  • Ist auch "en" nicht als Alternative angegeben, so wird die erste angegebene Sprache als Alternative angezeigt.

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).

captionGibt 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:

DmsObjectDetailsContextAction

uriTemplate-

Sie definieren in der Eigenschaft uriTemplate die URL, die aufgerufen werden soll, wenn der Anwender auf die Kontextaktion klickt. Sie können Platzhalter definieren, um weitere Informationen zum aktuellen Kontext zu erhalten. Die Platzhalter werden beim Aufrufen der Erweiterung durch die tatsächlichen Eigenschaften ersetzt. Die Eigenschaften werden URL-codiert in die URI übernommen. Mögliche Platzhalter finden Sie weiter unten.

Das Verwenden eines Platzhalters im Host-Teil der URL ist aus Sicherheitsgründen nicht erlaubt und führt zu einem Fehler. 

iconUri-

Gibt den Link zum Symbol an, das für Kontextaktion angezeigt wird. Die Datei für das Symbol muss im PNG-Format vorhanden sein.

Wenn Sie eine eigene PNG-Datei als Symbol verwenden möchten, ist es empfehlenswert, die PNG-Datei im Ordner des Installationsverzeichnisses d.3one/dms/Client/Custom zu speichern.

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


ThemaWertBeschreibung
Repositoryrepository.idID 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.
Benutzeruser.d3.group_id

Aktivierungsbedingung: ID einer d.3-Benutzergruppe (maximal acht Zeichen), in der der aktuell angemeldete Anwender Mitglied ist.

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

Aktivierungsbedingung: GUID einer Benutzergruppe der identity provider-App, in der der aktuell angemeldete Anwender Mitglied ist.

Platzhalter uriTemplate: Liste der GUIDs der Benutzergruppen der identity provider-App als Array im JSON-Format, in denen der aktuell angemeldete Anwender Mitglied ist.

Eigenschaften zum Elementdmsobject.property_editorBearbeiter des Elements.
dmsobject.property_ownerBesitzer des Elements.
dmsobject.property_filenameDateiname des Elements.
dmsobject.property_filetypeDateityp des Elements.
dmsobject.property_document_numberDokumentnummer des Elements.
dmsobject.property_creation_dateErstellungsdatum des Elements.  
dmsobject.property_sizeDateigröße des Elements.
dmsobject.property_state

Dokumentstatus des Elements.

Mögliche Werte:

  • Archived: Das Element hat den Status Archiv.
  • VerificationInProgress: Das Element hat den Status Prüfung.
  • Processing: Das Element hat den Status Bearbeitung.
  • Released: Das Element hat den Status Freigabe.
dmsobject.property_variant_numberVariantennummer des Elements.
dmsobject.property_access_dateZugriffsdatum des Elements.
dmsobject.property_remarkBemerkungen zum Element.
dmsobject.property_last_alteration_dateÄnderungsdatum des Elements.
dmsobject.property_captionTitel des Elements.
dmsobject.property_categoryID der Kategorie des Elements.
dmsobject.property_colorcodeFarbmarkierung des Elements.
dmsobject.property_document_class

Aktivierungsbedingung: Kürzel einer Dokumentklasse des Elements.

Platzhalter uriTemplate: Liste der IDs der Dokumentklassen des Elements als Array im JSON-Format.

dmsobject.property_document_idDokument-ID des Elements.
dmsobject.property_display_version_idEindeutige ID der Anzeigeversion seitens der DMSApp.
dmsobject.type

Typ des Elements.

Mögliche Werte:

  • Document: Das Element ist ein Element vom Typ "Dokument".
  • Folder: Das Element ist ein Element vom Typ "Akte".
dmsobject.<NUMBER>

Geben Sie für den Platzhalter <NUMBER> die ID der erweiterten Eigenschaft an, wie sie im d.3-Repository definiert ist.

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 <NUMBER> die Datenbankposition der erweiterten Eigenschaft an.

Wir empfehlen Ihnen dringend, die ID der erweiterten Eigenschaft (dmsobject.<NUMBER>) zu verwenden. Verwenden Sie die Datenbankposition nur im Ausnahmefall, wenn Ihnen die ID der erweiterten Eigenschaft nicht vorliegt oder diese nur sehr aufwändig zu ermitteln ist.

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.

Originaldatei des Elementsdmsobject.mainblob.content_typeMIME-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_relativeRelative URL der Originaldatei. Wenn der Benutzer keine Berechtigung hat, das Dokument zu exportieren, dann ist dieser Parameter leer.
dmsobject.mainblob.idID der Originaldatei, falls der Anwender das Recht besitzt, die Originaldatei zu exportieren.
Abhängige Dateien zum Elementdmsobject.dependentblobsListe 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_relativeRelative 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.

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

EigenschaftEigenschaften eines enthaltenen ObjektsBeschreibung
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.

propertyIdGibt 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 or-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft einem der Werte entspricht. Die Groß-/Kleinschreibung wird nicht berücksichtigt.

notOr: Eine notOr-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft keinem der Werte entspricht. Die Groß-/Kleinschreibung wird nicht berücksichtigt.

valuesGibt 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:

DmsObjectDetailsPreview

uriTemplate
-

Sie definieren in der Eigenschaft uriTemplate die URL, die aufgerufen werden soll, wenn der Anwender die Anzeige-Perspektive der Detailansicht öffnet. Sie können Platzhalter definieren, um weitere Informationen zum aktuellen Kontext zu erhalten. Die Platzhalter werden beim Aufrufen der Erweiterung durch die tatsächlichen Eigenschaften ersetzt. Die Eigenschaften werden URL-codiert in die URI übernommen. Mögliche Platzhalter finden Sie weiter unten.

Das Verwenden eines Platzhalters im Host-Teil der URL ist aus Sicherheitsgründen nicht erlaubt und führt zu einem Fehler. 

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

ThemaWertBeschreibung
Repositoryrepository.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.

Im Kapitel Ermitteln eines Repositorys können Sie nachlesen, wie Sie die ID zu einem Repository programmatisch ermitteln.

Benutzeruser.d3.group_id

Aktivierungsbedingung: ID einer d.3-Benutzergruppe (maximal acht Zeichen), in der der aktuell angemeldete Anwender Mitglied ist.

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

Aktivierungsbedingung: GUID einer Benutzergruppe der identity provider-App, in der der aktuell angemeldete Anwender Mitglied ist.

Platzhalter uriTemplate: Liste der GUIDs der Benutzergruppen der identity provider-App als Array im JSON-Format, in denen der aktuell angemeldete Anwender Mitglied ist.

Eigenschaften zum Elementdmsobject.property_editorBearbeiter des Elements.
dmsobject.property_ownerBesitzer des Elements.
dmsobject.property_filenameDateiname des Elements.
dmsobject.property_filetypeDateityp des Elements.
dmsobject.property_document_numberDokumentnummer des Elements.
dmsobject.property_creation_dateErstellungsdatum des Elements.
dmsobject.property_sizeDateigröße des Elements.
dmsobject.property_state

Dokumentstatus des Elements.

Mögliche Werte:

  • Archived: Das Element hat den Status Archiv.
  • VerificationInProgress: Das Element hat den Status Prüfung.
  • Processing: Das Element hat den Status Bearbeitung.
  • Released: Das Element hat den Status Freigabe.
dmsobject.property_variant_numberVariantennummer des Elements.
dmsobject.property_access_dateZugriffsdatum des Elements.
dmsobject.property_remarkBemerkungen zum Element.
dmsobject.property_last_alteration_dateÄnderungsdatum des Elements.
dmsobject.property_captionTitel des Elements.
dmsobject.property_categoryID der Kategorie des Elements.
dmsobject.property_colorcodeFarbmarkierung des Elements.
dmsobject.property_document_class

Aktivierungsbedingung: ID einer Dokumentklasse des Elements.

Platzhalter uriTemplate: Liste der IDs der Dokumentklassen des Elements als Array im JSON-Format.

dmsobject.property_document_idDokument ID des Elements.
dmsobject.property_display_version_idEindeutige ID der Anzeigeversion seitens der DMSApp.
dmsobject.property_version_idEindeutige ID der aktuellen Version seitens der DMSApp.
dmsobject.type

Typ des Elements.

Mögliche Werte:

  • Document: Das Element ist ein Element vom Typ "Dokument".
  • Folder: Das Element ist ein Element vom Typ "Akte".
dmsobject.<NUMBER>Geben Sie für den Platzhalter <NUMBER> die ID der erweiterten Eigenschaft an, wie sie im d.3-Repository definiert ist.
dmsobject.fieldposition.<NUMBER>

Geben Sie für den Platzhalter <NUMBER> die Datenbankposition der erweiterten Eigenschaft an.

Wir empfehlen Ihnen dringend, die ID der erweiterten Eigenschaft (dmsobject.<NUMBER>) zu verwenden. Verwenden Sie die Datenbankposition nur im Ausnahmefall, wenn Ihnen die ID der erweiterten Eigenschaft nicht vorliegt oder diese nur sehr aufwändig zu ermitteln ist.

Originaldatei des Elementsdmsobject.mainblob.content_typeMIME-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_relativeRelative URL der Originaldatei. Wenn der Benutzer keine Berechtigung hat, das Dokument zu exportieren, dann ist dieser Parameter leer.
dmsobject.mainblob.idID der Originaldatei, falls der Anwender das Recht besitzt, die Originaldatei zu exportieren.
Abhängige Dateien zum Elementdmsobject.dependentblobsListe 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_relativeRelative URL der abhängigen Datei mit der ID aus dmsobject.dependentblobs.