enaio® appconnector

Allgemeines

enaio® appconnector (OSRest) stellt ein auf dem HTTP-Protokoll basierendes API zur Verfügung, alle Aufrufe sind zustandlos und resourcenorientiert (REST). Das API versucht komplexe Funktionsaufrufe in enaio® zu bündeln und zu vereinfachen. Dazu gehört ein Mapping aller Indexdaten auf ein jeweilig für die konkrete Anwendung sinnvolles Schema.

Da als Protokoll HTTP verwendet wird, ist bei allen Aufrufen auf ein korrektes URL-Encoding zu achten.

Die Dokumentation ist generell gültig für alle Versionen, die sich im Support befinden (aktuellstes Service Release). 

enaio® appconnector (OSRest) ist ab Version 10.0 abgekündigt (Status "veraltet (deprecated)")

Bedeutung der Abkündigung

enaio® appconnector wurde bis zur Version 10.0 weiterentwickelt und gepflegt. Seit der Version 10.0 fokussiert OPTIMAL SYSTEMS sich auf die Weiterentwicklung der technischen Nachfolgeprodukte:

enaio® appconnector wird weiterhin gepflegt – jedoch nur in Ausnahmefällen mit neuen Features ausgestattet (siehe auch Product-Lifecycle-Informationen | "Anstehende Abkündigungen").

Der DMS Service für enaio® hat aktuell noch einen kleineren Umfang, aber einen neuen Technologie-Stack:
Er ist ein skalierbarer, cloud-fähiger Microservice und für "große Systeme" gebaut.
Langfristiges Ziel ist es, diese REST-API nach und nach zu erweitern und den Funktionsumfang an enaio® appconnector anzugleichen.

Der USERS Service für enaio® ist für die Themenbereiche Benutzer, Benutzergruppen und benutzerspezifische Konfigurationen wie z. B. Systemrollen und Trefferlistenkonfiguration zuständig.
Ziel ist es, eine fachliche Orientierung zu schaffen, die zu einer besseren Übersichtlichkeit führt, leichter wartbar ist und mehr Möglichkeiten zur Skalierung anbietet. Analog zum DMS Service wird auch der USERS Service nach und nach erweitert, weiterentwickelt sowie durch enaio® webclient selbst verwendet werden.

Search in appconnector ...

Authentifizierung

OSRest unterstützt bis einschließlich enaio 9.00 SP1 die Standard HTTP-Authentifizierung. Dabei können folgende Verfahren verwendet werden:

  • NTLM

  • HTTP SPNEGO Negotiate (Kerberos)

  • HTTP Basic Authentication (RFC2617)

Bei den Windows-basierten Authentifizierungsverfahren NTLM und SPNEGO wird die Authentifizierung an das unterlegende Windows Betriebssystem des OSRest-Servers delegiert. Die alternative HTTP Basic Authentication kann wahlweise Windows oder interne enaio®-Konten verwenden. Sollte die Anwendung es erfordern, kann OSRest auch für einen Betrieb ohne Authentifizierung mit einem technischen Benutzer konfiguriert werden. Die URL zur Admin-Oberfläche kann nur mit enaio®-Supervisor-Rechten aufgerufen werden.

Ab enaio 9.10 muss die Verbindung zwingend über das enaio® gateway erfolgen. Ein Standalone-Betrieb des enaio® appconnector mit direktem Zugriff ist nicht länger möglich.

Große Fließkommazahlen im JSON

Große Fließkommazahlen mit einem Wert ab 10000000.00 bzw. -10000000.00 werden vom JSON nach Java in exponentialer Schreibweise übernommen. Da innerhalb des AppConnectors keine mathematischen Operationen auf Feldwerte vorgenommen werden, führt dies erst im enaio® Server zu einem Fehler. Dieser wertet 1e7 in dem Falle als Zeichenkette aus und versucht diese in ein Fließkommafeld einzufügen, was scheitert. Als Lösung für große Fließkommazahlen können diese als Zeichenkette im JSON übergeben werden.

