Webservice

Diese Aktivität bindet Webservices vom Typ REST oder SOAP in einen Workflow ein.

Mit Webservices lassen sich Daten zwischen Systemen automatisch austauschen oder per Workflow Informationen in anderen Anwendungen erstellen, aktualisieren oder löschen.

Umgekehrt können Sie Daten aus anderen Programmen wie Ihr CRM oder Ihrer FiBu in einem DocuWare Workflow verwenden.

Um Webservices mit Workflow Manager nutzen zu können, registrieren Sie diese zunächst in der DocuWare Konfiguration unter Webservices.

Die Aktivität Webservices bietet Ihnen eine assistierte Struktur mit einer Schrittfolge zum Einrichten des Webservice-Aufrufs. Die wichtigsten Schritte werden im folgenden am Beispiel eines REST-Webservice dargestellt.

1. Allgemein

Im ersten Schritt wählen Sie den REST-Webservice aus und legen das Format für den Datenaustausch fest (JSON oder XML). Es stehen Ihnen die Dienste zur Auswahl, die zuvor in der DocuWare Konfiguration unter Webservices eingerichtet wurden. Abhängig vom ausgewählten Webservice-Typ unterscheiden sich die weiteren benötigten Angaben.

Wenn Ihr Webdienst eine OpenAPI-Spezifikationsdatei (*.json, *.txt, *.yml oder *.yaml) anbietet, haben Sie die Möglichkeit, diese zu importieren. Nach dem Import werden alle verfügbaren Endpunkte in der Dropdown-Liste aufgeführt:

DocuWare Web Service Activity 1

Oder Sie verwenden die Standard Webservice DocuWare Platform API, bei der die Endpunkte bereits vorkonfiguriert sind.

2. Anforderung

Wählen Sie die Methode und erstellen die HTTP-Abfrage. Oben wird dann eine Vorschau angezeigt. Den URL-Pfad, die Abfrageparameter und die Body-Inhalte können Sie mit Variablen dynamisch gestalten.

Am Ende testen Sie die Abfrage und sehen im Tab "HTTP Response Status Codes", ob die Abfrage erfolgreich war.

Sie müssen für jede Variable einen Testwert angeben, um den Test durchzuführen.

DocuWare Web Service

HTTP Body

Auf der Registerkarte HTTP body haben Sie die Möglichkeit, das aktuelle Dokument an die HTTP-Anfrage an einen externen RESTful Web Service anzuhängen. Damit können Sie zum Beispiel ein gespeichertes Dokument wie eine Rechnung an einen externen KI-Erfassungsdienst senden, um das Dokument zu erfassen und die erfassten Informationen Indexfeldern oder globalen Variablen zuzuordnen.

Das Dokument kann als Originaldokument oder als pdf ohne Anmerkungen exportiert werden. Wenn das DocuWare Dokument mehrere Dateien enthält (geheftet), werden alle Dateien separat exportiert und angehängt. Die HTTP-Anfrage enthält dann mehrere Datei-Objekte.

Mit DocuWare Version 7.12 können Sie hier auch ein Testdokument angeben, das in die Test-Webservice-Anfrage aufgenommen wird.

Validierung des HTTP-Bodys

Die Validierung des HTTP-Bodys wird entweder mit Senden oder automatisch beim Speichern der Konfiguration durchgeführt. Wird ein Teil des Inhalts für ungültig befunden, wird der entsprechende Fehler hervorgehoben und eine entsprechende Meldung angezeigt. Auch bei Validierungsproblemen kann die Konfiguration gespeichert werden.

Verschlüsselung von HTTP-Abfragen

Für die Verschlüsselung von HTTP-Anfragen drei Optionen zur Auswahl:

  1. Sonderzeichen kodieren (Empfohlen): Alle Sonderzeichen werden kodiert, z.B. wird "AT&T" zu "AT%26T" und "Rapid Transport" zu "Rapid%20Transport"

  2. Sonderzeichen außer reservierten URL-Zeichen kodieren: ?#[]@!$&/*+,;='() Außer den reservierten URL-Zeichen werden alle Sonderzeichen kodiert, z.B. bleibt "AT&T", aber "Rapid Transport" wird zu "Rapid%20Transport".

  3. Sonderzeichen nicht kodieren: Weder Sonder- noch Leerzeichen werden kodiert.

Die Kodierung wird auf alle Werte angewendet, deren Übergabe auf den Reitern Route und Abfragen festgelegt wird, nicht aber auf die Werte der Reiter HTTP Header und HTTP Body.

Konfiguration von Endpunkten

