Was ändert sich?

Mit der Erfolgsgeschichte unserer Produkte für intelligentes Dokumentenmanagement und digitale Geschäftsprozesse, ist die Bereitstellung von Programmierschnittstellen für Software-Entwickler:innen eng verbunden. Unsere Programmierschnittstellen ermöglichen neben projektspezifischen Anbindungen an führende Systeme auch die Integration in Fremdsoftware und individuelle Produkterweiterungen. Für den Zugriff auf die hierzu verwendete d.3 API, wurden im Laufe der Zeit viele verschiedene Programmierschnittstellen genutzt. Am bekanntesten ist die als SOAP-Webservice bezeichnete Schnittstelle, die auf dem Artikel d.3 web webservice basiert.

Parallel zum SOAP Dialekt gibt es bereits seit 2013 auch REST, um über einen HTTP-basierten webservice mit unserer Software technisch zu kommunizieren. Seit Einführung unserer Cloudlösung d.velop documents 2016 ist der Leistungsumfang unseres REST Webservice immer mehr gewachsen, der die Möglichkeiten unserer App-Architektur für Software-Entwickler:innen nutzbar macht. Der REST Webservice wird von Technologiepartnern und App-Buildern schon seit Jahren für für den Zugriff auf DMS-Funktionen von d.velop documents erfolgreich eingesetzt und hat gegenüber älteren Schnittstellen viele Vorteile:

  • Bei Nutzung der DMS-App API: Gleiche Programmierschnittstellen für die Nutzung in der Cloud und in lokalen Installationen. Ein späterer Wechsel von einer lokalen Installation in die Cloud kann Schnittstellen zu Fremdsystemen mit geringem Aufwand durchgeführt werden.
  • RESTful API für die schlanke und flexible Entwicklung von Web Apps
  • Einbinden von HTML-Anwendungsoberflächen möglich
  • Datenaustausch per Menschen und Maschinen lesbarem JSON-Nachrichtenformat
  • Erweiterung der DMS-App mit Anwendungsoberflächen in d.3one möglich. Beispielsweise als Kontextaktionen oder um einen eigenen Dokumentenviewer einzubinden.
  • DMS-App-API ist Basis unserer Produkte in der Cloud und damit stets aktuell.
  • Leichtgewichtige HTTP-basierte Kommunikation


Hinweis

Die Nutzung der klassischen d.3 API und aller Zugriffs-Schnittstellen ist mit den Versionen Current 2025.Q1 bzw. Annual 2025 abgekündigt. Der REST-basierte webservice ist unsere künftig einheitliche Programmierschnittstelle.

Ausnahme: Die Schnittstelle für den Zugriff auf d.3 web webservices ist bereits zur Version Annual 2024 (bzw. Current Q1.2024) abgekündigt. Für diese Zugriffe ist eine Umstellung auf die Public REST API erforderlich. Wenn eine Umstellung aufgrund fehlender Funktionen absolut nicht möglich ist, empfehlen wir als Übergangslösung eine Anpassung des Aufrufs auf das Protokoll d.3fc over http. Wir haben für die Anpassung eine Kurzanleitung für Sie bereitgestellt: Kurzanleitung d3fc-over-http

Was muss ich tun?

  • Bestehender Programmcode muss bis zum Update auf die Versionen Current 2024.Q1 bzw. Annual 2024 auf REST Webservices umgestellt worden sein.
  • Prüfen Sie, ob von Ihnen erstellter oder verwendeter Programmcode die in dieser Liste aufgeführten Zugriffs-Schnittstellen auf die d.3 API nutzt.
  • Prüfen Sie den von Ihnen erstellten oder verwendeter Programmcode auf die Verwendung der d.3 API-Funktionen. In dieser Liste finden Sie eine Referenz der Funktionsnamen von d.3 API-Funktionen. Bitte beachte Sie dabei, dass Funktionsnamen je nach verwendeter Zugriffs-Schnittstelle geringfügig von der Schreibweise in der Liste abweichen können.

Welche Voraussetzungen gelten für die Nutzung der REST Webservices?

Produkte

  • Die DMS-App als REST Webservice, ist technisch betrachtet Teil des Lieferumfanges des d.3one webclients. Der d.3one webclient wird damit für die Nutzung der REST Webservices als installiert vorausgesetzt. Der d.3one webclient ist in d.velop documents in der Cloud enthalten und zusätzlich als lokale Installation verfügbar.

Bei lokaler Installation wird die Nutzung der DMS-App in der jeweils aktuellen Version empfohlen. Ältere Versionen der DMS-App-API haben einen reduzierten Funktionsumfang.

Die Version der DMS-App lässt sich in der Cloud und lokal durch den Aufruf der Funktion /dms ermitteln. Beispielsweise so: https://ecm.d-velop.de/dms

Lizenzen

Wenn Sie bereits das aktuelle Lizenzmodell der d.velop nutzen (d.3ecm user S - L, d.3ecm user for third-party software integration oder d.velop documents in den Editionen business und ultimate) sind sie bereits ausreichend lizenziert. Anderenfalls benötigen Sie folgende Lizenzen:

Lizenzierung des Produkts d.3one webclient

  • Für den Einsatz der REST-Webservices wird die Lizenzierung des Produkts d.3one webclient vorausgesetzt (Lizenz-Key: d.3one webclient (user))
  • Wenn das Produkt d.3one webclient noch nicht lizenziert wurde, aber eine Lizenz für den Artikel d.3 web webservice vorhanden ist, dann kann kundenseitig ein kostenfreier Artikel nachlizenziert werden. Bitte beachten Sie hierbei, dass dies nur dann gilt, wenn sie den Artikel d.3 web webservice explizit kaufmännisch erworben haben.