{ "myBigNumber": "1002000987" }

Services

OSRest stellt verschiedene Services zur Verfügung:

  • DocumentService /osrest/api/documents - Methoden zur Suche von Indexdaten

  • DocumentFileService /osrest/api/documentfiles - Methoden zum Umgang mit Dokumentendateien

  • NotificationService /osrest/api/notifications - Zugriff auf enaio®-Benachrichtigungen

  • SessionService /osrest/api/session - Informationen zur Benutzersitzung

  • ServiceinfoService /osrest/api/serviceinfo - Allgmeine Informationen zum OSRest-Service

  • OSFileService /osrest/api/anon - Anonymer Service zur Erzeugung von enaio®-internen Linkdateien

  • WorkflowService /osrest/api/workflows - Methoden zum Starten und Bearbeiten von Workflows

  • ObjectDefinitionService /osrest/api/objdef - Methoden für das Arbeiten mit der Objektdefinition in JSON-Form

  • OrganizationService (/organization) /osrest/api/organization - Methoden für Benutzer und Gruppen sowie den E-Mail-Versand

  • IconService (/icon) /osrest/api/icon - Methoden zum Abrufen von Katalog-Icons

Alle Methoden liefern standardmäßig in JSON notierte Resultate zurück.

Ergebnisse

OSREST liefert drei Arten von Ergebnissen:

  • Trefferlisten

  • Benachrichtigungslisten

  • gespeicherte Anfragen

Trefferlisten

{ - documentResult: { pagesize: 500 startposition: 0 totalHits: 18 - documents: [ - { id: "1452" type: "FOLDER" - fields: { title: "Stadtwerke Jena GmbH" info: "Göschwitzer Str. 22 7745 Jena" } fav: false }, ... ] } }

Das documentResult ist das root-Element einer Trefferliste. Es enthält die Informationen pagesize, startposition (offset) und totalHits sowie eine Liste von documents.

Das documents-Element repräsentiert die Treffer aus enaio®. Ein document hat die Attribute id, type, fields und fav.

id: OSID des Treffers

type: Dokumenttyp des Treffers. Mögliche Werte: FOLDER, REGISTER, DOCUMENT

fields: Liste von gemappten Indexdaten des Treffers (siehe auch: Metadaten-Mapping)

fav: Flag, das angibt, ob sich der Treffer im Favoritenordner befindet.

Benachrichtigungslisten

notifications: [ - { id: "9015" type: "DOCUMENT" notificationType: "REVISIT" eventDate: 1282654839000 - fields: { title: "Hugo Distler" info: "" } },... ]

notifications ist das root-Element der Benachrichtigungsliste. Es enthält eine Liste von Benachrichtigungen.

Eine Benachrichtigung enthält die Informationen id, type, notificationType, eventDate und fields.

id: OSID des Treffers

type: Dokumenttyp des Treffers. Mögliche Werte: FOLDER, REGISTER, DOCUMENT

notificationType: Art der Benachrichtigung. Mögliche Werte: REVISIT, SUBSCRIPTION, WORKFLOW

eventDate: Datum der Benachrichtigung

fields: Liste von gemappten Indexdaten des Treffers (siehe auch: Metadaten-Mapping)

{ - storedqueries: [ - { id: 14004695 name: "offene Supportcalls" queryParams: [ ] } - { id: 14041962 name: "E-Mails" - queryParams: [ - { object: "Email" field: "Datum:" dataType: "DATE" } ] },... ] }

storedqueries ist das root-Element. Es enthält eine Liste von gespeicherten Anfragen.

Eine gespeicherte Anfrage enthält die Informationen id, name und queryParams.

id: OSID der gespeicherten Anfrage

name: Name der gespeicherten Anfrage

queryParams: Liste der Parameter der gespeicherten Anfrage (falls vorhanden)

JS-Scripting Support (intern)

