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.
Parameter | Bedeutung | Erforderlich | Mögliche Werte/ Anmerkungen | Base64-URL kodiert | |
---|---|---|---|---|---|
ep | Encrypted Parameter | Kann nur in Verbindung mit einem Integrationstyp (p-Parameter) verwendet werden | Alle folgenden Parameter in verschlüsselter Form, die Passphrase muss in der DocuWare Administration festgelegt sein | Ja | |
ns | Noise | Sorgt dafür, dass das Ergebnis der Verschlüsselung niemals gleich ist, d.h. der Ciphertext ist immer unterschiedlich. Um das sicherzustellen sollte Noise immer zu Beginn des Parameter-Strings stehen. | |||
p | Elemente, die integriert werden sollen: V = nur Viewer RLV = Ergebnisliste und Viewer D = Download (Plugin) SRLV = Suchdialog, DH = Versionsübersicht (document history) IND = Indexdialog (Info Dialog) WFTL = Workflow Task List WFST = Workflow Single Task SWT = Anfrage senden (Simple Workflow Task) SWO = Gesandte Anfragen (Simple Workflow Owner) B=Briefkorb DL= Dokumentver- knüpfung (document link) | Ja | Für DH muss in der DocuWare Administration für das entsprechende Archiv die Option " Versionsmanagement" aktiviert werden Für WFTL, WFST, SWO und SWT ist das Modul Workflow Manager erforderlich. SRLV: Bei einer Suche per URL-Integration werden die Treffer einer Volltextsuche im Viewer nicht farbig markiert. Eine Ergebnisliste mit Ordnerstruktur wird nicht unterstützt. | ||
lc | DocuWare-Kennung | Alle existierenden DocuWare-Benutzer-Kennungen; die Kennung muss base64URL-kodiert sein | Ja | ||
lct | Token für DocuWare-Kennung | Wenn ein login credential token beim Authentication Server hinterlegt ist, kann sich der Anwender mit einer GUID beim Web Client einloggen, eine Passworteingabe ist dann nicht nötig. Ein login credential token lässt sich über den Platform Service erzeugen, es muss base64URL-kodiert sein | ja | ||
rl | Ergebnisliste | Nur erforderlich, wenn kein Suchdialog in der URL definiert ist Erforderlich bei Intgeration von Info-Dialog | GUIDs der Ergebnisliste | ||
q | Abfrage | Nur erforderlich, wenn kein Suchdialog via URL festegelegt ist | Beliebig gültige Abfragen im UTF-8-Format, die Abfragen müssen base64URL-kodiert sein Für die Suche im Volltext muss der Feldname „DocuWareFulltext" verwendet werden, z.B. : [DocuWareFulltext] LIKE "*EINSTEIN*" | Ja | |
did | DocID | Erforderlich, wenn keine Abfrage (über Aufgabenliste oder Parameter) und kein Suchdialog definiert ist; sinnvoll, wenn ein spezifisches Dokument angezeigt werden soll Erforderlich, wenn als Integration DH (Versionsübersicht) ausgewählt ist. Dann bezeichnet die DocID das Dokument, dessen gesamte Versionen angezeigt werden sollen. | Alle existierenden DocIDs des Archivs oder der Ergebnisliste, die in der URL integriert ist | ||
dv | legt Feldwerte für Suchdialog, Ergebnisliste und Viewer (SRLV) fest | Spezifizieren Sie in einem Suchdialog bestimmte Feldeinträge, so dass die Suche teilweise bereits vorgegeben ist. Beliebig gültige Abfragen im UTF-8-Format, die Abfragen müssen base64URL-kodiert sein | Ja | ||
displayOneDoc | zeigt bei einem eindeutigem Treffer das Dokument direkt an | Wenn nur ein Dokument gefunden wird, wird dieses bei einer Integration DH oder RL direkt im Viewer angezeigt anstatt zunächst in einer Liste. | |||
docLink | ID von der Dokument- | Ja, für Integrationstyp "Dokument- | |||
bid | ID vom Briefkorb | Ja | ID vom Briefkorb | ||
dt | Download-Typ | Nicht erforderlich: Ist „D" für die Integration definiert, wird als Standard „Plugin" als Download-Typ genommen; nur erforderlich, wenn „Download" als Typ definiert sein soll | Download | ||
sed | Suchdialog | Erforderlich, wenn Benutzern die Möglichkeit der Suchabfrage gegeben werden soll; Abfrage wird in dem Fall nicht über die Definition einer Aufgabenliste oder über Parameter in der URL definiert | Alle GUIDs von Suchdialogen | ||
waitDocContent | Wait for document content | Nicht erforderlich. Der Standardwert ist "true". | Für "Indexdialog mit Viewer": Mit "true" legt die Integration erst dann einen Datenbankeintrag an, wenn er mit einem Dokument verknüpft ist.Mit "false" speichert die Integration den Datenbankeintrag,sobald er erstellt ist. Das Dokument kann dann später hinzugefügt werden. | Yes | |
wiid | Workflow instance ID | Erforderlich, wenn als Integrationstyp "Workflow Task" oder "Sent requests" fegelegt ist | |||
wid | Workflow ID | Erforderlich, wenn als Integrationstyp "Workflow Task" oder "Workflow Task List" fegelegt ist | |||
wtid | Workflow Task ID | Erforderlich, wenn als Integrationstyp "Send Request" ausgewählt ist | |||
wr | Workflow Role d = designer c = controller | Erforderlich, wenn als Integrationstyp "Workflow Task List" fegelegt ist | |||
vf | Gültig von | Optional. Definieren einen gültigen Zeitraum für die URL, sie können einzeln oder gemein-sam gesetzt werden, ist z.B.nur „vf" gesetzt, wird die URL nach dem Zeitpunkt ‚"vf" nie ungültig werden. | Format nach ISO 8601: „yyyy-MM-ddThh:mm:ss.fffffffzz" „yyyy" = Jahr „MM" = Monat „DD" = Tag „hh" = Stunde „mm" = Minuten „ss" = Sekunden „fffffff" = Sekunden-Bruchteile „zz" = Zeitzone oder UTC offset (z.B. „Z" für GMT, „+01" für Berlin) Von rechts nach links kann jeder Teil weggelassen werden. Fehlt „zz" wird die lokale Zeit angenommen, yyyy-MM-dd definiert ein Datum ohne Zeitangabe, :,T,-,. sind lediglich Trennzeichen | ||
vu | Gültig bis | Ja | Ja |
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.