Parameter für die URL-Integration

Die URL-Integration in DocuWare ermöglicht den Zugriff auf archivierte Dokumente und DocuWare Funktionen direkt über Weblinks. Dieser Artikel bietet einen Überblick über die verfügbaren Parameter, mit denen sich URL-Integrationen in DocuWare anpassen und steuern lassen.

URL-Struktur

Die URL für den Aufruf von Teilen vom DocuWare Client aus anderen Anwendungen besteht immer aus der Basis-URL sowie weiteren Parametern - was im folgenden erklärt wird.

Hier erhalten Sie weitere Codebeispiele und NuGet Pakete.

Basis-URL

Die Basis-URL für die Integration setzt sich aus drei Bestandteilen zusammen: der Adresse zum DocuWare Client, beziehungsweise Web Client, ggf. der Organisations-GUID sowie dem Suffix "Integration". Diese Bestandteile stehen für jede Organisation fest und müssen nicht geändert werden. Hier finden Sie die Angaben:

Adresse vom DocuWare Client

Die HTTP-Adresse des DocuWare Client setzt sich zusammen aus dem Servernamen des Rechners, auf dem der Platform Service installiert wurde, sowie dem Zielverzeichnis des IIS (Internet Information Services), in das der Platform Service publiziert wurde.

• http://<ihr_servername>/<DocuWare>/<Platform>/WebClient

Sie finden die Adresse in der DocuWare-Administration auf Systemebene in den Webverbindungen.

Standard-Erweiterung "Integration"

An diese Adresse fügen Sie dann die Standard-Erweiterung "Integration" an.

• http://<ihr_servername>/<DocuWare>/<Platform>/WebClient/Integration

Organisations-GUID

Die Organisations-GUID als Kennung wird nur benötigt, wenn ein DocuWare On-Premises-System mehr als ein Unternehmen hat. Sie finden die Organisations-GUID in der DocuWare Administration unter <Organisation x > Allgemein. Fügen Sie sie die GUID in die URL vor dem Integrations-Suffix ein:

• http://<ihr_servername>/<DocuWare>/<Platform>/WebClient/OrgGUID/Integration

Cloud-Kunden können ab DocuWare Version 7.1 eine Integrations-URL auch ohne OrgGUID anlegen, da das Unternehmen in der Basisadresse der URL verschlüsselt ist. Gleiches gilt für Anwender von DocuWare On-Premises, wenn das System nur eine Organisation hat.

Mit der Version 7.1 von DocuWare enthalten alle von DocuWare generierten URLs die GUID der Organisation anstatt der ID. Bestehende URL-Integrationen funktionieren auch nach dem Upgrade auf DocuWare Version 7.1.

Tabelle URL-Parameter

An die Basis-URL schließen sich die Parameter an. Der Datenteil der URL mit den Parametern wird mit dem Fragezeichen (?) eingeleitet.

Diese Tabelle gibt eine Übersicht über mögliche Parameter. Informationen zur Base64-Kodierung und zur Verschlüsselung finden Sie in den folgenden Kapiteln.

Bitte beachten Sie:

• Die Parameter müssen zwingend in Kleinbuchstaben geschrieben werden. Ausnahme: Die Werte für den Parameter p (z.B. V für Viewer-Integration) müssen im Gegensatz dazu unbedingt in Großbuchstaben geschrieben werden.

• Die Parameter ep, ns, vf, vu werden nur im Falle einer Verschlüsselung (siehe Kapitel Automatisches Login in Web Client über URL) verwendet.

Base64 URL Encoding

Für die URL-Parameter „lc" und „q" müssen die Werte kodiert werden, da nur über die Kodierung die komplexen Daten in einer gültigen URL genutzt werden können. DocuWare benutzt dazu die Base64URL-Kodierung. Da in einer URL die Zeichen „+" und „/" nicht genutzt werden können, müssen sie in „-„ und „_" umgewandelt werden. Detailliertere Spezifikationen dazu finden Sie im Dokument RFC 4648, section 5 (http://tools.ietf.org/html/rfc4648#section-5). Der entsprechende Code sieht beispielsweise in PHP so aus:

function base64url_encode($plainText)
{
       $base64 = base64_encode($plainText);
       $base64url = strtr($base64, '+/', '-_');
       return ($base64url);
}

Bitte beachten Sie bei Strings, die Hochkommata enthalten (siehe Kapitel Beispiele, z.B. [COMPANY]="Peters Engineering"), dass das Hochkomma je nach Editor unterschiedlich sein kann und damit auch unterschiedliche Base64 Codierungen haben kann. Die Funktionsweise der URL wird dadurch nicht beeinträchtigt.

Außerdem entfernt DocuWare die Trailing ‘=’ Zeichen und fügt je nachdem, wie viele Zeichen entfernt worden sind, eine 0, 1 oder 2 hinzu. Die Implementierung benutzt die .NET Funktion "HttpServerUtility.UrlTokenEncode", zu der Sie auf der Microsoft Webseite mehr Informationen finden.

Weitere Informationen zu den Parametern

Details zur kodierten DocuWare Kennung