Falls Sie eine OpenAPI-Spezifikationsdatei oder den Standard-REST-Webdienst "DocuWare Platform API" verwenden, konfigurieren Sie den im vorherigen Schritt ausgewählten Endpunkt. Um die Konfiguration zu vereinfachen, werden alle erforderlichen Parameter automatisch auf Basis des gewählten Endpunkts voreingestellt.

Speziell für die DocuWare Platform API definieren Sie in den Abschnitten Route und Queries fehlende Werte, zum Beispiel das Archiv oder Dokument, auf das zugegriffen werden soll.

Im Bereich HTTP Body geben Sie die erforderlichen Informationen und Eigenschaften an, die zur Ausführung der ausgewählten Operation benötigt werden, z. B. die GUID des zu platzierenden Stempels.

3. Datenzuweisung

Hier weisen Sie die Werte aus der Antwort-Variablen oder Indexdaten zu. Dabei wählen Sie die benötigten Werte aus dem empfangenen JSON oder XML aus einer Baumstruktur (siehe unten) aus.

Auf diese Weise können Sie bestimmte Informationen aus der Antwort extrahieren und für die weitere Verwendung in Ihrem Workflow speichern.

WFDes_Webservice_3

pictemplate_small

Wenn Sie alle zurückgegebenen Einträge verarbeiten wollen, ersetzen Sie den Index im Array-Indexer manuell durch ein Sternchen (*). Dies ermöglicht eine umfassende Verarbeitung aller Einträge innerhalb des Arrays.

DocuWare Web Service Activity 5

Standard Webservice DocuWare Platform API

Sie können auf Ihre Archive und die Dokumente in diesen Archiven über den integrierten Standard Webservice DocuWare Platform API zugreifen.

In der Liste unten finden Sie die Endpunkte, die für DocuWare Platform API bereits verfügbar sind.

!Einige Endpunkte können mehrere Operationen ausführen!

Zum Beispiel setzen Sie mit der Operation "documentAnnotations" einen Stempel an einer beliebigen oder an einer festen Position im Dokument oder Sie fügen eine Textanmerkung ein.

Für diese drei Funktionen mit documentAnnotations ist der Pfad/Endpunkt der gleiche. Der Unterschied ist der HTTP Body. Es kann aber von DocuWare nur ein HTTP Body automatisch vorausgefüllt werden.

Für das Beispiel “documentAnnotations” wird standardmäßig der HTTP Body für die Funktion “Stempel an einer automatisch ermittelten Position hinzufügen” ausgefüllt. Wenn Sie mit “documentAnnotations” eine andere Funktion verwenden möchten, müssen Sie den HTTP Body manuell austauschen und anpassen - die entsprechenden Vorlagen finden Sie unten in der Liste der Endpunkte.

Die Zeile "Standard" in der Liste der Endpunkte gibt an, welcher HTTP-Body bei der Wahl einer Operation automatisch vorausgefüllt wird.

Hier ist ein Überblick über die Funktionen, die sich denselben Pfad/Endpunkt teilen:

  • documentAnnotations

    POST /FileCabinets/{TrayId/FileCabinetId}/Operations/ProcessDocumentAction?docId={DocId}

    • Stempel an einer automatisch ermittelten Position hinzufügen - Standard

    • Stempel auf einer festen Position hinzufügen

    • Textanmerkung auf einer festen Position hinzufügen

  • processDocumentAction

    PUT /FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}/Annotation

    • Ebenen zusammenführen - Standard

    • Dokument anhängen

  • userRoles

    PUT /Organization/UserRoles?UserId={UserId}

    • Benutzer zu einer Rolle hinzufügen - Standard

    • Benutzer aus einer Rolle entfernen

  • userGroups

    PUT /Organization/UserGroups?UserId={UserId}

    • Benutzer zu einer Gruppe hinzufügen - Standard

    • Benutzer aus einer Rolle entfernen

Um die ID/GUID eines Benutzers zu übergeben, schreiben Sie einfach den Benutzernamen in eine globale Variable vom Typ "User" und übergeben Sie die Variable in der HTTP-Anfrage. Das System liefert automatisch die entsprechende GUID.

Liste der Endpunkte

Gesamtzahl der Dokumente in einem Archiv oder Briefkorb abrufen

  • Beschreibung: DialogId (optional): ID vom Suchdialog

    FieldName (optional): Name des Feldes, dessen Werte zusammengezählt werden

  • Standard: ja

  • Operation: countResult

  • Befehl: POST

  • Pfad:
    /DocuWare/Platform/FileCabinets/ {TrayId/FileCabinetId}/Query/CountExpression?dialogId={DialogId}&fieldName= {FieldName}