Lizenzierung von Benutzern

Für die Lizenzierung von Benutzern gibt es zwei Alternativen:

1) Sind die Benutzer in der zentralen Benutzerverwaltung im Unternehmen (Beispiel: MS AD,LDAP) vorhanden, so ist eine nutzerbasierte Lizenzierung per d.3 client access license erforderlich.

Die Nutzung der REST-Webservices erfolgt immer im Kontext eines Benutzers, sodass eine d.3 client access license pro Benutzer belegt wird. Die Anzahl der benötigten d.3 client access licenses richtet sich auch bei Verwendung des Fremdprodukts immer nach der Anzahl der Personen, die tatsächlich über die Fremdanwendung mit dem d.3 System arbeiten. Insbesondere auch dann, wenn das Fremdprodukt intern über einen sogenannten "Technischen Benutzer" mit dem d.3-System kommuniziert. Eine ausreichende Lizenzierung ist kundenseitig sicher zu stellen.

2) Sind die Benutzer nicht in der zentralen Benutzerverwaltung im Unternehmen (Beispiel: MS AD,LDAP) vorhanden und außerdem dem Kunden nicht rechtlich zuzuordnen, so kann eine dokumentenbasierte Lizenzierung per d.velop documents portal integration genutzt werden.

d.velop documents portal integration dient zum Dokumentenaufruf, wenn auf ein bestehendes d.velop documents extern und anonym über Webportale,Shopsysteme, CMS-Systeme, etc. zugegriffen werden soll.

Know-How

  • Kenntnisse zu RESTful APIs als einem Programmiersprachen- und Framework-neutraler Standard auf Basis der HTTP/HTTPS-Kommunikation.
  • Kenntnisse in der Softwareentwicklung mit einer Programmiersprache, die die Einbindung und Nutzung von RESTful APIs ermöglicht.
  • Die Lerneinheit Entwickeln von Integrationen mit der DMS-App API wurde durchgeführt.

Tipps zur Umstellung auf REST-Webservices

  • E-Learning zur den Grundfunktionen der DMS-App-API: Entwickeln von Integrationen mit der DMS-App API
  • Integriertes Mapping nutzen
  • Die Umstellung von Programmcode, der administrative Funktionen zur Konfiguration eines Repositorys nutzt, muss in Bezug auf die Verfügbarkeit von vergleichbaren Funktionen sorgfältig geprüft werden. Sollen Dokumentarten, Eigenschaften, Benutzer, Gruppen, Berechtigungen, Aktenstrukturen, Wertemengen und mehr per REST Webservices bearbeitet werden, so ist dies Stand heute mit den REST Webservices der DMSConfig-App und nur mit einem d.velop documents der Cloud möglich. Die Bereitstellung der DMSConfig-App für lokale Installationen ist in Vorbereitung und wird Rahmen des Abkündigungs-Zeitraumes zur Verfügung gestellt.
  • Werden die REST Webservices mit lokalen Installationen genutzt und ist die eingesetzte Produktversion keine Current- oder Annual-Version oder die d.3 Version kleiner gleich 8.1, so weicht der Funktionsumfang der REST Webservices ab.

Antworten auf häufig gestellte Fragen

Können die in d.ecs forms erstellten Skripte ohne Änderung weiter genutzt werden auch wenn Sie d.3 API Funktionen nutzen?

Ja, d.ecs forms ist von der Abkündigung der d.3 API nicht betroffen, sofern die von d.ecs forms freigegebenen d.3 API-Funktionen genutzt werden: https://portal.d-velop.de/documentation/ddfss/de/anhang/liste-aller-unterstuetzten-d-3-api-funktionen-fuer-direkten-zugriff

Bestehende Implementierungen von Skripten mit API-Nutzung müssen dann nicht geändert werden.

Müssen auch die kundenspezifisch erstellten Projektlösungen auf REST-Webservices umgestellt werden?

Ja, alle Projektlösungen, die d.3 API verwenden, müssen umgestellt werden.

Sind die d.3 API und die Zugriffs-Schnittstellen nach dem Ablauf des Abkündigungszeitraumes weiterhin nutzbar?

In den Current-Versionen bis Current 2024.Q4 und der Annual-Version 2024 sind die d.3 API und die Schnittstellenfunktionen für den Zugriff enthalten. Alle späteren Veröffentlichungen enthalten weder die API noch die Schnittstellenfunktionen für den Zugriff. Für die Version Current 2024.Q4 leisten wir noch bis zum Release der Version Current 2025.Q1 Patch-Support. Für die Version Annual 2024 leisten wir noch sechs Monate nach dem Release der Version Annual 2025 Patch-Support. Eine Nutzung der d.3 API über den Support-Zeitraum hinaus ist damit nur ohne Wartung und ohne Weiterentwicklung der verwendeten Version möglich.

Was ist zu tun, wenn der Funktionsumfang der REST-Webservices die Umstellung verhindert?

Eine 1:1 Umstellung des Codes wird nicht in allen Fällen möglich sein. Gegebenenfalls können auch andere fachliche Abläufe genutzt werden. Bitte prüfen Sie daher, ob sich mit den API-Funktionen der von Ihnen genutzten Produktversionen eine Umstellung durchführen lässt.

Sollten zwingend relevante Funktionen fehlen, so beschreiben Sie bitte den fachlichen Anwendungsfall und teilen Sie uns dies per E-Mail an info@d-velop.de mit.