Die OpenText Documentum -REST API? – Ein Erfahrungsbericht aus Entwicklersicht
Apr 26, 2018 | by Maximilian Krone | 0 Comments

Dieser Blog-Artikel beleuchtet die Documentum REST API von OpenText und gibt einen Einblick in deren Technologie, Basis-Funktionalitäten und Möglichkeiten zur Erweiterbarkeit. Hierbei berichte ich aus eigenen Erfahrungen und freue mich wenn ich anderen „Techies“ wie mir damit ein wenig weiterhelfen kann 😉

Was ist die „Documentum Rest API“?
Prinzipiell verbirgt sich hinter dem Begriff der Documentum REST API eine mit Documentum 7 eingeführte Webschnittstelle, die den Zugriff auf Objekte und Funktionen von OpenText Documentum erlaubt. Diese basiert auf Spring-Boot, wird als WAR-Datei ausgeliefert und muss auf einem Applikationsserver – z.B. Apache Tomcat – installiert werden. Diese Schnittstelle kann verwendet werden um customisierte Clients, Apps, oder auch Plug-Ins anderer Systeme zu schreiben.


Bevor es die Documentum Rest API gab, musste vor allem auf die APIs DFS und DFC als Schnittstelle für Business-Applikationen zurückgegriffen werden, um mit Documentum interagieren zu können. DFS basiert auf SOAP und ist damit ebenfalls eine Webschnittstelle, während DFC auf Java basiert.
Die REST API besteht aus mehreren Restkonformen Web-Services, die mit OpenText Documentum interagieren. Sie ist dabei „hypertext-driven, server-side stateless, and content negotiable, which provides you with high efficiency, simplicity, and makes all services easy to consume“.[Quelle: https://community.emc.com/docs/DOC-32266, Zeitpunkt der Erhebung: 29.11.2016 – 11:51]

Einführung in REST-Services
Um die Funktionsweise der Documentum REST API zu verstehen, muss zuallererst die grundlegende Funktionsweise von einem allgemein gültigen REST-Service erklärt werden. REST steht für Representational State Transfer und setzt auf einem statuslosen, client-server- und cache-fähigen Kommunikationsprotokoll auf. In nahezu allen Fällen wird dafür das http Protokoll genutzt. REST ist zusätzlich hypertext gesteuert, d.h. REST-Clients müssen zu jedem gegebenen Moment alle Informationen zur Verfügung haben, die sie für die Entscheidung benötigen, wohin diese weitergeleitet werden sollen. Durch Hypermedia werden die Ressourcen miteinander verbunden und ihre Fähigkeiten in maschinenlesbarer Weise beschrieben. Aus diesem Grund muss ein REST-Client nur eine Sache kennen, um mit dem REST-Server zu kommunizieren – das Verständnis von Hypermedia.

REST an sich ist ein Architekturstil für Netzwerkdienste (Webservices), bei dem komplexe Mechanismen möglichst durch die Nutzung von einfachen http-Aufrufen vermieden werden sollen.
Dadurch ergibt sich, dass ein REST-Webservice und damit auch seine Funktionen, ohne großen Aufwand von einem simplen http-Client aufgerufen werden kann. Auch ein Aufruf über den Browser – dieser setzt ebenfalls auf einen http-Client auf – ist möglich, sofern der Webservice zu der angegebenen Service-URL einen GET-Aufruf implementiert hat. Gerade wegen des http-Protokolls lassen sich die Funktionen und die Erreichbarkeit der REST Services leicht testen und so z.B. für die Eigenentwicklung eines Clients nutzen, dessen Codebasis man selber bestimmen kann.
Außerdem lässt sich von jedem beliebigen Client auf die REST API zugreifen, sofern dieser Client im selben Netzwerk hängt und sich authentifizieren und autorisieren kann. Eine Installation von lokaler Software ist für die Erreichbarkeit nicht nötig – für die Nutzung der Funktionen muss lediglich ein http-Client vorliegen (z.B. Browser oder eigenentwickelter Client). Im Vergleich zu SOAP bedeutet REST darüber hinaus einen kleinen Performancevorteil.

Funktionen der Services
Die Documentum REST API wird mit einigen REST Services ausgeliefert, die den Aufruf von grundlegenden Funktionen von Documentum ermöglichen. Es folgt eine kurze Auflistung der – meiner Meinung nach interessantesten – Services:

Objekt Service
Dieser Service ermöglicht die Interaktion mit Objekten von Documentum, die von dm_sysobject erben, wie z.B. Cabinets, Folder und Dokumente. So kann man sich mithilfe des Services Objekte anzeigen lassen, neue Objekte erzeugen und ändern (z.B. auch ein Check-Out/Check-In, neue Rendition, …) oder Objekte löschen. Objekte, die nicht von dm_sysobject erben, müssen über eine Erweiterung der REST API implementiert werden. Mehr dazu im Punkt Erweiterbarkeit.

Benutzer Service
Mit diesem Service können Benutzer, Gruppen und ACLs administriert werden. Dadurch lässt sich die Benutzerverwaltung auch aus einer externen Quelle aufrufen und nach den eigenen Prozessen und Wünschen bequem anpassen.

DQL Service
Der DQL Webservice ist ein Service der es ermöglicht, DQL-Abfragen auszuführen und deren Ergebnis dem Client zurück zu melden. Standardmäßig unterstützt der DQL-Service aus Sicherheitsgründen nur Select-Abfragen. Änderungen an Objekten über DQL sollten aus Sicherheitsgründen durch eigene, abgesicherte Services umgesetzt werden.

Beispielaufruf des Object Service
Sobald die REST API auf einem Applikationsserver erfolgreich installiert wurde, kann diese, vorausgesetzt die Firewall-Regeln sind richtig eingerichtet, unter dem Link „/dctm-rest“ (Beispiel: http://vm-documentum-app-test:8080/dctm-rest für Standard-Tomcat-Konfiguration) von jedem beliebigen Client aus dem lokalen Netzwerk aufgerufen werden. Bei einem Aufruf dieser URL z.B. über den Browser sollte man dann folgendes sehen können:

Sollte der oben genannte Link, angepasst an die lokalen Gegebenheiten, weder per Netzwerk, noch lokal vom Applikationsserver, aufrufbar sein, so müssen die Log-Dateien inspiziert werden. Höchstwahrscheinlich ist in dem Fall bei der Installation der REST API etwas fehlgeschlagen.

Über den Klick auf den Knopf „Services“ würde „/dctm-rest/services“ (Beispiel: http://vm-documentum-app-test:8080/dctm-rest/services) aufgerufen werden.
Das Ergebnis, bei Aufruf der Seite, sollte ungefähr wie folgt aussehen:

Ruft man nun z.B. die erste URL auf, so würden einem alle Documentum Repositories angezeigt:

Über die in den Einträgen enthaltenen URLs könnte man nun sich mithilfe von gültigen Anmeldedaten mit den Repositories verbinden, um dort beispielsweise eine DQL-Query auszuführen, ein Dokument auszuchecken oder ähnliches.

Einarbeitung
Bei entsprechendem Wissen über die Architektur und Funktion von REST-Services ist eine Einarbeitung relativ schnell möglich, da die Documentum REST API einer RESTkonformen Schnittstelle entspricht. Zusätzlich gibt es von OpenText viele hilfreiche Tutorials und Code-Beispiele, die man sich im Internet ansehen kann. OpenTexts Code-Bibliotheken, die in fast allen gängigen Programmiersprachen (Java, C#, Pyton, Swift, Ruby, Objective-C, AngularJS, …) auf Git-Hub vorliegen, komplettieren den simplen Einstieg.
Nichtsdestotrotz sollten die genannten Git-Hub-Bibliotheken mit Bedacht gewählt werden, da man sich von dem geschriebenen Code abhängig macht und die Bibliotheken jederzeit vom Hersteller angepasst werden können. Funktionen könnten mit einem neuen Patch anders aufgebaut sein und nichtmehr so funktionieren wie zuvor, was zu Fehlern führen kann.
Die andere Option wäre, sich eine eigens geschriebene Code-Bibliothek anzufertigen, die auf die API zugreift. So wird eine Unabhängigkeit von den von OpenText bereitgestellten Code-Bibliotheken erreicht und verfügt bei der Entwicklung über mehr Kontrolle darüber, was im Vordergrund geschieht.

Erweiterbarkeit
Wie bereits im Punkt der einzelnen Funktionen der Documentum REST Services angedeutet, wird im Standard nicht jede Funktion von Documentum über die hier beschriebene Webschnittstelle ermöglicht.
Sollten Funktionen, die für die Business-Logik dringend nötig sind, in der Standardauslieferung der REST API fehlen, so können diese allerdings über Erweiterungen der REST Services implementiert werden. Hierbei gilt es zu beachten, dass die Einarbeitung nicht ganz so simpel ist, wie z.B. für den initialen Einstieg der Erstellung eines Dokumentenverwaltungs-Clients. Dank der Dokumentation der REST API und anhand von guten Beispielen auf der OpenText-Community-Seite, lassen sich die meisten Anfangsprobleme allerdings gut bewältigen.
Implementiert wird in Java und mithilfe des Build-Management-Tools Apache Maven.

Docker Unterstützung
Seit Version 7.3 lassen sich die Documentum REST Webservices offiziell auch als fertiges Docker-Image in einem Docker-Container ausführen. Die Unterstützung von Docker ist in meinen Augen ein richtiger Schritt um die REST API als primäre Webschnittstelle zu platzieren. Durch Docker kann diese einfach skaliert und ohne viel Aufwand auf andere Server migriert werden. Aus diesem Grund lässt sich die fertige REST API u.a. recht schnell ins interne Netzwerk einbinden und nutzen, sofern schon die nötige Documentum-Infrastruktur vorhanden ist.

Resümee
Die Documentum REST Webservices bieten eine gute und einsteigerfreundliche Möglichkeit um aus eigenimplementierten Systemen oder Clients mit OpenText Documentum zu interagieren. Vor allem die recht schnell mögliche Einarbeitung in die Funktionsweise und Nutzung der API ist in meinen Augen positiv herauszuheben. Man sollte aber vorsichtig mit Spezialfällen umgehen, denn die Implementierung einer Erweiterung der Standard-API ist eine zeitintensive Geschichte und bedarf einiger Einarbeitung. Sehr schön ist auch die Möglichkeit, die Services aus allen möglichen Programmiersprachen und damit auch mit jedem Betriebssystem zu nutzen.