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 du den Dokumentationen zur API der Identityprovider-App und zur API der DMS-App entnehmen. Die API der Identityprovider-App ermöglicht die Anmeldung von Benutzern und die Ermittlung von Informationen zu Benutzern und Gruppen. Die API der DMS-App 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.

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. Bitte wähle beim ersten Start die Option Startkonfiguration verwenden aus.

Folgende Informationen deines d.3one-Zielsystems werden benötigt:

  • baseURI: Basis-URL, mit der d.3one erreichbar ist. Beispiel: https://mytenant.d-velop.cloud. In den nachfolgenden Beispielen verwenden wir den Platzhalter <baseURI> für die Basis-URL.
  • apiKey: API-Key zur Authentifizierung an d.3one. Du kannst einen API-Key in d.3one erstellen, indem du das Feature Konfiguration öffnest, im Bereich Anmeldeverwaltung den Eintrag Einstellungen für die Anmeldung auswählst und auf Manage API keys (Fingerabdrucksymbol) klickst. Das Feature Konfiguration ist nur für d.3one-Administratoren sichtbar. Du erstellst den API-Key für einen Benutzer, der die gewünschten Berechtigungen für Kategorien besitzt.
  • repoId: Repository-ID des gewünschten Repositorys. Du kannst die IDs aller verfügbaren Repositorys ermitteln, indem du die URL mit der Basis-URI und /repo/repositories/ eingibst. Beispiel: https://mytenant.d-velop.cloud/repo/repositories/. In den nachfolgenden Beispielen verwenden wir den Platzhalter <repoId> für die Repository-ID.

 2. Quellsystem und Zuordnungen (Mappings)

Für die Softwareentwicklung mit der DMS-App-API musst du ein Quellsystem bereitstellen und Zuordnungen konfigurieren, um auf Dokumentarten und Eigenschaften im d.3-Repository zugreifen zu können. Je nach Einsatzfall deiner Software kannst du einen vordefinierten Standard oder eine individuelle Konfiguration verwenden.

 2.1. Verwenden eines vordefinierten Standards

Du kannst die Konfiguration eines vordefinierten Standards für einen schnellen Einstieg, zum Testen der DMS-App-API oder für einmalige individuelle Entwicklungen für ein einziges d.3-Repository in einem einzigen Mandanten verwenden. Beim vordefinierten Standard wird auf das sogenannte Standardquellsystem zurückgegriffen, welches in jedem Mandanten mit einer URL erreichbar ist, z.B. https://<baseURI>/dms/r/<repoId>/source.

Wenn du das Standardquellsystem verwendest, kannst du direkt mit dem Schritt zum Festlegen deiner Beispieldaten fortfahren.

 2.2. Verwenden einer individuellen und skalierbaren Lösung

Diese Konfiguration ist für Software geeignet, die skalierbar und für mehrere Repositorys und Mandanten programmiert wird. Siehe auch: Grundlegendes zu Zuordnungen Zur Einrichtung eines Quellsystems sind folgende Schritte erforderlich:

 2.2.1 Erstellen einer Quelldefinition für die Zuordnungen (Mappings)

Für die Nutzung von Funktionen der DMS-App-API ist die Konfiguration von Zuordnungen erforderlich.
Zum Konfigurieren von Zuordnungen 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:

 2.2.2 Bereitstellen der Quelldefinition als Webanwendung

Hinweis

Um Konflikte mit anderen Quelldefinitionen zu vermeiden, solltest du einen Unternehmensnamen als Präfix für die Webanwendung verwenden. Beispiel: "myCompanyMyMapping". Für den Namen der Webanwendung darfst du nur Zahlen und Buchstaben verwenden. Der Name der Webanwendung muss der erste Teil der URI nach der Basis-URL sein. Beispielsweise https://yourWebHostUri/yourWebAppName.

Die Webanwendung muss für das d.3one-Zielsystem erreichbar und die JSON-Objekte müssen per HTTPS mit dem Content-Type application/json über folgende Routen ausgeliefert werden:

  • source.json: https://yourWebHostUri/yourWebAppName/sources
  • sourceurl.json: 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.

 2.2.3 Registrieren der Quelldefinition als neue App im d.3one-Zielsystem.

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 Registrierung 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 im Windows-Startmenü. Die Registrierung der App erreichst du mit dem Feature Apps.

 2.2.4 Konfigurieren des Mappings

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

 3. Festlegen deiner Beispieldaten

Für das Hochladen und Bearbeiten von Dokumenten und Metadaten im folgenden Beispielcode benötigst du noch Informationen aus deinem Quellsystem für Dokumentart, Eigenschaften und Quellen-ID. Du kannst diese Informationen einfach aus den json-Objekten deines Quellsystems ermitteln. Rufe zum Ermitteln der Informationen die URL zu deinem Quellsystem auf und notiere dir den Wert für das Attribut key einer Kategorie Schriftverkehr (Kunde) unter categories und die Werte für folgende fünf key-Attribute unter properties: Betreff, Kundennummer, Kundenname, Belegdatum und property_filename. Zusätzlich benötigst du den Wert von id. Wenn du das Standardquellsystem verwendest, lautet deine URL zu den json-Objekten folgendermaßen:https://<baseURI>/dms/r/<repoId>/source.

Hinweis

Bitte prüfe in d.3one, ob der Benutzer, dessen API-Key du verwendest, Schreibrechte für die ausgewählte Kategorie hat. Du kannst die Berechtigungen in d.3one in der Benutzer- und Gruppenverwaltung konfigurieren. Die Benutzer- und Gruppenverwaltung findest du im Feature Konfiguration im Bereich Manage users and groups.

 4. Start coding ;-)

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