Diese Anleitung beschreibt die notwendigen Vorbereitungen zur Anbindung eines externen Systems an die DMS-App. Das Produkt d.3one stellt die hierfür benötigten RESTful APIs bereit und ist sowohl in der d.velop cloud als auch on-premises verfügbar. Weitergehende Informationen kannst den Dokumentationen zur IdentityProvider-API und zur DMS-API entnehmen. Die IdentityProvider-API ermöglicht die Anmeldung von Benutzern und die Ermittlung von Informationen zu Benutzern und Gruppen. Die DMS-API stellt die CRUD-Operationen für das Hochladen, Ändern, Suchen und Herunterladen von Dateien und Metadaten, sowie das Löschen von Dokumenten zur Verfügung.

Für einen schnellen Einstieg ist Beispielcode auf GitHub verfügbar.

Vor dem ersten Aufruf einer API-Funktion musst du aber folgende Schritte durchführen:

 1. Ermitteln der Verbindungsinformationen zur DMS-App.

Sofern dir noch kein d.3one-Zielsystem zur Verfügung steht, kannst du im d.velop store das Produkt d.velop documents buchen. Wenn du d.velop documents nutzt und nur die Quellcodebeispiele ausführen möchtest, sind einige der folgenden Schritte nicht notwendig. Folgende Informationen werden benötigt:

  • baseURI: Basis-URL, über die d.3one erreichbar ist. Beispiel: https://mytenant.d-velop.cloud.
  • apiKey: API-Key zur Authentifizierung an d.3one. Du kannst einen API-Key in d.3one erstellen, indem du die Kachel Konfiguration und dann Identity Provider auswählst und auf API key (Fingerabdrucksymbol) klickst. Die Kachel Konfiguration ist nur für Administratoren sichtbar.
  • repoId: Repository-ID des gewünschten Repositorys. Du kannst die IDs aller verfügbaren Repositorys ermitteln, indem du die URL baseURI und /repo/repositories/ eingibst. Beispiel: https://mytenant.d-velop.cloud/repo/repositories/

 2. Erstellen einer Quelldefinition für die Zuordnungen (Mappings)

Hinweis

Für die Ausführung der Code-Beispiele mit d.velop documents ist dieser Schritt nicht notwendig.

Für die Nutzung von Funktionen der DMS-App-API ist die Konfiguration von Zuordnungen erforderlich.
Hierzu musst du zunächst Quelldefinitionen als JSON-Objekte erstellen. Du benötigst ein JSON-Objekt für die Quelldefinition selbst (source.json), sowie ein JSON-Objekt für die Route zur Quelldefinition (sourceurl.json).

Beispiele für die JSON-Objekte: - source.json - sourceurl.json

 3. Bereitstellen der Quelldefinition als Webanwendung

Hinweis

Für die Ausführung der Code-Beispiele mit d.velop documents ist dieser Schritt nicht notwendig.

Die JSON-Objekte müssen von einer Webanwendung per HTTP oder HTTPS mit dem Content-Type application/json ausgeliefert werden. Die Webanwendung (beispielsweise "yourWebAppName") muss für das d.3one-Zielsystem erreichbar sein.

Hinweis

Um Konflikte mit anderen Quelldefinitionen zu vermeiden, solltest du einen Unternehmensnamen als Prefix für die Webanwendung verwenden. Beispiel: "myCompanyMyMapping". Für den Namen der Webanwendung darfst du keine Bindestriche oder Minuszeichen verwenden. Der Name der Webanwendung muss der erste Teil der URI nach der Basis-URL sein. Beispielsweise https://yourWebHostUri/yourWebAppName.

Du kannst die Webanwendung für die Auslieferung der JSON-Objekte individuell und mit der Technik deiner Wahl erstellen. Zwei einfache Möglichkeiten werden in den folgenden Abschnitten beschrieben. Alle Angaben erfolgen ohne Gewähr.

 Hosten einer statischen Website auf Amazon S3 in der Cloud