Suche per Dialog

  • Beschreibung: DialogId: ID vom Suchdialog

  • Standard: ja

  • Operation: dialogExpression

  • Befehl: POST

  • Pfad:
    /DocuWare/Platform/FileCabinets/ {TrayId/FileCabinetId}/Query/CountExpression?dialogId={DialogId}&fieldName= {FieldName}

  • HTTP body (sample): 

    { "Condition":[ {"DBName":"COMPANY", "Value":["Peter's Engineering"]},{"DBName":"CONTACT", "Value":["EMPTY()"]},{"DBName":"DocuWareFulltext", "Value":["Solar Panels"]}], "Operation":"And"}

In einem Briefkorb oder Archiv einen Datenbankeintrag erstellen

  • Standard: ja

  • Operation: documents

  • Befehl: POST

  • Pfad: /FileCabinets/{TrayId/FileCabinetId}/Documents

  • HTTP body (sample): 

    { "Fields": [ { "FieldName": "COMPANY", "Item": "Peter's Engineering" }, { "FieldName": "CONTACT", "Item": "Peter Sanders" }, { "FieldName": "DOCUMENT_DATE", "Item": "2020-01-01" }, { "FieldName": "COST_CENTER", "Item": { "$type": "DocumentIndexFieldKeywords", "Keyword": [ "A", "B", "C" ] } } ] }

Dokumentinformationen abrufen

  • Standard: ja

  • Operation: document

  • Befehl: GET

  • Pfad: /FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}

Dokument löschen

  • Standard: ja

  • Operation: documentDelete

  • Befehl: DELETE

  • Pfad: /FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}

Sektion von einem Dokument löschen

  • Beschreibung: Wenn der einzige Abschnitt eines Dokuments gelöscht wird, wird er automatisch in einen Datenbankeintrag umgewandelt.

  • Standard: ja

  • Operation: sectionDelete

  • Befehl: DELETE

  • Pfad: /FileCabinets/{TrayId/FileCabinetId}/Sections/{SectionId}

Stempel an einer automatisch ermittelten Position hinzufügen

  • Standard: ja

  • Operation: documentAnnotations

  • Befehl: POST

  • Pfad: /FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}/Annotation

  • HTTP-body (sample): 

    { "Annotations": [ { "PageNumber": 0, "SectionNumber": 0, "AnnotationsPlacement": { "Items": [ { "$type": "StampPlacement", "StampId": "73d54f34-1b80-4b43-81ec-f0d31176d990", "Layer": 1, "Field": [ { "Name": "<#1>", "TypedValue": { "Item": "*Test007*" }, "Value": "Jenkins" }, { "Name": "<#2>", "TypedValue": { "Item": "*Test007*" }, "Value": "Approved" } ], "Password": null } ] } } ] }

Stempel auf einer fest definierten Position hinzufügen

  • Operation: documentAnnotations

  • Befehl: POST

  • Pfad: FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}/Annotation

  • HTTP body (sample): 

    { "Annotations": [ { "PageNumber": 0, "SectionNumber": 0, "AnnotationsPlacement": { "Items": [ { "$type": "StampPlacement", "Location": { "X": "100", "Y": "100" }, "StampId": "6ab67774-074d-4d93-99c5-5bc46262b84c", "Layer": 1, "Field": [ { "Name": "<#1>", "TypedValue": { "Item": "September" }, "Value": "Sep." } ], "Password": null } ] } } ] }

Textanmerkung hinzufügen

  • Operation: documentAnnotations

  • Befehl: POST

  • Pfad:
    FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}/Annotation

  • HTTP body (sample): 

    { "Annotations": [ { "PageNumber": 0, "SectionNumber": 0, "AnnotationsPlacement": { "Items": [ { "$type": "Annotation", "Layer": [ { "Id": "1", "Items": [ { "$type": "TextEntry", "Font": { "FontName": "Lucida Console", "Bold": true, "Italic": true, "Underlined": false, "StrikeThrough": false, "FontSize": 200, "Spacing": 0 }, "Value": "Test annotation", "Location": { "Left": 100, "Top": 100, "Width": 1500, "Height": 500 }, "Color": "Black", "Rotation": 0, "Transparent": false, "StrokeWidth": 50 } ] } ] } ] } } ] }

