Server-API Übersicht

Dies ist eine Api-Facade für den DMS Server, kompatibel mit NETStandard 2.0 und verfügbar für .Net Framework 4.6.1 und .Net Core 3.1. Diese Dokumentation bezieht sich auf die aktuelle Version 2023.11.221. Die Änderungen können in den Release Notes eingesehen werden.

Zweck der Api ist es eine einfache Anbindung an den DMS-Server zu ermöglichen um Zugriff auf Dokumente und Akten zu ermöglichen. Dazu stellt die Api eine Verbindung über den LEXolution Service Bus zu dem DMS Server her. Wurde dies erfolgreich getätigt, können über mehrere Unterobjecte Funktionalitäten des Servers aufgerufen werden.

Wichtig: Diese API ist nicht dafür gemacht für jeden Aufruf neu initialisiert zu werden. Es stellt vielmehr einen DMS-Client dar. Die Vorgehensweise ist so, dass die Api einmalig gestartet und an einer zentralen Stelle festgehalten/referenziert wird.

Überblick zum Einsatz der Api

Schnellstart

Hier eine Anleitung, wie man zu einem funktionierenden DMS-Client kommt. Zuerst muss das aktuellste NuGet-Paket in das Projekt installiert werden (DevOps Feed):

PM> Install-Package LEXolution.DMS.ApiCore

using STP.Ecm.ApiCore;
var lsbConfig = new LocalhostDefaultLsbConfiguration(); // vorbelegt für lokalen RabbitMQ
var dms = new Dms(lsbConfig);

Development API Lizenz übermitteln

In der lsbConfig gibt es das Feld ‘LicenseString’. Dieser String muss mit einer gültigen Development API Lizenz befüllt werden, damit die Api genutzt werden kann. Diese verschlüsselte Lisa-Lizenz kann über den LEXolution Support angefragt werden. Es handelt sich um ein XML-String, welcher schematisch so aussieht (Beispiel):

<?xml version="1.0" standalone="yes"?>
<XMLLicense xmlns="http://tempuri.org/XMLLicense.xsd">
    <License>
        <GUID></GUID>
        <Name>C7+D2BSYRdGYJ5lzMsjM9w==</Name>
        <Nummer>XsiBW92x2NousbMQxt6+gw==</Nummer>
        <GIS>XsiBW92x2NousbMQxt6+gw==</GIS>
        <Bemerkung>wdN0aZq0QOKs9PQAFZEJgyIbwiyIebUlAg2jby/baPs=</Bemerkung>
        <Products>
            <Product>
                <ProductName>7PrB1HfurdbKGaTkwqNX5YqynRPemD0IRcxHSBptF74=</ProductName>
                <ProductID>XsiBW92x2NousbMQxt6+gw==</ProductID>
                <Moduls>
                    <Modul>
                        <ModulName>1gH0Y96u782eNG9JcoYWMuc5uAIKLqQy8hBlLrddIUI=</ModulName>
                        <ModulID>zYnlhmjrV2PxB4ffxaHprQ==</ModulID>
                        <Count>B4qWQS/Sjitlcm1m/VcmQA==</Count>
                        <Expiry>rNxtk6P39blKoXohxSBDIA==</Expiry>
                        <Concurrent>e1k/hMuSkVglAtjPhXIavw==</Concurrent>
                    </Modul>
                </Moduls>
            </Product>
        </Products>
    </License>
</XMLLicense>

Die Initialisierung kann bei der Definition der lsbConfig so erfolgen:

using STP.Ecm.ApiCore;
var lsbConfig = new LocalhostDefaultLsbConfiguration()
lsbConfig.LicenseString = "<!-- XML License String hier einfügen -->"
var dms = new Dms(lsbConfig);

Anschließend muss eine Anmeldung am STP Usermanagement vorgenommen werden. Hier gibt es eine ausführlichere Beschreibung des Init-Vorgangs.

var initResult = dms.Init(); // Windowsanmeldung (funktioniert nicht mit .Net Core)
if (!initResult.Success)
{
    Environment.Exit(-1); // Anmeldung fehlgeschlagen. Beispielprogramm wird beendet
}

Nun sind die Unterobjekte gesetzt (vorher sind sie null) und können verwendet werden. Es gibt eines für jeden Themenbereich der Api. Die Themenbereiche werden im Anschluß gesondert beschrieben. Hier wird nun ein kleiner Anwendungsfall implementiert.

Dokument suchen und herunterladen

Wir suchen das Dokument nach dem Titel, nehmen dort das erste und laden dessen Inhalt herunter.

