enaio® server-api

Diese Dokumentation wurde von ECMind GmbH auf Basis der originalen enaio® Server-API Dokumentation erstellt, die unter https://help.optimal-systems.com/enaio/v120/admin/PDF/OS_ServerApi_de.pdf verfügbar ist. Alle Rechte an der Dokumentation verbleiben bei der OPTIMAL SYSTEMS GmbH.

1. Maschinenlesbare Bereitstellung

Diese Dokumentation steht zusätzlich in zwei maschinenlesbaren Formen bereit, beide direkt aus diesem Container:

  • Skills als ZIP herunterladen — 418 selbsttragende Claude-Skills (SKILL.md + reference/ + examples/ pro Operation), entpackbar nach ~/.claude/skills/ oder <projekt>/.claude/skills/. Geeignet für Claude Code, Anthropic SDK und FastMCP-fähige Clients.

  • MCP-Endpoint (/mcp/, Streamable HTTP) — Live-Zugriff auf dieselben Skills via FastMCP SkillsDirectoryProvider. Zusätzlich zwei MCP-Tools für Clients ohne Skill-Support: search_documentation(query, language, limit) (Volltextsuche per SQLite FTS5) und read_documentation(namespace, procedure, language) (vollständige adoc-Quelle einer Prozedur).

2. Einleitung

enaio® ist ein leistungsfähiges Dokumentenmanagement-, Workflow- und Archivsystem. Ein besonderes Kennzeichen der Produktfamilie ist die hohe Konfigurierbarkeit und ihre Schnittstellenstärke, die es erlaubt, an den unterschiedlichsten Stellen eine Integration in andere Systeme vorzunehmen.

Im nachfolgenden Dokument werden die durch die enaio® server-api bereitgestellten Funktionen detailliert beschrieben. Das Dokument hat den Charakter einer Funktionsreferenz. Nähere Informationen über den Aufbau von enaio® und der einzelnen Komponenten sind den entsprechend verfügbaren Dokumentationen zu entnehmen.

Der enaio® Server dient als Laufzeitumgebung für diverse Engines im Archiv-, DMS- und Workflow-Umfeld. So werden durch den Server verschiedene Aufgaben zum dokumentenorientierten Informationsfluss wahrgenommen. Dies sind etwa die Aufnahme, Verwaltung und Bearbeitung von Dokumenten und den dazugehörigen Indexdaten, die Volltextrecherche, das Workflowmanagement, die Archivierung und viele weitere Funktionen.

2.1. Engine

Eine Engine – auch Executor genannt – wird durch den Applikationsserver geladen und dadurch befähigt, Jobs auszuführen. Jeder Executor verwaltet eine oder mehrere Engines, in denen die Serverjobs organisiert sind. Folgende Engines werden standardmäßig ausgeliefert:

DMS-Engine

Recherche und Manipulation von Index- und Dokumentdaten

Workflow-Engine

Bearbeitung und Verwaltung von Workflowprozessen und -modellen

Standard-Engine

Sammlung von diversen Funktionen zur Archivierung, zum Datei- und Dokumententransfer

Volltext-Engine

Abfrage der Volltextengine

OCR-Engine

Optische Zeichenerkennung aus Bildern oder gescannten Belegen

Abonnement-Engine

Benachrichtigungsfunktionen bei Änderungen am Dokumentenbestand

Core-Services

Initialisierung, Lizenzierung und Sessionmanagement

Datenbankpiping

Ermöglicht einen Zugriff auf die Datenbank über die Serverschnittstelle in Form eines internen Formates oder als Active Data Objects

2.1.1. Serverjob

Jobs sind Aufgaben, die durch den Server ausgeführt werden sollen, und eine bestimmte Akquise, Manipulation von Daten oder Steuerungsfunktionen abbilden. Somit lassen sich Jobs auch mit Funktionen vergleichen. Ein Serverjob hat folgenden allgemeinen Aufbau:

  • Name des Jobs: Der Name setzt sich aus der Engine – in der der Job implementiert ist – und der Jobbezeichnung zusammen (z. B. dms.XMLInsert).

  • Eingabeparameter

  • Eingabe-Dateiliste: Wenn dem Job Dateien übergeben werden müssen, wird hier der absolute Pfad und Name der jeweiligen Datei übergeben.

  • Ausgabeparameter

  • Ausgabe-Dateiliste: Wenn der Job Dateien zurückliefert, wird hier der absolute Pfad und Name der jeweiligen Datei übergeben.

  • Rückgabewert: Jeder Job generiert einen Rückgabewert. Dieser ist im Erfolgsfall stets 0. Ist ein Fehler aufgetreten, kann er über den Rückgabewert grob qualifiziert werden.