Mit der Umstellung auf Java 8 wird nun auch Scripting unterstützt. Das ermöglicht es, den Rest-Service zur Laufzeit zu erweitern. Voraussetzung ist, dass es den Rest-Aufruf unterstützt, daher wird es eher fließend so nach und nach eingeführt und auch an den entsprechenden Aufrufen erkenntlich gemacht. Mehr dazu später.

MetadatenMapping

Bei dem Metadatenmapping geht es um die Anreicherung von Dateimetadaten in die Indexdaten durch den enaio® ExtractionService. Eine in JSON formatierte Mappingdatei im Schema-Verzeichnis legt fest, welche Werte aus dem ExtractionService an welche Indexdatenfelder gebunden werden. 

Aufruf aus dem OSRest heraus

Gibt 2 Geschmacksrichtungen des Aufrufs

  • Einmal mit Angabe einer ObjectId eines Objekts mit 2 Optionalen Parametern (GET, mimetype: application/json). Hier wird auf ein bestehendes Objekt das Mapping angewendet.

    • Override = „gibt an, ob die „override“ Angabe im Mapping ignoriert werden soll und immer alle Felder gemappt werden sollen

    • Preview = „gibt an, ob das Mapping als JSON zurückgeliefert werden soll. Wird es nicht angegeben oder auf false gesetzt, wird das Dokument mit dem Mapping aktualisiert (XMLUpdate) und nur ein OK zurück geliefert. (Standardverhalten)

    • ../documentfiles/processmetadata/[id][?override=[true|false]&preview=[true|false]]

  • Der zweite Aufruf heißt genauso, erfüllt aber einen anderen Zweck. Hier können Dokumente als Multipart gesendet werden, die nicht in enaio® vorhanden sind, welche zusammen mit einer ObjectTypeId quasi ein Mapping-Vorschlag macht. Dieser Vorschlag kommt per application/json zurück. Nochmal die Unterschiede zum vorherigen Request im Überblick:

    • POST Request

    • Multipart

    • Response ist application/json

    • ../documentfiles/processmetadata/[objectTypeId]

Konfiguration OSRest für ExtractionService

In der osrest.properties wird die URL zum ExtractionService hinterlegt. Der Eintrag sieht wie folgt aus:

extractionservice.url=http\://10.10.0.31:9303/extraction

Aufbau Mapping-Datei

Im Schema-Verzeichnis des OSRest wird eine Datei „extraction.mapping.config“ erwartet. Es ist eine Textdatei, die Konfiguration selbst ist in JSON gehalten.

Weitere Merkmale:

  • Innerhalb der Dokumenttypen, können Mappings für unterschiedliche mimetypen erstellt werden.

  • Das Property „override“ gibt an, ob (=false) nur die Leeren Indexdatenfelder mit dem Mapping befüllt werden sollen oder (=true) ob vorhanden Indexdaten mit dem Mapping überschrieben werden soll. Dies kann im Request auch nochmal direkt übersteuert werden (GET-Requestvariante)

  • Die Feldmappings selbst sind Arrays mit einem oder mehreren ExtractionService-Feldern. Da nicht immer dieselben Felder ausgeliefert werden, kann man sich hier eine Art Fallback schaffen, wenn mal ein Wert nicht dabei sein sollte.

  • Der Bereich Variablen ist direkt erstmal nicht für das Mapping wichtig sondern ist für den JavaScript-Teil interessant. Hier können analog wie zu Indexdatenfeldern, extraction-Werte mit Fallback gemappt werden und diese werden dann u. a. in das JavaScript weitergereicht. Dort können diese Infos dann ausgewertet und verarbeitet werden (wenn z. B. bestimmte Katalogwerte gesetzt werden sollen, abhängig von div. Extraction-Werten oder sie in einer bestimmten Art formatiert werden sollen (siehe GeoData für Dashlet)). Wichtig: Indexfelder die damit befüllt werden sollen, müssen zumindest in der darüber liegenden Sektion vorhanden sein.

  • Datums-Werte automatisch, soweit möglich, in enaio®-freundliches deutsches Datumsformat gewandelt

