URL-Integration manuell erstellen

Struktur einer Integrations-URL

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 darüber hinaus 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.

Details zu Login-Parametern

Kodierte 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".

Details zu Query-Parametern

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.

Details zum 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.

Beispiele

Alle Beispiele, die hier aufgeführt sind, können Sie in Ihrer DocuWare-Installation ausprobieren. Voraussetzung ist, dass Sie das Beispielarchiv installiert haben und der Platform Service in die Standardseite des IIS publiziert ist. Sie müssen den realen Servernamen eintragen. Alle weiteren Parameter müssen den Werten Ihrer Installation entsprechen.

Alle URLs der folgenden Beispieladressen beginnen mit

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

Voraussetzung für die Beispiel-URLs in diesem Kapitel ist, dass der Benutzer die Rechte auf die Archive und Ergebnis- oder Aufgabenliste hat, siehe dazu auch das Kapitel "Voreinstellungen".

Beispiele Login-Parameter

Eine Ergebnisliste &p=RLV&rl=<result list id>

soll per Integrations-URL aufgerufen werden, und zwar

ohne automatisches Login

• http://<ihr_servername>/<DocuWare>/<Platform>/WebClient/Integration?p=RLV&rl=<result list id>

Der Benutzer muss seine DocuWare-Kennung eingeben, bevor die Ergebnisliste angezeigt wird.

mit Single Sign-on

Der Parameter für das Windows-Login ist "SSO". Er wird in die Basis-URL vor die Identifizierungsnummer eingefügt.

• http://<ihr_servername>/<DocuWare>/<Platform>/WebClient/SSO/Integration?p=RLV& rl=<result list id>

Der Benutzer wird automatisch angemeldet. Er muss weder seine Windows- noch seine DocuWare-Kennung eingeben.

mit Benutzernamen und Passwort in URL

Mit einem automatischen Login kann beispielsweise der Kunde aus einer internen Anwendung ein Element aus DocuWare aufrufen, ohne seine Logindaten eingeben zu müssen. Der Parameter "lc" integriert die Kennung in die URL, dazu müssen die Logindaten vorher Base64-kodiert werden.

Logindaten: User=administrator\nPwd=admin.

Logindaten Base64URL-kodiert: VXNlcj1hZG1pbmlzdHJhdG9yXG5Qd2Q9YWRtaW4=

Dieser String wird mit dem Parameter "lc" in die URL integriert:

• http://<ihr_servername>/<DocuWare>/<Platform>/WebClient/Integration&p=RLV&rl=<result list id>&lc=VXNlcj1hZG1pbmlzdHJhdG9yXG5Qd2Q9YWRtaW4=

Zudem muss die URL den Benutzernamen und das Passwort in verschlüsselter Form enthalten. Die URL für ein automatisches Login ist folgendermaßen aufgebaut:

• http://<ihr_servername>/<DocuWare>/<Platform>/WebClient/Integration?ep=<verschlüsselte Parameter für Loginkennung>

Sie können eine URL über den URL-Creator verschlüsseln lassen, siehe Kapitel DocuWare-URL-Creator. Verschlüsseln Sie die verschlüsselbaren Parameter selbst, weil die URLs on the fly erzeugt werden müssen, können Sie dazu entweder GAPI verwenden oder die Algorithmen zur Verschlüsselung in Kapitel Algorithmen zur Verschlüsselung nutzen.

Unverschlüsselte URLs mit den Login-Parametern lc oder lct können ab DocuWare Version 7.1 nicht mehr verwendet werden.

Um bestehende Integrations-URLs zu aktualisieren, gehen Sie wie folgt vor:

• Wählen Sie im URL Creator im ersten Schritt "Parse URL"

• Kopieren Sie die bisherige URL in das Textfeld und klicken Sie auf "Next"

• Aktivieren Sie "Use passphrase" und geben Sie die Passphrase ein.
   Sie finden die Passphrase in der DocuWare Administration im Organisationsbereich unter "Allgemein"

• Klicken Sie auf "Next" bis zur Summary-Seite und kopieren Sie die neue URL mit dem sicher verschlüsselten Login.

Wenn eine Anwendung Ihre URL generiert, müssen Sie diese mit der Passphrase aus der DocuWare Administration anpassen.

Mehr Informationen zur Verschlüsselung

Beispiele: Integration von Elementen

Nur Integration von Viewer, keine Ergebnisliste, spezifisches Dokument wird geöffnet

DocID des spezifischen Dokuments ist „8"