Zur Ausführung der Jobs muss zwischen einem anfordernden Client und dem Server eine Session erzeugt werden. Diese besteht einerseits aus einer Verbindung über ein technisches Protokoll (z. B. TCP) und andererseits aus verschiedenen Informationen zu dieser Verbindung, wie z. B. Authentifizierungs-, Stations- und Lizenzdaten. Über das technische Protokoll wurde zur Formulierung der Anfragen und Ergebnisse der Bearbeitung das Protokoll BIN-RPC gelegt. Dieses Protokoll legt fest, wie Anfragen, Parameter und Ergebnisse dargestellt werden müssen.

Der Kommunikationsverlauf zwischen Client und Server folgt diesem Schema:

  1. Aufbau einer TCP-Verbindung mit dem enaio®-Server

  2. Initialisierung einer Session mit entsprechenden Parametern

  3. Jobaufrufe und Empfang der Antwortdaten

  4. Beenden der Verbindung

Der Client ruft einen Job auf, indem die Jobbezeichnung und die dazugehörigen Parameter in XML verpackt und zum Server gesandt werden. Danach wartet der Client auf eine Antwort. Der Server-Kernel interpretiert die empfangenen Daten, ermittelt welche Engine den Job ausführen kann, und übergibt diesen an dessen Queue-Mechanismus zur Bearbeitung. Das Ergebnis wird dann von der Engine über den Server-Kernel an den Client übermittelt.

Das BIN-RPC-Format sieht vor, dass alle Parameter innerhalb einer binären Struktur übertragen werden. Bei der Übertragung von Dateien (also Binärdaten) wäre es deshalb notwendig, die Dateien durch eine MIME-Kodierung in einen String umzuwandeln. Aus Gründen der Performance und des Speicherbedarfs wurde hier vom Standard abgewichen: Die Dateien werden nach dem Versand der Jobparameter als TCP-Stream gesondert übertragen.

2.2. Schnittstellenbibliotheken

Um die interne Kommunikation vor den fachlichen Anforderungen zu verbergen, stehen mehrere Möglichkeiten offen, das Protokoll auch ohne tiefere Kenntnisse der Kommunikationsabfolge zu benutzen. Zu diesem Zweck existieren Klassen und Bibliotheken, die von Optimal Systems GmbH bereitgestellt werden:

  • COM-Schnittstelle zur Kommunikation mit dem enaio® Server (oxsvrspt)

  • REST-Interface zur Kommunikation mit dem enaio® Server (Microservice DMS)

  • Java-Interface zur Kommunikation mit dem enaio® Server (auf Anfrage)

  • Weitere Bibliotheken, die Serveraufrufe kapseln (auf Anfrage)

Vom prinzipiellen Aufbau gleichen sich die Schnittstellen in der Benutzung. Nach einer Initialisierung und der Herstellung einer Verbindung zum Applikationsserver werden Jobobjekte aufgebaut, denen Eingabeparameter und Eingabedateien übergeben werden. Nach der Ausführung können Ausgabeparameter und Ausgabedateien vom Objekt gelesen werden. Darüber hinaus wird ein Fehlerstack bereitgestellt, der mögliche fachliche und technische Fehlermeldungen aufnehmen kann.

Eingabe- und Ausgabelisten werden je nach verwendeter Programmiersprache als Hashlists, Arrays oder sonstige Objekte dargestellt.

2.3. Realisierung einer Archivanbindung

2.3.1. DMS-Objektstruktur

Ziel einer Archivanbindung für verschiedene Applikationen ist es, Dokumente, die mit Struktur- und Indexmerkmalen versehen sind, im DMS abzulegen, im Datenbestand zu recherchieren, Dokumente zu downloaden und ggf. zu löschen. Wie bereits beschrieben, werden die Funktionen durch den Aufruf von Serverjobs durchgeführt, die in der DMS-Engine und der Standard-Engine implementiert wurden.