Wenn du d.3one in der Cloud verwendest, kannst du die statische Website mit Amazon S3 bereitstellen.

  1. Erstelle in der AWS S3-Konsole einen Bucket und gib den Namen deiner Website ein, beispielsweise yourWebAppName.
  2. Erstelle folgende Verzeichnisse im neuen Bucket: yourWebAppName und yourWebAppName\sources.
  3. Lade die beiden JSON-Dateien hoch: Speichere die Datei sourceurl.json im Verzeichnis yourWebAppName und die Datei source.json im Verzeichnis yourWebAppName\sources.
  4. Ändere den Dateinamen der beiden JSON-Dateien in index.json.
  5. Wechsle zur Registerkarte Eigenschaften > Hosten einer statischen Website und gib unter Indexdokument den Dateinamen index.json ein.
  6. Wechsle zur Registerkarte Berechtigungen und deaktiviere unter Öffentlichen Zugriff blockieren die Option Blockieren jeglichen öffentlichen Zugriffs.
  7. Navigiere zu Zugriffskontrollliste > öffentlicher Zugriff und wähle für Everyone: Objekte auflisten die Option ja aus.
  8. Wähle für beide JSON-Dateien Menü > Metadaten aus, füge den Schlüssel Content-Type hinzu und wähle application/json aus.

 Hosten einer statischen Website mit d.3 presentation server in einer lokalen Umgebung

Verwendest du d.3one in einer lokalen Umgebung, kannst du für die Auslieferung der JSON-Objekte die Anwendung d.3 presentation server verwenden. d.3 presentation server ist Bestandteil deiner d.3 Server-Infrastruktur.

  1. Öffne das Installationsverzeichnis von d.3 presentation server, beispielsweise d:\d.3\d.3 presentation server.
  2. Erstelle im Verzeichnis ...\custom\webapps den Ordner yourWebAppName und die Unterverzeichnisse yourWebAppName\sources und yourWebAppName\WEB-INF.
  3. Erstelle die Datei web.xml im Verzeichnis ...\yourWebAppName\WEB-INF mit folgendem Inhalt: <?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://java.sun.com/xml/ns/javaee"> <display-name>yourWebAppName</display-name> <welcome-file-list> <welcome-file>source.json</welcome-file> <welcome-file>sourceurl.json</welcome-file> </welcome-file-list> <mime-mapping> <extension>json</extension> <mime-type>application/hal+json</mime-type> </mime-mapping> </web-app>
  4. Füge die beiden JSON-Objekte in die Verzeichnisse ein: Speichere die Datei sourceurl.json im Ordner yourWebAppName und die Datei source.json im Verzeichnis yourWebAppName\sources.
  5. Starte die Custom-Instanz von d.3 presentation server mithilfe der Webkonsole von d.3 process manager (HTTP) neu.
  6. Starte d.3 presentation server gateway mithilfe der Webkonsole von d.3 presentation server admin (HTTP) neu.

 4. Quelldefinition als neue App im d.3one-Zielsystem registrieren.

Hinweis

Für die Ausführung der Code-Beispiele mit d.velop documents ist dieser Schritt nicht notwendig.

Mit der Registrierung der Webanwendung als App stellst du eine Verbindung zwischen der Quelldefinition und d.3one her.

  • Verwendest du d.3one in der Cloud, musst du dich für die Registierung deiner Webanwendung als neue App an unseren cloud.support@d-velop.de wenden. Teile uns in der Anfrage bitte die URL zu deiner Webanwendung mit (beispielsweise https://yourWebHostUri/yourWebAppName).
  • Verwendest du d.3one in einer lokalen Umgebung, so kannst du die Webanwendung mit der Webkonsole von d.ecs http gateway admin (HTTP) registrieren. Die Webkonsole erreichst du auf dem d.3one Applikationsserver über das Windows-Startmenü. Die Registrierung der App erreichst du mit der Kachel Apps.

 5. Konfiguration des Mappings

Sobald die App für deine Webanwendung registriert ist, steht dir in d.3one die Kachel Zuordnungen zur Verfügung. Mit der Kachel Zuordnungen erstellst du eine neue Zuordnung und verbindest so deine Quelldefinition mit den Dokument- und Aktenarten im d.3one-Zielsystem. Die Kachel ist nur für d.3one-Administratoren sichtbar.

 6. Start coding ;-)

Code samples on GitHub: https://github.com/d-velop/dvelop-examples-cs