Die Anmelde-Kennung muss eine UTF-8-Zeichenkette sein, die base64URL-kodiert ist. Die unkodierte Zeichenkette hat folgende Form:

User=<username>\nPwd=<password> (\n kennzeichnet den Zeilenvorschub)

Wenn Sie beispielsweise die Kennung Benutzer ist gleich administrator und Passwort ist gleich admin kodieren wollen, geben Sie zunächst folgende Form vor:

User=administrator\nPwd=admin

Diese Zeichenfolge kodieren Sie. Das Ergebnis ist:

VXNlcj1hZG1pbmlzdHJhdG9yXG5Qd2Q9YWRtaW4=.

Diesen Wert nutzen Sie dann für den Parameter „lc".

Query-Parameter

Die Abfrage muss eine UTF-8-Zeichenkette sein, die base64URL-kodiert ist.

Die unkodierte Zeichenkette hat folgende Form:

[Name of a field in the database]<any number of WhiteSpaces><relational operator><any number of WhiteSpaces>"<search criteria for the field type of DocuWare field>"

z.B.

[COMPANY]="Peters Engineering"

[CONTACT] LIKE „Wi*"

Bitte achten Sie darauf, dass die Feldnamen dem jeweiligen Namen in der Datenbank genau entsprechen, beachten Sie auch die Groß- und Kleinschreibung.

Sollten in der Query Zahlwerte enthalten sein, funktioniert die Abfrage in gleicher Weise wie bei Buchstaben, beispielsweise

[RECORDNUMBER]="12345"

Für eine Dezimalzahl ist beim Trennzeichen ein Punkt oder ein Komma zu setzen, z. B. "123,45".

Wenn in der Query eine Datumsabfrage enthalten ist, muss die Datumsangabe im sprachunabhängigen Format „YYYY-MM-DD" erfolgen, damit die Abfrage in jedem Fall reibunglos funktioniert. Für ein Datum mit Uhrzeit verwenden Sie das Format YYYY-MM-DD HH:mm:ss.

Sollte(n) in der Query ein oder mehrere Anführungszeichen oben vorhanden sein, muss dem jeweiligen Anführungszeichen ein Backslash \ vorangestellt werden, um die Metabedeutung der Anführungszeichen aufzuheben. Beispiel:

[SUBJECT]="Sogenanntes \"Web 2.0\""

Mögliche relationale Operatoren sind:

<=, >=, <, >, = und LIKE; wobei LIKE nur für Textfelder gültig ist. Wird der Operator LIKE verwendet, muss das Suchkriterium mindestens ein Sternchen „*" enthalten.

Einzelne Suchausdrücke können miteinander durch logische Operatoren zu komplexeren Suchabfragen verbunden werden, z.B.:

[COMPANY]="Peters Engineering" AND [STATUS]="Valid"

Mögliche logische Operatoren sind:

AND, OR, NOT.

Achten Sie darauf, dass vor und hinter dem jeweiligen logischen Operator immer mindestens ein Leerzeichen vorkommt. Das gilt auch für den Operator LIKE.

Die jeweils gültige Suchabfrage kodieren Sie mit der base64-Kodierung. Das Beispiel

[COMPANY]="Peters Engineering" lautet dann:

W0NPTVBBTlldPZRQZXRlcnMgRW5naW5lZXJpbmeU.

Abfragen mit numerischen Feldern

Verwenden Sie in einem numerischen Feld bei Dezimalstellen immer einen Punkt - unabhängig von der Spracheinstellung. Dadurch kann die Suchabfrage unabhängig von Sprach.- und Ländereinstellungen ausgeführt werden.

Parameter dv

Mit dem Parameter dv können Sie für eine Integration des Typs Suchdialog, Ergebnisliste und Viewer (SLRV) einzelne oder mehrere Feldwerte festlegen. Damit sind diese Felder in der Suchmaske bereits ausgefüllt. Der Benutzer kann diese Feldeinträge bei Bedarf löschen, beziehungsweise ändern.

Nomenklatur

Der gesamte String muss Base64URL-kodiert sein. Die Feldwerte müssen folgendes Format haben:

"[FieldName1]=fieldValue1&[FieldName2]=fieldValue2"

Als Feldname sollte der Datenbankname des Feldes eingetragen werden.

Beispiel: "[COMPANY]=Peters Engineering&[CONTACT]=SANDERS"

Wenn in einem numerischen oder einem Datums-Feld eines der "Von" oder "Bis"-Felder - oder beide - ausgefüllt werden sollen, werden diese Felder mit ; getrennt.

Beispiele:

[NUMERIC_FIELD]=1;5 sowohl "von" als auch "bis" werden gefüllt

[NUMERIC_FIELD]=;5 füllt nur den "Bis"-Wert

[NUMERIC_FIELD]=1 füllt nur den "Von"-Wert

Bei KEYWORD-Feldern ist eine Liste erforderlich, deren Einträge ebenfalls mit dem Semikolon ; getrennt sind.

Wenn mit dem dv-Parameter eine Datumssuche definiert wird, muss die Datumsangabe im sprachunabhängigen Format „YYYY-MM-DD" erfolgen, damit die Abfrage in jedem Fall reibunglos funktioniert.