enaio® verwendet folgende DMS-Objekte für die Abbildung von Informationsstrukturen:

Schrank

Der Begriff Schrank wurde als Analogie zu einem Aktenschrank gewählt. Ein Aktenschrank enthält Ordner, Register und Dokumente. Er stellt die oberste Verwaltungsebene im DMS dar – alle weiteren DMS-Objekte können nur als Subobjekt eines Schrankes existieren. Ein Schrank erhält als einziges Attribut einen Namen.

Ordner

Ordner werden durch Indexdaten beschrieben und sind Container für darunter liegende Objekte. Sie sind vergleichbar mit Ordnern im Dateisystem auf Wurzelebene. Pro Schrank existiert immer nur ein Ordnertyp.

Register

Register dienen der weiteren Feingliederung der Informationsstruktur. Pro Schrank kann es mehrere Registertypen geben, die sich nach der Struktur der Indexdaten unterscheiden.

Dokumente

Dokumente zeichnen sich neben den Indexdaten zusätzlich dadurch aus, dass mit ihnen Dokumentdateien assoziiert sind. Jeder Dokumenttyp besitzt die Eigenschaft eines Haupttyps, wodurch gekennzeichnet ist, ob es sich bei den assoziierten Dateien um Images, Windows-Quelldokumente oder andere Dateitypen handelt. Der enaio® Client verhält sich je nach Haupttyp beim Erfassen und Ausgeben der Dokumente unterschiedlich.

Die Klassen von Ordnern, Registern und Dokumenten heißen Objekttypen. So ist beispielsweise ein Kundenordner oder eine Rechnungsart ein Objekttyp. Alle Instanzen der Klasse verfügen über die gleichen Felder zur Indexierung. Bei Dokumenten wird über den Objekttypen auch der Haupttyp festgelegt. Die Struktur der Indexdaten wird durch das Objektmodell vorgegeben, sodass für jeden Objekttypen eine eigene Menge von Feldern zur Verschlagwortung und Recherche definiert werden kann.

Nachfolgend werden Dokumente, Register und Ordner als Objekte bezeichnet, sofern eine genauere Spezifikation unerheblich ist. Jedes Objekt ist durch Indexdaten und sogenannte Basisparameter gekennzeichnet. Basisparameter werden automatisch vom System vergeben und sind zur internen Verwaltung der Objekte vorgesehen. Sie beinhalten Informationen über den Anleger eines Objektes, seine ObjektID, Änderungsdaten usw.

Jedes Objekt im DMS wird durch seinen Objekttypen und seine ObjektID eindeutig beschrieben. Für die meisten Jobs werden Objekttyp und ObjektID als Eingabeparameter erwartet.

2.3.2. Typische Szenarien

Recherche: Anhand von Suchparametern werden Indexdaten und Basisparameter von Objekten zur weiteren Verarbeitung ermittelt. Über die ermittelten ObjektIDs und Objekttypen können dann weitere Recherchen durchgeführt oder die Dokumentdateien selbst heruntergeladen werden.

Import: Die aufrufende Applikation gibt Indexdaten und ggf. Dokumentdateien vor; daraufhin werden im System neue Objekte angelegt.

2.3.3. Jobs für eine typische Archivanbindung

Aufgabe Job

Session erzeugen

krn.SessionAttach

User anmelden

krn.SessionLogin

Objektdefinition lesen

dms.GetObjDef

Recherche (Ordner, Register, Dokumente)

dms.GetResultList

Dokument herunterladen

std.StoreInCacheByID

Objekte einfügen

dms.XMLInsert

Objekt löschen

dms.XMLDelete

Session beenden

krn.SessionLogout

2.4. Testmöglichkeiten

Für Tests einzelner Jobs des enaio®-Servers und seiner Engines stellt Optimal Systems GmbH das Programm axlabjobs.exe zur Verfügung. Die Jobs können mit beliebigen Parametern und beliebig oft ausgeführt werden. Über einen Connect-String kann angegeben werden, an welchem Server sich das TestLab anmelden soll. Es ist möglich, mit vielen TestLabs an einem Server zu arbeiten, um Belastungstests durchzuführen. Das Programm wird standardmäßig im Serververzeichnis installiert.