var filter = new SimpleExpression(SimpleOperator.Like, STP.Ecm.ApiCore.Fieldname.Document.Title, "Rechnungsdokument%");
var foundIds = await dms.Document.FilterDocumentIds(filter);
if (foundIds != null && foundIds.Count > 0) 
{
    var firstId = foundIds.First();
    var documentData = await dms.Document.LoadDocumentData(firstId);
    dms.Document.DownloadContent(firstId, @"C:\Temp\" + documentData.Versions.Last().Filename);
}

Damit haben wir den Inhalt heruntergeladen und lokal abgespeichert.

Bereiche

Hier werden die Unterbereiche des Hauptobjekts Dms beschrieben.

Document

Dieser Bereich enthält Funktionen, die sich auf Dokumente beziehen, also Import, Bearbeitung, … ApiCore - Document

Container

Hier geht es um Akten und Ordner. ApiCore - Container

AccessRights

Zugriffsrechte auf unterschiedliche Objekttypen (Dokumente, Akten, …) können hier gelesen und geändert werden. ApiCore - AccessRights

Collector

Die Api hat keinen direkten Zugang zu dem Collector im DMS-Server, aber mit diesem Modul können die Collector-Definitionen geladen werden und die Verarbeitungsvorlage eines Collectors kann bei einem Import (auch mehrere Dokumente) angewendet werden. Es werden dabei Indexdaten gesetzt und z.B. Aufgabenlisten gestartet. ApiCore - Collector

TasksAndNotices

Aufgaben, Notizen und Aufgabenlisten können hier angelegt, bzw. gestartet werden. ApiCore - TasksAndNotices

RollContainer

Vorgänge, Nicht zugeordnete Dokumente, Meine Importe und Papierkorb sind hier zusammengefasst. ApiCore - RollContainer

Favoriten

Dokumentfavoriten können mit der Api verändert werden. Beim Abfragen werden zudem auch die Aktenfavoriten ausgegeben. ApiCore - Favorites

Schema

Zugriff auf Datenschemata von DMS (Themen, Listendefinitionen). ApiCore - Schema

Impersonierung

Die Api kann Aufrufe impersoniert ausführen. Dies funktioniert allerdings nicht mit “Notifications”! ApiCore - Impersonation

Notifications

In diesem Modul kann man keine Funktionen aufrufen, aber Callbacks eintragen, welche bei bestimmten Aktionen des DMS-Servers aufgerufen werden. ApiCore - Notifications

ValueStore

Zusatzdaten zu jedem DMS-Objekt ablegen. ApiCore - ValueStore

Mail

Mailspezifische Funktionen. ApiCore - Mail

Feldnamen

Für viele Funktionen in der API werden Feldnamen benötigt. Zum Beispiel für Filter oder auch um Daten zu ändern. Diese Feldnamen sind Strings. Ein vollständiger Satz befindet sich in der der Datei “de-DE_topic.lang_id”, welche sich in jedem Installationsverzeichnis eines DMS-Produkts befindet.

Die schönere Variante ist aber der Namespace STP.Ecm.ApiCore.Fieldname. Dort finden sich Klassen mit Stringkonstanten für die Felder in Document, Dossier und Folder.

Themenspezifische Felder finden sich in Unterklassen, wie zum Beispiel Mail.

Beispiel:

var feldMailBetreff = STP.Ecm.ApiCore.Fieldname.Document.Mail.Subject;
// feldMailBetreff = "Mail.DocumentInfo.MailBetreff"

var filter = new SimpleExpression(
                     SimpleOperator.Equals, 
                     STP.Ecm.ApiCore.Fieldname.Document.Mail.Subject,
                     "AW: Testmail");

Serverabfrage

Über das Objekt DmsServerQuery kann eine Abfragen (Who-Is-There) an einen LSB gesendet werden, um alle angebundenen DMS-Systeme abzufragen.

Die Klasse wird instanziiert mit einer LSB-Configuration, analog zum Dms-Objekt. Danach kann die Methode Query aufgerufen werden, welcher man einen Timeout und einen Handler mitgibt. Es wird bis zum Ablauf des Timeouts gewartet, dass DMS-Systeme auf die Who-Is-There-Anfrage antworten. Für jedes System, welches eine Antwort sendet wird der Handler aufgerufen, welcher den Anzeigenamen und die System-Id erhält.

Mit dieser System-Id kann dann eine eigentliche Api-Instanz initiiert werden.

var query = new DmsServerQuery(lsbConfig);
query.Query(TimeSpan.FromSeconds(10), info = > {
    // wird immer dann aufgerufen, wenn ein Server antwortet.
    Console.WriteLine(info.DisplayName);
});
// nach 10 Sekunden ist die Methode abgeschlossen (angegebener Timeout).

Die erhaltenen Infoobjekte enthalten die folgenden Angaben und können Live in eine Liste eingetragen werden, damit der Anwender eine Auswahl treffen kann.