Dokument übertragen

  • Beschreibung: Verschieben oder kopieren eines Dokuments aus einem Quellarchiv oder einer Quellablage in das angegebene Archiv oder den angegebenen Briefkorb

    Inhaltstyp muss eingestellt sein auf: application/vnd.docuware.platform.documentstransferinfo+json

  • Standard: ja

  • Operation: transfer

  • Befehl: POST

  • Pfad: /FileCabinets/ {TrayId/FileCabinetId} /Task/Transfer

  • HTTP body (sample): 

    { "SourceFileCabinetId": "ae156510-ffa8-48b1-a3ec-baec3180669c", "Documents": [ { "Id": 123456, "Fields": null } ], "KeepSource": true, "FillIntellix": false,"UseDefaultDialog": true}

Datei im Ziel-Dokument mit der aktuellen Datei ersetzen

  • Beschreibung: Das Quell-Dokument ist das aktuelle Dokument im Workflow. Das Ziel-Dokument können Sie definieren.

  • Standard: ja

  • Operation: sectionData

  • Befehl: POST

  • Pfad: /FileCabinets/{TrayId/FileCabinetId}/Sections/{SectionId}/Data

Aktuelles Dokument an ein Ziel-Dokument anhängen

  • Beschreibung: Hängen Sie das aktuelle Dokument an ein anderes Dokument in einem Archiv oder einem Briefkorb an.
    Das Dokument kann im Originalformat oder als PDF ohne Anmerkungen oder Stempel angehängt werden.
    Wenn das Ziel ein Ddatenbankeintrag ist, wird es automatisch in ein Dokument umgewandelt.

  • Standard: ja

  • Operation: sections

  • Befehl: POST

  • Pfad: /FileCabinets/{TrayId/FileCabinetId}/Sections?DocId={DocId}

Ebenen zusammenführen

  • Beschreibung: Führen Sie die Anmerkungsebenen in einem Dokument zusammen. Damit wird ein neues PDF erstellt, welches das vorige ersetzt.

  • Standard: ja

  • Operation: processDocumentAction

  • Befehl: PUT

  • Pfad:
    /FileCabinets/{TrayId/FileCabinetId}/Operations/ProcessDocumentAction?docId={DocId}

  • HTTP body (sample): 

    { "DocumentAction": "MergeAnnotations","DocumentActionParameters":{"$type":"MergeAnnotationsParameters","SectionNumber":0}}

Dokument anhängen

  • Beschreibung: Hängen Sie ein Dokument an ein anderes Dokument in einem Archiv oder Briefkorb an.

    Wenn das Ziel ein Datenbankeintrag ist, wird dieser automatisch in ein Dokument umgewandelt.

  • Operation: processDocumentAction

  • Befehl: PUT

  • Pfad:
    /FileCabinets/{TrayId/FileCabinetId}/Operations/ProcessDocumentAction?docId={DocId}

  • HTTP body (sample): 

    { "DocumentAction": "Append", "DocumentActionParameters": { "$type": "AppendActionParameters", "RemoveSourceDocuments": false, "DocumentsInFront": [ ], "DocumentsAtBack": [ { "SourceCabinetId": "ae156510-ffa8-48b1-a3ec-baec3180669c", "Documents": [ 123456 ] } ] } }

Benutzer anlegen

  • Beschreibung: Inhaltstyp muss eingestellt sein auf:  application/vnd.docuware.platform.createorganizationuser+json

  • Standard: ja

  • Operation: createUser

  • Befehl: POST

  • Pfad: /Organization/UserInfo

  • HTTP body (sample): 

    { "EMail": "firstname.lastname@domain.com", "Name": "MyUserName", "DBName": "MYUSERNA", "Password": "eLK%4s*Z", "NetworkID": "Domain\\MyUserName" }

Benutzereigenschaften ändern

  • Standard: ja

  • Operation: modifyUser

  • Befehl: PATCH

  • Pfad: /Organization/UserInfo

Alle Benutzer einer Organisation abrufen

  • Standard: ja

  • Operation: users

  • Befehl: GET

  • Pfad: /Organization/Users?Active={true|false}&Name={UserName}

Alle Benutzer einer Gruppe abrufen

  • Beschreibung: GroupID muss angegeben werden

  • Standard: ja

  • Operation: UsersByGroup

  • Befehl: GET

  • Pfad: /Organization/GroupUsers?groupId={GroupId}

Alle Benutzer einer Rolle abrufen

  • Beschreibung: RoleID muss angegeben werden
    IncludeGroupUsers (optional): Boolean - default: 'false'

  • Srandard: ja

  • Operation: usersByRole

  • Befehl: GET

  • Pfad:
    /Organization/UserRoles?UserId={UserId}&Active={true|false}&Name={RoleName}&Type={Standard|Default|Administrator}

Informationen zu einem Benutzer abrufen

  • Beschreibung: Zu den Informationen zählen zum Beispiel der Status oder die Abwesenheit

    UserID muss angegeben werden.

  • Standard: ja

  • Operation: userById

  • Befehl: GET

  • Pfad: /Organization/UserByID?userId={UserId}