Zur Überwachung von Jobaufrufen steht der enaio® enterprise-manager zur Verfügung. Dort können sowohl Rechner als auch Jobs spezifiziert werden, die überwacht werden sollen. Zu Jobs, zu denen Dateien mitgeschickt werden, können auch diese Dateien über ein temporäres Verzeichnis zugänglich gemacht werden.

Die Funktionen zur Jobüberwachung sind im enterprise-manager über den Bereich Erweiterte Administration > Überwachung > Jobaufrufe erreichbar.

3. Engine-Referenz

Nachfolgend sind alle Engines des enaio®-Servers mit ihren Serverjobs beschrieben. Jeder Engine ist ein eindeutiges Kürzel zugeordnet, über das ihre Jobs adressiert werden.

3.1. Engine-Übersicht

Engine Präfix Beschreibung Bereiche

DMS-Engine

dms

Anfragen und Bearbeiten von Indexdaten, DMS-Objekten und Mappen

XML Import · XML Export (Recherche) · Sicherheitssystem · Mappen (Portfolios) · Benutzerbezogene Daten · Sonstige Jobs

Workflow-Engine

wfm

Bearbeitung und Verwaltung von Workflowprozessen und -modellen

Organisationsstruktur · Workflowmodell · Workflowprozess und Arbeitsschritt · Workflow-Maske, Event und Skript · Administration · Historienverwaltung · Sonstige Jobs · Serverinterne Jobs

Standard-Engine

std

Work-, Cache-, Datei- und Archiv-Verwaltung

Work-, Cache- und Archiv-Verwaltung · Datei-Verwaltung · Interne Jobs · Sonstige Jobs

Abonnement-Engine

abn

Einrichtung und Steuerung von Abonnements zur Information über Veränderungen am Dokumentenbestand

Convert-Engine

cnv

Konvertierung und Zugriff auf Bilddateien

Volltext-Engine

vtx

Bearbeitung von Volltextanfragen der Clients

OCR-Engine

ocr

Optische Zeichenerkennung

Benutzer/Gruppen-Engine

mng

Zugriff auf Gruppen und Benutzer von enaio®

ADO-Datenbank-Engine

ado

Zugriff auf die Datenbank über die Serverschnittstelle (Active Data Objects)

Core-Services (direkt im Server-Kernel implementiert)

Kernel

krn

Batch-Verwaltung, Serverüberwachung, Registry-Verwaltung und Administration geladener Engines zur Laufzeit

Registry-Verwaltung · Batch-Verwaltung · Server-Verwaltung · Session-Verwaltung · Engine-Verwaltung · Sonstige Jobs

Administrations-Engine

adm

Verwaltung von Systemdateien und Konfigurationsaufgaben am Server

Lizenz-Engine

lic

Lizenzverwaltung für das gesamte enaio®-System

Datenübernahme-Services

dtr

Serverseitiger Aufruf des Datenübernahmeservers (MS-Office-Datenübernahme)

4. Glossar

Cache-Verzeichnis

Verzeichnis unterhalb des Serverpfades (..\server\CACHE). Es wird benutzt, um archivierte Dokumente, die aus Archivierungsmedien gelesen wurden, für weitere Zugriffe bereitzuhalten, damit der nächste Benutzer nicht erneut zeitaufwendig auf das Archivierungsmedium zugreifen muss.

Flag

Parameter, der eine bestimmte Eigenschaft aktivieren bzw. markieren soll.

OSTEMP-Verzeichnis

Verzeichnis, deklariert in der Umgebungsvariable OSTEMP, das von einigen Jobs zur Zwischenlagerung oder Erzeugung temporärer Dateien benutzt wird.

Work-Verzeichnis

Verzeichnis unterhalb des Serverpfades (..\server\WORK), das als Ablageort für alle nicht archivierten Dokumente genutzt wird. Aus Gründen der Performance erfolgt die Ablage in diesem Verzeichnis und nicht in der Datenbank.

Optionaler Parameter

Parameter und Rückgabewerte, die in eckige Klammern [Parameter] eingeschlossen sind, sind optional. Diese Parameter müssen, wenn sie nicht benötigt werden, beim Jobaufruf nicht angegeben werden.