• &p=V&rl=a60d2279-227d-454b-815c-14d64eb165a1&did=8

Wenn Sie hier keine DocID angeben, wird automatisch der erste Treffer der Ergebnisliste angezeigt. Oder Sie können eine Abfrage in der URL definieren.

• &p=V&rl=69e807b6-70e8-48c2-8857-2864dfebc4ac

Integration von Viewer und Ergebnisliste

• &p=RLV&rl=69e807b6-70e8-48c2-8857-2864dfebc4ac

Bei der Ergebnisliste, die über die GUID in dieser URL definiert ist, muss es sich um eine Aufgaben- oder Ergebnisliste handeln.

Es ist auch möglich, den RLV-Parameter mit einem Suchdialog zu kombinieren. Das Ergebnis unterscheidet sich nicht von der Integration einer Ergebnisliste mit der rl-GUID.

• ?p=RLV&fc=<c1699bcf-6ae6-4f1c-b881-17792edbdd92>&sed=<b0342b12-0050-45f8-9060-db44f47d7b8f>

Die Archiv-ID ist nicht zwingend erforderlich. Ohne Archiv-ID wird jedoch in allen Archiven nach dem Suchdialog gesucht, was die Ladzeit verlängern kann.

Integration von Suchdialog sowie Viewer und Ergebnisliste

• &p=SRLV&sed=0c825e8b-e21f-48e8-b31f-590bf60a6c59

Hier muss kein Parameter für eine Ergebnisliste vorgegeben sein, da sich ein Suchdialog öffnet. Jedem Suchdialog ist immer eine Ergebnisliste zugeordnet.

Download-Integration

• &p=D&rl=a60d2279-227d-454b-815c-14d64eb165a1&did=8

Bei dieser URL öffnet sich das Dokument im Plugin-Programm, da nicht explizit als Download-Typ "Download" vorgegeben ist. Möchten Sie ein Dokument zum Herunterladen anbieten, lautet die URL:

• &p=D&rl=a60d2279-227d-454b-815c-14d64eb165a1&did=8&dt=Download

Sie können auch für eine Download-Integration eine Aufgabenliste oder eine Abfrage definieren. Sollten mehrere Treffer gefunden werden, wird immer der erste Treffer im Plugin-Programm angezeigt oder zum Herunterladen angeboten.

Selbstverständlich lässt sich für alle Beispiele in diesem Kapitel die Kennung als Parameter definieren; alternativ zur Aufgabenliste können Sie auch die Abfrage als Parameter definieren.

Beispiele für Abfragen in der URL

Bei allen folgenden Beispielen erfolgt der Zugang über Benutzer-Kennung in der URL; Benutzername ist guest und Passwort ist ebenfalls guest. Der Einfachheit halber sind hier nur die Parameter aufgelistet. Die Basis-URL ist die gleiche wie bei den Beispielen zuvor.

Wenn Sie eine Abfrage in der URL definieren, und die Ergebnisliste eine Aufgabenliste ist, kann der Parameter „q" die Abfrage der Aufgabenliste weiter verfeinern.

Abfragen mit einfachem Suchausdruck

[COMPANY]="Peters Engineering"

• &p=RLV&lc=VXNlcj1ndWVzdFxuUHdkPWd1ZXN0&rl=a60d2279-227d-454b-815c-14d64eb165a1&q=W0NPTVBBTlldPZRQZXRlcnMgRW5naW5lZXJpbmeU

[CONTACT] LIKE "Lau*"

• &p=RLV&lc=VXNlcj1ndWVzdFxuUHdkPWd1ZXN0&rl=a60d2279-227d-454b-815c-14d64eb165a1&q=W0NPTlRBQ1RdIExJS0Ugk0xhdSqT

Abfragen mit komplexen Suchausdrücken

[COMPANY]="US-Steel" AND [DEPARTMENT]="Production"

• &p=RLV&lc=VXNlcj1ndWVzdFxuUHdkPWd1ZXN0&rl=a60d2279-227d-454b-815c-14d64eb165a1&q=W0NPTVBBTlldPZNVUy1TdGVlbJMgQU5EIFtERVBBUlRNRU5UXT2TUHJvZHVjdGlvbpM=

[COMPANY]="Phone Wizard" AND [DEPARTMENT]="Accounting" AND [STATUS]="to be approved"