Alle Rollen eines Benutzers abrufen

  • Beschreibung:
    UserID muss angegeben werden.

    Aktiv (optional): Boolean - default: leer

    Name (optional): Name der Rolle

    Typ (optional): {Standard|Default|Administrator}

  • Standard: ja

  • Operation: userRoles

  • Befehl: GET

  • Pfad: /Organization/UserRoles?UserId={UserId}

Benutzer zu einer Rolle hinzufügen

  • Beschreibung: UserID muss angegeben sein

  • Standard: ja

  • Operation: userRoles

  • Befehl: PUT

  • Pfad: Organization/UserRoles?UserId={UserId}

  • HTTP body (sample): 

    { "Ids": [ "2d89fc45-a3c4-49c6-971b-ebc696a67d78" ], "OperationType": "Add" }

Benutzer aus einer Rolle entfernen

  • Beschreibung: UserID muss angegeben sein

  • Operation: userRoles

  • Befehl: PUT

  • Pfad: Organization/UserRoles?UserId={UserId}

  • HTTP body (sample): 

    { "Ids": [ "2d89fc45-a3c4-49c6-971b-ebc696a67d78" ], "OperationType": "Remove" }

Alle Gruppen von einem Benutzer abrufen

  • Beschreibung: UserID muss angegben werden

  • Standard: ja

  • Operation: userGroups

  • Befehl: GET

  • Pfad: /Organization/UserGroups?UserId={UserId}

Benutzer zu einer Gruppe hinzufügen

  • Beschreibung: UserID muss angegben werden

  • Standard: ja

  • Operation: userGroups

  • Befehl: PUT

  • Pfad: /Organization/UserGroups?UserId={UserId}

  • HTTP body (sample): 

    { "Ids": [ "2d89fc45-a3c4-49c6-971b-ebc696a67d78" ], "OperationType": "Add" }

Benutzer aus einer Gruppe entfernen

  • Beschreibung: UserID muss angegeben sein

  • Standard: ja

  • Operation: userGroups

  • Befehl: PUT

  • Pfad: /Organization/UserGroups?UserId={UserId}

  • HTTP body (sample): 

    { "Ids": [ "2d89fc45-a3c4-49c6-971b-ebc696a67d78" ], "OperationType": "Remove" }

Alle Rollen von einer Organisation abrufen

  • Beschreibung:
    Aktiv (optional): Boolean - default: leer

    Name (optional): Name der Rolle

    Typ (optional): {Standard|Default|Administrator}

  • Operation: roles

  • Befehl: GET

  • Pfad: /Organization/Roles? Active={true|false}&Name={RoleName}&Type={Standard|Default|Administrator}

Informationen zu einer Rolle abrufen

  • Beschreibung:
    Zum Beispiel den Status "aktiv". RoleID ist verpflichtend.

  • Standard: ja

  • Operation: role

  • Befehl: GET

  • Pfad: /Organization/Role?roleId={RoleId}

Alle Gruppen einer Organisation abrufen

  • Beschreibung:
    Aktiv (optional): Boolean - default: leer

    Name (optional): Name der Gruppe

  • Standard: ja

  • Operation: groups

  • Befehl: GET

  • Pfad: /Organization/Groups?&Active={true|false}&Name={GroupName}

Informationen zu einer Gruppe abrufen

  • Beschreibung: Zum Beispiel den Status "aktiv", GroupID muss angegeben sein

  • Standard: ja

  • Operation: group

  • Befehl: GET

  • Pfad: /Organization/Group?groupId={GroupId}

Anwendungsbeispiel für den Endpunkt "documentAnnotations"

Nachdem eine Rechnung in der Buchhaltungssoftware bearbeitet wurde, soll sie in DocuWare automatisch mit dem Stempel "Bezahlt" versehen werden. Um dies zu konfigurieren, richten Sie zunächst einen Autoindex-Job ein, der den Indexeintrag der Rechnung auf "Bezahlt" ändert.

Auf die Änderung des Indexeintrags startet ein Workflow, dessen Webservice-Aktivität den Stempel „Bezahlt“ automatisch auf das Rechnungsdokument setzt.

Beachten Sie, dass der "Paid"-Stempel konfiguriert und dem Benutzer zugewiesen sein muss, der für den Workflow angegeben ist, um automatische Aktivitäten auszuführen.

Die Konfiguration des Endpunkts "documentAnnotations" sieht wie folgt aus:

Web service platform table example

Web service platform table example 2

Web service platform table example 3