Folgend ein Beispiel (von der Cebit) (Nicht wundern, ist für die E-Mail mit Leerzeichen formatiert)

{ "262199": { // ObjectTypeId des Dokuments, Registers oder Schranks "override": false, // gibt an, ob alle Mappingfelder übernommen werden sollen. "mimeTypeMappings": [{ "mimeTypes": ["image/*"], // MimeType Einschränkung. "mappings": { "picture_type": ["OS:FileType"], "picture_width_px": ["OS:ImageWidth", "File:ImageWidth", "ExifIFD:ExifImageWidth"], "picture_height_px": ["OS:ImageHeight", "File:ImageHeight", "ExifIFD:ExifImageHeight"], "horizontal_resolution": ["JFIF:XResolution", "IFD0:XResolution", "Photoshop:XResolution"], "vertical_resolution": ["JFIF:YResolution", "IFD0:YResolution", "Photoshop:YResolution"], "picture_orientation": [""], "colour_modus": [""], "colour_depth": ["OS:BitsPerSample", "File:BitsPerSample"], "picture_filesize": ["OS:FileSize", "System:FileSize"], "picture_date": ["OS:CreateDate", "System:FileCreateDate"], "geodata": [""] // leerfeld, damit es per Javascript gesetzt werden kann }, "variables": { "GPS_LONG": ["OS:GPSLongitude", "GPS:GPSLongitude", "Composite:GPSLongitude"], "GPS_LAT": ["OS:GPSLatitude", "GPS:GPSLatitude", "Composite:GPSLatitude"] } }] }, "262144": { "override": false, "mimeTypeMappings": [{ "mimeTypes": ["application/pdf"], "mappings": { "Dateityp": ["OS:FileType", "File:FileType"], "Bearbeiter": ["OS:Author", "PDF:Author"], "Beschreibung": ["${'Erstellt mit ' + OS_Creator}"] } }] } }

Die JavaScript-Datei

Für die Verarbeitung per JavaScript wird im ExtractionService-Fall eine Datei namens „extraction.processing.js“ im Schema Verzeichnis erwartet.  Die JavaScript-Datei wird (derzeit) für jedes Indexdatenfeld einzeln aufgerufen.

Folgende Objekte sind aktuell in diesem Skript vorhanden:

  • ObjectTypeId : ObjectTypeId des Objektes.

  • FieldName : aktueller interner Name des Feldes

  • FieldValue : aktueller Feldwert

  • ResultValue : Wert, der nach der Verarbeitung diesem Feld zugewiesen wird.

  • os_map : Key-Value Map mit allen gemappten Indexdatenfeldern, die in der Mapping-Datei definiert wurden

  • var_map : Key-Value Map mit den Variablen, die in der Mapping-Datei definiert wurden

  • es_map : Key-Value Map mit allen ExtractionService-Werten. Achtung:  Da die Werte aus dem Service ":"-Zeichen enthalten, werden diese, um sie im JavaScript nutzungsfähig zu bekommen, durch "_"-Zeichen ersetzt. Also "OS:FileType" wird im JavaScript mit "OS_FileType" verwendet.

Folgend das passende JS zu dem Mapping.

if (this.ObjectTypeId == 262199) { switch (this.FieldName) { case "picture_type": { switch (this.FieldValue) { case "JPEG": this.ResultValue = "JPG"; break; case "TIFF": this.ResultValue = "TIF"; break; } break; } case "picture_orientation": { if (this.os_map.picture_width_px > this.os_map.picture_height_px) { this.ResultValue = "Querformat"; } else if (this.os_map.picture_width_px < this.os_map.picture_height_px) { this.ResultValue = "Hochformat" } else { this.ResultValue = "Anderes Format"; } break; } case "geodata": { this.ResultValue = this.var_map.GPS_LAT + ", " + this.var_map.GPS_LONG; break; } } }

Comma-seperated list of object oids on which the search should be executed. If empty, all objects are searched (optional)