• &p=RLV&lc=VXNlcj1ndWVzdFxuUHdkPWd1ZXN0&rl=a60d2279-227d-454b-815c-14d64eb165a1&q=W0NPTVBBTlldPZNQaG9uZSBXaXphcmSTIEFORCBbREVQQVJUTUVOVF09k0FjY291bnRpbmeTIEFORCBbU1RBVFVTXT2UdG8gYmUgYXBwcm92ZWSU

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.

Beispiel Indexdialog

Ein Indexdialog (Info-Dialog) lässt sich mit dem folgenden URL-Schema aufrufen:

• ? p=IND&rl=<Resultlist_ID>&fc=<FileCabinet_ID>&did=<doc_ID>

IND = Parameter für Indexdialog

rl = Parameter für die ID einer Ergebnisliste

fc = Archiv-ID

did = ID vom Dokument, für das der Indexdialog angezeigt werden soll.

IDs der DocuWare-Elements

Alle Parameter müssen verschlüsselt werden.

Beispiel für Briefkorb

Eine Briefkorb-Intgeration stellt alle Funktionen des Briefkorbs wie im Web Client zur Verfügung.

Ein Briefkorb kann mit dem folgenden URL-Schema eingebettet werden:

• ? p=B&bid=<Basket_ID>

B = Parameter für Briefkorb

bid = ID vom Briefkorb

IDs der DocuWare-Elements

Alle Parameter müssen verschlüsselt werden.

Beispiel für Dokumentverknüpfung

Mit diesem URL-Schema können Sie eine Dokumentverknüpfung einbetten:

• ?p=DL&fc=<FileCabinet_ID>&did=<doc_ID>&docLink=<doc_ID>

DL = Parameter für Dokumentverknüpfung (document link)

fc = Archiv-ID, es muss hier das Quellarchiv angegeben werden, also das Archiv, in welchem der Link enthalten ist.

did = ID des Dokuments zu dem der Link gehört

docLink = ID der Dokumentverknüpfung

IDs der DocuWare-Elemente

Verschlüsselung

Setzen Sie einzelne, fest vorgegebene URLs ein, so können Sie diese mit dem DocuWare-URL-Creator verschlüsseln und entschlüsseln lassen (siehe Kapitel DocuWare-URL-Creator). Verschlüsseln Sie die verschlüsselbaren Parameter selbst, weil die URLs on the fly erzeugt werden müssen, können Sie dazu entweder GAPI verwenden oder die Algorithmen zur Verschlüsselung in Kapitel Algorithmen zur Verschlüsselung nutzen.

Algorithmen zur Verschlüsselung

Bitte beachten Sie, dass zur Verschlüsselung einige Parameter base64URL-kodiert sein müssen. Hinweise dazu finden Sie im Kapitel URL-Parameter.

Verschlüsselung der URL

Es wird ein symmetrischer Verschlüsselungs-Algorithmus benutzt.

Zur Verschlüsselung wird der Advanced Encryption Standard (AES) entsprechend der Spezifikation FIPS-197 mit folgenden Parametern verwendet:

• Block Size = 128 Bits

• Cipher size = CBC (Cipher Block Chaining)

• Initialization vector (IV) = 128 bits

• Key length = 256 bits

• Kein salt

Schlüssel

Zur Ver- und Entschlüsselung wird ein AES-Schlüssel mit 256 Bits und ein Initialisierungs-Vektor (IV) mit 128 Bits verwendet. Der Schlüssel und der Initialisierungs-Vektor müssen auch der externen Anwendung bekannt sein. Dazu werden Passphrasen verwendet. Aus dieser Passphrase errechnet DocuWare den Schlüssel und den Initialisierungs-Vektor. Die Passphrase wird verschlüsselt und als Eigenschaft in den Einstellungen der Organisation abgelegt. Der Administrator muss in der externen Anwendung die Passphrase ebenfalls eingeben und verschlüsseln lassen.

Ab DocuWare 6.5 finden Sie die Passphrase zur Verschlüsselung im Bereich Organisation / Allgemein / Webverbindung.

Zur Ermittlung des AES-Schlüssels und des Initialisierungs-Vektors aus der Passphrase wird folgender Algorithmus verwendet:

• Ermittlung eines SHA-512 Hashs aus der Passphrase (ergeben 512 Bits). Das kann mit der SHA512Managed-class in .NET implementiert werden und wird auch von Java und PHP unterstützt. Für JavaScript sind third-party Add-Ons verfügbar.

• Nutzen Sie die ersten 256 Bits (32-Bytes-Array) für den AES-Schlüssel.

• Nutzen Sie die folgenden 128 Bits (16-Bytes-Array) für den Initialisierungs-Vektor.